@techierathore/techieflow 1.0.0

package/.tfcore/tasks/day1-greenfield.md

@@ -0,0 +1,224 @@
+# day1-greenfield
+
+Day-1 master task for a GREENFIELD (new) project. Produces all day-1 deliverables in a single session: target Architecture + BRD + **UI mockups** + Coding Standards + .editorconfig + PROJECT-STATUS + CLAUDE.md + UsageGuide.
+
+## Purpose
+
+Replace the multi-step paste-and-substitute prompt with a single command: `*day1-greenfield {AppName}`. For new projects there's no existing code to reverse-doc; instead the analyst takes a free-form concept (sentence, paragraph, bullets — whatever the user has, even half-baked) and proposes a target architecture + BRD in bulk.
+
+## elicit
+
+elicit=false (after at most a 3-question kickoff). The task asks ONLY for `{AppName}` (if missing), the concept (any length), and optional custom instructions / source-doc hints — then drafts every artifact (including the full BRD) in one pass and presents them for one-shot review. NO per-section confirmation. NO per-requirement confirmation.
+
+## Inputs
+
+- `{AppName}` argument (required). PascalCase, no spaces.
+- `{Concept}` — free-form description of the app. **Any length** — single sentence, multiple paragraphs, bulleted list of features, half-baked stream-of-thought notes, mockup descriptions, "kind of like X but with Y" comparisons. The more the user puts in, the better the first-pass BRD. The analyst MUST NOT cap or summarize the user's input — read all of it and use it as the primary source.
+- `{Hints}` — OPTIONAL. Free-form text containing any combination of:
+  - Paths to existing concept docs, mockups, requirement notes, competitor analyses, napkin sketches converted to text, etc. that should be HARVESTED into the BRD/Architecture.
+  - Custom drafting instructions (e.g. "use Blazor WebAssembly not Server", "skip the auth section, this is internal-only", "make it mobile-first", "include offline mode in NFR").
+- If `{AppName}` missing: ask once. Then ask once: "Describe the app concept — any length is fine. Sentence, paragraph, bullets, half-baked notes, comparisons to other apps. The more you give, the better the first-pass draft. (No need to be polished; you'll edit the doc afterwards.)" Then ask once (optional): "Any existing notes/mockups/docs to harvest, or specific drafting instructions (stack overrides, scope limits, etc.)? Paths/notes, or `none`."
+- All templates live at `.tfcore/templates/v4custom/` in THIS project. Read them with relative paths. Do NOT look outside the project for templates.
+
+## SEQUENTIAL Execution
+
+### 1. Resolve app name + concept + hints + persist config
+
+- Capture `{AppName}`, `{Concept}` (full, untruncated), and `{Hints}` (may be empty).
+- Parse `{Hints}` the same way day1-brownfield §1.5 does: paths/globs → `SourceDocs[]` (Read each), instructions → `CustomInstructions` text blob, `none`/empty → both empty.
+- **Collision policy:** apply day1-brownfield §1.6 verbatim — every deliverable written fresh at its canonical name; any pre-existing version moves to `docs/OldDocs/` (created if missing, date-suffixed on collision); superseded source docs move there after harvesting; NEVER ask merge-vs-new; NEVER write `-v2`-style variants.
+- Update `.tfcore/core-config.yaml` with the `customTechnicalDocuments` paths AND the `devLoadAlwaysFiles` list exactly as in day1-brownfield §1.
+
+### 2. Propose target architecture → `docs/{AppName}-Architecture.md`
+
+- Load `.tfcore/templates/v4custom/app-architecture-tmpl.md` as the structural template.
+- Status field: "Target" (this is greenfield).
+- **Input priority for every section:**
+  1. **`SourceDocs[]`** from §1 (if any) — harvest verbatim where they speak to stack, components, or flows.
+  2. **`{Concept}`** — the user's own description is authoritative for goals and feature scope.
+  3. **`CustomInstructions`** — overrides defaults (stack, scope, NFR).
+  4. **Defaults below** — only when 1–3 are silent on a given choice.
+- Pick stack defaults unless the concept or `CustomInstructions` imply otherwise:
+  - Runtime: .NET 9
+  - UI: Blazor Server with TrBlazeUI (so /trblazeui is in scope)
+  - DB: SQLite for dev, configurable per env
+  - Vector store: SqliteVec for dev (only if RAG/AI is implied by the concept)
+  - Auth: cookie auth for MVP, JWT for API tier if API is in scope
+- Populate Mermaid diagrams (component map, primary user journey, deployment) from the concept and any source docs. The richer the concept, the richer the diagrams — a 5-bullet feature list should produce a 5-component diagram, not a 2-box generic placeholder.
+- **Depth mandate (Architecture is a HUMAN document):** if `SourceDocs[]` exist, apply the information-preservation rule — their architecture content carries forward, never gets summarized into a stub. Each non-trivial module in §4 gets a short prose paragraph (not just a table row), and any significant runtime flow beyond the primary path (background jobs, ingestion pipelines, auth handshakes, external-API round-trips) gets its own `sequenceDiagram` or `flowchart`. A reader skimming only the diagrams should grasp how the system hangs together.
+- Seed §7 ADRs with: `ADR-001 — {chosen UI host}`, `ADR-002 — {chosen DB}`, `ADR-003 — {chosen vector store, if RAG}` — each with a one-line reason that cites the concept/CustomInstructions when relevant.
+- **Table of Contents:** the template at `.tfcore/templates/v4custom/app-architecture-tmpl.md` ships with a `## Table of Contents` section. After drafting, regenerate that section to match the actual H2 headings you wrote. Use the slug rule from `.tfcore/templates/v4custom/html-render-shell.md §1` so the links work in both MD and the rendered HTML.
+- Write to `docs/{AppName}-Architecture.md`. Do NOT prompt the user mid-draft.
+
+### 3. Draft the FULL BRD in one pass → `docs/{AppName}-BRD.md`
+
+**Do NOT run `author-brd`. Do NOT prompt per section.**
+
+- Load `.tfcore/templates/v4custom/app-brd-tmpl.md`.
+- Derive content from (priority order):
+  1. **`SourceDocs[]`** from §1 — harvest goals, audience, features verbatim where the source docs speak to them. Cite the source file inline (e.g. `BRD-3 — From design-notes.md §2`).
+  2. **`{Concept}`** — this is the user's primary input. Mine it for every feature, actor, and constraint mentioned. If the concept is a bullet list, each bullet probably maps to one or more BRDs. If it's a paragraph, parse sentences for "users should be able to …" / "the app needs to …" patterns.
+  3. The target architecture (§2) — every component implies functional requirements.
+  4. **`CustomInstructions`** — apply throughout (scope limits, stack overrides, NFR additions).
+  5. Reasonable inference for sections still empty. Mark inferred items with `<!-- inferred — please verify -->` HTML comments so the user can scan and confirm.
+- **INFORMATION-PRESERVATION RULE (when SourceDocs exist):** the BRD must be a SUPERSET of the requirements content in the harvested docs — never a summary. Tables, matrices, screen lists, persona detail, and per-feature workflows carry forward (updated, attributed), not compressed into one-liners. Length sanity check: a draft under ~60% of the source docs' requirements content means you compressed — go back and restore the detail. One-line statements are allowed ONLY in the §10 ledger; this is a HUMAN document read as rendered HTML (the coding agents get their compact view later from `*split-brd` / the Checklist).
+- **§4 Development status (greenfield: this is the build ROADMAP):** fill the §4 table with one row per §9 feature-catalog F-code. Nothing is built yet, so every row is `Planned`, `0%`, with its target Phase (and a one-line Notes scope). Set the "Snapshot as of" date to today. As build phases complete later, the live status lives in PROJECT-STATUS + the checklists; this table stays the human roadmap view.
+- **§9 Feature catalog (the heart of the doc):** one `### F-{CODE}: {Name}` subsection per feature/capability area implied by the concept and source docs. Per feature: personas + phase, 1-2 paragraphs of what/why, a screens & routes table (proposed, for greenfield), a numbered workflow (inputs → outputs), and the owning BRD-N IDs. Depth scales with the concept — a rich concept should yield 8–25 features; there is NO cap. Every F-code MUST also appear as a row in the §4 Development status table.
+- For §10 Functional requirements ledger: walk the feature catalog and emit `BRD-1`, `BRD-2`, … as one-line `<actor> can <action>` statements, each tagged `(F-CODE)`. **One BRD per discrete capability — the count scales with the concept; NEVER merge capabilities to keep the count low.** Suffix BRDs pulled directly from a source doc with `<!-- from: <source-file> -->`.
+- For §11 Non-functional: cover performance, security, accessibility, auth model — derived from the stack you chose in §2 and from any NFR signals in the concept or CustomInstructions. Present concrete targets (latency, uptime, concurrency) as a target table. **ALWAYS include the standing Observability NFR: Serilog file-based logging (rolling file sink under `logs/`) in EVERY executable head — web, API, MAUI, desktop, console, background service — no exceptions and no owner prompt needed** (the wiring recipe lives in the coding-standards §Logging block; `*split-brd` turns this BRD into a `REQ-NFR-*` row so the build phase implements it like any other requirement).
+- **Mermaid mandate:** the three canonical diagrams (context, user journey, component sketch — copied from the architecture, adapted to BRD framing) are the MINIMUM. Every feature-catalog entry with a multi-step or multi-actor flow gets its own diagram. Simple CRUD features may skip it. **Every diagram MUST follow the authoring rules in `.tfcore/templates/v4custom/html-render-shell.md §5.5` — quote every node/edge/subgraph label and never use `end` as a node id; unquoted special characters in flowchart labels are the #1 cause of broken diagrams in the rendered HTML.**
+- Append footer with `Highest BRD ID: BRD-{N}`, a `Sources harvested:` line, a `Custom instructions applied:` line, and the note: "First-pass draft from concept — review and edit. New BRDs may be added (append-only); do not renumber existing IDs."
+- **Table of Contents:** the BRD template includes a `## Table of Contents` section. Regenerate it to match the actual H2 headings, and list each `### F-…` feature-catalog entry as an H3 sub-entry under "Feature catalog". Use the slug rule from `.tfcore/templates/v4custom/html-render-shell.md §1`.
+
+### 3.5. Migrate an existing development/phase plan → split requirement docs (CONDITIONAL)
+
+If `SourceDocs[]` includes a phased plan / roadmap (`*Development-Plan*.md`, `*Roadmap*.md`, or content structured as Phase 0/1/2… with build order/statuses), do NOT leave the BRD split as a separate step. Follow day1-brownfield §3.5 exactly: execute `.tfcore/tasks/split-brd.md` inline, seed the one checklist `docs/{AppName}-Checklist.md` with the plan's phase tags and any pre-marked completions (`Done (pre-existing)` + evidence pointer), header-note the migration, and — per the §1 collision policy — move the now-superseded plan file unchanged to `docs/OldDocs/` (date-suffix on name collision). If no such plan exists, SKIP — the user runs `*split-brd {AppName}` after reviewing the BRD and mockups.
+
+### 3.6. Create UI mockups (greenfield UI design — the build's visual contract)
+
+Greenfield has no code, so the UI is built freehand unless there's a design to build against — that is exactly why a new app's UI ends up broken. Produce **TrBlazeUI-replicable mockups** now so the build (and the verifier's visual-truth gate) have a baseline.
+
+Run `.tfcore/tasks/mockups.md` for `{AppName}` end-to-end: it reads the trblazeui component catalog FIRST (so it designs only with controls that exist), then produces `docs/{AppName}-UIDesign.md` (the per-screen UI Design Spec with a `region → TrBlazeUI control` component map) + rendered `docs/mockups/*.html` (styled to look like TrBlazeUI), one per key screen from the BRD §9 feature catalog. These are the design `/trblazeui` builds from and the image the verifier diffs the live screen against.
+
+The mockups are part of the day-1 review (§8) — the owner approves them alongside the BRD and Architecture before any build. (If the concept is purely an API/no-UI app, `mockups.md` self-detects "no screens" and records "skipped — no UI"; that is not an error.)
+
+### 4. Create the Coding Standards → `docs/{AppName}-Coding-Standards.md`
+
+Use the exact template content embedded in `day1-brownfield.md` §4 (the canonical block), including its one per-project decision: the instance-field prefix. Greenfield has no existing code to detect from, so default to `obj` unless `CustomInstructions` pick no-prefix. Record the decision in the standards file and CLAUDE.md per §4's instructions.
+
+### 5. Create `.editorconfig` at repo root
+
+Copy `.tfcore/templates/v4custom/app-editorconfig-tmpl.editorconfig` verbatim. No substitution.
+
+### 5b. Close the `.gitignore` on the stack you just chose (MANDATORY)
+
+```bash
+bash .tfcore/utils/tf-gitignore-audit.sh . --fix
+```
+
+**Run it here, in this step, and read the output.** The scaffold wrote a `.gitignore`
+covering **TechieFlow's** artifacts — `.tfcore/`, `.claude/`, `node_modules/`,
+`tests/.artifacts/`, `playwright-report/`, `logs/` — every section framework-managed
+and labelled as such. It says **nothing** about the stack, because at scaffold time
+nobody had chosen one. **You just did.** You picked the stack, wrote it into
+`core-config.yaml` and generated the solution; you are the only step that knows the
+answer, and the file the scaffold left is complete-looking enough to be read as
+finished.
+
+That is exactly how it went wrong once (TfLens TF-007, 2026-08-29): a repository whose
+`core-config.yaml` and four `.csproj` files said .NET throughout carried an ignore file
+with **no `bin/`, no `obj/`, and no rule of any kind for .NET**. The first build produced
+output and one commit — named, with some irony, *"Updated git ignore"* — swept **1,041**
+build-output files into the index; four later commits reached **1,962**. Those files carry
+the static-web-assets manifest, whose content roots are **machine-absolute** (`/mnt/c/…`
+after a WSL build, `C:\…` after a Windows one), so committing them ships one machine's
+paths to another — a plausible route to precisely the asset 404 that TF-007 is about.
+
+**The agent that ran day-1 generated that file and did not read it. That agent was
+responsible**, and the audit exists to make the mistake harder rather than to move the
+blame — a generator's omission is not a defence for the agent operating the generator.
+
+Two outputs, and the second one is the one people miss:
+
+- **Missing rules** — `--fix` appends them under their own labelled header. Existing
+  owner content is never rewritten.
+- **Build output that is ALREADY TRACKED** — reported, never fixed here. **A tracked file
+  is never ignored, whatever the ignore file says**, so adding the rule does nothing on
+  its own. The audit prints the exact `git rm -r --cached <path>` lines; **put them in
+  your §8 summary for the owner to run.** Agents never run git, in any mode.
+
+### 6. Create `PROJECT-STATUS.md`
+
+Load `.tfcore/templates/v4custom/app-project-status-tmpl.md` and substitute:
+- `{AppName}` everywhere
+- `{YYYY-MM-DD}` → today
+- `stack:` line → from §2's choices
+- `current_phase:` → `Discovery`
+- `last_verified_build:` → if a `.csproj`/`.sln` exists, run the build using the **invocation ladder** at `.tfcore/templates/v4custom/build-invocation-ladder.md`. Follow the same MANDATORY workflow as day1-brownfield §6:
+  - Solution-scan first (check each .csproj for MAUI/iOS/Android targets).
+  - Solution containing ANY MAUI/iOS/Android project → start at rung #4.
+  - Workload-missing errors (`NETSDK1178`, etc.) are wrong-rung signals — switch rungs, don't log as blocker.
+  - BANNED Known-blocker entries: "MAUI build cannot run on WSL", "iOS/Android workload missing", "dotnet not in PATH" — see the ladder doc.
+  - Record `PASS`/`FAIL`/`not-run` per the ladder.
+  - If no project file exists yet (pure scaffolding), record `not-run` with a Known blocker: "No .csproj/.sln yet — create the solution before next phase." (This IS a real blocker.)
+- **Where I am:** one paragraph summarizing the concept and the chosen stack/architecture.
+- **Next command to run:** HTML is rendered by this task itself (§7.5) — point at the real next step: `/TechieFlow:agents:analyst *split-brd {AppName}` (OpenCode: `/flow-analyst *split-brd {AppName}`) (or the first build-phase command if §3.5 already split).
+- **Open requirements / blockers / verification log / library feedback:** empty (initial values from the template).
+
+### 7. Create `AGENTS.md` (the harness-neutral session memory — both harnesses load it)
+
+Copy `.tfcore/templates/v4custom/app-agents-md-tmpl.md` and substitute `{AppName}` throughout; resolve the field-prefix line to this project's decision. `AGENTS.md` carries the CONTENT (required reading, hard rules, project basics, REQ prefixes, verification, slash-command table): OpenCode auto-loads it directly (and skips `CLAUDE.md` whenever an `AGENTS.md` exists); Claude Code loads it through `CLAUDE.md`'s `@AGENTS.md` import. **`AGENTS.md` is committed.** If a previous `AGENTS.md` exists, archive it per the §1 collision policy and write fresh.
+
+### 7.2. Create `CLAUDE.md` (Claude-only wrapper — imports AGENTS.md)
+
+Copy `.tfcore/templates/v4custom/app-claude-md-tmpl.md` and substitute `{AppName}` throughout. It is a thin wrapper: `@AGENTS.md` plus the Claude-only permissions/tool-preference section. `CLAUDE.md` stays gitignored as before.
+
+### 7.4. Create the Usage Guide (test users + test plan) → `docs/{AppName}-UsageGuide.md`
+
+Always create this — follow day1-brownfield §7.4, with the greenfield differences:
+- Load `.tfcore/templates/v4custom/app-usageguide-tmpl.md` and substitute `{AppName}`.
+- **Test users table:** greenfield has no DB yet, so list the *intended* test accounts — one row per actor/role named in the BRD (§9 feature catalog personas) — all `Created? = ⬜` (planned; created on first build only after confirming with the owner, per `_smoke-test-policy.md`). Do NOT create any users.
+- **Screen-by-screen test plan:** one subsection per *proposed* screen/route from the BRD §9 feature catalog's screens-and-routes tables, in navigation order, each naming the test user, the steps, the expected result, and the BRD-N it covers.
+- **Setup/Deployment + Test + Smoke + Known limitations:** fill from the chosen stack (§2) at a roadmap level; mark commands that depend on not-yet-built projects clearly. Subject to the §1 collision policy.
+
+### 7.5. Auto-render every day-1 doc to HTML — no separate render step
+
+Follow day1-brownfield §7.5 exactly: render `docs/{AppName}-BRD.md`, `docs/{AppName}-Architecture.md`, `docs/{AppName}-UsageGuide.md`, `docs/{AppName}-UIDesign.md` (the mockup spec, if §3.6 produced one), `PROJECT-STATUS.md` (no-toc + "NEXT COMMAND TO RUN" CTA box), each to its sibling `.html`, using `.tfcore/tasks/generate-html.md` with the shared shell. (`mockups.md` already rendered the `docs/mockups/*.html` screens.) **Do NOT render the checklist to HTML** — if §3.5 produced it, it stays markdown (AI-agent working document). Write tool only, no bash heredocs. The user must NEVER be told to run a render command after day-1.
+
+### 7a. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"day1-greenfield","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+### 8. HALT — summary + next-step pointer
+
+Output a numbered summary listing what was created (same shape as day1-brownfield §8, including the HTML renders). Then say:
+
+```
+Day-1 artifacts complete — MD docs AND their HTML renders are all written. Nothing left
+to run. Everything was drafted in bulk from your concept (and any source docs / custom
+instructions you provided). Review and APPROVE the human-readable docs (open the .html
+files, or edit the .md sources directly): the BRD (verify BRD-1..BRD-{N} reflect intent),
+the Architecture, AND the UI MOCKUPS (open docs/mockups/*.html + docs/{AppName}-UIDesign.md
+— this is the visual design the UI will be built to match, so flag any screen that's wrong
+NOW, before build). To change a mockup, edit the concept and re-run, or run
+*mockups {AppName} --update later.
+
+If you edit any .md afterwards, re-render just that file:
+  /generate-html @docs/{AppName}-BRD.md      (Claude Code form; in OpenCode use the plain path without @)
+
+Next workflow step (after you approve the BRD + Architecture + mockups): *split-brd {AppName}
+via /TechieFlow:agents:analyst (OpenCode: /flow-analyst) — unless this run already migrated a phased plan (§3.5), in
+which case the next step is *build-phase shown in PROJECT-STATUS.md.
+```
+
+Do NOT auto-advance past day-1 (no split/build without the user). Rendering HTML is NOT auto-advancing — it is part of day-1 (§7.5).
+
+## Output Checklist
+
+- [ ] core-config.yaml has customTechnicalDocuments for this app
+- [ ] `docs/{AppName}-Architecture.md` (status: Target) with Mermaid
+- [ ] `docs/{AppName}-BRD.md` with a §4 Development status table (one row per F-code, all `Planned` for greenfield) + a populated §9 Feature catalog (one `### F-…` per feature) + §10 BRD-N ledger + Mermaid diagrams (canonical three + per-feature where non-trivial), every diagram passing the §5.5 authoring self-check (quoted labels, no `end` ids)
+- [ ] If SourceDocs were harvested: BRD is a SUPERSET of their requirements content (no tables/detail dropped)
+- [ ] `docs/{AppName}-UIDesign.md` + `docs/mockups/*.html` produced (§3.6, TrBlazeUI-replicable, one per key screen) — or "skipped — no UI" recorded for an API-only app
+- [ ] `docs/{AppName}-Coding-Standards.md`
+- [ ] `.editorconfig`
+- [ ] `PROJECT-STATUS.md` (phase = Discovery)
+- [ ] `CLAUDE.md`
+- [ ] `AGENTS.md` (§7.2 OpenCode pointer)
+- [ ] `docs/{AppName}-UsageGuide.md` — Test-users table (all planned ⬜ for greenfield; NO users created) + screen-by-screen test plan from the BRD feature catalog
+- [ ] If a phased plan was among SourceDocs (§3.5): the one `docs/{AppName}-Checklist.md` written with phase tags and pre-existing completions — NOT left for a separate `*split-brd` run
+- [ ] Mockups presented for owner approval in the §8 review (BRD + Architecture + mockups approved before build)
+- [ ] §7.5 auto-render done: every day-1 .md deliverable has a sibling .html — the user was NOT told to run a render command
+- [ ] Summary and next-command pointer delivered
+- [ ] Did NOT prompt the user mid-task for per-section confirmation

package/.tfcore/tasks/devguide.md

@@ -0,0 +1,224 @@
+# devguide
+
+Generate (or incrementally refresh) the **screen-by-screen Developer Guide** — the human-developer document that traces every screen, control, and value from the UI down to the database (Razor page → control → service method → data-access method → stored proc / query), grouped by user role. It documents the **code as built**, so a developer can find and fix bugs and verify AI-generated code without reverse-engineering the whole repo. Its OBSERVE pass (§5a) also **captures a screenshot of every screen** (for greenfield-built and brownfield apps alike) — these images both ground the guide in runtime reality AND become the source material for the end-user **Product Guide** (`*productguide`), so the same screen inventory serves developers and future external users.
+
+Output: `docs/{AppName}-DevGuide.md` (single doc for small apps, kept directly in `docs/`) **or**, for a multi-part split (large apps), a dedicated **`docs/devguides/`** subfolder holding the index `docs/devguides/{AppName}-DevGuide.md` + one `docs/devguides/{AppName}-DevGuide-{Role}.md` per role — each rendered to a sibling `.html`. The subfolder keeps a multi-file guide from cluttering `docs/`. Template: `.tfcore/templates/v4custom/app-devguide-tmpl.md`.
+
+**Three modes — the unit you map depends on what the project IS** (a **library is a first-class TechieFlow project**: it gets the SAME full doc set as an app — PROJECT-STATUS, Checklist, Coding-Standards, this DevGuide — "it's just a library" is NOT a reason to skip status or a DevGuide):
+- **Application mode (default)** — an app with its own routable screens: map **screen-by-screen** (role → screen → control → service → data-access → proc), as the rest of this task describes.
+- **UI-component library mode** — ships **UI components** (e.g. TrBlazeUI), exercised by a bundled demo app. Map **component-by-component** (the component's `[Parameter]` API is the contract) — see **§0**.
+- **Service/SDK library mode** — ships **services/APIs** (e.g. TechieRag: `AddTechieRag(...)` + `ITechieRag`, zero shipped UI), exercised by a bundled sample app. Map **service/API-by-service** (the DI surface + public methods are the contract) — see **§0**. **Do NOT document a service library by its sample app's screens** — that documents the demo, not the package a consumer codes against.
+
+## When to use
+
+- **After a build phase** that added/changed screens, to give developers a current map (auto-run at handoff — `handoff-phase §3a`).
+- **Anytime a developer needs to chase a bug** and the BRD/Architecture/DB-design don't show the code path.
+- **Re-runnable**: regenerate after code changes. Use `--update` (or pass a `{Scope}`) to refresh only the changed screens instead of remapping everything (saves tokens — see `.tfcore/TOKEN-GUIDE.md`).
+
+This task documents code; it **never edits source**. If there is no built code yet (greenfield day-1), HALT and tell the user to build first.
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- `{Scope}` — OPTIONAL: `all` (default) · a role name · a screen/route · a comma-list of either. Limits which screens are (re)mapped.
+- `--update` — OPTIONAL flag: incremental refresh. Re-map only screens whose Razor/service/data-access files changed since the DevGuide's last generation (by file mtime vs the guide's subtitle date), or only the `{Scope}` given. Preserve every unchanged screen entry verbatim.
+- `--split` / `--single` — OPTIONAL: force the structure instead of auto-deciding (§3).
+
+## SEQUENTIAL Execution
+
+### 0. Detect the mode — application, UI-component library, or service/SDK library
+
+Before anything else, decide which mode applies. It changes the **unit** you map, not the rigor. First, is this repo a packable **library** (its product is a NuGet package, not an app)? Signs: `<IsPackable>true</IsPackable>` / a `PackageId` / `Directory.Build.props` packaging, the product lives in `src/…`, and it is exercised by a **bundled showcase under `demos/` or `samples/`** rather than being a deployable app itself. If NOT a library → **application mode** (the default — proceed to §1, screen-by-screen).
+
+If it IS a library, pick the sub-type by **what the package actually ships** (look in `src/`, not in the sample):
+
+- **UI-component library** — ships **UI components**: a `src/*.Components` (or `*.Primitives`/`*.Icons`) project, `.razor` components in the package. The consumer's contract is **component parameters**. → unit = **component**. (TrBlazeUI is canonical.)
+- **Service/SDK library** — ships **services/APIs**, **few or zero UI components** (the only `.razor` live in the sample). The consumer's contract is a **DI entrypoint** (`AddXxx(...)` `IServiceCollection` extension) + **facade interface(s)** + public service classes/methods + options/config types. → unit = **public service / API**. (TechieRag is canonical — it ships `AddTechieRag(...)` + `ITechieRag`, 0 package `.razor`.)
+
+> ⚠ **Do NOT document a library by its sample app's screens.** A NuGet consumer never uses your `samples/` UI — they code against the package's public surface (components or services). A screen-by-screen guide of the sample documents the *demo*, not the *product*; it leaves the actual contract (parameters / `AddXxx` options / public methods) undocumented. The sample/demo is the **exerciser** (the thing you boot for screenshots + usage examples), not the unit of the guide.
+
+**In either library sub-type, the work-list is the PUBLIC SURFACE a consumer codes against, not (role, screen) pairs**, and the app you boot for the OBSERVE pass (§5a) is the **demo/sample showcase project**. Everything else still applies unchanged — fan-out (§4), render-truth (§4 hooks), no-hallucinated-paths, defect→checklist (§6a), HTML render (§6), single-vs-split (§3, but split by **category/module**, not by role). Then:
+
+1. **Inventory the public surface.**
+   - *UI-component library:* every public `.razor` (+ `.razor.cs`) component the package ships (incl. `*.Primitives`/`*.Icons` as their own categories). Echo `N components across K categories` (Inputs / Layout / Overlays / Data display / Feedback / Icons).
+   - *Service/SDK library:* every public service/API the package exposes — the `AddXxx(...)` DI extension(s) + their options, the facade interface(s) (e.g. `ITechieRag`), and each public service class + its public methods. Echo `N services across K modules` (e.g. Ingestion / Embedding / Query-RAG / LLM / Resilience+Token / Admin).
+2. **For each item, document its CODE FLOW** (the library analogue of a screen's lineage), per the template's per-item block:
+   - **Purpose** — one line.
+   - **Public API surface (the consumer's contract — READ at `file:line`, never inferred):**
+     - *Component:* every `[Parameter]`/`[CascadingParameter]` (name, type, default, required?), every `EventCallback`, public methods, `@typeparam`, `[Parameter(CaptureUnmatchedValues=true)]`.
+     - *Service/API:* the `AddXxx(...)` registration + every option/config property, the facade/interface methods (full signatures: params, return type, async), and how the consumer resolves it from DI.
+   - **Internal flow** — how it behaves as built (cite `file:line`):
+     - *Component:* state fields, lifecycle (`OnParametersSet`/`OnAfterRender`), key private methods, JS interop (`IJSRuntime` + the `.js`), cascading values, event propagation.
+     - *Service/API:* the call pipeline (e.g. ingest → chunk → embed → upsert; query → embed → vector-search → prompt → LLM), external dependencies it calls (LLM endpoint, vector store, DB), resilience/retry/token-tracking, key private methods.
+   - **Demo / usage** — the `demos/`/`samples/` page or sample code that exercises it (path) + a **screenshot from the booted demo app** (§5a) **where it has UI**, plus the minimal usage snippet a developer copies (`<Component … />` for UI; `services.AddTechieRag(...)` / an `ITechieRag` call for a service).
+   - **Known issues** — undeclared-required-param traps, broken parameters, unhandled errors, a11y gaps, etc., logged to the checklist (§6a) like any other defect.
+3. **Cross-check public surface against demo/sample COVERAGE — the sample is part of the deliverable, not just a backdrop.** For each public item from step 1, find where the `demos/`/`samples/` app exercises it. A library's sample app exists to **demonstrate every public capability**; the DevGuide can only show/screenshot/verify an item that the sample actually exercises. So as you map:
+   - **Covered** → document it with its demo page + screenshot + snippet (step 2).
+   - **NOT covered** (a public component/service/overload the sample never touches — e.g. a "bring-your-own `IEmbeddingProvider`" extension point with no example, a facade method like `DeleteDocumentAsync`/`ClearAsync` no screen calls) → still document the API + internal flow from code, but mark **`⚠ no demo coverage`**, and **log it to the checklist (§6a) as a sample gap** ("REQ/sample: add a demo for `X`"). This is the answer to "does the sample also need updating?": **the DevGuide regen is the diagnostic** — if it finds uncovered public API, yes, the sample needs a small addition (a showcase page or sample snippet) so that item is demonstrable + verifiable; if coverage is complete, only the DevGuide changes. Report the covered/uncovered tally in §8 so the owner can decide which gaps to fill.
+4. Then skip to §3 (structure — split by category/module), §4 (fan out: one subagent per category/module), §5a (boot the demo/sample app; screenshot each item's showcase page where it has UI; items marked `⚠ no demo coverage` get no screenshot — that's the gap), §6 (render + checklist write-back) — applying them with "component/service" wherever they say "screen".
+
+### 1. Confirm there is code to map
+
+Verify the app has built source (e.g. `src/{AppName}.Web` Razor files exist). If the repo is doc-only (no UI/code yet), HALT: "No built UI found — the DevGuide maps as-built code. Run the build phases first, then re-run `*devguide {AppName}`." **(Library mode (§0): the "built source" is the package under `src/…` (UI components and/or services) + its `demos/`/`samples/` showcase app — confirm those exist; a library is never skipped just because it has no app screens of its own.)**
+
+### 2. Discover roles, menus, and screens (the work-list)
+
+Build the list of `(role, screen)` pairs to document. Gather from, in order:
+
+1. **Roles** — `docs/{AppName}-UsageGuide.md` Test-users table (canonical role list) + authorization in code (`[Authorize(Roles=…)]`, policy registrations, role/claim constants). Reconcile the two.
+2. **Menus** — the nav definition(s) (`Shared/NavMenu.razor` / menu config) and any per-role menu filtering, so you can record which role sees which menu item and what it opens.
+3. **Screens** — every routable Razor page (`@page` directives) and significant component, mapped to the role(s) that can reach it. A screen reachable by several roles is documented once, noted under each role's menu map.
+
+Produce a flat work-list: `role → [screens]`. Echo a one-line count: `N roles, M distinct screens`.
+
+### 3. Decide structure — single doc vs per-role split
+
+- **`--single` / `--split`** if the user forced it.
+- **Auto** otherwise: **split per role** when `roles ≥ 3` OR `distinct screens > 12` OR any single role has `> 8` screens (large app like a multi-tenant admin suite). **Single doc** otherwise (small app). State which you chose and why.
+- **Single:** one `docs/{AppName}-DevGuide.md` from the template (directly in `docs/`), all roles' screens under §4.
+- **Split:** create a **`docs/devguides/`** subfolder and write the whole multi-part guide into it, so the many files don't clutter `docs/`. `docs/devguides/{AppName}-DevGuide.md` is the **index** (template §1–§3 + the role→file table + menu maps, no per-screen bodies); each `docs/devguides/{AppName}-DevGuide-{Role}.md` carries template §4 for that role's screens (plus a short §1/§2 pointer back to the index). Index and role files are co-located in `docs/devguides/`, so the index's relative links (`./{AppName}-DevGuide-{Role}.md`) resolve as-is.
+- **Switching structure on a re-run:** if the guide already exists in the *other* layout (a single `docs/{AppName}-DevGuide.md` that now splits, or a `docs/devguides/` set that now collapses to a single doc), move/delete the stale-location file(s) so only one canonical copy survives — never leave both a `docs/{AppName}-DevGuide.md` and a `docs/devguides/{AppName}-DevGuide.md` (+ their `.html`).
+
+### 4. Map the code — FAN OUT across roles (token-bounded)
+
+**Do not read the whole codebase in one context.** Spawn one subagent per role (or per screen-cluster for a huge role), each scoped to map only its slice. This keeps each context small and lets the work run in parallel — the single biggest token lever for this large doc (see `.tfcore/TOKEN-GUIDE.md`).
+
+Each subagent is told to, for its assigned screens ONLY:
+- Open each screen's Razor page/component (+ code-behind) and list the **controls** (grids, charts, forms, tables, buttons that load/compute data).
+- For each control/action, follow the call chain in code: Razor → injected **service method** → **data-access method** (repository / DbContext / Dapper) → **stored proc name or SQL query**. Record file paths. If a value is **calculated**, name the calculator method and where.
+- Draft the screen's **flowchart**, **Controls** table, **Data lineage** table, business-rules and known-issues bullets per the template's `### {Role} · {Screen}` block.
+- Return the finished markdown section(s) only — raw doc text, no commentary.
+
+**LANDING-TRUTH — read the routing, never infer it.** Where a screen says it is "reached via" / where a role "lands" after login is a **claim about the code that MUST be read, not inferred from folder or role names**. Resolve the actual post-login route from the login/redirect code (the `NavigateTo(...)` after a successful login, the default `@page "/"`, `App.razor`/authentication redirect, `[Authorize]` fallback) and cite the `file:line` that performs the navigation. ❌ "Admin logs in → lands on Admin Dashboard (because the page is in the Admin folder)" is exactly the hallucination this guide exists to kill. ✅ "After login `LoginPage.razor.cs:57` does `NavigateTo("/Index")` for **all** roles; Admin Dashboard is reached only from the menu." If a role's landing is the same shared home page, say so.
+
+**RENDER-TRUTH — verify the data REACHES and RENDERS, not just that a method exists.** "The service/proc exists" is NOT verification — the whole point is to catch the case where code is wired but the control still shows blank/empty/stale. For each control, also check:
+- **Guards & binding:** the `@if (X != null)` / `@if (list.Any())` conditions, and whether the bound data can actually be non-empty. A header that renders while its table is hidden by a null guard is a *defect*, not "working".
+- **Source returns:** does the query/proc actually return rows, and do its **columns map to the model's property names** (case/underscore)? Are there **computed getters** (e.g. `BirthDate => new DateTime(BYear,…)`) that throw or blank when the source columns are unmapped/empty? Rows present but cells blank = a real defect.
+- **Required component parameters:** is every parameter the control needs actually declared and supplied (e.g. a grid bound to `Pagination="@pagination"` where `pagination` is never declared)? A missing/undeclared/null required param that suppresses rendering is a defect.
+- Tag each lineage/control row with its render status: **renders** · **renders-empty/blank (suspected defect — why)** · **{unresolved — TODO}**. A "suspected defect" MUST also be logged to the checklist per §6a.
+
+**Verify, don't trust.** A lineage row is a claim about the code. Confirm named methods/procs/components actually exist AND that data reaches the control (above). If a path can't be confirmed, record `{unresolved — TODO: reason}` rather than inventing a name. Prefer "I read X at file:line and it does Y" over any inference.
+
+For `--update`: locate the existing guide first (single `docs/{AppName}-DevGuide.md`, or the split set under `docs/devguides/`), only spawn subagents for changed/in-scope screens, reuse existing entries for the rest, and write back to wherever the guide already lives.
+
+### 5. Assemble the doc(s)
+
+- Fill the template header (§1 How to use, §2 Architecture cheat-sheet from `docs/{AppName}-Architecture.md` + the real project layout, §3 Roles-and-menu map from §2's discovery).
+- Insert each role's screen sections (single doc) or write each role file + the index (split).
+- Every Mermaid diagram MUST pass the `html-render-shell.md §5.5` self-check (quoted labels, no `end` node id).
+- Subtitle/footer: `Generated {today YYYY-MM-DD} · reflects code as built`.
+
+### 5a. OBSERVE + RECONCILE — ground the guide in the RUNNING app (mandatory attempt)
+
+A guide built only from reading code is a hypothesis, not the truth — static reading cannot see that a table renders blank, a list shows a count over zero visible rows, or a calc returns empty at runtime. So after drafting the map, **run the app and observe**, then reconcile.
+
+**OBSERVE (reuse the verifier — do not build a second app-runner).** Invoke the verifier's runtime render sweep (`.tfcore/tasks/verify-phase.md §4a` + the §4b visual-truth gate) over the screens in this DevGuide: it boots the app via the build-invocation-ladder, logs in as each role's `docs/{AppName}-UsageGuide.md` test user, navigates each screen, and records for **every control** in the draft map whether it **RENDERS** its data or is **RENDER-EMPTY / RENDER-ERROR / UNREACHABLE**, plus whether the screen is **VISUAL-OK / VISUAL-FAIL** (overlap/clip/off-viewport) (per `_smoke-test-policy.md` — running it is mandatory, "can't run on Linux" is banned). For a MAUI **Android / iOS / Mac Catalyst** app, the verifier drives the screens over its **Appium** endpoint (`verify-phase.md §3b`) instead of Playwright — same observations, same screenshots; an unregistered/unreachable head is observed as `⚠ STATIC-ONLY` for that head, not faked.
+
+**CAPTURE a screenshot of every screen — for EVERY DevGuide, greenfield and brownfield alike.** Whenever the OBSERVE pass boots the app (which is any time there is built code to map — a greenfield app's DevGuide is generated post-build/at handoff and gets screenshots exactly like a brownfield one; only a not-yet-built greenfield repo has none, because there is nothing to screenshot), save a full-page screenshot of each observed screen to `docs/screenshots/{AppName}/{role}-{screen-slug}.png` (desktop 1280×800; add a `-mobile` shot at 390×844 for screens with responsive layout). **Embed/link each shot into that screen's DevGuide block** (an `![{screen}](../screenshots/{AppName}/{role}-{screen-slug}.png)` image under the Controls table — use the path relative to wherever the guide lives: `screenshots/...` from `docs/`, `../screenshots/...` from `docs/devguides/`). These real-screen images serve THREE purposes: the runtime visual baseline (brownfield's equivalent of greenfield's mockups), the owner visual-review (§5b), and the **source images the end-user Product Guide reuses** (`*productguide` — the DevGuide is the as-built map for developers AND the screenshot source for external-user documentation).
+
+**Boot the WHOLE stack yourself — a multi-service app is NOT an excuse to hand the boot to the owner.** Many of these apps are multi-process (an API + a Blazor web + a database + an LLM endpoint). **"The dependent API/stack is down"** is something you BRING UP yourself, not a reason to stamp STATIC-ONLY and ask the user. Read each dependent project's `appsettings*.json` / launch settings for its configured URL, then start each service yourself **in dependency order** (DB/LLM first, then API, then web) on its pinned port via the build-invocation-ladder, following the `verify-phase.md §3a` escalation (rung #2 → rung #4 Windows-side → another port). Only once that full order has genuinely failed do you fall to the STATIC-ONLY path below.
+
+**RECONCILE.** Diff the static map against what was observed:
+- Tag each control in the doc with its **observed** status — `renders ✓ (runtime-confirmed {date})` / `renders-empty (DEFECT — {what})` / `render-error` / `unreachable` — NOT a static guess.
+- Every deviation (documented-to-render but observed-empty/error, or a landing that differs from what was read) is a **runtime-confirmed defect** → log it to the checklist in §6a (these carry more weight than static suspicions).
+- Stamp the file header with a **verification-status banner** (see below).
+
+**Only if the stack STILL cannot be booted after you have tried the full escalation yourself** (every dependent service started via the ladder, rung #4 Windows-side attempted, ports retried, and — per `verify-phase.md §3a`, as the LAST resort — you finally asked the user to start it and even that failed): do NOT fake render-status. Stamp the guide **`⚠ STATIC-ONLY — NOT runtime-verified`**, leave control render-status as `static-only (unconfirmed)`, and tell the user in §8 to run `*verify {scope}` (or re-run `*devguide`) once the stack is up so the OBSERVE pass can complete. A static-only guide is explicitly a draft, never presented as confirmed. **Asking the user to run the app is the LAST resort, never the opening move** — the owner set the environment up (`WORKFLOW.html §0`) so you can boot it yourself, and you still run the OBSERVE pass yourself once they reply `go`.
+
+**Verification-status banner (top of the index AND every area file):**
+- `> ✅ Runtime-verified {date} — exercised as: {roles}. Control render-status below is observed, not inferred.` — when OBSERVE ran.
+- `> ⚠ STATIC-ONLY ({date}) — built from code reading; NOT yet runtime-verified. Render-status is unconfirmed until \`*verify\` runs against the running app.` — when it didn't.
+
+### 5b. OWNER VISUAL-REVIEW GATE — show the screenshots, ask what to change (the discussion checkpoint)
+
+The OBSERVE pass (§5a) captured a real screenshot of every screen. Before build/fix work continues, **give the owner a visual review of the actual UI** — this is the brownfield counterpart to the greenfield mockup-approval gate, and it is exactly where the "the UI is completely broken even though it verified" problem gets caught by a human, not just by the gates.
+
+- Present the captured screenshots (the per-screen images now embedded in the DevGuide / under `docs/screenshots/{AppName}/`) and ask the owner, screen by screen: **"Here is how each screen actually renders. What needs to change?"** Keep it to a real discussion — let them point at overlap, broken layout, wrong content, missing controls, awkward flows.
+- This gate runs **after** the docs are authored and the app has been observed, **before** the next build/fix phase — it is a review of reality, not a day-1 blocker (so it does not hold up doc generation).
+- Capture each requested change as a **defect logged into the one checklist** via §6a (Remarks + `Needs re-verify` on the owning `REQ-UI-*`, prefix layout issues `⚠ visual:`), and/or queue them for `*fix-issues {AppName} {folder}`. Note in the §8 report how many owner-requested changes were logged.
+- **When this gate is reached non-interactively** (e.g. chained inside `day1-brownfield §7.6` with no owner present): skip the live Q&A, but still embed the screenshots and tell the owner in the closing message to review `docs/screenshots/{AppName}/` and run `*fix-issues` (or `*devguide {AppName} --update`) with any screens that need changes.
+
+### 6. Render to HTML (human doc)
+
+Render each produced markdown to a sibling `.html` via `.tfcore/tasks/generate-html.md` (shared shell — light/dark theme, TOC, mermaid toolbar). The DevGuide **is** a human-readable doc, so it gets HTML (unlike the checklists). For a split guide, render the index + every role file **in place inside `docs/devguides/`** (each `.html` sits beside its `.md`).
+
+### 6a. Log confirmed defects into the checklists (the findings must reach the source of truth)
+
+Mapping the code as-built routinely surfaces real defects — a Save handler that's a no-op, a page missing `[Authorize]`, a GET/POST (405) mismatch, stubbed/hard-coded data, an unwired stat, a value that's never persisted, a route the menu points at that doesn't exist. **These are exactly the "verifier passed but it's still buggy" issues the guide exists to expose, and they MUST land in the tracked source of truth — the checklist Requirements Status tables — not only in the DevGuide prose.** A finding logged only in the DevGuide gets lost.
+
+For each **confirmed** defect (not a `{unresolved — TODO}` you couldn't verify):
+- Map the affected screen → its owning `REQ-*` using the checklist's detail sections (which list which REQ covers which screen). All defects land in the one checklist `docs/{AppName}-Checklist.md` (UI defects on `REQ-UI-*` rows, functional/data/API defects on `REQ-FN/RAG/NFR-*` rows — same file).
+- **Append** (never overwrite) a dated note to that REQ's **Remarks** cell: `⚠ DevGuide {date}: {one-line defect + file:line}`.
+- If the defect means the feature does **not** work as specified (no-op, missing auth, 405, won't-compile, stub data, never-persisted), set that REQ's **Status to `Needs re-verify`** and lower `%` to reflect reality. **Never mark anything `Verified`**, and do **not** downgrade an item whose only gap is externally-blocked-but-correct (e.g. needs a live dependency) — add a remark only.
+- For a `{unresolved — TODO}` (a hop you could not confirm from code): add a Remarks note flagging it for review, but do **not** change Status (uncertain ≠ defect).
+- **Runtime-confirmed defects from §5a (OBSERVE) are logged the same way and carry the strongest evidence** — an observed RENDER-EMPTY/RENDER-ERROR control with a screenshot is a hard defect, not a suspicion; flag its REQ `Needs re-verify` with the observed note. (When OBSERVE could not run — STATIC-ONLY — these are static *suspicions*; still log them, but say "static — confirm at runtime".)
+- These are **markdown-only** edits to the checklist tables — do NOT render the checklists to HTML.
+
+### 7. Note it in PROJECT-STATUS (light touch — NOT the full gate)
+
+Add/refresh one line under "Where I am" / artifacts: `DevGuide generated {date}: docs/{AppName}-DevGuide.md (single) or docs/devguides/ (split) (+ .html); {N} defects logged to the checklists`. This task does not change build/verify state, so do not touch `current_phase` or `last_verified_build`; the only Requirements Status table edits allowed are the §6a defect remarks/flags. Re-render `PROJECT-STATUS.html` only if you edited it.
+
+### 7a. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"devguide","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+### 8. HALT — report
+
+```
+# DevGuide — {AppName}
+Structure: {single | split per role (R files)}
+Verification: {✅ runtime-verified {date} as {roles} | ⚠ STATIC-ONLY — not yet runtime-verified}
+Roles: {list}   Screens documented: {M}   Unresolved paths: {k (listed below)}
+Render defects found at runtime: {r (controls observed empty/error — logged to checklist)}
+Visual defects found at runtime: {v (screens observed overlap/clip/off-viewport — logged to checklist)}
+Screenshots: docs/screenshots/{AppName}/ ({M} screens captured)   Owner-requested changes logged: {c}
+Files: docs/{AppName}-DevGuide.md (single) — or, split, docs/devguides/{AppName}-DevGuide.md + -{Role}.md ... — and sibling .html
+{if any} Unresolved lineage (code path not found — review): screen/control → reason
+Next: {if static-only → "run `*verify {scope}` (or re-run `*devguide`) with the app up to runtime-confirm render-status"} ; open the .html in a browser to chase bugs.
+```
+
+## Hard rules
+
+- **Never edit source code.** Read-only mapping of the as-built code into a doc.
+- **No hallucinated paths or inferred routing.** Every service/data-access/proc name in a lineage row must be a real symbol you READ in the code; if you can't confirm it, mark `{unresolved — TODO}`. **Never infer a screen's post-login landing or "reached via" from folder/role names — read the redirect code and cite file:line** (LANDING-TRUTH, §4). Inventing a plausible proc name, or asserting a landing page you didn't trace, defeats the guide's entire purpose (catching AI hallucination — the framework exists to FIND bugs, not generate confident-but-wrong docs).
+- **Render-truth over method-existence (§4).** "The method/proc exists" is not "the control works". Verify data actually reaches and renders — guards, column→property mapping, throwing computed getters, undeclared required component params. Mark each control renders / renders-empty (suspected defect) / unresolved, and log suspected defects to the checklist (§6a).
+- **Render-status must be OBSERVED, not inferred (§5a).** The strongest version of render-truth is running the app. Always attempt the OBSERVE pass (reuse the verifier); write control render-status from what you saw at runtime. If the app could not be booted, stamp the guide `⚠ STATIC-ONLY — NOT runtime-verified` and mark control status `static-only (unconfirmed)` — NEVER present a static "renders ✓" as confirmed. Every index + area file carries the verification-status banner.
+- **Capture a screenshot of every screen and review them with the owner (§5a/§5b) — greenfield AND brownfield.** Whenever OBSERVE boots the app (i.e. there is built code — true for a greenfield app's post-build/handoff DevGuide too, not just brownfield), save a real screenshot of each screen to `docs/screenshots/{AppName}/` and embed it in the screen's block. Then run the owner visual-review gate — show the screenshots and ask "what needs to change?" — logging requested changes as checklist defects. This catches a visually-broken-but-data-present UI; it also provides the images the end-user **Product Guide** (`*productguide`) reuses. (Non-interactive runs skip the live Q&A but still capture + embed the shots and point the owner at them.)
+- **Checklists stay markdown; the DevGuide is human-readable and IS rendered to HTML.** Do not confuse the two.
+- **Incremental by default when re-running.** Preserve unchanged screen entries verbatim; only remap what changed or what `{Scope}` names. Don't burn tokens regenerating a 60-screen guide to fix one screen.
+- **Confirmed defects go into the checklists (§6a).** A bug found while mapping but logged only in the DevGuide prose is lost — route every confirmed defect to its owning `REQ-*` Remarks (and flag `Needs re-verify` when it means the feature doesn't work). Never mark anything `Verified`; never downgrade an externally-blocked-but-correct item.
+- **Boot the app yourself — including multi-service stacks (§5a).** Running the app for the OBSERVE pass is YOUR job, not the owner's. Start every dependent service (API, web, DB/LLM endpoints) yourself, in dependency order, via the build-invocation-ladder + `verify-phase.md §3a` escalation. "The dependent stack is down / it's multi-service / it targets Windows / it can't run on Linux / Playwright needs a GUI" are **banned excuses** (`_smoke-test-policy.md`). Asking the user to run it is the LAST resort, only after the full escalation genuinely fails — and you still run the OBSERVE pass yourself once they reply `go`.
+- **Never run git — git is manual in this framework.** Do NOT run `git diff` / `git log` / `git status` / `git blame` / `gh` to inspect changes or chase a defect while mapping. The owner keeps ALL git activity manual and will (correctly) deny the permission prompt, which only stalls you. Investigate the as-built code by **READING the working-tree files** at their paths — the files on disk ARE the code this guide documents, and a defect's evidence is the `file:line` you read, never a diff. (`refresh-status` was de-git-ed for exactly this reason — see `WorkFlow-Context.md`.)
+- **Token discipline:** fan out per role/cluster (§4) rather than loading the whole repo into one context. See `.tfcore/TOKEN-GUIDE.md`.
+
+## Output Checklist
+
+- [ ] Built code confirmed present (HALT if doc-only)
+- [ ] Roles + menus + screens discovered and reconciled (UsageGuide ↔ code authorization)
+- [ ] Structure decided (single vs split per role) with stated reason / honored `--single`/`--split`
+- [ ] **Split guides written to `docs/devguides/`** (index + role files co-located there); single guides kept at `docs/{AppName}-DevGuide.md`; no stale copy left in the other location after a structure switch
+- [ ] Each screen has: route + Razor file, flowchart, Controls table, full Data lineage (Razor → service → data-access → proc/query), business rules, known issues
+- [ ] **Landing-truth:** every "reached via" / post-login landing was READ from the redirect/routing code and cites file:line — none inferred from folder/role names
+- [ ] **Render-truth:** each control tagged renders / renders-empty (suspected defect, with reason) / unresolved — guards, column→property mapping, computed getters, and required component params (e.g. an undeclared `pagination`) checked; not just method-existence
+- [ ] Code paths verified real (no invented proc/method names; unresolved ones flagged `{unresolved — TODO}`)
+- [ ] **OBSERVE pass attempted (§5a):** the app was booted and each control's render-status + screen visual-status was observed at runtime (reusing the verifier render + visual gates) — OR the guide is stamped `⚠ STATIC-ONLY` because the stack couldn't be booted (never a faked "renders ✓")
+- [ ] **Screenshot of every screen captured to `docs/screenshots/{AppName}/` and embedded** in its DevGuide block
+- [ ] **Owner visual-review gate (§5b):** screenshots shown + "what needs to change?" asked (or, non-interactive, the owner pointed at the screenshots in the closing message); requested changes logged as checklist defects
+- [ ] **Verification-status banner** present on the index AND every area file (✅ runtime-verified {date}/{roles}, or ⚠ STATIC-ONLY)
+- [ ] Runtime-observed RENDER-EMPTY/ERROR **and VISUAL-FAIL** deviations logged to the checklist as defects (§6a)
+- [ ] Every Mermaid diagram passes the §5.5 self-check
+- [ ] Markdown + sibling HTML produced (index + role files if split); checklists NOT rendered
+- [ ] Confirmed defects logged into the owning checklist Requirements Status tables (Remarks + `Needs re-verify` where the feature is broken; never `Verified`; markdown only, no checklist HTML)
+- [ ] PROJECT-STATUS got the one-line DevGuide note incl. defect count (no full status gate)
+- [ ] Report printed with structure, counts, defects logged, and any unresolved paths