@techierathore/techieflow 1.0.1 → 1.0.3

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

@@ -1,224 +1,39 @@
 # 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.
+`*day1-greenfield {App}` starts a product that has no code. It runs in two stages with one owner review between them. Stage 1 produces the Architecture, the mockups and the BRD, then stops for review. `*day1-greenfield {App} --stage2` runs only after the owner has approved them and produces the checklist and the remaining documents. No mode skips the review: YOLO runs one stage to completion, never both.
 
-## Purpose
+First, before anything else: `bash .tfcore/utils/tf-phase.sh start day1-greenfield {App}` prints the start time and marks the command running.
 
-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.
+## Stage 1 — Architecture, mockups, BRD
 
-## elicit
+Ask once each, and nothing per section:
 
-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.
+1. `{App}` if missing. PascalCase, no spaces.
+2. The concept: "Describe the app, any length: a sentence, paragraphs, bullets, half-baked notes, comparisons to other apps. You will edit the document afterwards." Read all of it. Never cap or summarise the owner's input.
+3. Hints, optional: paths to notes or mockups to harvest, and drafting instructions. `none` is fine.
+4. The stack: "Which answer set: `dotnet` (`.tfcore/templates/stack-defaults/dotnet.md`), or answer the questions in `.tfcore/templates/stack-questions.md`?" Then ask only the questions the set leaves open (for dotnet: Q4, and the rendering mode of Q8).
+5. The size: count the routed pages in the concept (every page with its own route, sign-in included; dialogs and tabs are regions of a page) and the roles, then ask: "Size: Small (up to 10 screens, one role, 50 requirements), Medium (up to 20 screens, 100 requirements) or Large (split into phases)? I count {N} screens and {N} roles, so I propose {X}." Kind is `app` unless the concept is a library.
 
-## Inputs
+Then, in this order:
 
