feat: /onboarding — trilho de retomada no decision log + modo expresso --report-only

DOCS.md

@@ -912,7 +912,7 @@ Planning, specs and scope:
 | `/quick "small change"` | Triage: SIMPLE only when blast radius ≤ ~3 files, one obvious shape, and none of: schema/migrations, auth/permissions, payments, new dependency, new route/page, new UI component, destructive data op. SIMPLE ships in one sitting with the guardrails on + one `## Q-NNN` audit line in `ai-docs/todos/quick-log.md`; anything else routes to `/feature`/`/bug` with the reason. Never touches the roadmap. |
 | `/note "idea"` | Appends `- [ ] YYYY-MM-DD — <idea>` to `ai-docs/inbox.md` and stops — zero questions. Later `/feature`/`/quick`/`/spec` tick items with `→ spec NNNN` / `→ Q-NNN` / `→ task NN`. |
 | `/absorb [focus?]` | Onboards an EXISTING system: surveys the code, writes `map.yaml`, the as-built PRD (never overwriting a human PRD — `PRD-as-built.md` instead), `stack.md` from what was observed, `conventions.md`, the as-built component registry and a distilled project skill; short interview for what code can't reveal. Changes no code, creates no tasks; recommends `/kit` when the registry comes out empty/duplicated. |
-| `/onboarding [focus?]` | The first command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each command's own file stays the law — interviews, decision logs and approvals included), then hands over explaining `/idea` (module-sized discovery, in Pi) vs `/feature` (one-sentence delta). |
+| `/onboarding [focus?] [--report-only]` | The first command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each command's own file stays the law — interviews, decision logs and approvals included), resumable via its `onboarding` decision-log rail, then hands over explaining `/idea` (module-sized discovery, in Pi) vs `/feature` (one-sentence delta). `--report-only` defers the `/kit` decisions to a later run. |
 
 Design system and references:
 
@@ -1483,6 +1483,12 @@ Shared conventions between the harness (Claude Code/Cursor) and Pi, all under
   history. Commands read the recent logs before interviewing and never re-ask
   a decided question. The log preserves the interview; the artifact
   (PRD/spec/manifest) stays the source of truth for WHAT was decided.
+  `/onboarding` uses the same script as a **resume rail** rather than an
+  interview log: `open onboarding` when the tour starts, one
+  `note <id> --text "stage <name>: …"` per completed stage, `close` at the
+  wrap-up — `latest onboarding --json` finding an `open` log is how an
+  interrupted tour resumes from its last stage note (never `open` again
+  mid-tour: that would supersede the trail).
 - **Stack research** — `ai-docs/research/<tech>.md`: before `/stack` documents
   or equips a technology, it must research FOUR dimensions — docs
   (+ `llms.txt`), agent skills (skills.sh registry), official CLI, official
@@ -1703,7 +1709,7 @@ theme, design, examples, launch, update_roster.
 | `/design` | `images + scope` | Layout redesign from references — structure from the image, identity from OUR system. |
 | `/example` | `URL [notes] \| list` | Register an external reference on the shelf (license researched, `What NOT to take` mandatory). |
 | `/agents` | — | Opens the viewer's Agents tab (`npm run agents -- --detach`) to edit engines/models/fallbacks; Pi is forbidden from editing `imp/fia.config.yaml` itself. |
