fix(agents): build every onboarding prompt from one discovery-first builder

.claude/skills/hack-init/SKILL.md

@@ -12,6 +12,6 @@ Fetch the current onboarding guidance from the installed Hack CLI.
 
 1. Fetch the canonical onboarding prompt:
    - With shell access: run `hack agent onboard` (works for new and existing projects).
-   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
+   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it and pass `repoRoot` (the repository root path) so the prompt includes Hack's repo inventory; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
 2. Apply the relevant phases to the authorized workflow; preserve native approvals, credential safety, and runtime ownership.
 3. Verify the requested services and host workflows. Report remaining blockers; unrelated optional integration warnings do not prevent completion.

.codex/skills/hack-cli/SKILL.md

@@ -14,7 +14,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -192,6 +192,6 @@ Use `hack` as the primary interface for local-first development.
 - MCP is opt-in, only for clients without shell access and only when explicitly selected: add the separate `hack-mcp` plugin, or use `hack setup mcp` (client and scope via `hack mcp install --help`). Do not configure other clients as a side effect.
 - Standalone export is an opt-in alternative to the plugin: `hack setup cursor` (rules), `hack setup claude` (hooks and skill), `hack setup codex` (skills) or `hack setup agents` (AGENTS.md/CLAUDE.md snippets). Use one integration path per client.
 - Setup and onboarding never write AGENTS.md, CLAUDE.md, rule files, or repository skill copies unless the user asks for them.
-- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
+- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content. No-shell clients pass `repoRoot` (the repository root path) to the `hack-init` MCP prompt to include Hack's repo inventory.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`

.codex/skills/hack-init/SKILL.md

@@ -12,6 +12,6 @@ Fetch the current onboarding guidance from the installed Hack CLI.
 
 1. Fetch the canonical onboarding prompt:
    - With shell access: run `hack agent onboard` (works for new and existing projects).
-   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
+   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it and pass `repoRoot` (the repository root path) so the prompt includes Hack's repo inventory; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
 2. Apply the relevant phases to the authorized workflow; preserve native approvals, credential safety, and runtime ownership.
 3. Verify the requested services and host workflows. Report remaining blockers; unrelated optional integration warnings do not prevent completion.

.cursor/rules/hack.mdc

@@ -9,7 +9,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

docs/agent-guidance.md

