nubos-pilot 0.3.0 → 0.4.0

package/workflows/discuss-project.md

@@ -0,0 +1,177 @@
+---
+command: np:discuss-project
+description: Project-level discovery — adaptive interview that fills (bootstrap) or refreshes (refresh) PROJECT.md sections (Domain, Target Users, Non-Goals, Success Criteria, Strategic Decisions) and proposes REQ candidates.
+---
+
+# np:discuss-project
+
+Deep, adaptive interview on project identity. Called automatically from
+`np:new-project` (bootstrap mode — obligatory before roadmap/plan work),
+and on demand later (refresh mode) when positioning or scope shifts.
+
+The interview is informed by a codebase scan (so when the project already
+contains code, the discussion builds on what exists rather than asking in
+a vacuum).
+
+## Philosophy
+
+<philosophy>
+Five boilerplate questions do not a project understand. PROJECT.md is the
+one artifact every downstream agent reads before asking what to build, and
+its quality caps the quality of every plan that follows. This workflow
+treats the project discussion as a first-class moment — adaptive, grounded
+in the scanned workspace, and ends with a filled PROJECT.md plus a
+user-reviewable list of proposed requirements.
+</philosophy>
+
+## Scope Guardrail
+
+<scope_guardrail>
+Writes only:
+- `.nubos-pilot/PROJECT.md` (section bodies only — structure preserved)
+- `.nubos-pilot/REQUIREMENTS.md` (append-only "Proposed" block)
+
+Never:
+- rewrites application source
+- touches `.nubos-pilot/codebase/` (that is `np:scan-codebase`'s job)
+- writes requirements into the Active list (user promotes manually)
+</scope_guardrail>
+
+## Downstream Awareness
+
+<downstream_awareness>
+- `np:discuss-phase` reads PROJECT.md's Constraints and Domain.
+- `np:planner` reads Non-Goals to avoid scope creep.
+- `np:researcher` reads Strategic Decisions before proposing libraries.
+- REQ-IDs appended by this workflow are consumed by `np:plan-phase` after
+  the user promotes them.
+</downstream_awareness>
+
+## Single-Call Init
+
+```bash
+INIT=$(node np-tools.cjs init discuss-project ${BOOTSTRAP:+--bootstrap})
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse: `mode`, `sub_mode` (`bootstrap` or `refresh`), `project_md_exists`,
+`scan_context`, `questions[]`, `required_fields[]`.
+
+## Process
+
+### Step 1: Ground the user in the scan
+
+Show the scan context before questions:
+
+```
+Before we discuss — here is what I found in the workspace:
+
+- Files: <scan_context.file_count>
+- Languages: <top 3 from language_distribution>
+- Manifests: <manifest_paths>
+- README head:
+  <first 10 lines or "none">
+- Git: <commits[0..2] subjects or "no git repo">
+
+Does this match what you expect, or am I missing something?
+```
+
+Let the user correct (e.g. "the README is stale, ignore it"). Record
+corrections — they shape follow-up questions.
+
+### Step 2: Adaptive interview across the six required fields
+
+The six required fields come from `required_fields[]`:
+
+1. `project_description` — What This Is (2–3 sentences)
+2. `domain_text` — Domain / lore / background
+3. `target_users_text` — Target users
+4. `non_goals_text` — Explicit Non-Goals
+5. `success_criteria_text` — Observable success criteria
+6. `strategic_decisions_text` — Strategic tech/business decisions
+
+For each field: ask the seed question from `questions[]`, then follow up
+with 1–3 deepening questions based on the answer. Use `np-tools.cjs
+askuser` for every prompt (SC-5 enforcement — never bypass the gateway).
+
+Tailor follow-ups to the scan:
+
+- If the workspace has code, ask "I see `src/auth/` and `services/api/` —
+  does the Non-Goals list carve out what these will not do?"
+- If no code, ask "For Strategic Decisions, what language/runtime are you
+  committing to?"
+
+When the user's answer references an existing doc (e.g. "see README
+section X"), fetch it and ground your summary in that.
+
+### Step 3: Propose requirements
+
+Based on the Success Criteria + Domain + Non-Goals, propose 3–7 candidate
+REQ entries. Present them for user confirmation:
+
+```
+I see these requirements emerging from your answers. Want me to add them to
+REQUIREMENTS.md under "Proposed"?
+
+REQ-02 — must operate offline (no network calls)
+REQ-03 — persists all state as plain Markdown files
+REQ-04 — supports Node 22+ and Python 3.12+
+
+(confirm all / pick subset / none)
+```
+
+Write the confirmed list to a JSON file:
+
+```bash
+REQ_FILE=$(mktemp -t np-proposed-reqs-XXXXXX.json)
+# [{"id":"REQ-02","text":"..."}, ...]
+```
+
+### Step 4: Apply answers
+
+```bash
+ANSWERS=$(mktemp -t np-discuss-project-answers.XXXXXX.json)
+# Write the six answer fields as JSON
+
+node np-tools.cjs init discuss-project --apply "$ANSWERS" \
+  ${BOOTSTRAP:+--bootstrap} \
+  ${REQ_FILE:+--proposed-requirements "$REQ_FILE"}
+```
+
+The subcommand replaces PROJECT.md section bodies (structure preserved)
+and appends a "Proposed" block to REQUIREMENTS.md. Both writes are atomic.
+
+### Step 5: Commit respecting config.commit_docs
+
+```bash
+COMMIT_DOCS=$(node np-tools.cjs config-get workflow.commit_docs 2>/dev/null || echo "true")
+if [[ "$COMMIT_DOCS" == "true" ]]; then
+  git add .nubos-pilot/PROJECT.md .nubos-pilot/REQUIREMENTS.md 2>/dev/null || true
+  git commit -m "docs: np:discuss-project ${BOOTSTRAP:+bootstrap}${BOOTSTRAP:-refresh}" 2>/dev/null || true
+fi
+```
+
+## Output
+
+```
+np:discuss-project complete (<sub_mode>).
+
+Updated:
+  .nubos-pilot/PROJECT.md
+  .nubos-pilot/REQUIREMENTS.md   (if requirements were proposed)
+
+Next:
+  - Promote proposed REQs to Active in REQUIREMENTS.md
+  - Run `np:scan-codebase` if you have not yet (recommended)
+  - Run `np:discuss-phase 1` when ready to scope the first phase
+```
+
+## Errors
+
+| Code | Trigger | User action |
+|------|---------|-------------|
+| `discuss-project-not-initialized` | `.nubos-pilot/` missing | Run `np:new-project` |
+| `discuss-project-missing-field` | answer JSON lacks one of six fields | Complete the interview |
+| `discuss-project-cannot-refresh` | refresh mode but PROJECT.md missing | Run bootstrap mode first |
+| `discuss-project-bootstrap-requires-project` | bootstrap but no scaffold | Run `np:new-project` |
+| `discuss-project-answers-parse-error` | answers file not valid JSON | Retry |

package/workflows/new-project.md

@@ -1,26 +1,34 @@
 ---
 command: np:new-project
-description: Greenfield project scaffold — runs interactive interview, writes PROJECT.md + REQUIREMENTS.md + roadmap.yaml + first phase dir + ROADMAP.md.
+description: Greenfield project scaffold — scans existing workspace, runs bootstrap interview (5 questions), scaffolds the baseline artifacts, then chains into obligatory project discovery and initial codebase scan.
 ---
 
 # np:new-project
 
-Initialize a new project through a short interview, then scaffold the five
-baseline artifacts (`PROJECT.md`, `REQUIREMENTS.md`, `roadmap.yaml`,
-`ROADMAP.md`, `STATE.md`) plus the first phase directory with a
-`CONTEXT.md` placeholder. This is the greenfield entry point; all other
-`np:*` workflows assume a project exists.
+Initialize a new nubos-pilot project in three phases:
+
+1. **Phase 0 — Workspace Scan** (context capture)
+2. **Phase 1 — Bootstrap Interview** (5 structural questions → scaffold)
+3. **Phase 2 — Project Discovery** (obligatory, chains into `np:discuss-project --bootstrap`)
+
+Optionally runs an initial codebase scan at the end when the workspace
+contains existing source (`np:scan-codebase`). Everything lands under
+`.nubos-pilot/`; no source files are ever modified.
 
 ## Philosophy
 
 <philosophy>
-The most leveraged moment in any project is the first interview. Deep
-questioning up front means better roadmaps, better plans, and better
-executions. `np:new-project` does not try to be clever — it asks five
-specific questions whose answers hard-constrain every downstream workflow,
-writes the five files, and exits. The user can edit `PROJECT.md` and
-`REQUIREMENTS.md` any time; this workflow's job is to produce a
-well-formed scaffold, not to pretend to understand the project.
+The most leveraged moment in any project is the first interview, and the
+first interview must be grounded in what actually exists. A bare interview
+produces generic PROJECT.md stubs; a grounded one captures the specific
+project under specific constraints. This workflow therefore scans *first*,
+uses the scan to enrich the interview, and then makes the deeper
+discovery step obligatory — no more jumping into phases with a skeleton
+PROJECT.md.
+
+Runtime-agnostic throughout: scanner is deterministic Node code; interview
+uses the askuser gateway; discovery is delegated to `np:discuss-project`
+which dispatches the documenter agent through whatever host is active.
 </philosophy>
 
 ## Scope Guardrail
@@ -29,86 +37,92 @@ well-formed scaffold, not to pretend to understand the project.
 This workflow ONLY touches `.nubos-pilot/` and creates its first phase
 directory. It NEVER:
 
-- runs outside the current working directory
-- writes when `.nubos-pilot/PROJECT.md` already exists (D-28 Pitfall 8)
-- mutates files in parent directories
-- spawns agents or long-running tasks
-
-If `.nubos-pilot/PROJECT.md` already exists, the subcommand throws
-`project-already-initialized` and this workflow offers two paths: abort
-or destructively reset (user must confirm destructively).
+- modifies files outside `.nubos-pilot/`
+- writes when `.nubos-pilot/PROJECT.md` already exists (refuses with
+  `project-already-initialized`)
+- mutates application source code
+- spawns long-running tasks without user consent (batched codebase scan
+  offers pause between batches)
 </scope_guardrail>
 
 ## Downstream Awareness
 
 <downstream_awareness>
-The five files this workflow writes are consumed by:
-
-- `np:next` (reads `.nubos-pilot/STATE.md` + `.nubos-pilot/roadmap.yaml`)
-- `np:discuss-phase` (reads `PROJECT.md` for constraints, writes
-  `phases/01-<slug>/01-CONTEXT.md` which we scaffold as placeholder)
-- `np:plan-phase` (reads `REQUIREMENTS.md` for requirement IDs)
-- `np:progress` (reads `roadmap.yaml` for totals)
-
-Downstream workflows expect `REQUIREMENTS.md` to have `REQ-*` IDs matching
-the format `**REQ-NN**`. The template seeds `REQ-01` as a TBD — the user
-is expected to edit it before running `np:plan-phase 1`.
+This workflow writes:
+- `.nubos-pilot/PROJECT.md` (section bodies later filled by discovery)
+- `.nubos-pilot/REQUIREMENTS.md` (REQ-01 placeholder)
+- `.nubos-pilot/roadmap.yaml` + `ROADMAP.md`
+- `.nubos-pilot/STATE.md`
+- `.nubos-pilot/phases/01-<slug>/01-CONTEXT.md`
+- (optional) `.nubos-pilot/codebase/` via chained `np:scan-codebase`
+
+`np:discuss-project` (Phase 2) chains automatically — not skippable.
+`np:scan-codebase` chains when the workspace contains >= 1 source file.
 </downstream_awareness>
 
-## Single-Call Init
+## Phase 0: Workspace Scan
 
-All context — the interview question set plus metadata — comes from a
-single `np-tools.cjs init new-project` call.
+Probe the workspace for context before asking anything:
 
 ```bash
-INIT=$(node np-tools.cjs init new-project)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+SCAN=$(node -e '
+  const { scan } = require("./lib/workspace-scan.cjs");
+  const r = scan({ cwd: process.cwd(), batchSize: 1000 });
+  process.stdout.write(JSON.stringify({
+    file_count: r.stats.file_count,
+    langs: r.language_distribution,
+    manifests: Object.keys(r.manifests),
+    docs: Object.keys(r.docs),
+    readme_head: r.docs["README.md"]
+      ? r.docs["README.md"].content.split("\\n").slice(0, 20).join("\\n")
+      : null,
+    git: r.git,
+  }));
+')
 ```
 
-The payload shape:
-
-```json
-{
-  "mode": "interview",
-  "questions": [
-    { "key": "project_name", "type": "input", "question": "Project name?" },
-    { "key": "core_value", "type": "input", "question": "Core value — one sentence…" },
-    { "key": "primary_constraints", "type": "input", "question": "Primary constraints…" },
-    { "key": "first_milestone_name", "type": "input", "question": "First milestone name…" },
-    { "key": "first_phase_name", "type": "input", "question": "First phase name…" }
-  ]
-}
+Show findings to the user and offer pre-filled suggestions:
+
 ```
+Workspace inventory:
+- Files: <file_count>
+- Top languages: <top 3>
+- Manifests found: <list>
+- README detected: <yes/no>
+- Git repo: <yes/no, N commits>
+
+I can suggest defaults from this scan. Review and adjust.
+```
+
+Use the scan to propose:
+- `project_name` — from directory basename; edit if off
+- `primary_constraints` — derived from manifests (e.g. "Node 22" from
+  `package.json.engines.node`)
+- `core_value` — best-effort extraction from README first paragraph
 
-## Interview
+## Phase 1: Bootstrap Interview
 
-All five questions go through `np-tools.cjs askuser` (Phase 3 D-03). No
-runtime-native question tool is permitted anywhere in this file — the
-gateway subcommand is the single allowed path.
+The 5 structural questions. All prompts go through the askuser gateway.
+
+```bash
+INIT=$(node np-tools.cjs init new-project)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
 
 ```bash
 ANS_PROJECT_NAME=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Project name?"}')
-ANS_CORE_VALUE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Core value (1 sentence)?"}')
+ANS_CORE_VALUE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Core value — one sentence that must stay true if everything else fails?"}')
 ANS_CONSTRAINTS=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"Primary constraints (comma-separated)?"}')
 ANS_FIRST_MS=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"First milestone name?"}')
 ANS_FIRST_PHASE=$(node np-tools.cjs askuser --json '{"type":"input","prompt":"First phase name?"}')
 ```
 
-<answer_validation>
-The subcommand slugifies `first_milestone_name` and `first_phase_name`
-and throws `invalid-slug` if either produces an empty string after
-stripping non-`[a-z0-9-]` characters. The user sees this error immediately
-and can re-run the workflow with a different answer.
+When Phase 0 produced a suggestion, include it as the prompt default in
+the askuser call (e.g. `"prompt":"Project name? (suggested: T-AI)"`).
 
-`project_name`, `core_value`, and `primary_constraints` are stored verbatim
-inside the rendered templates — the subcommand's `render()` helper treats
-them as plain strings, so shell metacharacters, Markdown syntax, and YAML
-control chars are all inert. Task 2's NP-5 test asserts this.
-</answer_validation>
+## Apply scaffold
 
-## Apply
-
-Write the five answers to a tmp JSON file and feed it to the subcommand.
+Write the five answers to a tmp JSON file and call the subcommand:
 
 ```bash
 ANSWERS=$(mktemp -t np-new-project-answers.XXXXXX)
