@techierathore/techieflow 1.0.1 → 1.0.3

package/.tfcore/templates/v4custom/app-checklist-tmpl.md

@@ -1,90 +1,65 @@
-# {AppName} — Checklist
-
-## Table of Contents
-
-<!-- Auto-maintained. Slug rule: .tfcore/templates/v4custom/html-render-shell.md §1. Update when sections change. As pages grow, list each `### Page: ...` as an H3 sub-entry under "UI / Pages". -->
-
-1. [Goal](#goal)
-2. [Requirements Status](#requirements-status)
-3. [UI / Pages](#ui--pages)
-4. [Functional requirements](#functional-requirements)
-5. [RAG / AI requirements (→ /techierag)](#rag-ai-requirements-techierag)
-6. [Non-functional](#non-functional)
+<!-- tf-schema
+doc: checklist
+file: docs/{App}-Checklist.md
+header: App, Size
+section: Goal | required | max 120
+section: Requirements Status | required
+rule: checklist-rows
+-->
+<!-- Authoring notes (agent only). An agent document: never rendered, never reviewed by the owner.
+     Sections: Goal, Requirements Status (the one table), then one section per page or group holding
+     the detail entries. No other sections: bugs, UAT findings and feedback go to the misses stream.
+     Row rules (tf-doc-check.sh refuses the file otherwise):
+       - header exactly | ID | Requirement | Status | % | Remarks | Details |
+       - ID is REQ-UI-, REQ-FN-, REQ-RAG- or REQ-NFR- plus three digits; row count within the size cap
+       - Status is one of the fixed values; Verified is written only by a verify run (hook)
+       - % is 0, 25, 50, 75 or 100
+       - Details links to the entry's anchor in this file
+       - every entry names its BRD-N item; UI rows link a mockup that exists
+       - exactly one acceptance line per entry: "When <actor> <does what> on <screen>, then <observable result>"
+         ("Given …," may precede it; NFR rows name the measurement instead of a screen); at most 30 words,
+         target 20, one behaviour per row (a bundled line is split into rows); the title is everyday words
+       - a perf-budget line is copied verbatim from the BRD, never invented:
+         perf-budget: <p50|p95|max> <ttfb|load> <= <N>ms [@ concurrency <N>]
+       - Remarks holds the current state only, at most 60 words; history lives in gates.jsonl and misses.jsonl
+     Prefix routing: REQ-UI- built from the mockups by the UI sub-agent; REQ-RAG- by the RAG sub-agent;
+     REQ-FN- and REQ-NFR- by the build phase. `*verify ui|functional|all` filters this table by prefix.
+     Large project: one checklist per phase (docs/{App}-Checklist.md, docs/{App}-P2-Checklist.md, …), a
+     header row "| Phase | n of m |", REQ numbers running on across phases. tf-split-brd.sh does this. -->
+
+# {App} — Checklist
+
+| | |
+|---|---|
+| App | {App} |
+| Size | Small, Medium or Large |
 
 ## Goal
-<one paragraph; ties back to BRD §1. This single checklist is the whole app's work list — UI, functional, RAG, and NFR requirements live together, distinguished only by their REQ prefix.>
 
-## Requirements Status
+{One paragraph tying back to the BRD summary. This single checklist is the whole work list.}
 
-<!-- ============================================================
-     SINGLE SOURCE OF TRUTH for the WHOLE app (UI + functional +
-     RAG + NFR). There is exactly ONE checklist per app — the two
-     former files (UI-Checklist / Functional-Checklist) were merged
-     into this one. Build, self-smoke, and the verifier ALL write
-     their outcomes into THIS table — never into a separate dated
-     results file. One row per REQ, grouped by prefix:
-       REQ-UI-*  → built by /trblazeui (from the mockups)
-       REQ-FN-*  → built by the unified build-phase
-       REQ-RAG-* → built by /techierag
-       REQ-NFR-* → built by the unified build-phase
-     Scopes (`*verify ui|functional|all`) filter THIS table by
-     prefix — they do NOT pick a separate file. Update Status + % +
-     Remarks every time work (implementation, smoke, or verify)
-     touches the REQ. Bugs and change notes live in the Remarks
-     column, NOT in docs/qa/*.md.
-     ============================================================ -->
+## Requirements Status
 
 | ID | Requirement | Status | % | Remarks | Details |
 |----|-------------|--------|---|---------|---------|
-| REQ-UI-001  | Dashboard top nav | Not Started | 0% | — | [view](#d-req-ui-001) |
-| REQ-FN-001  | <short name> | Not Started | 0% | — | [view](#d-req-fn-001) |
-| REQ-RAG-001 | <short name> | Not Started | 0% | — | [view](#d-req-rag-001) |
-| REQ-NFR-001 | <short name> | Not Started | 0% | — | [view](#d-req-nfr-001) |
-
-**Status values:** `Not Started` · `In Progress` · `Implemented` (code done, not yet verified) · `Verified` (self-smoke or verifier PASS — acceptance AND data-render AND visual gates all pass) · `Done (pre-existing)` (migrated from an earlier dev plan as already complete — build agents must NOT rebuild; terminal like `Verified`) · `Needs re-verify` (a defect or change was logged — must be re-run before it can return to `Verified`) · `PARTIAL` (some acceptance unmet — say what in Remarks) · `FAIL` (verifier ran and failed — bug in Remarks) · `Blocked` (external/library gap — link the TR-/TR-RAG- entry in Remarks) · `N/A`.
-
-**% guide:** `0` not started · `25` scaffolded · `50` in progress · `75` implemented-unverified · `100` verified.
-
-**Remarks:** date + what was done / what is missing / bug or library reference. This is the home for bugs and change notes — do not spawn a separate file. Visual-gate failures are prefixed `⚠ visual:`; security findings `⚠ SECURITY`.
-
-## UI / Pages
+| REQ-UI-001 | {short name} | Not Started | 0% | — | [view](#d-req-ui-001) |
+| REQ-FN-001 | {short name} | Not Started | 0% | — | [view](#d-req-fn-001) |
+| REQ-NFR-001 | {short name} | Not Started | 0% | — | [view](#d-req-nfr-001) |
 
-<!-- Each REQ carries an explicit `<a id="d-REQ-ID">` anchor (lowercase) so the
-     Details column above links straight to it in both Markdown and rendered HTML.
-     UI REQs are built by /trblazeui from the approved mockups (docs/{AppName}-UIDesign.md
-     + docs/mockups/*.html); cite the mockup screen each REQ realizes.
+**Status values:** `Not Started` · `In Progress` · `Implemented` · `Verified` · `Done (pre-existing)` · `Needs re-verify` · `PARTIAL` · `FAIL` · `Blocked` · `Owner-UAT` · `N/A`. `Owner-UAT` marks a row only the owner can close, by following the UsageGuide test plan; the verifier cannot reach it from this machine.
 
-     A REQ whose BRD NFR declared a `perf-budget:` carries that line VERBATIM in its
-     Acceptance bullet — split-brd copies it across unchanged. It is machine-read by
-     verify-phase §4c, which grades speed only where such a line exists. Never add one
-     that the BRD did not state, and never paraphrase it: the grammar is
-         perf-budget: <p50|p95|max> <ttfb|load> <= <N>ms [@ concurrency <N>] -->
-
-
-### Page: Dashboard (`/dashboard`)
+## Page: {Screen name} (`/route`)
 
 <a id="d-req-ui-001"></a>
-- **REQ-UI-001** — TrBlazeUI top nav (logo, user menu, theme toggle). *Mockup:* docs/mockups/dashboard.html.
-  - *Acceptance:* page renders; nav fixed-top; theme toggle persists in localStorage; controls do not overlap at desktop + mobile widths (visual gate).
-
-## Functional requirements
+- **REQ-UI-001** — {what the screen shows}. *BRD:* BRD-{N} · *Mockup:* mockups/{screen-slug}.html
+  - *Acceptance:* When {actor} opens {screen}, then {what is visible, with real data, at desktop and mobile widths}.
 
 <a id="d-req-fn-001"></a>
-- **REQ-FN-001** — <trigger / acceptance>.
-
-<!-- Example of a perf-gated NFR row (only where the BRD declared the budget):
-<a id="d-req-nfr-001"></a>
-- **REQ-NFR-001** — Public pages stay responsive under normal load. (BRD-N)
-  - *Acceptance:* pages return 200 and render their data; perf-budget: p95 load <= 2000ms @ concurrency 1
--->
-
-
-## RAG / AI requirements (→ /techierag)
-
-<a id="d-req-rag-001"></a>
-- **REQ-RAG-001** — <trigger / acceptance via TechieRag>.
+- **REQ-FN-001** — {what the user can do}. *BRD:* BRD-{N}
+  - *Acceptance:* When {actor} {does what} on {screen}, then {observable result}.
 
 ## Non-functional
 
 <a id="d-req-nfr-001"></a>
-- **REQ-NFR-001** — <perf / security / accessibility>.
+- **REQ-NFR-001** — {the requirement}. *BRD:* BRD-{N}
+  - *Acceptance:* When {the measurement is taken}, then {the value within its limit}; perf-budget: p95 load <= 2000ms @ concurrency 1

package/.tfcore/templates/v4custom/app-claude-md-tmpl.md

@@ -26,7 +26,7 @@
 | Confirm a **framework** file exists | Glob/Grep for its name — **returns nothing even when it is there** | **Read** the literal path (`.tfcore/…`) — see below |
 | Loop over a list of files | `for f in ...; do ...; done` | Multiple parallel Read/Edit calls in one assistant turn |
 
-**Glob and Grep cannot see the framework tree.** `.tfcore/`, `.claude/`, `.codex/`, `.opencode/` and `.agents/skills/` are hidden dot-directories *and* are gitignored in this repo (deliberately — the deployed framework copies are never committed). Grep is ripgrep-backed: it skips hidden paths AND honours `.gitignore`, so it needs **both** flags — `rg --hidden --no-ignore`, i.e. `rg -uu`. `--hidden` alone is not enough. Glob, `git grep` and `git ls-files` are blind for the same reasons.
+**Glob and Grep cannot see the framework tree.** `.tfcore/`, `.claude/` and `.opencode/` are hidden dot-directories *and* are gitignored in this repo (deliberately — the deployed framework copies are never committed). Grep is ripgrep-backed: it skips hidden paths AND honours `.gitignore`, so it needs **both** flags — `rg --hidden --no-ignore`, i.e. `rg -uu`. `--hidden` alone is not enough. Glob, `git grep` and `git ls-files` are blind for the same reasons.
 
 So **a search returning nothing is not evidence that a framework file is missing.** Confirm framework files by **Read**ing the literal path (every one has exactly one canonical location, and whatever needs it names that path). Never report one as absent without having tried the path first — that false negative gets written into the checklist and the BRD, where the next agent inherits it as fact. If a framework file really is gone, the repo needs `update-framework.sh <repo>` run once on this machine; say that rather than working around it. Full rule: `.tfcore/tasks/_status-update-gate.md` §"The framework tree is INVISIBLE to search".
 

package/.tfcore/templates/v4custom/app-coding-standards-tmpl.md

@@ -0,0 +1,52 @@
+<!-- tf-schema
+doc: coding-standards
+file: docs/{App}-Coding-Standards.md
+header: App, Stack answer set, Date
+section: Standards applied | required
+section: Project rules | required
+section: Enforcement | required
+budget: S 800 1200 | M 800 1200 | L 800 1200
+rule: standards-pointer
+-->
+<!-- Authoring notes (agent only; never visible text).
+     The standards themselves live in the framework and are not copied here:
+       .tfcore/standards/coding-standards-core.md    (every project, technology-neutral)
+       .tfcore/standards/coding-standards-<stack>.md (the stack's answer set, e.g. dotnet)
+     This file says which of those apply and lists only the rules specific to this project.
+     The Project rules table is often empty; a mixed-technology build rule or a per-project naming
+     choice is the kind of thing that belongs here. Fixed budget for every size. -->
+
+# {App} — Coding Standards
+
+| | |
+|---|---|
+| App | {App} |
+| Stack answer set | {name, or "none"} |
+| Date | {YYYY-MM-DD} |
+
+## Standards applied
+
+| File | Applies | Notes |
+|---|---|---|
+| `.tfcore/standards/coding-standards-core.md` | yes | every project |
+| `.tfcore/standards/coding-standards-{stack}.md` | yes | {from the Stack answer set} |
+
+Per-project choices the stack file leaves open:
+
+| Choice | Decision |
+|---|---|
+| {e.g. instance-field prefix} | {…} |
+
+## Project rules
+
+Rules that hold in this project only. Empty is a valid answer.
+
+| Rule | Why | Since |
+|---|---|---|
+| {…} | {…} | {YYYY-MM-DD} |
+
+## Enforcement
+
+- **Editor configuration:** `.editorconfig` at the repository root carries the machine-checkable subset.
+- **Analyzers:** {which, or "none"}.
+- **Verifier checks:** the standards check runs the greps listed in the stack file's Enforcement section, plus: {any project-specific grep, or "none"}.

package/.tfcore/templates/v4custom/app-deployment-checklist-tmpl.md

@@ -0,0 +1,86 @@
+<!-- tf-schema
+doc: deployment-checklist
+file: docs/{App}-Deployment-Checklist.md
+header: App, Hosting target, Pipeline document, Date, Proven
+section: Who does what | required
+section: Secrets and settings | required
+section: Before the first deploy | required
+section: Deploy | required
+section: After the deploy | required
+section: Rollback | required
+section: Routine operations | required
+section: Troubleshooting | required
+section: Proven | required
+budget: S 2500 4000 | M 2500 4000 | L 2500 4000
+rule: deploy-who-table
+rule: deploy-secrets-once
+rule: deploy-checkboxes
+rule: deploy-proven
+-->
+<!-- Authoring notes (agent only; never visible text).
+     One document per hosting target, produced after UAT from the owner's pipeline guidance document
+     and the Stack answers Q9 (hosting) and Q10 (production secrets and pipeline). Running the
+     application locally is NOT in it; that is the UsageGuide's Execution guide.
+     Every item in sections 3 to 6 is a checkbox ("- [ ]") with one action and one observable result;
+     no narrative paragraphs anywhere. Each secret or setting name appears in exactly one row of the
+     Secrets and settings table and is never re-described elsewhere. Proven says "never" until a real
+     deploy has been executed, then the date. Schema: docs/TechieFlow-Document-Schemas.md §3.10. -->
+
+# {App} — Deployment Checklist
+
+| | |
+|---|---|
+| App | {App} |
+| Hosting target | {one target: VPS, Docker host, IIS, Azure App Service, …} |
+| Pipeline document | {path of the owner's pipeline guidance document} |
+| Date | {YYYY-MM-DD} |
+| Proven | never |
+
+## 1. Who does what
+
+| Step | Done by |
+|---|---|
+| {Build and publish the artefact} | pipeline |
+| {Approve the release} | owner |
+
+## 2. Secrets and settings
+
+| Name | Where it is set | What breaks without it |
+|---|---|---|
+| {CONNECTION_STRING} | {host environment variable} | {the application cannot start} |
+
+## 3. Before the first deploy
+
+- [ ] {One action} — {the result that shows it worked}
+
+## 4. Deploy
+
+- [ ] {One action} — {the result that shows it worked}
+
+## 5. After the deploy
+
+- [ ] {The command to run} — {the output that proves it worked}
+
+## 6. Rollback
+
+- [ ] {One action} — {the result that shows it worked}
+
+A rollback does not undo: {database migrations; …}.
+
+## 7. Routine operations
+
+| Task | Command |
+|---|---|
+| {Restart the service} | `{command}` |
+
+## 8. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| {…} | {…} | {…} |
+
+## 9. Proven
+
+| What | Executed for real | When |
+|---|---|---|
+| {Deploy to the target} | no | — |

package/.tfcore/templates/v4custom/app-devguide-tmpl.md

@@ -1,167 +1,90 @@
-# {AppName} — Developer Guide (Screen-by-Screen Code Map)
-
-> {Verification-status banner — REQUIRED, set by the OBSERVE pass (devguide §5a). One of:}
-> ✅ **Runtime-verified {YYYY-MM-DD}** — exercised as: {roles}. Control render-status **and per-screen visual-status** below are **observed** (data renders + screen looks right), not inferred. Per-screen screenshots in `docs/screenshots/{AppName}/`.
-> ⚠ **STATIC-ONLY ({YYYY-MM-DD})** — built from code reading; **NOT yet runtime-verified**. Render/visual status is unconfirmed and no screenshots were captured until `*verify` runs against the running app.
-
-> **Purpose — this is the document a HUMAN developer uses to trace any screen, control, or number on the page all the way down to the database, so they can find and fix a bug, or verify that AI-generated code is actually correct.** The BRD explains *what* the app does; the Architecture explains *how the system is shaped*; the database design explains *the data*. **None of those tell a developer "the dashboard's Ruling-Planet chart comes from `DashboardService.GetRulingPlanets()` → `KundliRepository.QueryRulingPlanets()` → `usp_RulingPlanets`."** This guide does exactly that, per user role, per screen, down to the stored procedure or query.
->
-> It documents the **AS-BUILT code**, not the plan. Regenerate it with `*devguide {AppName}` after meaningful code changes (it is also refreshed automatically at handoff). It is a **human-readable** doc — it is rendered to HTML; it is NOT one of the AI checklists.
-
-<!-- AGENT-ONLY AUTHORING NOTES. Everything in this comment is an instruction to the DRAFTING
-     AGENT, not content for the document's human reader. Carry it into the generated document
-     ONLY as this HTML comment (or drop it entirely) — NEVER as visible text: the owner reads
-     the rendered HTML and must not see authoring instructions (generate-html.md strips any
-     that leaked from older templates). The two blockquotes ABOVE (verification-status banner +
-     Purpose) ARE reader-facing and stay visible.
-
-  DEPTH MANDATE (read before drafting): every screen entry must connect the visible UI to the
-  code that produces it: the Razor page/component (with file path), each meaningful CONTROL on
-  it, and the full DATA LINEAGE for each control/action — Razor component → service method →
-  data-access method → stored procedure name / SQL query. If a value is calculated, say where
-  and how. "It's handled in the service" is NOT acceptable — name the method and the file.
-  A developer who has never seen the code must be able to open this guide, find the screen,
-  and know exactly which files to open to fix a bug.
-
-  TWO RULES THAT KEEP THIS GUIDE TRUE (not hallucinated):
-  • Landing-truth — a screen's "Reached via" / where a role lands after login MUST be read from
-    the routing/redirect code (the NavigateTo(...) after login, the default @page "/", the auth
-    redirect) and cite file:line. NEVER infer it from the folder a page lives in or its name
-    (e.g. don't assume an Admin lands on an Admin Dashboard just because the page is under Admin/).
-  • Render-truth — confirm the data actually REACHES AND RENDERS in each control, not merely
-    that a method/proc exists. Check the @if guards, whether the query's columns map to the
-    model (case/underscore), computed getters that can throw/blank, and required component
-    parameters that must be declared (e.g. a grid's Pagination). Tag each control renders /
-    renders-empty (suspected defect — why) / {unresolved — TODO}; a suspected defect is also
-    logged to the checklist.
+<!-- tf-schema
+doc: devguide
+file: docs/{App}-DevGuide.md
+header: App, Kind, Size, Verified on, Date
+section: Architecture cheat-sheet | required | max 300
+section: Roles and menu map | app
+section: Screen-by-screen code map | required
+section: Cross-cutting flows | required
+section: Known issues | required
+entries: Screen-by-screen code map |
+per-entry: 300 450
+budget: S 4000 6000 | M 7000 10000 | L 7000 10000
+rule: entry-screenshot
+rule: entry-call-chain
+rule: entry-break-table
 -->
-
-## Table of Contents
-
-1. [How to use this guide](#how-to-use-this-guide)
-2. [Architecture cheat-sheet](#architecture-cheat-sheet)
-3. [Roles and menu map](#roles-and-menu-map)
-4. [Screen-by-screen code map](#screen-by-screen-code-map)
-5. [Cross-cutting flows](#cross-cutting-flows)
-6. [How to fix a bug with this guide](#how-to-fix-a-bug-with-this-guide)
-
----
-
-## How to use this guide
-
-- **Find your screen** in §4, grouped by user role. Each screen tells you the route, the Razor file, every control, and where each control's data comes from.
-- **Chasing a wrong number / missing data?** Find the control in that screen's *Data lineage* table → it names the service method → the data-access method → the stored proc / query. Open those files in order.
-- **Verifying AI-generated code?** Compare what this guide claims against the actual files. If a row says `usp_GetDashboardKpis` but the service actually calls inline SQL, the guide (or the code) is wrong — that mismatch is exactly the kind of hallucination this guide is meant to catch.
-- **For a large app (many roles / screens)** this guide is split into one file per role, kept together in the `docs/devguides/` subfolder (so they don't clutter `docs/`) — see the [index](#roles-and-menu-map). Open only the role file you need.
-- **Library variant (a library is documented by its PUBLIC SURFACE, not its sample app's screens — `devguide.md §0`).** Replace "Roles and menu map" with a **catalog by category/module**, and each item block documents **Purpose · Public API surface** (the consumer's contract, read at file:line) **· Internal flow** (file:line) **· Demo & usage** (the `demos/`/`samples/` page or sample code + screenshot where it has UI + a copy-paste snippet) **· Known issues**. The unit depends on what the package ships:
-  - **UI-component library** (e.g. TrBlazeUI) → **component-by-component**; API surface = every `[Parameter]`/`EventCallback`/`@typeparam`; categories = Inputs / Layout / Overlays / Data display / Feedback / Icons; snippet = `<Component … />`.
-  - **Service/SDK library** (e.g. TechieRag) → **service/API-by-service**; API surface = the `AddXxx(...)` DI registration + options + facade/interface method signatures; modules = e.g. Ingestion / Embedding / Query-RAG / LLM / Resilience+Token / Admin; snippet = `services.AddXxx(...)` + an `IFacade` call.
-
-  The "find your screen / chase a wrong number" guidance above reads as "find your component/service / chase a broken parameter or method". Any public item the sample app does **not** exercise is marked **`⚠ no demo coverage`** (a sample gap logged to the checklist) — the sample app is part of the library's deliverable, not just a backdrop.
+<!-- Authoring notes (agent only; never visible text).
+     A developer's map from each screen to the code that serves it, written so they can set breakpoints
+     and debug it. Documents the code AS BUILT, read at file:line; never inferred from folder names.
+     One `###` per screen (per component for a UI library, linked to the sample-app screen that shows it;
+     per public service for a service library: registration, call chain, where to break; owner 2026-09-06).
+     Each entry: the screenshot captured from the running app; one "Call chain:" line, page method to
+     service class and method to data-access class and method; a where-to-break table, one row per step:
+     file and line, function, the variable to watch, the value it should hold. Line numbers are as of
+     "Verified on"; the function name is what to search for when a line has moved.
+     Produced when the build completes the checklist; refreshed at handoff.
+     Large project: one DevGuide per phase (docs/{App}-DevGuide.md, docs/{App}-P2-DevGuide.md, …) with a
+     header row "| Phase | n of m |". Cross-cutting flows are written once, in phase 1; a later phase
+     repeats them only if it changed them, otherwise one line points at phase 1's section. -->
+
+# {App} — Developer Guide
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small, Medium or Large |
+| Verified on | {YYYY-MM-DD, the run the screenshots and line numbers come from} |
+| Date | {YYYY-MM-DD} |
 
 ## Architecture cheat-sheet
 
-Brief — just enough to navigate the code. (Full detail lives in `docs/{AppName}-Architecture.md`.)
-
-| Layer | Project / folder | What lives here | Example types |
-|-------|------------------|-----------------|---------------|
-| UI (Blazor) | `src/{AppName}.Web` | Razor pages/components, layouts, nav menu | `Pages/`, `Components/`, `Shared/NavMenu.razor` |
-| App services | `src/{AppName}.Application` (or `.Services`) | Business logic, orchestration | `DashboardService`, `KundliService` |
-| Data access | `src/{AppName}.Infrastructure` (or `.Data`) | Repositories, DbContext, Dapper queries | `KundliRepository`, `AppDbContext` |
-| Database | `database/` / `src/{AppName}.Db` | Tables, stored procs, seed scripts | `usp_*.sql`, migrations |
+```mermaid
+flowchart LR
+  UI["Pages"] --> Svc["Services"] --> Data["Data access"] --> DB[("Database")]
+```
 
-- **Stored-proc vs ORM vs inline SQL:** {state the project's convention — e.g. "reads go through stored procs `usp_*`; writes via EF Core SaveChanges" — fill from the actual code}.
-- **How a Razor component gets its data:** {e.g. "components inject a `*Service`; services inject a `*Repository`; repositories call `usp_*` via Dapper" — fill from the actual code}.
+| Layer | Project or folder | What lives here |
+|---|---|---|
+| UI | `src/{App}/Pages` | {…} |
+| Services | `src/{App}.Core/Services` | {…} |
+| Data access | `src/{App}.Core/Data` | {…} |
 
 ## Roles and menu map
 
-The app has these user roles (from `docs/{AppName}-UsageGuide.md` test-users + the authorization policies in code). For a **split** guide, this index and every role file live together in `docs/devguides/`, and each role links to its own file (relative `./{AppName}-DevGuide-{Role}.md`).
-
-| Role | Test user (see UsageGuide) | Authorization (policy / role claim in code) | Menus this role sees | Detail file |
-|------|----------------------------|----------------------------------------------|----------------------|-------------|
-| {App Admin} | {admin@…} | {`[Authorize(Roles="Admin")]` / policy name} | {Dashboard, Users, Settings, …} | [{App}-DevGuide-AppAdmin.md](./{AppName}-DevGuide-AppAdmin.md) |
-| {App Manager} | {manager@…} | {…} | {Dashboard, Reports, …} | [{App}-DevGuide-AppManager.md](./{AppName}-DevGuide-AppManager.md) |
-| {End user} | {user1@…} | {…} | {Home, Profile, …} | [{App}-DevGuide-EndUser.md](./{AppName}-DevGuide-EndUser.md) |
-
-For each role, list the **menu → menu-item → screen** mapping so a developer knows, for a given role, what appears and what each item opens:
-
-### {Role} — menu structure
-- **{Menu group}** → **{Menu item}** → opens `{Route}` (`{RazorFile}`) — see [§4 {Role} · {Screen}](#role--screen)
-- ...
+| Role | Test user | Menu items and the screen each opens |
+|---|---|---|
+| {Role} | {user #} | {Menu → screen (`/route`)} |
 
 ## Screen-by-screen code map
 
-One subsection per screen, grouped by role, in navigation order. **In a split guide, the per-role file carries only that role's screens.** Repeat the block below for every screen.
-
----
-
-### {Role} · {Screen / Page name}
+### {Screen name} (`/route`)
 
-- **Route:** `{@page "/dashboard"}`
-- **Razor file:** `src/{AppName}.Web/Pages/Dashboard.razor` (+ code-behind `Dashboard.razor.cs` if present)
-- **Reached via:** {Menu group → menu item}; **Log in as:** {test user from UsageGuide}
-- **What this screen does:** {one or two lines}
-- **Visual status:** {✅ looks-right (runtime-confirmed {date}) | ⚠ visual-broken (DEFECT — {what} @ {width}, {date}) | static-only (unconfirmed)}
+![{Screen name}](screenshots/{App}/{screen-slug}.png)
 
-**Screenshot** — the real rendered screen (captured by the OBSERVE pass, devguide §5a). Review this for layout/overlap issues.
+**Call chain:** `{Page}.razor.cs:{HandleX}` → `{Service}.{Method}` → `{DataAccess}.{Method}` → `{table or procedure}`
 
-![{Screen} — {Role}](../screenshots/{AppName}/{role}-{screen-slug}.png)
+| File and line | Function | Watch | Expected value |
+|---|---|---|---|
+| `src/{App}/Pages/{Page}.razor.cs:127` | `HandleX` | `aModel.Email` | the email typed in the box |
+| `src/{App}.Core/Services/{Service}.cs:54` | `{Method}` | `vResult` | {…} |
+| `src/{App}.Core/Data/{DataAccess}.cs:31` | `{Method}` | `vRows.Count` | {…} |
 
-<!-- Path is relative to where this guide lives: `screenshots/...` from docs/, `../screenshots/...` from docs/devguides/. STATIC-ONLY guides omit the image (no shot captured). -->
-
-
-**Screen flowchart** — show every meaningful control on the screen and where its data comes from. (Follow the Mermaid authoring rules in `.tfcore/templates/v4custom/html-render-shell.md §5.5` — quote every label, never use `end` as a node id.)
-
-```mermaid
-flowchart TD
-  P["Dashboard.razor"] --> C1["Kundli list (grid)"]
-  P --> C2["Ruling-Planet chart"]
-  P --> C3["Ruling-Planet table"]
-  C1 --> S1["DashboardService.GetKundliList()"]
-  C2 --> S2["DashboardService.GetRulingPlanets()"]
-  C3 --> S2
-  S1 --> R1["KundliRepository.QueryList()"]
-  S2 --> R2["KundliRepository.QueryRulingPlanets()"]
-  R1 --> DB1[("usp_GetKundliList")]
-  R2 --> DB2[("usp_RulingPlanets")]
-```
-
-**Controls on this screen**
-
-| Control | Type | Purpose | Populated / calculated by |
-|---------|------|---------|---------------------------|
-| {Kundli list} | {grid} | {lists kundlis for the tenant} | {`DashboardService.GetKundliList()`} |
-| {Ruling-Planet chart} | {chart} | {shows current ruling planets} | {`DashboardService.GetRulingPlanets()` — values computed in `RulingPlanetCalculator`} |
-
-**Data lineage** — the full path for each control/action. This is the heart of the guide.
-
-| Control / Action | Razor component (file) | Service method (file) | Data-access method (file) | Stored proc / Query | Notes / calculation |
-|------------------|------------------------|-----------------------|---------------------------|---------------------|---------------------|
-| {Load Kundli list} | {`Dashboard.razor` line ~40} | {`DashboardService.GetKundliList()`} | {`KundliRepository.QueryList()`} | {`usp_GetKundliList`} | {paged; tenant-filtered} |
-| {Ruling-Planet chart} | {`Dashboard.razor` `<RulingPlanetChart>`} | {`DashboardService.GetRulingPlanets()`} | {`KundliRepository.QueryRulingPlanets()`} | {`usp_RulingPlanets`} | {planet strengths computed in `RulingPlanetCalculator.Compute()` from the proc rows} |
-| {Save / submit action} | {…} | {…} | {…} | {…} | {…} |
-
-**Business rules / calculations on this screen**
-- {Any non-trivial computation, validation, or derived value — name the method that does it.}
-
-**Known issues / gotchas**
-- {Anything fragile, any TR-NNN library gap, any `Blocked` REQ touching this screen.}
-
-_(Repeat the `### {Role} · {Screen}` block for every screen the role can reach.)_
-
----
+**Calculations on this screen:** {method name and what it computes, or "none"}
 
 ## Cross-cutting flows
 
-Flows that span screens or run in the background (auth/login, token refresh, background jobs, notifications, file ingestion). One subsection each with a Mermaid diagram and the same service → data-access → proc lineage. Skip if the app has none.
+### Sign-in
+**Call chain:** {…}
+
+| File and line | Function | Watch | Expected value |
+|---|---|---|---|
+| {…} | {…} | {…} | {…} |
 
-## How to fix a bug with this guide
+### Configuration, logging, errors
+{One line each: where it is wired, file and line.}
 
-1. Reproduce the bug and note **which screen** and **which control** shows it.
-2. Open §4, find that role + screen, find the control in the **Data lineage** table.
-3. Walk the lineage **top-down**: Razor component → service method → data-access method → stored proc/query. The bug is in one of those four.
-4. If the visible value is *calculated*, the lineage row names the calculator method — check it.
-5. After fixing, re-run the screen's walkthrough in `docs/{AppName}-UsageGuide.md`, then re-generate this guide (`*devguide {AppName}`) if the code path changed.
+## Known issues
 
----
-_Generated/refreshed by `*devguide {AppName}`. Reflects the code as built at the time shown in the subtitle — regenerate after code changes._
+- {one line each, with the REQ or feedback id}

package/.tfcore/templates/v4custom/app-phases-tmpl.md

@@ -0,0 +1,35 @@
+<!-- tf-schema
+doc: phases
+file: docs/{App}-Phases.md
+header: App, Kind, Size, Date
+section: Phases | required
+budget: S 300 600 | M 300 600 | L 300 600
+rule: phases-table
+-->
+<!-- Authoring notes (agent only; never visible text).
+     Large projects only. One row per phase; each phase fits Medium on its own (at most 20 screens,
+     100 requirements). Phase 1 keeps the plain file names (docs/{App}-BRD.md, -Checklist, -UIDesign,
+     -DevGuide); phase 2 onward are docs/{App}-P2-BRD.md and so on. BRD-N and REQ- ids run on across
+     phases and are never reused, so the ranges never overlap. An item added to an earlier phase after a
+     later phase exists takes the next free id and the row gets a second range: "BRD-1 to BRD-73, BRD-111 to BRD-118". Every screen sits in exactly one phase;
+     the screens of a phase are exactly the "### Screen:" entries of that phase's UIDesign.
+     Status is planned, building or done. The phase being worked is appPhase in core-config.yaml
+     (bash .tfcore/utils/tf-day1-files.sh {App} --phase N); handoff moves it on.
+     tf-doc-check.sh --app {App} refuses a screen in two phases, an id in two phases, a BRD id outside
+     its phase's range, and a phase row without its BRD file. -->
+
+# {App} — Phases
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app |
+| Size | Large |
+| Date | {YYYY-MM-DD} |
+
+## Phases
+
+| Phase | Name | Screens | BRD range | Status |
+|---|---|---|---|---|
+| 1 | {Name} | {Screen, Screen, Screen} | BRD-1 to BRD-{N} | planned |
+| 2 | {Name} | {Screen, Screen} | BRD-{N+1} to BRD-{M} | planned |