@@ -17,9 +17,9 @@ run only `hack agent prime`. See [model-policy ownership](reference/agent-client
 | `apps/macos/AGENTS.md` | Explicit maintenance of the unsupported native app |
 | `.ai/skills/` | Contributor quality, verification, work units, performance and TLA+ workflows |
 | `src/agents/instruction-source.ts` | Project AGENTS/CLAUDE snippets, standalone/shared Hack skill, Cursor rules, session primer, native plugin skill/rule |
-| `src/agents/onboarding-prompt.ts` | `hack agent onboard`, init handoff, and MCP onboarding prompt |
+| `src/agents/onboarding-prompt.ts` | The one onboarding builder: `hack agent onboard`, `hack agent init`, init handoff, and MCP onboarding prompt (same core, per-entry framing only) |
 | `src/agents/hack-init-skill.ts` | Thin Claude/Codex/plugin adapter that fetches onboarding guidance |
-| `src/agents/init-patterns.ts`, `init-assistant.ts` | Optional init inventory and pattern hints |
+| `src/agents/init-patterns.ts`, `init-assistant.ts` | Repo inventory embedded by the onboarding builder, and pattern hints |
 | `src/agents/install-skill.ts`, `remote-bootstrap-skill.ts` | Plugin installation/channel selection and fresh-host/cloud setup skills |
 | `src/agents/focused-skills.ts` | Plugin `hack-branches`, `hack-env` and `hack-diagnose` skills, composed from canonical section ids, and the plugin `hack-cli` routing description |
 | `src/agents/error-code-reference.ts` | `hack-diagnose` error-code reference, rendered from the exported `HACK_ERROR_CODES` registry in `src/lib/cli-result.ts` |

docs/guides/agent-first-setup.md

@@ -5,6 +5,13 @@ existing setup — instead of doing it by hand. One canonical onboarding prompt
 every entry point below; the content lives in the CLI, so it is always current for
 your installed version.
 
+Every entry point calls the same builder with the same repo inventory. For the same
+repo, `hack init --with`, `hack agent onboard`, `hack agent init`, and the
+`hack-init` MCP prompt (with `repoRoot`) produce byte-identical prompt content; each
+adds at most a fixed framing line. The mode follows the repo: `existing-project`
+when `.hack/` exists (project name and dev host come from its config),
+`new-project` otherwise.
+
 ## Entry points (same prompt, four ways in)
 
 | You have | Use |
@@ -25,8 +32,9 @@ hack init --auto --with claude   # or codex, or both
   onboarding prompt (`claude "<prompt>"` / `codex "<prompt>"`).
 - If the agent CLI is not on PATH, the prompt is printed with copy-paste
   instructions instead.
-- If `.hack/` already exists, init is skipped and the handoff proceeds in
-  existing-project mode.
+- The handoff always runs after `.hack/` exists, so the prompt is in
+  existing-project mode. A framing line says whether this run scaffolded `.hack/`
+  or found it already present and skipped init.
 - With `--no-interactive` (or `HACK_NO_INTERACTIVE=1`, or no TTY) nothing is
   spawned — the prompt is always printed.
 
@@ -37,8 +45,15 @@ hack agent onboard          # prints the onboarding prompt for this project
 hack agent onboard | pbcopy # copy it for any agent session
 ```
 
-The prompt picks up the project name and dev host from `.hack/hack.config.json`
-when present.
+The prompt starts with a pre-computed repo inventory and picks up the project name
+and dev host from `.hack/hack.config.json` when present.
+
+The `hack-init` MCP prompt takes an optional `repoRoot` argument (relative paths
+resolve against the MCP server's working directory). With `repoRoot` it returns the
+same content as `hack agent onboard` for that repo and ignores the `mode`,
+`projectName`, and `devHost` arguments. Without it the server scans nothing, uses
+those arguments (default `existing-project`), and the prompt states that no
+inventory was run.
 
 ## Agent-side skill: `/hack-init`
 
@@ -47,7 +62,8 @@ through your client's plugin manager (see
 [Optional native plugins](../integrations.md#optional-native-plugins)). The skill
 tells the agent to run `hack agent onboard` and follow the printed prompt. Without
 shell access it fetches the `hack-init` MCP prompt only when a Hack MCP server, such
-as the opt-in `hack-mcp` plugin, is installed; otherwise it reports that blocker.
+as the opt-in `hack-mcp` plugin, is installed, and passes `repoRoot` so the prompt
+includes the repo inventory; otherwise it reports that blocker.
 The content stays in the CLI, so the skill fetches guidance matching the installed
 CLI.
 
@@ -117,10 +133,11 @@ The ground rules tell the agent not to create or modify `AGENTS.md`, `CLAUDE.md`
 rule files, or repository skill copies unless asked. Onboarding configures the
 runtime; it does not install agent instructions. The agent also reports the
 discovery limits it hit: a missing agent client (the prompt was printed instead of
-launched), a non-interactive run, or the no-shell `hack-init` MCP prompt, which
-defaults to existing-project mode without a repo inventory.
+launched), a non-interactive run, the inventory's remaining discovery limitations,
+or a `hack-init` MCP prompt request without `repoRoot`, which defaults to
+existing-project mode without a repo inventory.
 
-`hack agent init` adds a pre-computed inventory before the same prompt. It reads
+The pre-computed inventory comes before the phases in every entry point. It reads
 file names and manifest keys only, never env-file contents, lockfile contents or
 pin values. It ends with a list of discovery limitations, such as conflicting
 package managers or non-JS services whose entrypoints were not inferred.

examples/basic/AGENTS.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -163,7 +163,7 @@ Agent setup (plugin-first):
 - MCP is opt-in, only for clients without shell access and only when explicitly selected: add the separate `hack-mcp` plugin, or use `hack setup mcp` (client and scope via `hack mcp install --help`). Do not configure other clients as a side effect.
 - Standalone export is an opt-in alternative to the plugin: `hack setup cursor` (rules), `hack setup claude` (hooks and skill), `hack setup codex` (skills) or `hack setup agents` (AGENTS.md/CLAUDE.md snippets). Use one integration path per client.
 - Setup and onboarding never write AGENTS.md, CLAUDE.md, rule files, or repository skill copies unless the user asks for them.
-- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
+- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content. No-shell clients pass `repoRoot` (the repository root path) to the `hack-init` MCP prompt to include Hack's repo inventory.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`
 <!-- hack:agent-docs:end -->

examples/basic/CLAUDE.md

@@ -6,7 +6,7 @@ Use `hack` as the single interface for local-first runtime orchestration (compos
 Integration freshness:
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 Product boundary:
 - Supported CLI surface: project init, up/down/restart, open, logs, env, host exec/shell, sessions, doctor, and daemon.
@@ -163,7 +163,7 @@ Agent setup (plugin-first):
 - MCP is opt-in, only for clients without shell access and only when explicitly selected: add the separate `hack-mcp` plugin, or use `hack setup mcp` (client and scope via `hack mcp install --help`). Do not configure other clients as a side effect.
 - Standalone export is an opt-in alternative to the plugin: `hack setup cursor` (rules), `hack setup claude` (hooks and skill), `hack setup codex` (skills) or `hack setup agents` (AGENTS.md/CLAUDE.md snippets). Use one integration path per client.
 - Setup and onboarding never write AGENTS.md, CLAUDE.md, rule files, or repository skill copies unless the user asks for them.
-- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
+- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content. No-shell clients pass `repoRoot` (the repository root path) to the `hack-init` MCP prompt to include Hack's repo inventory.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`
 <!-- hack:agent-docs:end -->

plugins/hack/rules/hack.mdc

@@ -14,7 +14,7 @@ Prefer `hack` when shell access is available. Use MCP only when shell access is
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 ## Product boundary
 

plugins/hack/skills/hack-branches/SKILL.md

@@ -35,4 +35,4 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).

plugins/hack/skills/hack-cli/SKILL.md

@@ -16,7 +16,7 @@ Use `hack` as the primary interface for local-first development.
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 ## Product boundary
 
@@ -194,7 +194,7 @@ Use `hack` as the primary interface for local-first development.
 - MCP is opt-in, only for clients without shell access and only when explicitly selected: add the separate `hack-mcp` plugin, or use `hack setup mcp` (client and scope via `hack mcp install --help`). Do not configure other clients as a side effect.
 - Standalone export is an opt-in alternative to the plugin: `hack setup cursor` (rules), `hack setup claude` (hooks and skill), `hack setup codex` (skills) or `hack setup agents` (AGENTS.md/CLAUDE.md snippets). Use one integration path per client.
 - Setup and onboarding never write AGENTS.md, CLAUDE.md, rule files, or repository skill copies unless the user asks for them.
-- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content.
+- Agent-assisted onboarding: `hack init --with claude|codex` (new repos) or `hack agent onboard` (existing projects) print/hand off the full setup prompt; the `/hack-init` skill and the `hack-init` MCP prompt return the same content. No-shell clients pass `repoRoot` (the repository root path) to the `hack-init` MCP prompt to include Hack's repo inventory.
 - Init prompt: `hack agent init` (use --client cursor|claude|codex to open)
 - Init patterns: `hack agent patterns`
 

plugins/hack/skills/hack-diagnose/SKILL.md

@@ -37,7 +37,7 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).
 
 ## References
 