-- `{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.
+6. `bash .tfcore/utils/tf-day1-files.sh {App} --size {S|M|L} --kind {app|library}` writes the size, the kind and the document paths into `core-config.yaml`; for Large it also writes `docs/{App}-Phases.md`, whose table you fill first: one row per phase, each within Medium, every screen in exactly one phase. On a re-run of stage 1, first `bash .tfcore/utils/tf-day1-files.sh --archive docs/{App}-BRD.md docs/{App}-Architecture.md docs/{App}-UIDesign.md` moves the old copies to `docs/OldDocs/`. Never write a `-v2` variant; never ask merge-or-new.
+7. Architecture: `docs/{App}-Architecture.md` from `.tfcore/templates/v4custom/app-architecture-tmpl.md`, in the template's order. Stack decisions come from the answer set and the owner's answers, each row citing its source. Harvested notes carry into the sections attributed, never summarised away. Quote every mermaid label; never use `end` as a node id.
+8. BRD, first half: `docs/{App}-BRD.md` from `app-brd-tmpl.md`: the header (App, Kind, Size, Stack answer set, Status, Date), Summary, Scope, Users and roles, and the Screens and flow table. A dialog is a row under its parent screen with `on /route` in the Route column.
+9. Mockups: run `.tfcore/tasks/mockups.md` for `{App}`. It reads the Screens and flow table and produces `docs/{App}-UIDesign.md` and one `docs/mockups/<screen>.html` per screen. An app with no screens records "skipped — no UI".
+10. BRD, second half: the Requirements ledger, one `BRD-N` per thing the verifier will test, each naming its screen, linking its mockup and carrying one acceptance line "When <actor> <does what> on <screen>, then <observable result>"; the Non-functional table (a `perf-budget:` only where the owner gave a number; the logging requirement from the answer set); the Development status table, one row per screen, all Planned. The concept is the primary source: every feature, actor and constraint in it becomes an item. Mark inferred items `<!-- inferred — please verify -->`. Harvested requirements carry in as items, attributed, none dropped. If the count would pass the size cap, propose a phase split instead of merging items.
+   Large: steps 8 to 10 run once per phase of the Phases table, phase 1 in `docs/{App}-BRD.md` and `docs/{App}-UIDesign.md`, phase n in `docs/{App}-Pn-BRD.md` and `docs/{App}-Pn-UIDesign.md`, each header carrying `Phase | n of m` and its own Size, ids running on across phases. Every screen gets its mockup now.
+11. `bash .tfcore/utils/tf-doc-check.sh --app {App}`; fix every FAIL.
+12. Run the status gate (`.tfcore/tasks/_status-update-gate.md`); the run record carries `"cmd":"day1-greenfield","mode":"stage1"`.
+13. Stop and say: "Stage 1 is complete: BRD, Architecture and mockups are written and rendered. Review them in the HTML files, or edit the markdown. When you approve, run `*day1-greenfield {App} --stage2`. To change a screen, edit the concept and re-run stage 1, or run `*mockups {App} --update`."
 
-## SEQUENTIAL Execution
+## Stage 2 — checklist and the remaining documents
 
-### 1. Resolve app name + concept + hints + persist config
+Only with `--stage2`, and only when `docs/{App}-BRD.md` exists. Ask nothing.
 
-- 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
+0. If the owner gave corrections at the review, apply them to the stage-1 documents first (ids never renumbered; `bash .tfcore/utils/tf-doc-check.sh --app {App}` must pass), count them, and after this run's record append a `review` record: `{"kind":"review","phase":"day1-review","reviewed_run_id":"<stage 1 started>","correction_run_id":"<this run's started>","corrections":N,"what":"<one sentence>"}` through `tf-emit.sh misses`.
+1. Checklist: run `.tfcore/tasks/split-brd.md` for `{App}` (Large: with `--all-phases`, one checklist per phase). The owner never types `*split-brd`.
+2. Coding Standards: `docs/{App}-Coding-Standards.md` from `app-coding-standards-tmpl.md`. "Standards applied" names `.tfcore/standards/coding-standards-core.md` and the stack file, plus the choices the stack file leaves open (for dotnet, the instance-field prefix, default `obj`). "Project rules" stays empty unless the concept demands a rule true of this project alone.
+3. `bash .tfcore/utils/tf-day1-files.sh {App} --prefix {obj|none}` writes `.editorconfig`, `AGENTS.md` and `CLAUDE.md` from their templates.
+4. UsageGuide: `docs/{App}-UsageGuide.md` from `app-usageguide-tmpl.md`. The Test users table lists the intended accounts, one per role, none created. The Execution guide is at roadmap level, marking commands that depend on projects not yet built. One "How to test" section per screen in navigation order, naming the user, the steps, the expected result and the REQ ids.
+5. `bash .tfcore/utils/tf-gitignore-audit.sh . --fix`. Read its output. Any untracking commands it prints go into your summary for the owner to run; agents never run git.
+6. Run the status gate; the run record carries `"mode":"stage2"`. The next command is `*build-phase {App}`.

package/.tfcore/tasks/deploy-checklist.md

@@ -0,0 +1,19 @@
+# deploy-checklist
+
+`*deploy-checklist {App} {pipeline-document}` writes `docs/{App}-Deployment-Checklist.md`: the steps to put the application on its host, one document per hosting target, produced after UAT from the owner's pipeline guidance document and the Stack answers about hosting and production secrets. It never deploys anything and never edits code. Running the application locally is not in it; the UsageGuide's Execution guide owns that.
+
+First: `bash .tfcore/utils/tf-phase.sh start deploy-checklist {App}` prints the start time and marks the command running.
+
+## Inputs
+
+- `{App}`, or read it from `core-config.yaml`.
+- `{pipeline-document}`: the path of the owner's pipeline guidance document. If missing, ask once: "Which document describes the pipeline and the host? A path, or `none` to write the checklist from the Stack answers alone."
+
+## Steps
+
+1. Read the pipeline document, the Architecture's Stack decisions, and the UsageGuide's Execution guide (so nothing local is repeated). If the Stack decisions have no Q9 (hosting) or Q10 (production secrets and pipeline) row, ask those two questions now, once, and add the rows to the Architecture, citing the owner.
+2. If `docs/{App}-Deployment-Checklist.md` already exists for this target, `bash .tfcore/utils/tf-day1-files.sh --archive docs/{App}-Deployment-Checklist.md` moves it to `docs/OldDocs/` first; read it for facts, never copy its shape. Write `docs/{App}-Deployment-Checklist.md` from `.tfcore/templates/v4custom/app-deployment-checklist-tmpl.md`, in the template's order, for one hosting target. Every item in "Before the first deploy", "Deploy", "After the deploy" and "Rollback" is a checkbox with one action and the result that shows it worked; every secret or setting is one row in "Secrets and settings" and is named nowhere else; "Proven" lists what has been executed for real, and the header says `never` until a real deploy has run. A second hosting target is a second document, `docs/{App}-Deployment-Checklist-{Target}.md`.
+3. Where the pipeline document contradicts itself (a variable it says was deleted and still uses, a pipeline called settled on one page and never run on another), write the checklist from what the code and configuration say, and list each contradiction under "Troubleshooting" as a symptom with its fix. Log the contradiction as a miss when the document is the framework's own output.
+4. `bash .tfcore/utils/tf-doc-check.sh docs/{App}-Deployment-Checklist.md`; fix every FAIL.
+5. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"deploy-checklist"`. The next command is the one the gate printed.
+6. Report: the hosting target, the number of steps per section, the secrets named, the contradictions found, and that nothing has been proven until the owner executes a deploy and updates "Proven".

