docs(using,guides): refresh the using/guides/entry-point pages for v0.66.2

[edspencer]

Docs last had a systematic pass at v0.62; main is v0.66.2. This is the
using/ + guides/ + entry-point group: 12 WRONG, 10 STALE, 6 MISSING items, each
re-verified against source at b38dff2 before editing.

Docs-only — no changeset, no version bump. cd website && npm install && npm run build
exits 0 (51 pages).

The import → adopt decision (and why it reads the way it does)

I led with "adopt" everywhere, and where a page describes what the CLI prints, I say
so explicitly and cite #770.

The constraint: the web UI is uniformly adopt since #748 — zero user-visible
"import" strings in packages/web/src. But paddock --help and the CLI's startup text
still say "import", and so do the OpenAPI route summaries. Aligning the docs on "adopt"
alone would make getting-started.md contradict the first thing a brand-new user reads
in their own terminal.

So rather than pick one and let the reader hit the mismatch cold, three pages now name
it as a known lag with a link to #770 — getting-started.md, what-paddock-touches.md,
and working-in-chats.md. When #770 lands, those three parentheticals come out and
nothing else needs to change.

npm run import-chats keeps its name, as #770 says it should. working-in-chats.md
now explains why it keeps it, so the next pass doesn't "fix" it.

One correctness fix rides along: what-paddock-touches.md said "Import copies,
never moves". That is both the retired vocabulary and a claim #748 corrected as false —
under transcripts: host there is no copy, because .chats already is your Claude
home. The page now states the invariant that holds in both modes: your originals are
never moved or deleted.

The claude-CLI-and-triggers claim (W4–W7)

Four pages said the claude binary is needed for triggers. It isn't, on the default
drive mode. Verified end to end before editing:

• ws-triggers.ts:70-74 resolves a trigger's drive mode exactly like a chat's (project
  override, else cfg.driveMode) and passes it at :189
• ws-turn.ts:550-553 branches session → chatSession / batch → chat
• @herdctl/core job-control.js:414 — openChatSession hard-codes new SDKRuntime(...),
  never consults PATH
• models.ts:168 — DEFAULT_DRIVE_MODE = "session"
• herdctl.ts:1614 — the sweeper's manager.trigger(...) is the one unconditional call

Corrected in getting-started.md, contributing.md, guides/home-lab.md,
guides/agent-capabilities.md, plus a fifth instance the audit didn't flag: the scope
note in contributing/testing.md, which made the same claim about which agent lines
govern which runtime.

Fixed to the verified behaviour, not the source comments — those comments are the
origin of the error and are tracked as #771, cited in the two contributor-facing
pages so this doesn't regress on the next read-through.

Everything else

WRONG — proxmox-lxc.md health check on port 3000 → 7233 · History origin chip
"Imported" → Adopted · dead anchor #import-your-terminal-claude-history →
#adopt-your-terminal-claude-history · the sweeper's CLAUDE.md axis is managed
(derived !(repo || path)), not "non-repo-backed" — the old wording wrongly promised a
curated CLAUDE.md to an unmanaged path:-only project · index.mdx's "Project-first"
card rewritten off the retired repoBacked type onto the two real axes · testing.md's
server.mjs:119 → :127 · the E2E layer is 20 specs / 4 Playwright projects / 2
servers, not one spec file · the "error states, file pins, git UI not yet driven from
the browser" gap is closed (those specs exist).

MISSING — M1 is the security one: guides/securing.md never stated the
driveMode: batch credential-in-argv exposure, despite being the page an operator reads
before handing Paddock a token. Now a danger box + a checklist line, with the two things
that actually bite: a single project pinning batch reintroduces it instance-wide,
and on a multi-user box it means every local account can read the token. Also added:
promote_project as a second agent-chosen git clone route (repo is its only
required arg — easy to miss) in both untrusted-content.md and the write-scope danger
box in connect-claude-code.md; run_trigger in two tool lists; host plugin
inheritance as a truth table (mcpServers: host alone inherits no plugins —
enumeration gates on instructions) plus the mcp__plugin_<plugin>_<server>__*
allowlist shape; and environmentPrompt — including that it is silently not appended
on driveMode: batch, which is exactly what agent-capabilities.md tells you to pin
for Docker isolation.

STALE — --help env-override annotations · import-chats needs --project (exits
2 without it) · CI's check:nul and docs-site build steps · the release also publishes
to npm via OIDC · per-file test enumeration replaced with directory shape (it named 6
unit / 8 integration; there are 100 / 58, plus 72 web) · test:unit / test:integration
scripts · session has been the default since v0.36.0 (#316) · list_triggers added
to the hooksMcpEnabled row.

What I left, and why

• Coverage figures dropped rather than re-measured. "~90% stmts / 84% branch"
  predates ~150 test files. Rather than mint a number that goes stale again, the page now
  says how to measure it and notes @vitest/coverage-v8 is already a devDependency.
• architecture/herdctl-integration.md:105 carries the same dead anchor as
  scheduling-recurring-work.md:102. Out of scope — the concepts/architecture child owns it.
• No screenshots. Capture is on hold behind the design PRs (feat(web): design system foundation — Tailwind v4, semantic OKLCH tokens, enforced contrast, UI primitives #763–Home: empty states as invitations, not four voids #769). The prose is
  written so images slot in later without rework. One thing fixed regardless:
  creating-and-organizing-projects.md:405 ended a sentence in a colon with nothing after
  it, reading as a dropped image — now a complete sentence.
• CI never uploads the Playwright report: the artifact path is wrong and if-no-files-found: ignore hides it #774 (CI never uploads the Playwright report): contributing/testing.md's line
  about artifacts going to the temp dir is correct and stays. Added a note so a
  contributor doesn't hunt for a report that was never uploaded.

Two audit corrections

• The audit listed the trigger claim on four pages. There is a fifth, in
  contributing/testing.md's scope note — same error, contributor-facing. Fixed.
• working-in-chats.md:46-49 described adoption matching as "by checkout name for a
  repo-backed project, by exact path for a notebook one". The real axis is
  project.repo !== null (adoptable.ts:531-552), not managed/notebook — and the page
  omitted that since bug(adopt): repo-backed source matching is basename-only, pulling in unrelated dirs (hushpod offers another instance's chats) #659 a same-basename directory must prove it is a clone of that
  repo (a git remote must point there) before anything from it is offered. Both corrected.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	8bf1e29
Status:	✅  Deploy successful!
Preview URL:	https://55083537.paddock-7u2.pages.dev
Branch Preview URL:	https://docs-using-guides-0-66.paddock-7u2.pages.dev

View logs