plugins/hack/skills/hack-env/SKILL.md

@@ -34,4 +34,4 @@ description: >
 
 - These instructions were generated by hack CLI v4.2.1; use the content revision and command behavior to assess freshness.
 - Check guidance only when Hack is relevant and there is evidence of drift; use targeted `hack setup` checks for a read-only inventory. Routine tasks do not require a startup audit.
-- Content revision: `8f9bff2d631a` (version alone is not a freshness guarantee).
+- Content revision: `bd15ee2d251b` (version alone is not a freshness guarantee).

plugins/hack/skills/hack-init/SKILL.md

@@ -12,6 +12,6 @@ Fetch the current onboarding guidance from the installed Hack CLI.
 
 1. Fetch the canonical onboarding prompt:
    - With shell access: run `hack agent onboard` (works for new and existing projects).
-   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
+   - Without shell access: only if the `hack-mcp` plugin or another Hack MCP server is installed, fetch the `hack-init` MCP prompt from it and pass `repoRoot` (the repository root path) so the prompt includes Hack's repo inventory; otherwise report that onboarding needs shell access or an explicitly selected Hack MCP server.
 2. Apply the relevant phases to the authorized workflow; preserve native approvals, credential safety, and runtime ownership.
 3. Verify the requested services and host workflows. Report remaining blockers; unrelated optional integration warnings do not prevent completion.