package/.tfcore/tasks/devguide.md

@@ -1,224 +1,15 @@
 # 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.
+`*devguide {App} [scope] [--update]` writes the developer's map from each screen to the code that serves it: `docs/{App}-DevGuide.md` for phase 1, `docs/{App}-Pn-DevGuide.md` for a later phase, from `.tfcore/templates/v4custom/app-devguide-tmpl.md`. It documents the code as built, read at file and line, so a developer can set a breakpoint and find a bug. It never edits source. For a UI library the unit is the component; for a service library the unit is the public service; both are for the developer who maintains the library. Produced when the build completes the checklist, refreshed at handoff, and re-runnable with `--update` for changed screens only.
 
-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`.
+First: `bash .tfcore/utils/tf-phase.sh start devguide {App}` prints the start time and marks the command running.
 
-**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.
+## Steps
 
-## 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
+1. `bash .tfcore/utils/tf-devguide-list.sh {App} [--update]` prints the kind and the work list. For an app: every routed page found in the code with its file, its UIDesign screen and the roles that reach it; a screen the UIDesign names that has no code (a defect to log on its row); a route in the code with no UIDesign screen (document it, tell the analyst). For a UI library: every public component and the sample page that shows it. For a service library: every registration, interface and class and the sample that calls it. With `--update`: which entries have files newer than the guide's "Verified on" date; the rest are kept verbatim. NOTHING means there is no built code: say so and stop. A `{scope}` limits the list to the screens or roles named.
+2. Fan out one sub-agent per group of screens (or components, or services), each with its lines from the list. Every entry is read at file and line, never inferred: the screenshot link, one "Call chain:" line from the page method to the service method to the data-access method, and the where-to-break table (file and line, the function, the variable to watch, the value it should hold). A route, a landing page or a menu target is read from the navigation code, never guessed from a folder or role name. A path that cannot be confirmed is written `{unresolved — reason}`, never invented. A control whose data cannot reach it (a guard that hides it, a column that does not map to the property, a required parameter never supplied) is a defect, not a working control.
+3. Boot the application yourself (`bash .tfcore/utils/tf-build.sh run <head>`; a library boots its sample app; dependent services start first, in order, from their own configuration) and drive every screen with the verifier's render sweep (`.tfcore/tasks/verify-phase.md §4a`), signed in as each role's user from the UsageGuide. Save one screenshot per screen to `docs/screenshots/{App}/<role>-<screen>.png` (desktop width, and a mobile one when the layout is responsive) and link it from the entry. Write what was seen into each entry: renders, renders empty, error, unreachable. Only when the ladder's last rung has failed does the guide carry the banner `⚠ STATIC-ONLY — not runtime-verified` at the top and every entry `static-only (unconfirmed)`; a "renders" that was not seen is never written.
+4. Every confirmed defect goes into the checklist: a dated Remark `⚠ DevGuide {date}: <defect> <file:line>` on the owning row, and `Needs re-verify` when the feature does not work as specified. Never `Verified`. An unresolved path gets a Remark only, no status change.
+5. Show the screenshots to the owner and ask, screen by screen, what needs to change; log each answer on the owning row (`⚠ visual:` for layout) or as a miss. When nobody is present (a chained run), skip the questions and name the screenshots folder in the report.
+6. Run the status gate (`.tfcore/tasks/_status-update-gate.md`) with `"cmd":"devguide"`; the guide is a human document and is rendered.
+7. Report: the guide's file, runtime-verified as which roles or static-only and why, screens documented, unresolved paths, render and visual defects logged, the screenshots folder, owner-requested changes logged, and the next command from the gate.