@@ -116,30 +130,28 @@ trap 'rm -f "$ANSWERS"' EXIT
 
 node -e '
   const fs = require("fs");
-  const payload = {
+  fs.writeFileSync(process.env.ANSWERS, JSON.stringify({
     project_name: process.env.ANS_PROJECT_NAME,
     core_value: process.env.ANS_CORE_VALUE,
     primary_constraints: process.env.ANS_CONSTRAINTS,
     first_milestone_name: process.env.ANS_FIRST_MS,
     first_phase_name: process.env.ANS_FIRST_PHASE,
-  };
-  fs.writeFileSync(process.env.ANSWERS, JSON.stringify(payload));
-' ANS_PROJECT_NAME="$ANS_PROJECT_NAME" ANS_CORE_VALUE="$ANS_CORE_VALUE" ANS_CONSTRAINTS="$ANS_CONSTRAINTS" ANS_FIRST_MS="$ANS_FIRST_MS" ANS_FIRST_PHASE="$ANS_FIRST_PHASE" ANSWERS="$ANSWERS"
+  }));
+' ANSWERS="$ANSWERS" \
+  ANS_PROJECT_NAME="$ANS_PROJECT_NAME" ANS_CORE_VALUE="$ANS_CORE_VALUE" \
+  ANS_CONSTRAINTS="$ANS_CONSTRAINTS" ANS_FIRST_MS="$ANS_FIRST_MS" \
+  ANS_FIRST_PHASE="$ANS_FIRST_PHASE"
 
 node np-tools.cjs init new-project --apply "$ANSWERS"
 ```
 
-We pass the answers via env → `node -e` → JSON file to keep shell
-metacharacters inert (no heredoc interpolation). The subcommand emits
-`{mode:"apply", milestoneId, firstPhaseNumber, firstPhaseSlug, created: [...]}`
-on success.
+The six discovery-related PROJECT.md fields (`project_description`,
+`domain_text`, `target_users_text`, `non_goals_text`,
+`success_criteria_text`, `strategic_decisions_text`) are written as
+`_TBD — filled by /np:discuss-project._` placeholders. Phase 2 fills them.
 
 ## Re-Init Guard
 
-When `PROJECT.md` already exists, the subcommand throws
-`project-already-initialized`. The workflow catches it and offers a
-decision:
-
 ```bash
 set +e
 node np-tools.cjs init new-project --apply "$ANSWERS"
