@techierathore/techieflow 1.0.0

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

@@ -0,0 +1,204 @@
+# {AppName} — Business Requirements
+
+<!-- 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).
+
+  STABLE IDS: every requirement has a BRD-{N} ID. IDs are append-only across revisions.
+
+  DEPTH MANDATE (read before drafting): this is a HUMAN document, read as rendered HTML by the
+  product owner. It is NOT the coding checklist (that's docs/{AppName}-Checklist.md / split-brd
+  output). One-line entries belong ONLY in §10's requirements ledger. Every other section is
+  full prose, tables, and Mermaid diagrams. §9 Feature catalog is the heart of the document —
+  one detailed subsection per feature, with screens, workflows, and a diagram wherever the flow
+  is non-trivial. When harvesting existing source docs, this document must be an
+  information-preserving SUPERSET of their requirements content: carry their tables, matrices,
+  screen inventories, and menus forward (updated, not summarized away). If a reader of the old
+  doc would miss something in this one, the draft is wrong.
+
+  MERMAID MANDATE: every diagram MUST follow the authoring rules in
+  .tfcore/templates/v4custom/html-render-shell.md §5.5 — quote every node/edge/subgraph label
+  (A["Order Service (v2)"], not A[Order Service (v2)]) and never use `end` as a node id.
+  Unquoted special characters ( ( ) / & : , … ) in flowchart labels are the #1 cause of
+  "Syntax error" diagrams in the rendered HTML.
+-->
+
+
+## Table of Contents
+
+<!-- Auto-maintained by the analyst/day-1 tasks. Use the slug rule from .tfcore/templates/v4custom/html-render-shell.md §1 so links work in both MD and rendered HTML. Update this list whenever you add/rename a section. List each `### F-…` catalog entry as an H3 sub-entry under Feature catalog. -->
+
+1. [Executive summary](#executive-summary)
+2. [Business objectives](#business-objectives)
+3. [Scope](#scope)
+4. [Development status](#development-status)
+5. [Stakeholders / users](#stakeholders-users)
+6. [Context diagram](#context-diagram)
+7. [User journey — primary use case](#user-journey-primary-use-case)
+8. [Component sketch](#component-sketch)
+9. [Feature catalog](#feature-catalog)
+10. [Functional requirements (BRD ledger)](#functional-requirements-brd-ledger)
+11. [Non-functional requirements](#non-functional-requirements)
+12. [Constraints & assumptions](#constraints-assumptions)
+13. [Success metrics](#success-metrics)
+14. [Risks](#risks)
+15. [Glossary](#glossary)
+
+## 1. Executive summary
+<2-3 paragraphs: what we're building/changing and why it matters.>
+
+## 2. Business objectives
+- <measurable objective 1>
+- <measurable objective 2>
+
+## 3. Scope
+**In scope:** …
+**Out of scope (explicit):** …
+
+## 4. Development status
+
+<!-- SNAPSHOT (point-in-time) of what is BUILT vs PENDING, at the feature level — the first thing a
+     reader of an existing app wants to know. This is a HUMAN summary, NOT a competing source of truth:
+     the LIVE per-requirement status lives in PROJECT-STATUS.md + the one checklist's
+     "Requirements Status" table. Do NOT duplicate per-REQ status here — one row per feature only.
+       • Brownfield: fill from the migrated dev-plan and/or the code scan (what actually compiles/runs).
+         Mirror the phase tags used in the checklists.
+       • Greenfield: this is the build ROADMAP — every row is "Planned" with its target phase.
+     One row per §9 Feature-catalog F-code; group/order by phase. Keep the as-of date honest.
+     AUTO-MAINTAINED after day-1: the status gate (every build/verify/handoff phase) and
+     *refresh-status re-derive this table from the checklists and re-render the HTML, so it
+     tracks reality without manual edits — see _status-update-gate.md item 9. -->
+
+**Snapshot as of {YYYY-MM-DD}.** Live, per-requirement status: see `PROJECT-STATUS.md` and the **Requirements Status** table in `docs/{AppName}-Checklist.md`.
+
+| Feature (F-code) | Phase | Status | % | Notes |
+|------------------|-------|--------|---|-------|
+| F-{CODE}: {name} | {0 / 1 / 2 … or MVP} | Done | 100 | {what works} |
+| F-{CODE}: {name} | {phase} | Partial | {0–100} | {what's done / what's left} |
+| F-{CODE}: {name} | {phase} | Planned | 0 | {not started} |
+
+**Legend:** **Done** = shipped & working · **In progress** = actively being built · **Partial** = some sub-features done, others pending · **Planned** = not started. (Maps to the checklist's `Done (pre-existing)` / `In Progress` / `PARTIAL` / `Not Started`.)
+
+## 5. Stakeholders / users
+<!-- Full persona detail, not just a 2-row table. For each persona: role mapping (if an external auth/licensing system is involved), responsibilities, key screens, registration/onboarding path. If the app has license tiers / feature gating, include the full license & feature matrix here or as its own H2 (and add it to the TOC). -->
+| Role | Needs |
+|------|-------|
+| End user | … |
+| Admin    | … |
+
+## 6. Context diagram
+```mermaid
+flowchart LR
+  User(["End User"]) --> App["{AppName}"]
+  App --> DB[("Database")]
+  App --> LLM[/"LLM Provider"/]
+```
+
+## 7. User journey — primary use case
+```mermaid
+sequenceDiagram
+  actor U as User
+  participant W as Web UI
+  participant A as App API
+  U->>W: action
+  W->>A: request
+  A-->>W: response
+  W-->>U: result
+```
+
+## 8. Component sketch
+```mermaid
+flowchart TB
+  UI["Blazor UI — TrBlazeUI"] --> API["ASP.NET API"]
+  API --> SQL[("SQL")]
+  API --> Rag["RAG — TechieRag"]
+  Rag --> Vec[("Vector store")]
+```
+
+## 9. Feature catalog
+
+<!-- THE HUMAN-READABLE HEART OF THE BRD. One `### F-{CODE}: {Name}` subsection per
+     feature / capability area. A real app typically has 8–25 entries; depth scales with
+     the app, NOT with a template quota. Repeat the skeleton below per feature.
+     Per feature include, where applicable:
+       - personas + phase/priority
+       - 1-2 paragraphs of what/why
+       - screens & routes table
+       - workflow / processing steps (numbered), inputs → outputs
+       - a Mermaid diagram for any multi-step or multi-actor flow (flowchart or
+         sequenceDiagram) — generic features (simple CRUD lists) may skip the diagram
+       - the BRD-N IDs this feature owns (forward links into §10)
+     Every F-code here MUST appear as a row in the §4 Development status table. -->
+
+### F-{CODE}: {Feature name}
+
+**Personas:** <who uses it> · **Phase:** <0/1/2/… or MVP/Later>
+
+<1-2 paragraphs: what this feature does and why it exists.>
+
+| Screen | Route | Description |
+|--------|-------|-------------|
+| … | `/…` | … |
+
+**Workflow:**
+1. <step>
+2. <step>
+
+```mermaid
+flowchart LR
+  A["input"] --> B{"decision"} --> C["output"]
+```
+
+**Requirements:** BRD-x, BRD-y (see §10)
+
+## 10. Functional requirements (BRD ledger)
+
+<!-- The machine-traceable ledger consumed by *split-brd and the coding pipeline.
+     One line per discrete capability, `<actor> can <action>` or `system shall <behavior>`.
+     Each line names its catalog feature: `(F-CODE)`. The count scales with the app —
+     one BRD per capability, NEVER merge capabilities to keep the list short. -->
+
+- **BRD-1** — <one-line requirement> *(F-{CODE})*
+- **BRD-2** — <one-line requirement> *(F-{CODE})*
+
+## 11. Non-functional requirements
+<!-- Keep the BRD-N IDs, but give each NFR its target table when there are concrete numbers
+     (latency, uptime, concurrency, import throughput), as a human reader expects.
+     The Observability/logging NFR below is a TechieFlow STANDING requirement — it appears in
+     EVERY .NET app's BRD (web, API, MAUI, desktop, console, background service), never gets
+     dropped, and split-brd turns it into a REQ-NFR row like any other NFR.
+
+     PERFORMANCE — the `perf-budget:` line is MACHINE-READ. verify-phase §4c grades a REQ on
+     speed if and ONLY if it carries one, in exactly this grammar:
+         perf-budget: <p50|p95|max> <ttfb|load> <= <N>ms [@ concurrency <N>]
+     Omit it and the perf gate simply never fires for that REQ — which is the correct outcome
+     when there is no agreed number. Do NOT invent a budget to make the row look complete: a
+     threshold nobody agreed to produces failures nobody asked for, and the first false failure
+     is the moment gate verdicts stop being believed. Write one only where the owner states it.
+     Prose like "should feel fast" is not a budget and is deliberately not gradeable. -->
+- **BRD-N** — Performance: …
+      <!-- e.g.  Public pages stay responsive under normal load.
+                 perf-budget: p95 load <= 2000ms @ concurrency 1
+                 perf-budget: p95 ttfb <= 500ms @ concurrency 50   -->
+
+- **BRD-N+1** — Security: …
+- **BRD-N+2** — Accessibility: …
+- **BRD-N+3** — Observability: Serilog file-based logging in every executable head — rolling file sink under `logs/`, wired at startup, unhandled exceptions logged (see Coding Standards §Logging).
+
+## 12. Constraints & assumptions
+- …
+
+## 13. Success metrics
+- …
+
+## 14. Risks
+| Risk | Likelihood | Impact | Mitigation |
+
+## 15. Glossary
+- TrBlazeUI, TechieRag, REQ-UI-*, REQ-FN-*, REQ-RAG-*, REQ-NFR-*
+
+---
+Last updated: {YYYY-MM-DD}
+Highest BRD ID: BRD-{N}

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

@@ -0,0 +1,90 @@
+# {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)
+
+## 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
+
+<!-- ============================================================
+     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.
+     ============================================================ -->
+
+| 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
+
+<!-- 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.
+
+     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`)
+
+<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
+
+<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>.
+
+## Non-functional
+
+<a id="d-req-nfr-001"></a>
+- **REQ-NFR-001** — <perf / security / accessibility>.

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

@@ -0,0 +1,33 @@
+# {AppName} — Claude Code session memory
+
+<!-- Since 2026-08-20 the harness-neutral project memory lives in AGENTS.md
+     (app-agents-md-tmpl.md — required reading, hard rules, project basics,
+     REQ prefixes, verification, slash-command table). Claude Code pulls it in
+     through the @import below; OpenCode auto-loads AGENTS.md directly and
+     never reads this file. Keep ONLY Claude-specific material here.
+     AGENTS.md is committed; this file stays gitignored. -->
+
+@AGENTS.md
+
+## Permissions and tool preference (read before using Bash)
+
+`.claude/settings.json` auto-allows every dedicated tool (Read, Edit, Write, Glob, Grep, MultiEdit, Task, WebFetch, WebSearch, TodoWrite, NotebookEdit) and **all Bash** (bare `Bash` allow). Only deletes (`rm`, `rmdir`) and `sudo` prompt; **`git` / `gh` are DENIED** (Hard rule 1 — git is manual; a PreToolUse hook also blocks compound forms like `cd x && git log`); catastrophic `rm -rf` paths are denied.
+
+**Still: never reach for bash for file inspection or file writing.** The dedicated tools are faster, diff-aware, and keep the transcript readable:
+
+| Want to | Bash (avoid) | Use this tool instead |
+|---------|--------------|------------------------|
+| Check if a file exists | `if [ -f x ]; then ...` | **Read** — returns content or "file does not exist" |
+| Get file size / mtime | `wc -c < x`, `date -r x` | **Read** (you usually want content anyway) — or skip mtime entirely and use today's date |
+| Write a file | `cat <<EOF > x` or `echo … > x` | **Write** |
+| Edit a file | `sed -i 's/a/b/' x` | **Edit** with old_string / new_string |
+| Find files by pattern | `find . -name '*.cs'` | **Glob** |
+| Search file contents | `grep -r pattern src/` | **Grep** |
+| 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.
+
+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".
+
+Reserve Bash for things that genuinely need a shell: `dotnet build`, `dotnet test`, `dotnet run`, `npm install`, `winrun "..."`, `playwright …`, single-command file listings like `ls src/`. Anything more complex than a single command — use a dedicated tool.

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

@@ -0,0 +1,167 @@
+# {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.
+-->
+
+## 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.
+
+## 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 |
+
+- **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}.
+
+## 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)
+- ...
+
+## 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}
+
+- **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)}
+
+**Screenshot** — the real rendered screen (captured by the OBSERVE pass, devguide §5a). Review this for layout/overlap issues.
+
+![{Screen} — {Role}](../screenshots/{AppName}/{role}-{screen-slug}.png)
+
+<!-- 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.)_
+
+---
+
+## 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.
+
+## How to fix a bug with this guide
+
+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.
+
+---
+_Generated/refreshed by `*devguide {AppName}`. Reflects the code as built at the time shown in the subtitle — regenerate after code changes._

package/.tfcore/templates/v4custom/app-editorconfig-tmpl.editorconfig

@@ -0,0 +1,44 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.cs]
+# File-scoped namespaces
+csharp_style_namespace_declarations = file_scoped:warning
+
+# Async suffix
+dotnet_naming_rule.async_methods_end_in_async.severity = warning
+dotnet_naming_rule.async_methods_end_in_async.symbols  = async_methods
+dotnet_naming_rule.async_methods_end_in_async.style    = end_in_async
+dotnet_naming_symbols.async_methods.applicable_kinds = method
+dotnet_naming_symbols.async_methods.required_modifiers = async
+dotnet_naming_style.end_in_async.required_suffix = Async
+dotnet_naming_style.end_in_async.capitalization = pascal_case
+
+# Prefer var
+csharp_style_var_for_built_in_types     = true:warning
+csharp_style_var_when_type_is_apparent  = true:warning
+csharp_style_var_elsewhere              = true:warning
+
+# Forbid _underscore on private fields
+dotnet_naming_rule.private_fields_no_underscore.severity = warning
+dotnet_naming_rule.private_fields_no_underscore.symbols  = private_fields
+dotnet_naming_rule.private_fields_no_underscore.style    = pascal_no_underscore
+dotnet_naming_symbols.private_fields.applicable_kinds           = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+dotnet_naming_style.pascal_no_underscore.required_prefix =
+dotnet_naming_style.pascal_no_underscore.capitalization  = pascal_case
+
+# Nullable reference types
+dotnet_diagnostic.CS8600.severity = warning
+dotnet_diagnostic.CS8602.severity = warning
+dotnet_diagnostic.CS8603.severity = warning
+
+# Suppress StyleCop conflicts (uncomment if StyleCop.Analyzers added)
+# dotnet_diagnostic.SA1101.severity = none   # don't require this. qualification

package/.tfcore/templates/v4custom/app-library-feedback-tmpl.md

@@ -0,0 +1,31 @@
+<!-- ============================================================
+     ONE FEEDBACK FILE PER LIBRARY — never a combined file.
+     TrBlazeUI and TechieRag are separate codebases with separate
+     teams; each team receives (or pulls) only its own file:
+       docs/{AppName}-TrBlazeUI-Feedback.md  (issue IDs TR-NNN)
+       docs/{AppName}-TechieRag-Feedback.md  (issue IDs TR-RAG-NNN)
+     A future library {LibName} gets docs/{AppName}-{LibName}-Feedback.md
+     with its own ID prefix (WORKFLOW.html §9.1).
+     Create a library's file on the FIRST issue for that library;
+     substitute {Library} and the ID prefix below.
+     ============================================================ -->
+
+# {Library} Feedback — surfaced during {AppName}
+
+## Summary (filled by /flow-master on consolidation)
+- 0 blockers, 0 major, 0 minor, 0 nice-to-have
+- Last consolidated: {YYYY-MM-DD}
+
+## Issues
+
+<!-- Append entries as gaps are found. IDs are append-only, never renumbered.
+     TrBlazeUI → TR-NNN · TechieRag → TR-RAG-NNN -->
+
+### TR-001 — <short title>
+- **Severity:** blocker | major | minor | nice-to-have
+- **Repro:** <minimal code snippet>
+- **Expected:** …
+- **Actual:** …
+- **Encountered in:** REQ-UI-013
+- **Workaround:** <what you did in app code>
+- **Suggested fix:** <hypothesis for the library team>

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

@@ -0,0 +1,54 @@
+# {AppName} — Product Guide
+
+> **Audience: end users (not developers).** This is the how-to-use-the-app manual — task-oriented, screenshot-illustrated, plain language. It explains *what each screen is for* and *how to do each thing*, not how the code works (that's the DevGuide). It is a HUMAN document → always written as markdown AND rendered to HTML.
+
+## Table of Contents
+
+<!-- Auto-maintained. Slug rule: .tfcore/templates/v4custom/html-render-shell.md §1. List each `## <Role/Area>` and its `### <Feature/Screen>` sub-entries. -->
+
+1. [Welcome](#welcome)
+2. [Getting started](#getting-started)
+3. [Roles at a glance](#roles-at-a-glance)
+4. [Using {AppName}](#using-appname)
+
+## Welcome
+
+<one short paragraph: what {AppName} is and who it's for, in product language drawn from the BRD §1/§9 — no jargon, no architecture.>
+
+## Getting started
+
+- **Sign in:** {how to reach the app + log in; the sign-in screen with its screenshot}.
+- **What you'll see first:** {the landing screen per role — keep it accurate to the real post-login landing, the same one the DevGuide's LANDING-TRUTH established}.
+
+![Sign in](./screenshots/{AppName}/{anon}-login.png)
+
+## Roles at a glance
+
+<one row per user role/persona, plain-language "what this role can do" — derived from the BRD personas + the DevGuide's role→menu map.>
+
+| Role | What you can do |
+|------|-----------------|
+| {Role} | {one line} |
+
+## Using {AppName}
+
+<!-- One `## {Role or Area}` section, then one `### {Feature / Screen}` block per screen, in the order a
+     user would naturally use them (navigation order from the DevGuide's menu map). Each block is
+     task-oriented and carries the REAL screenshot captured by the DevGuide OBSERVE pass. For a large
+     app this section is split per role into docs/productguides/ (see the task). -->
+
+### {Feature / Screen name}
+
+**What it's for:** {one or two plain sentences — the user benefit, from the BRD feature catalog.}
+
+**How to use it:**
+1. {step — what the user clicks/enters}
+2. {step}
+3. {what they should see / the result}
+
+![{Screen name}](./screenshots/{AppName}/{role}-{screen-slug}.png)
+
+**Tips & notes:** {gotchas, limits, anything from the UsageGuide's known-limitations that a user should know — plain language, no defect IDs.}
+
+<!-- Repeat the ### block for every user-facing screen/feature. Omit purely internal/admin-plumbing
+     screens that an external user never touches, unless the role section is the admin guide. -->