-| `/onboarding` | `[focus?]` | First command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each stage's own prompt is the law; stages whose artifacts already exist can be kept and skipped), then hands over explaining the split — `/idea` for a MODULE-sized addition vs `/feature` for a one-sentence delta. |
+| `/onboarding` | `[focus?] [--report-only]` | First command on an EXISTING system: chains `/absorb` → `/stack` → `/kit` in one guided pass (each stage's own prompt is the law; stages whose artifacts already exist can be kept and skipped), then hands over explaining the split — `/idea` for a MODULE-sized addition vs `/feature` for a one-sentence delta. The tour keeps a **resume rail** in the decision log (`open onboarding` → one stage note each → `close`): an interrupted session resumes from its last stage note instead of restarting. `--report-only` is the express path — the `/kit` stage presents its gap report and defers the design decisions to a later `/kit` run. |
 | `/absorb` | `[focus?]` | Brownfield onboarding (as-built PRD/map/conventions/registry + project skill in `.pi/skills/project/` AND `.claude/skills/project/`); recommends `/kit` when the registry comes out empty/duplicated. |
 | `/kit` | `[focus?] [--report-only]` | Brownfield design-system audit → gap report → approved design-only tasks. |
 | `/status` | — | Read-only progress: tasks, milestones (status as declared), specs, inbox, latest runs and failed phases. |

README.md

@@ -134,7 +134,7 @@ imp handoff                    # continue the newest Pi conversation in `claude`
 | `/bug "the symptom"` | Records the defect, proves a valid failing test first (RED), then fixes it. |
 | `/quick "small change"` | Triage: a genuinely small change ships in one sitting; anything bigger routes to `/feature` or `/bug`. |
 | `/spec [capability]` | Durable spec — requirements + BDD scenarios + traceability gates. |
-| `/onboarding [focus?]` | Existing project, first run: chains `/absorb` → `/stack` → `/kit` in one guided pass — ends ready for `/idea` or `/feature`. |
+| `/onboarding [focus?] [--report-only]` | Existing project, first run: chains `/absorb` → `/stack` → `/kit` in one guided pass — ends ready for `/idea` or `/feature`. Interrupted tours resume where they stopped; `--report-only` defers the design-system decisions. |
 | `/absorb [focus]` | Existing project → as-built PRD, map, conventions, stack manifest and component registry. |
 | `/kit` | Design-system audit of existing code: as-built registry, gap report, design-only tasks. |
 | `/component`, `/theme`, `/design`, `/example` | Design system: add a component, change colors/fonts, redesign from references, register an external reference. |

pi-templates/.pi/prompts/onboarding.md

@@ -1,6 +1,6 @@
 ---
 description: First command on an EXISTING system — /absorb → /stack → /kit in one guided pass, ending ready for /idea or /feature
-argument-hint: "[optional focus, e.g. only the sales module]"
+argument-hint: "[optional focus] [--report-only]"
 ---
 Read `.pi/skills/fia/SKILL.md`. This is the ONE command to run right after
 installing on an EXISTING system: it chains the three brownfield onboarding
@@ -9,13 +9,25 @@ the sequence — each stage's own prompt is the law: follow it to the letter
 (interviews, decision logs, approvals included). NEVER change product code
 here (the only exception is /kit's `/ui-components` page, per its own prompt).
 
-Focus (optional, passed to the /absorb stage): $@
+Focus/flags (optional; the focus goes to the /absorb stage): $@
 
-0. **Guard + announce** — run `node imp/scripts/project-mode.mjs --json` and
-   trust it. Not `brownfield` → stop: there is nothing to absorb; route in one
-   line — no PRD yet → /idea (discover the product), PRD exists but nothing
-   built → /grill then /map. Brownfield → announce the tour: three stages,
-   what each produces, roughly what I will be asked.
+0. **Guard + resume rail + announce** — run
+   `node imp/scripts/project-mode.mjs --json` and trust it. Not `brownfield`
+   → stop: there is nothing to absorb; route in one line — no PRD yet →
+   /idea (discover the product), PRD exists but nothing built → /grill then
+   /map. Brownfield → the tour keeps a resume rail in the decision log
+   (cookbook `.pi/skills/fia/cookbooks/decision-log.md`):
+   - `node imp/scripts/decision-log.mjs latest onboarding --json` FIRST. An
+     `open` log = an interrupted tour: read its stage notes, confirm the
+     resume point with me in ONE question and KEEP that log id — a new
+     `open` would supersede the trail. No open log →
+     `open onboarding --topic "brownfield onboarding tour"`.
+   - After EACH stage lands: `note <id> --text "stage <absorb|stack|kit>:
+     done|skipped|report-only (<one line>)"` — that note trail is exactly
+     what a resumed tour reads.
+   Then announce the tour: three stages, what each produces, roughly what I
+   will be asked — and, on a large codebase, that this is a long session
+   (`--report-only` is the express path: the /kit decisions are deferred).
 1. **Absorb** — follow `.pi/prompts/absorb.md`: as-built PRD, `ai-docs/map.yaml`,
    conventions, stack manifest, component registry and the project skill. If
    `ai-docs/map.yaml` AND the as-built PRD already exist, show what is there
@@ -24,13 +36,18 @@ Focus (optional, passed to the /absorb stage): $@
    still "decide later", run the mandatory research, write
    `ai-docs/apis/<tech>.md` for each technology in use and equip the project
    (skills, CLIs, MCPs).
-3. **Kit** — follow `.pi/prompts/kit.md`: as-built registry + `/ui-components`
-   page, gap report vs the core kit, and ONLY engineer-approved design-only
-   tasks — "nothing approved" is a valid outcome; approved tasks run later via
-   /task or /goal.
-4. **Wrap-up** (mandatory) — recap the three stages in one line each (artifact
-   paths), then hand over — the system now behaves like a project "with a
-   PRD". Explain the split:
+3. **Kit** — follow `.pi/prompts/kit.md`, passing `--report-only` through
+   when I gave it (express mode: the gap report is presented and the design
+   decisions are deferred — running /kit later picks them up). Full mode:
+   as-built registry + `/ui-components` page, gap report vs the core kit,
+   and ONLY engineer-approved design-only tasks — "nothing approved" is a
+   valid outcome; approved tasks run later via /task or /goal.
+4. **Wrap-up** (mandatory) — recap the three stages in one line each
+   (artifact paths), then close the rail:
+   `close <id> --outcome "<stages done/skipped/deferred>"
+   --artifact ai-docs/PRD.md --artifact ai-docs/stack.md` and commit the
+   docs per the cookbook. Then hand over — the system now behaves like a
+   project "with a PRD". Explain the split:
    - `/idea "<module>"` — something MODULE-sized: a new area of the product
      (new actor, new data domain, several screens). Deep interview → a
      `## Module: <name>` chapter appended to the PRD; /feature then turns it
@@ -40,5 +57,5 @@ Focus (optional, passed to the /absorb stage): $@
      tasks, shown for my approval before anything runs.
    Rule of thumb: can't describe it in one sentence → /idea; otherwise
    /feature. (Defect → /bug; tiny change → /quick.)
-   A stage was skipped or /kit tasks were approved → say what is pending and
-   the command that resumes it.
+   A stage was skipped, /kit ran report-only or /kit tasks were approved →
+   say what is pending and the command that resumes it.

pi-templates/.pi/skills/fia/SKILL.md

@@ -46,7 +46,7 @@ Short commands (prompt templates in `.pi/prompts/`) are the student entry points
 | `/design [images]` | layout redesign from references, inside the design system | design |
 | `/example [URL or slug]` | register an external reference (repo, code, docs, design) on the examples shelf | examples |
 | `/agents` | visual roster editor — engines, models, fallbacks (viewer "Agents" tab) | update_roster |
-| `/onboarding [focus?]` | first command on an existing system — chains /absorb → /stack → /kit in one guided pass, ends ready for /idea or /feature | — |
+| `/onboarding [focus?] [--report-only]` | first command on an existing system — chains /absorb → /stack → /kit in one guided pass (resumable via its decision-log rail; `--report-only` defers the kit decisions), ends ready for /idea or /feature | decision-log |
 | `/absorb [focus]` | existing project → as-built PRD + map + conventions + stack manifest + component registry | — |
 | `/kit` | existing code → design-system audit: as-built registry + `/ui-components`, gap report vs the core kit, approved design-only tasks (`Kind: kit`) | components |
 | `/status` | progress + latest runs | observability |

pi-templates/.pi/skills/fia/cookbooks/decision-log.md

@@ -56,6 +56,13 @@ The log NEVER replaces the artifact — the PRD/spec/manifest remains the source
 of truth for WHAT was decided; the log preserves the interview itself (question,
 recommendation, answer) for audit and reuse.
 
+`/onboarding` uses the same script as a **resume rail** rather than an
+interview log: `open onboarding` when the tour starts, one `note <id> --text
+"stage <name>: done|skipped|report-only (…)"` after each stage, `close` at the
+wrap-up. `latest onboarding --json` is how an interrupted tour finds where it
+stopped — an `open` log means resume from its last stage note; never `open`
+again mid-tour (that would supersede the trail).
+
 ## Reading it back
 
 - `latest <command> [--json]` — most recent run of a command.