@@ -167,38 +179,75 @@ if [ "$APPLY_STATUS" -ne 0 ]; then
 fi
 ```
 
-Default on ambiguity: abort. This workflow never deletes `.nubos-pilot/`
-without an explicit `select` answer containing `Delete`.
+## Phase 2: Project Discovery (obligatory)
 
-## Optional Commit
+Do not let the user skip this. Chain into `np:discuss-project --bootstrap`:
+
+```bash
+BOOTSTRAP=1 /np:discuss-project
+```
+
+The user answers the six adaptive discovery questions (Target Users,
+Domain, What-This-Is, Non-Goals, Success Criteria, Strategic Decisions),
+reviews proposed requirements, and ends with a fully populated PROJECT.md.
+
+If the user tries to exit mid-discovery, warn:
+
+```
+PROJECT.md still has _TBD placeholders. Downstream phases will treat
+the project as under-specified. Continue discovery? (yes / no, I will
+finish later)
+```
+
+Record the skip in STATE.md so the next `np:next` reminds the user.
 
-When `config.commit_docs` is true, commit the scaffold. Use `execFileSync`
-arg arrays (no shell-string concatenation) — see Phase 3 D-03 docs.
+## Phase 3 (conditional): Initial Codebase Scan
+
+If Phase 0 reported `file_count > 0` with code files (not only manifests
+and docs), offer to run the initial scan now:
+
+```bash
+RUN_SCAN=$(node np-tools.cjs askuser --json '{
+  "type": "confirm",
+  "prompt": "Run initial codebase scan now (np:scan-codebase)?",
+  "default": true
+}')
+
+if [[ "$RUN_SCAN" == "true" ]]; then
+  /np:scan-codebase
+fi
+```
+
+Empty workspaces skip this cleanly.
+
+## Optional Commit
 
 ```bash
 if [ "$(node np-tools.cjs config-get workflow.commit_docs 2>/dev/null)" = "true" ]; then
   git add .nubos-pilot/
