---
name: Scan - Extract via the extract-doc CLI
description: Run extract-doc to locate the real page, detect chart types, and extract endpoints / business rules / entity props
next_step: step-02-generate.md
---

## STEP 01: Scan — run the `extract-doc` CLI

### Purpose

Gather the data needed for generation **deterministically** via the colocated
`extract-doc` CLI, instead of parsing controllers/entities by hand. The CLI is
read-only (writes nothing) and returns a JSON report.

### Run it

```bash
npx --prefer-offline tsx skills/documentation/cli/extract-doc/index.ts \
  --spec '{"type":"user","target":"<module>","application":"<app>","projectPath":"<project-root>"}'
```

- Optional `"pagePath":"<relative .tsx>"` — force a specific page (skip auto-detection) when you already know which page to document.
- `<project-root>` is the SmartStack project being documented (its layers are auto-detected — no hardcoded `SmartStack.*` paths).

> **Windows note:** PowerShell mangles the inline JSON quotes when calling `npx`.
> Invoke through the Bash tool (single-quoted JSON passes literally) or escape
> every `"` as `\"`.

### Read the `report`

| Field | Use |
|-------|-----|
| `resolved.pageTsxPath` | **READ this file** and reproduce it faithfully as annotated Mock UI (do NOT invent a generic table/KPI layout). If `null`, author from the live app / pagespec. |
| `resolved.pageCandidatesTried` | Other pages that matched — pick a different one via `pagePath` if the auto-pick is wrong. |
| `charts[]` | For each chart, `mockUiPattern` tells you the faithful Mock UI shape (recharts type → histogram / donut / line / area). `rechartsType: null` = inspect the source yourself. |
| `apiEndpoints[]` | Real endpoints (method, path, handler, resolved permission) for the Technical Reference section. |
| `businessRules[]` | Domain guard rules (deduped) — raw material; **curate**, don't dump verbatim. |
| `entity.properties[]` | Drives realistic form fields / table columns / mock records. |
| `namespace`, `navRoute`, `suggestedRoutes` | Feed these into `scaffold-doc` in step-03. |
| `existingDoc.forbiddenSections[]` | **Forbidden "sales" framing already in the EXISTING doc** (problème/solution, Bénéfices, Avant/Après) — each `{ file, line, token }`. **Non-empty → you MUST strip these while regenerating** (step-02). The step-03 gate re-runs this scan and blocks until empty. |
| `existingDoc.missingRequired[]` | **Mandatory elements ABSENT from the EXISTING doc** (the mirror check). `"objective"` = no Objectif Section 1; `"summary"` (user) = no header accent tagline. **Non-empty → you MUST add them while regenerating** (step-02). The step-03 gate blocks until empty. |

### developer / database / testing types

`extract-doc` returns a thin report for these (they are authored from tool /
schema knowledge, not project code). Gather as before:
- **database** — read `…/Persistence/Configurations/*.cs` + the model snapshot for tables/relationships.
- **developer / testing** — tool docs (WebSearch for current versions), integration points, commands.

### Success metrics

- [x] `extract-doc` ran and returned `success: true`
- [x] (user) real page located and **read** before any Mock UI is written
- [x] (user) each chart's recharts type noted for faithful reproduction
- [x] endpoints + business rules + entity props captured as raw material to curate

### Next step

→ **step-02-generate.md** — author the doc content, then run `scaffold-doc`.
