feat(cli)!: remove --here, and lead the docs with Discover (#798)

[edspencer]

Closes #798.

What this removes

--here opened the directory you were standing in as the workspace, with its own data dir at <dir>/.paddock. Discover (#745) does the job it was built for from one instance with as many linked directories as you like — which is also the only shape that can run as a background service (#796): a launchd agent hosts exactly one instance, so three directories opened with --here were three instances of which it could run at most one.

Gone: cli/here.ts entire (HERE_MARKER, isHereWorkspace, countClaudeSessions, ensureGitignored), the --here flag and the here key on CliOptions, announceHereConsent, offerHereIfSessionsExist. The entrypoint no longer reads process.cwd() and no longer writes into any directory.

The server is untouched. PADDOCK_PROJECTS_DIR remains a supported env var — it just stops being set from cwd, and falls back to the server's own default of <dataDir>/projects.

It deletes a live bug rather than patching it

HERE_MARKER was .paddock; the default data dir is ~/.paddock. So on any machine where Paddock had ever run bare, isHereWorkspace($HOME) was true — a later bare run from your home directory resumed the entire home as the workspace, wrote ~/.gitignore and created ~/.chats. An explicit --data-dir was honoured and did not help (PADDOCK_PROJECTS_DIR = cwd was set independently), and because it read as a resume the consent announcement was skipped. The only tell was the word (resumed).

Nothing on this box had a here-workspace to migrate (ls -d ~/code/*/.paddock empty, no ~/.paddock).

Two decisions worth reviewing

countClaudeSessions is deleted, not salvaged. #798 says to move it for #745, but Discover shipped in the meantime with its own path via adoptable.ts's transcriptFolders(). It was left used by nothing except the hint below.

The bare-run hint is deleted, not redirected. offerHereIfSessionsExist counted the current directory's Claude sessions and suggested paddock --here. Both halves were the problem — the flag is gone, and cwd-dependence is the thing being removed. A replacement scan would also be the wrong shape: it would duplicate Discover's heuristic in the CLI, cost a filesystem walk at boot, and print a number the UI is about to render better with a tick-box next to it.

What replaces it is one line in the existing first-run welcome — "Open the app to find directories you have used Claude Code in." No scan, true whatever a scan would have found, and it lands exactly where an empty instance's Home leads with Discover anyway.

Docs

One pass, ten files plus the USAGE string — four more than #798 listed (what-paddock-touches.md, who-its-for.md, deploying.md, kubernetes.md, environment.md, scripts/make-tarball.sh).

The new story: npx @edspencer/paddock starts the server; a new instance opens on Discover, which reads your Claude Code history, offers the directories you have actually been working in, and links the ones you tick. The caveat paragraph about what gets written into your repo is gone rather than reworded — nothing is written into a linked directory at all: no .paddock/, no .chats/, no .gitignore edit, no CLAUDE.md. (Traced through ProjectStore.create → acquirePath, which returns early for an existing path; the CLAUDE.md seed is gated on managed, and Discover always sends managed: false.)

Discover is described from the merged code, not from #745 — the soft/hard rule split, the excluded tally answering "why 5 and not 12?", lazy row expansion and tri-state tickboxes, and the recordedPath warning.

New What's New entry at 0.68 (both Discover changesets are still pending, so Discover and this ship together). The historical 0.59.1–0.60 and 0.61.1 entries still say --here existed and now link forward to its removal rather than being rewritten.

Tests

• test/unit/cli-here.test.ts deleted.
• cli-paddock.test.ts pins --here as a rejected unknown option. Worth being deliberate about: it decided which instance you got, so accepting it as a no-op would start the ~/.paddock instance while the user believed they had opened the directory they were standing in.
• A source-level guard that the entrypoint never sets PADDOCK_PROJECTS_DIR, never writes a .gitignore, and never reads process.cwd(). Justified inline: the behavioural version would have to spawn the CLI in a here-shaped directory and start a real server to reach side effects that ran between arg parsing and listen. Precedent is check-no-nul-bytes.
• cli-bin-invocation now asserts --help does not advertise the flag.

Local: server 2072 passed / 159 files, web 1774 / 84, typecheck clean on both, website builds (51 pages). Both new cross-page anchors verified against the built HTML.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	ddb1d6c
Status:	✅  Deploy successful!
Preview URL:	https://68f5ed27.paddock-7u2.pages.dev
Branch Preview URL:	https://chore-798-remove-here.paddock-7u2.pages.dev

View logs