-  git commit -m "chore: np:new-project scaffold"
+  git commit -m "chore: np:new-project scaffold + discovery"
 fi
 ```
 
 ## Output
 
-On success, print a summary block and point the user at `np:next`:
-
 ```
 np:new-project complete.
 
 Created:
-  .nubos-pilot/PROJECT.md
+  .nubos-pilot/PROJECT.md             (populated by discovery)
   .nubos-pilot/REQUIREMENTS.md
   .nubos-pilot/roadmap.yaml
   .nubos-pilot/ROADMAP.md
   .nubos-pilot/STATE.md
   .nubos-pilot/phases/01-<slug>/01-CONTEXT.md
+  .nubos-pilot/codebase/               (if initial scan ran)
 
-Next: run `np:next` to resume, or edit REQUIREMENTS.md before discussing
-the first phase with `np:discuss-phase 1`.
+Milestone: <milestoneId> · Phase 1: <firstPhaseSlug>
+
+Next:
+  - /np:discuss-phase 1 to scope the first phase
+  - /np:update-docs after any code change (agents will do this automatically)
 ```
 
 ## Errors
@@ -208,6 +257,4 @@ the first phase with `np:discuss-phase 1`.
 | `project-already-initialized` | `PROJECT.md` exists | Abort or re-run with destructive option |
 | `invalid-slug` | milestone/phase name has no `[a-z0-9]` content | Re-run with a different name |
 | `answers-missing-field` | empty answer | Re-run and fill all 5 fields |
-
-All errors propagate from the subcommand as `NubosPilotError` with a
-stable `code` — workflow consumers can script against them.
+| `discuss-project-bootstrap-requires-project` | Discovery invoked before scaffold | Restart workflow |

package/workflows/scan-codebase.md

@@ -0,0 +1,155 @@
+---
+command: np:scan-codebase
+description: Initial deep codebase scan — inventories files, groups them into coherent modules, writes skill-style docs under .nubos-pilot/codebase/ that dev-agents must read before touching code.
+---
+
+# np:scan-codebase
+
+Perform the initial codebase scan for a project. Produces a full set of
+module docs under `.nubos-pilot/codebase/modules/`, an `INDEX.md` pointer
+file, a `.hashes.json` manifest for staleness tracking, and a
+`.doc-index.json` mapping of doc → source paths.
+
+Dev-agents (executor, code-fixer, planner, researcher, documenter, custom)
+MUST read `INDEX.md` + any relevant module docs before modifying code, and
+MUST call `np:update-docs` after changes.
+
+## Philosophy
+
+<philosophy>
+The codebase doc layer is the shared memory of every agent working in the
+project. If it is empty or stale, each agent re-derives context from raw
+source, burns tokens, and can drift. This workflow pays the one-time cost
+of a deep inventory, hybrid-parser-plus-documenter-agent pass so that every
+subsequent agent starts informed.
+
+Nothing in this workflow is Claude-specific. The subcommand returns
+module-facts JSON, the documenter agent is a prompt that any orchestrator
+(Claude Code, OpenAI, Codex) can dispatch. Stay runtime-agnostic.
+</philosophy>
+
+## Scope Guardrail
+
+<scope_guardrail>
+This workflow ONLY writes inside `.nubos-pilot/codebase/`. It NEVER:
+
+- modifies application source code
+- touches PROJECT.md, REQUIREMENTS.md, or roadmap.yaml
+- runs git commands beyond read-only `git log` via the scanner
+- spawns network calls outside the documenter agent's own tool surface
+
+Refuse and report if any of these boundaries would be crossed.
+</scope_guardrail>
+
+## Downstream Awareness
+
+<downstream_awareness>
+- `np:update-docs` reads `.doc-index.json` + `.hashes.json` to diff.
+- Every `np:execute-*` workflow's post-step calls `np:update-docs`.
+- Every np-agent is instructed to read `.nubos-pilot/codebase/INDEX.md` and
+  relevant module docs before editing source.
+
+If this workflow produces malformed INDEX.md or unreadable frontmatter,
+every downstream agent degrades silently. Validate the written files at the
+end.
+</downstream_awareness>
+
+## Single-Call Init
+
+Scan, group, write manifest + stubs, emit module-facts in one call:
+
+```bash
+PLAN=$(node np-tools.cjs scan-codebase --project-name "$PROJECT_NAME")
+if [[ "$PLAN" == @file:* ]]; then PLAN=$(cat "${PLAN#@file:}"); fi
+```
+
+`--project-name` is optional; when provided it goes into `INDEX.md`. Other
+flags: `--batch-size N` (default 500), `--max-files N`.
+
+Parse: `mode`, `stats`, `modules[]` (each with `id`, `directory`,
+`primary_language`, `file_count`, `facts`), `index_path`, `manifest_path`.
+
+## Process
+
+### Step 1: Confirm scan scope with the user
+
+Show a summary before iterating modules:
+
+```
+Scan complete.
+- Files walked: <stats.file_count>
+- Hashed: <stats.hashed_count>
+- Languages: <top 3 by count>
+- Modules discovered: <modules.length>
+- Manifests captured: <manifests.length> (package.json, …)
+
+Generate doc prose for all <N> modules? (yes / pick subset)
+```
+
+Large codebases may warrant a subset pass. Honor the user's choice — do
+not blast through 500 agent calls without consent.
+
+### Step 2: For each selected module, dispatch the documenter
+
+Per module, build the prompt from `facts` and dispatch the documenter
+subagent. The subagent is defined in `agents/np-codebase-documenter.md` and
+is runtime-agnostic — pick whichever dispatch mechanism your host supports.
+
+```bash
+PROSE_FILE=$(mktemp -t np-prose-XXXXXX.json)
+# Host dispatches agent with buildDocumenterPrompt(facts) and writes JSON
+# to $PROSE_FILE. Validate JSON before proceeding.
+python -c 'import json,sys; json.load(open(sys.argv[1]))' "$PROSE_FILE"
+```
+
+Batch pacing: the user opted into batches during Step 1. Between batches,
+show a progress line (`[37/120 modules documented]`) and give the user a
+chance to pause with Ctrl-C. Never eat interrupt signals.
+
+### Step 3: Apply prose per module
+
+```bash
+node np-tools.cjs scan-codebase --apply-prose \
+  --module "$MODULE_ID" \
+  --prose-file "$PROSE_FILE"
+```
+
+The subcommand re-reads the module's source hashes (handles files that
+changed between scan and apply), merges the prose, and atomically writes
+`modules/<id>.md`.
+
+### Step 4: Validate written artifacts
+
+Before declaring success:
+
+```bash
+test -f .nubos-pilot/codebase/INDEX.md
+test -f .nubos-pilot/codebase/.hashes.json
+test -f .nubos-pilot/codebase/.doc-index.json
+ls .nubos-pilot/codebase/modules/ | wc -l
+```
+
+Warn if a module doc is still `_TBD_` — user may have opted out mid-run.
+
+## Output
+
+```
+np:scan-codebase complete.
+
+Indexed: .nubos-pilot/codebase/INDEX.md
+Modules: <N> (documented: <M>, stubs only: <N-M>)
+Manifest: .nubos-pilot/codebase/.hashes.json
+
+Dev-agents will now read INDEX.md + relevant module docs before editing.
+Next change → np:update-docs runs automatically from np:execute-* workflows.
+```
+
+## Errors
+
+| Code | Trigger | User action |
+|------|---------|-------------|
+| `scan-codebase-not-initialized` | `.nubos-pilot/` missing | Run `np:new-project` first |
+| `scan-codebase-missing-module` | `--apply-prose` without `--module` | Supply flag |
+| `scan-codebase-missing-prose` | `--apply-prose` without `--prose-file` | Supply flag |
+| `scan-codebase-module-not-found` | id does not exist in current scan | Re-list via default mode |
+| `scan-codebase-prose-unreadable` | prose JSON unreadable or invalid | Fix JSON; re-dispatch agent |