@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/templates/v4custom/app-decision-request-tmpl.md

@@ -0,0 +1,85 @@
+<!-- tf-schema
+doc: decision-request
+file: docs/{App}-Decision-Request.md
+header: App, Written, Waiting on
+section: What happened | required | max 250
+section: What I need you to decide | required
+section: What I do when you answer | required | max 200
+section: Copy this back to me | required | max 250
+entries: What I need you to decide |
+per-entry: 150 300
+rule: entry-decision-options
+rule: entry-recommendation
+rule: paste-back-block
+rule: no-glossary
+target-lines: 120
+max-lines: 260
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     WHEN TO WRITE ONE. A command has hit a choice only the owner can make and the
+     answer changes what gets built. Write this file, render it to HTML, and say one
+     line in the terminal: which file to open, and that it holds N decisions. Never
+     argue the decision out in the terminal — that fills the context and buries the
+     question. Everything the owner needs is in the file.
+
+     WHO READS IT. The owner, and nobody else. No task ever loads a Decision Request
+     as input, and it is never named in core-config.yaml. The way the answer comes
+     back is the owner pasting the block from §"Copy this back to me" — that pasted
+     prompt is the input, and the file's job is done the moment it is answered.
+
+     HOW IT IS WRITTEN. Plain, simple English, the way you would explain it to
+     someone who has not read a line of the framework. No coined terms. No framework
+     shorthand. No requirement ids in the question itself — name the thing, not its
+     number. If a word needs defining, it is the wrong word: change it. A glossary
+     section is refused by `rule: no-glossary`, because a document that has to teach
+     its own vocabulary before it can ask its question was written for the wrong
+     reader.
+
+     WHAT IT IS NOT. Not a defect report — that is the feedback file. Not an
+     architecture decision record — that is DECISIONS.md, written after the fact.
+     This file asks a question and then stops existing: when it is answered, it moves
+     unchanged to docs/OldDocs/ and the live name is free for the next one.
+
+     ONE LIVE FILE. All open decisions go in this one file as separate entries. Never
+     a dated copy, never a -v2. -->
+
+# {App} — decisions I need from you
+
+| | |
+|---|---|
+| App | {App} |
+| Written | {YYYY-MM-DD} |
+| Waiting on | {N} decisions. Nothing has been changed yet. |
+
+## What happened
+
+{Two short paragraphs, at most 250 words. What was being done, what stopped it, and
+why the choice is yours rather than something to be worked out. Plain words.}
+
+## What I need you to decide
+
+### {1. The short name of the choice}
+
+{One paragraph: what the choice actually is, in plain words.}
+
+| Option | What happens | What it costs |
+|---|---|---|
+| **A — {name}** | {what the project looks like afterwards} | {work, and what is given up} |
+| **B — {name}** | {what the project looks like afterwards} | {work, and what is given up} |
+
+**My recommendation: {A}** — {one sentence saying why.}
+
+## What I do when you answer
+
+{The steps, in order, one line each. What gets edited, what gets re-checked, roughly
+how long. So the answer is given with the consequences in view.}
+
+## Copy this back to me
+
+{One fenced block per decision. Each block is a complete instruction that stands on
+its own — the owner pastes it and nothing else needs saying.}
+
+```
+{App}: decision 1 — go with option A. {The one thing that changes.}
+```

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-library-feedback-tmpl.md

@@ -1,31 +1,86 @@
-<!-- ============================================================
-     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>
+<!-- tf-schema
+doc: feedback
+file: docs/{App}-{Upstream}-Feedback.md
+header: App, Upstream, Updated
+section: Summary | required | max 200
+section: Entries | required
+section: Replies from* | optional
+section: Resolution status* | optional
+entries: Entries |
+per-entry: 120 250
+rule: entry-feedback-fields
+rule: entry-blocks-line
+rule: feedback-blocking-count
+rule: no-glossary
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     ONE FEEDBACK FILE PER UPSTREAM — never a combined file. Each upstream owns a
+     separate codebase and receives only its own file:
+
+       docs/{App}-TrBlazeUI-Feedback.md    ids TR-NNN        (the UI library)
+       docs/{App}-TechieRag-Feedback.md    ids TR-RAG-NNN    (the RAG library)
+       docs/{App}-TechieFlow-Feedback.md   ids TF-NNN        (the framework itself)
+
+     A future library {LibName} gets docs/{App}-{LibName}-Feedback.md with its own
+     prefix. Create the file on the FIRST entry for that upstream.
+
+     REPORTING IS NEVER REFUSED. If something upstream is wrong, file it — whatever
+     the severity, whatever the day. What this schema constrains is the SHAPE, not
+     the right to report:
+
+     1. Every entry says whether it BLOCKS the work, in one word. That is the field
+        the owner reads first, and it decides whether the run stops.
+     2. A non-blocking entry is filed and the work CONTINUES. Never stop, never ask,
+        never write a page of analysis about it mid-run. One entry, then carry on.
+     3. 250 words for the REPORT, hard: the eight fields, and nothing else. An entry is
+        a bug report, not an essay. Evidence goes in a code block, not in prose.
+        Working-out that is genuinely worth keeping goes under a `#### Detail` heading
+        inside the entry, and is not counted — so a thorough analysis costs nothing and
+        an unreadable entry is still refused.
+     4. Plain English. No coined terms, no framework shorthand, no word the reader
+        would have to look up. If you find yourself writing a glossary, the words
+        are wrong — change the words. `rule: no-glossary` refuses the section.
+     5. A decision for the owner does NOT go in this file. It goes in a Decision
+        Request (`app-decision-request-tmpl.md`), which is written for the owner and
+        carries the prompt to paste back.
+
+     "Replies from {Upstream}" holds the upstream team's answers, newest block first.
+     Ids are append-only and never renumbered. A fixed entry keeps its body and gains
+     a resolution line; the record of what was wrong is the point. -->
+
+# {Upstream} feedback — found while building {App}
+
+| | |
+|---|---|
+| App | {App} |
+| Upstream | {Upstream} |
+| Updated | {YYYY-MM-DD} |
+
+## Summary
+
+{N} entries: {n} blocking now, {n} filed and not blocking, {n} fixed upstream.
+
+{One sentence naming what is blocked right now, or the sentence "Nothing is blocked."}
+
+## Entries
+
+### {TF-001} — {one line saying what is wrong}
+
+- **Severity:** blocker | major | minor
+- **Blocks:** yes — {the row or command that cannot proceed} | no — {what was done instead, and the work carried on}
+- **Repro:** {the shortest command or snippet that shows it}
+- **Expected:** {what should have happened}
+- **Actual:** {what happened}
+- **Encountered in:** {REQ-UI-013, or the command that was running}
+- **Workaround:** {what was done in this project, or "none"}
+- **Suggested fix:** {one concrete change for the upstream team}
+
+#### Detail
+
+{Optional, and not counted against the 250 words: the root cause, the reasoning, the
+longer version of the fix. Everything above must stand on its own without it.}
+
+## Replies from {Upstream}
+
+<!-- The upstream team's answers, newest block first. Left in full: this is the record. -->

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 |