fix(cli): explain the checkout requirement and fix the docs that led users outside one

[AbirAbbas]

Summary

Following the README's "built for coding agents" block literally fails. af-stack init my-ai-product scaffolds a small standalone app that calls a running BackAI; the next two lines, af-stack init --name … and af-stack agent new …, only work inside a clone of this repo, and the README never says so. The natural move — cd into the new app and run them — died with the bare must run from inside an AF Stack checkout, which gives no hint what a checkout is or how to get one.

The same confusion runs through the docs: the dx hub's golden path called the positional form a fork scaffold and then ran af-stack dev in it (which cannot work there), and the skill's "primary path" used af-stack init acme-coder --template coding-agent, which the positional form rejects with exit 2 (it only knows node and saas), followed by the same impossible dev.

Changes

CLI: one checkout finder with an error that explains itself. The duplicated root finders in initcmd and project move into services/cli/internal/checkout. When no clone encloses the working directory, the error names the directory, says a checkout is a clone containing apps/dashboard and apps/customer-app, recognises an app written by af-stack init <name> and says it has no surfaces to brand or extend, and prints both next steps: the git clone … && cd … for a fork, or af-stack init <name> for a standalone app. This covers init --name, dev, agent|module|plugin new, and deploy. Behaviour inside a clone, including subdirectories, is unchanged.

af-stack: init: must run from inside a BackAI checkout — a clone of https://github.com/Agent-Field/backai (a directory containing apps/dashboard and apps/customer-app); /home/me/my-ai-product is not one.
  /home/me/my-ai-product is a standalone app created by `af-stack init <name>`: it calls a running BackAI and has no fork surfaces to brand or extend.
  To brand a fork or add agents, modules, or plugins:  git clone https://github.com/Agent-Field/backai my-fork && cd my-fork
  To scaffold a standalone app instead:                af-stack init <name>   (works in any directory)

Docs: the clone comes before the fork commands, and each init form is named. README, the dx hub, docs/cli-distribution.md, docs/theming.md, and the skill's primary path now start the fork sequence with git clone … && cd …, state that the flag form and the scaffolds run inside that clone, and say plainly that af-stack init <name> is a different thing: a standalone app that calls a running BackAI, in any directory.

init --name on a fresh clone no longer opens with a Node stack trace. It ran pnpm run generate:brand unconditionally and echoed everything the failed command wrote, so on a clone without pnpm install — the README case — the first thing on screen was a twenty-line ERR_MODULE_NOT_FOUND trace. It now skips the generator when node_modules is absent or pnpm is not on PATH and says in one line what to run; a genuine generator failure is reported by the tail of its output, where the error is. The usage comment also advertised an --brand flag that does not exist.

Verification

• Contract tests in checkout, initcmd, and project: outside a clone the error carries the directory, the definition, the clone command, and the standalone alternative; inside a scaffolded app (both node and saas templates) it says so; a plain Node project is not mistaken for one; a clone that also carries the scaffold markers is still a clone; agent new from a clone subdirectory still writes to the root.
• Replayed the user's exact sequence with the rebuilt binary: init my-ai-product, cd, init --name … --logo …, agent new researcher, dev — each now prints the explanation above and exits 1.
• Replayed the rewritten README fork block and the rewritten skill primary path literally in a throwaway clone: init --name "Acme AI" --color "#2563EB" --logo ./logo.png updates brand.yaml and copies the logo, agent new researcher scaffolds the agent, and init --name "Acme Coder" --template coding-agent brands the clone and wires the coding agent into compose.
• Generator behaviour pinned by tests: skipped with a one-line hint when deps are missing, run when they are present, trimmed output on a real failure.
• Full go build, go vet, go test ./... pass; golangci-lint v2.13.1 in CI's new-issues mode reports 0 new issues; docs lint and the docs-site build pass.

🤖 Generated with Claude Code