@techierathore/techieflow 1.0.2 → 1.0.3

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

@@ -1,54 +1,57 @@
-# {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)
+<!-- tf-schema
+doc: productguide
+file: docs/{App}-ProductGuide.md
+header: App, Size, Date
+section: Welcome | required | max 150
+section: Getting started | required
+section: Roles at a glance | optional
+section: Using* | required
+section: Troubleshooting | optional
+entries: Using* |
+rule: entry-steps
+rule: entry-screenshot
+budget: S 2500 3500 | M 4500 6500 | L 4500 6500
+-->
+<!-- Authoring notes (agent only; never visible text).
+     The end user's manual: plain language, task by task, one real screenshot per task, no code and no
+     requirement ids. "Roles at a glance" only when there is more than one role. The Using section is
+     titled "Using {App}"; one `###` per task in the order a user meets them. -->
+
+# {App} — Product Guide
+
+| | |
+|---|---|
+| App | {App} |
+| Size | Small, Medium or Large |
+| Date | {YYYY-MM-DD} |
 
 ## 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.>
+{What it does and who it is for, at most 150 words.}
 
 ## 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}.
+1. {Open … and sign in.}
+2. {What you see first.}
 
-![Sign in](./screenshots/{AppName}/{anon}-login.png)
+![Sign in](screenshots/{App}/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}
+## Using {App}
 
-**What it's for:** {one or two plain sentences — the user benefit, from the BRD feature catalog.}
+### {Task name}
 
-**How to use it:**
-1. {step — what the user clicks/enters}
+1. {step}
 2. {step}
-3. {what they should see / the result}
+3. {what you should see}
 
-![{Screen name}](./screenshots/{AppName}/{role}-{screen-slug}.png)
+![{Task name}](screenshots/{App}/{screen-slug}.png)
 
-**Tips & notes:** {gotchas, limits, anything from the UsageGuide's known-limitations that a user should know — plain language, no defect IDs.}
+## Troubleshooting
 
-<!-- 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. -->
+- {problem}: {what to do}

package/.tfcore/templates/v4custom/app-project-status-tmpl.md

@@ -1,98 +1,88 @@
+<!-- tf-schema
+doc: project-status
+file: PROJECT-STATUS.md
+header: project, last_updated, current_phase, last_verified_build, last_verified_date
+section: Where I am | required | max 80
+section: Next command to run | required | max 60
+section: Open requirements | required | max 200
+section: Known blockers | required | max 150
+section: Verification log | required | max 250
+section: Library feedback summary | required | max 60
+section: Standards compliance | required | max 60
+section: Deferred / future | required | max 100
+max-lines: 120
+target-lines: 60
+rule: next-command-blocks
+rule: verification-log
+rule: open-requirements-max-10
+-->
+<!-- Authoring notes (agent only; never visible text).
+     A one-page snapshot of the CURRENT state, overwritten in place, never appended to. Exactly the
+     eight sections above, in this order, with their word limits; guard-status.sh refuses any other
+     heading and any write over 120 lines; tf-doc-check.sh refuses over-long sections. What a run did
+     is not written here: a run adds ONE Verification-log row (at most five kept) and updates the
+     checklist Remarks; the rest lives in the telemetry streams.
+     Next command to run: exactly two code blocks, one line each, labelled Claude Code then OpenCode,
+     so either can be copied on its own. No prose about the technical work. -->
+
 ---
-project: {AppName}
-stack: .NET 9 / Blazor [Server|WASM|Auto] / TrBlazeUI / TechieRag / [MAUI]
+project: {App}
 last_updated: {YYYY-MM-DD}
-current_phase: Discovery | UI build | UI verify | Functional build | Functional verify | Handoff | Released
-last_verified_build: PASS | FAIL | not-run
+current_phase: {Day-1 | Build | Verify | UAT | Handoff | Released} — {at most a half-line qualifier}
+last_verified_build: {PASS | FAIL | not-run}
 last_verified_date: {YYYY-MM-DD}
 ---
 
-# {AppName} — Status
-
-<!--
-  ============================================================================
-  THIS FILE IS A CRISP, FIXED-SHAPE SNAPSHOT — OVERWRITE IT, NEVER APPEND TO IT.
-  It has exactly the sections below and NO others. It should stay well under
-  ~60 lines — a human reads it in ten seconds.
-
-  When you update status you REPLACE the content of these sections in place.
-  Do NOT add a new dated section per run. The following are BANNED (they are
-  what turns this file into an unreadable 280-line append-log):
-    - A per-run prose H2 like "## *verify all — formal coverage matrix (DATE)",
-      "## *fix-issues — …", "## *build-phase — …". A run records its outcome as
-      ONE row in "## Verification log" + updated Remarks IN THE CHECKLIST. Period.
-    - A paragraph crammed into `current_phase:` or "## Where I am". `current_phase`
-      is ONE short line. The blow-by-blow lives in the checklist Remarks + .verify/.
-  See .tfcore/tasks/_status-update-gate.md §"CRISP, FIXED-SHAPE snapshot".
-  ENFORCED MECHANICALLY: the .tfcore/hooks/guard-status.sh PreToolUse hook
-  BLOCKS any write that adds a non-template H2, a command-run heading, a
-  paragraph current_phase, or a file longer than ~120 lines.
-  ============================================================================
--->
+# {App} — Status
 
 ## Where I am
-<one short paragraph — the current STATE only: which phase, what is built/verified, what is open.
- This is a status snapshot, NOT a technical to-do list. Do not narrate the implementation work
- still to be done (how to wire a service, fix a binding, etc.) — that lives in the checklist REQ rows.>
+
+{At most 80 words: which phase, what is built and verified, what is open. State, not story.}
 
 ## Next command to run
-<!--
-  Express the next step ONLY as a command pointed at a checklist/scope. NOT a prose description of
-  the technical work. The "what to do" already lives in the checklist's REQ rows — here we just say
-  WHICH COMMAND to run against WHICH checklist/REQs. At most one line naming the target checklist or
-  REQ IDs may accompany the command block.
-
-  GOOD:
-    ```
-    /TechieFlow:agents:verifier *verify ui      (OpenCode: /flow-verifier *verify ui)
-    ```
-    Resumes FAILed REQ-UI-007, REQ-UI-012 in docs/{AppName}-Checklist.md.
-
-  BAD (do not do this — technical narrative belongs in the checklist, not here):
-    Next, wire the AstroData service into the dashboard, fix the empty ruling-planet
-    table binding, add validation to the onboarding form, then re-run verification...
--->
+
+Claude Code:
+```
+/TechieFlow:agents:flow-master *build-phase {App}
+```
+OpenCode:
 ```
-/<agent> <exact prompt>      (OpenCode: <exact prompt>)
+/flow-master *build-phase {App}
 ```
-<one optional line naming the target checklist or REQ IDs>
+{Optional one line naming the target REQ ids.}
 
 ## Open requirements
-- [ ] REQ-UI-013 — <desc>
-- [ ] REQ-FN-007 — <desc>
+
+| Status | Count |
+|---|---|
+| Not Started | {n} |
+| In Progress | {n} |
+| Implemented | {n} |
+| Needs re-verify | {n} |
+| Blocked | {n} |
+
+- [ ] REQ-UI-001 — {short name} (at most ten named rows)
 
 ## Known blockers
-- None / <list>
-<!--
-  Known blockers are PROJECT-level issues — broken code, missing tests, real compile errors, hardcoded secrets, etc.
-  They are NOT environment / wrong-rung issues. Banned entries (these go in WORKFLOW.html §0 territory, not here):
-    - "MAUI build cannot run on WSL"
-    - "NETSDK1178 — iOS/Android/MacCatalyst workload missing"
-    - "Microsoft.iOS.Sdk / Microsoft.Android.Sdk / Microsoft.MacCatalyst.Sdk missing"
-    - "dotnet not in PATH"
-    - Anything that means "I used the wrong build invocation ladder rung"
-  If you wrote one of those, you skipped .tfcore/templates/v4custom/build-invocation-ladder.md.
-  Switch rungs and rebuild.
--->
 
+- None
 
 ## Verification log
-<!-- Status detail lives in the checklist's "Requirements Status" table (the single
-     source of truth). This log is just a dated index of verification passes. -->
+
+Last five passes; older passes live in `docs/metrics/gates.jsonl`.
+
 | Date | Phase | Result | Status table |
-|------|-------|--------|--------------|
-| {YYYY-MM-DD} | UI verify | 14/14 Verified | docs/{AppName}-Checklist.md#requirements-status |
+|---|---|---|---|
+| {YYYY-MM-DD} | {verify all} | {14/14 Verified} | docs/{App}-Checklist.md#requirements-status |
 
 ## Library feedback summary
-- TrBlazeUI: 0 major, 0 minor — docs/{AppName}-TrBlazeUI-Feedback.md
-- TechieRag: 0 major, 0 minor — docs/{AppName}-TechieRag-Feedback.md
 
-<!-- One feedback file PER library (separate teams). Files are created on first issue. -->
+- {Library}: {n} open — docs/{App}-{Library}-Feedback.md
+
+## Standards compliance
 
-## Standards compliance (last verifier check)
-- Underscore fields: not yet run
-- Test method underscores: not yet run
-- Mis-prefixed fields: not yet run
+- Last check {YYYY-MM-DD}: {n} findings, see the checklist Remarks.
 
 ## Deferred / future
-- <parked ideas>
+
+- {parked ideas, one line each}

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

@@ -1,48 +1,73 @@
-# {AppName} — UI Design Spec (Mockups)
+<!-- tf-schema
+doc: uidesign
+file: docs/{App}-UIDesign.md
+header: App, Kind, Size, UI library, Theme
+section: Design system | required | max 300
+section: Screens | required
+section: Click-through flow | optional-small
+section: Branding guide | optional
+entries: Screens | Screen:
+per-entry: 250 400
+rule: entry-mockup
+rule: entry-regions-table
+rule: entry-fields-table
+rule: entry-states
+rule: mockup-links
+-->
+<!-- Authoring notes (agent only; never visible text).
+     One `### Screen: Name (/route)` per routed page, in navigation order. The mockup shows the layout;
+     the entry lists what the mockup cannot say: regions to controls, fields with validation, the dialogs
+     the screen opens, and the empty, loading and error states. Do not describe in prose what the mockup
+     already shows. Use only controls that exist in the UI library's catalogue; a missing control goes
+     to the library feedback file, not into a workaround. The set of screens must equal the BRD's
+     Screens and flow table. For a library, this document is optional.
+     Large project: one UIDesign per phase (docs/{App}-UIDesign.md, docs/{App}-P2-UIDesign.md, …) with a
+     header row "| Phase | n of m |"; its screens are exactly that phase's row in docs/{App}-Phases.md.
+     The mockup folder stays one click-through set across every phase. -->
+
+# {App} — UI Design
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small, Medium or Large |
+| UI library | {library and version} |
+| Theme | {light, dark, both} |
+
+## Design system
+
+- **Layout shell:** {top nav, sidebar, both; the layout components used}
+- **Theme:** {…}
+- **Shared controls:** {the controls every screen uses}
+- **Rules:** {spacing, density, responsive breakpoints in one line each}
 
-> **What this is.** The approved visual design for {AppName}, produced at day-1 (greenfield) before any UI is built. Each screen has a **rendered mockup** (`docs/mockups/{screen}.html`, styled to look like TrBlazeUI) and a **component map** that ties every region to a real **TrBlazeUI control**, so the build (`/trblazeui`) reproduces it 1:1 and the verifier's visual-truth gate (`verify-phase.md §4b`) can diff the live screen against it. This is a HUMAN document → rendered to HTML. The owner APPROVES it (alongside the BRD + Architecture) before build.
-
-## Table of Contents
-
-<!-- Auto-maintained. Slug rule: .tfcore/templates/v4custom/html-render-shell.md §1. List each `### Screen: ...` under "Screens". -->
-
-1. [How to use](#how-to-use)
-2. [Design system (TrBlazeUI)](#design-system-trblazeui)
-3. [Screens](#screens)
-
-## How to use
-
-- Every screen below links to its rendered mockup in `docs/mockups/`. Open those `.html` files in a browser to see the intended layout.
-- The **Component map** is the build contract: `region → TrBlazeUI control`. Only controls that actually exist in the TrBlazeUI library are used (the analyst read the component catalog first). If a screen needs something the library lacks, it is flagged here and logged to `docs/{AppName}-TrBlazeUI-Feedback.md`.
-- To change a screen after approval: run `*mockups {AppName} --update` (or `*amend-docs` for a requirement change that adds screens).
-
-## Design system (TrBlazeUI)
+## Screens
 
-- **Source:** TrBlazeUI component library (`.trblazeui/TrBlazeUI-AI-Reference.md`). Mockups use its components and design language (spacing, color tokens, typography) so they are replicable in Blazor.
-- **Layout shell:** {top nav / sidebar / both — name the TrBlazeUI layout components}.
-- **Theme:** light/dark per the shared shell; warm off-white light default.
-- **Controls inventory used:** {list the TrBlazeUI controls this app's screens rely on — e.g. `TrNavMenu`, `TrCard`, `TrDataGrid`, `TrForm`, `TrButton`, `TrChart`, `TrDialog`}.
+### Screen: {Name} (`/route`)
 
-## Screens
+**Mockup:** [mockups/{screen-slug}.html](mockups/{screen-slug}.html) · **Roles:** {who reaches it} · **BRD:** BRD-{N}
 
-<!-- One `### Screen: ...` per key screen from the BRD §9 feature catalog. Each has its mockup link,
-     a component map (region → TrBlazeUI control + the data it shows), and state notes. -->
+| Region | Control | Shows or binds |
+|---|---|---|
+| {Top nav} | {control} | {…} |
+| {Main list} | {control} | {…} |
 
-### Screen: Dashboard (`/dashboard`)
+| Field | Type | Required | Validation |
+|---|---|---|---|
+| {Title} | text | yes | {1 to 120 characters} |
 
-**Mockup:** [docs/mockups/dashboard.html](./mockups/dashboard.html) · **Role(s):** {who reaches it} · **BRD:** BRD-X · **REQ:** REQ-UI-001
+**Dialogs opened here:** {Dialog name: fields …; or "none"}
 
-**Layout (one line):** top nav fixed; 3-card KPI row; full-width chart below; recent-activity table at the bottom.
+**States:** empty: {…} · loading: {…} · error: {…}
 
-**Component map:**
+## Click-through flow
 
-| Region | TrBlazeUI control | Shows / binds | States |
-|--------|-------------------|---------------|--------|
-| Top nav | `TrNavMenu` | logo, user menu, theme toggle | — |
-| KPI row | 3× `TrCard` | {metric} each | loading skeleton; zero-state |
-| Trend chart | `TrChart` (line) | {series} | empty: "no data yet" |
-| Activity | `TrDataGrid` | {columns} | empty row message; paged |
+```mermaid
+flowchart LR
+  A["Login"] --> B["Home"]
+```
 
-**Notes / interactions:** {sort, filter, drill-through, responsive behavior — what collapses/stacks at mobile width}.
+## Branding guide
 
-**Empty / loading / error:** {what each control shows when there's no data, while loading, on error — the verifier checks these aren't blank-but-broken}.
+{Only when colours or type differ from the library defaults.}

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

@@ -1,67 +1,82 @@
-# {AppName} — Usage Guide (Test Users · Test Plan · Setup)
+<!-- tf-schema
+doc: usageguide
+file: docs/{App}-UsageGuide.md
+header: App, Kind, Size, Date
+section: Test users | required
+section: Execution guide | required
+section: How to test, screen by screen | required
+section: Automated tests | required
+section: Known limitations | required
+section: Platform notes | optional
+section: How to call it | library
+entries: How to test, screen by screen |
+per-entry: 90 120
+budget: S 2500 3500 | M 4000 6000 | L 4000 6000
+rule: test-users-table
+rule: execution-code
+rule: entry-steps
+rule: entry-expected
+-->
+<!-- Authoring notes (agent only; never visible text).
+     The owner's test plan. Every agent (smoke, verify) and the owner's UAT use the SAME test users and
+     the SAME walkthrough; nobody invents accounts. One `###` per screen in navigation order, at most
+     120 words: who to sign in as, numbered steps, the expected result, the REQ ids covered.
+     The Execution guide is copy-pasteable commands, one per line, no narrative. Hosting and production
+     deployment are not here; they are in the Deployment Checklist after UAT.
+     For a library, "How to call it" says how a consumer installs and registers the package and gives one call
+     example per public service or component; the maintainer's map of each service is the DevGuide's. -->
+
+# {App} — Usage Guide
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small, Medium or Large |
+| Date | {YYYY-MM-DD} |
+
+## Test users
+
+| # | User | Password source | Role | Exists |
+|---|---|---|---|---|
+| 1 | {admin@app.test} | {user secrets key, seed script} | {Admin} | {yes, no} |
+
+## Execution guide
+
+Prerequisites: {runtime and version, database, anything else, one line}.
 
-> The single source for **how to test and run** this app. Every agent (flow-master self-smoke, the verifier) **and** the human UAT use the SAME test users and the SAME walkthrough listed here — no one invents throwaway accounts (enforced by `.tfcore/tasks/_smoke-test-policy.md`). Keep the Test-users table current: when an account is actually created, flip its `Created?` to ✅.
-
-## Test users (canonical — use THESE for all smoke / verify / UAT)
-
-One row per account needed to exercise the app. Cover every distinct role/permission level. These are the ONLY accounts smoke/verify/UAT may use.
-
-| # | Username / Email | Password | Role / Permission | Created? | Notes |
-|---|------------------|----------|-------------------|----------|-------|
-| 1 | {admin@app.test} | {Pass!23} | Admin | ⬜ | {seeded by …  / create on first build} |
-| 2 | {user1@app.test} | {Pass!23} | Standard user | ⬜ | {…} |
-| 3 | {…}              | {…}       | {role}           | ⬜ | {…} |
+```
+{restore command}
+{database setup or migration command}
+{build command}
+{run command, with the URL it serves}
+```
 
-- **Created?** — ✅ = the account exists in the database now (verified). ⬜ = planned; create it on first build, but **only after confirming with the owner** (see `_smoke-test-policy.md`). Never auto-create silently.
-- **To add or confirm an account:** edit this table — it is the registry the whole pipeline reads from.
-- **Seeding:** if the project seeds users via a migration / `database/*-seed-*.sql` / a DbUp step, reference it here so the accounts above are reproducible from a clean DB.
+Open {http://localhost:port} and sign in as user 1.
 
-## How to test — screen by screen / menu by menu
+## How to test, screen by screen
 
-One subsection per screen or top-level menu, in navigation order, so a tester (human or agent) can walk the whole app and exercise **every feature**. Each subsection names which test user to log in as.
+### {Screen name}
+- **Sign in as:** {user # from the table}
+- **Steps:** 1) {action} 2) {action} 3) {action}
+- **Expected:** {what proves it works}
+- **Covers:** {REQ ids}
 
-**Flowchart any complex flow.** When a flow is multi-step, multi-actor, or branches (approval queues, learning/feedback loops, ingestion→processing→review pipelines, auth/token handshakes, payment/consent gates), add a Mermaid `flowchart` (or `sequenceDiagram`) right above that flow's steps so the tester sees the path at a glance. Simple linear CRUD screens don't need one. **Every diagram MUST follow the authoring rules in `.tfcore/templates/v4custom/html-render-shell.md §5.5`** — quote every node/edge/subgraph label, never use `end` as a node id — or it will throw "Syntax error" in the rendered HTML. Example:
+## Automated tests
 
-```mermaid
-flowchart LR
-  A["User submits form"] --> B{"Valid?"}
-  B -->|"yes"| C["Save + confirm"]
-  B -->|"no"| D["Show error"]
 ```
+{test command}
+```
+{One line: what the suite covers.}
 
-### {Screen / Menu name}
-- **Log in as:** {user # from the table above}
-- **Steps:** 1) {action} → 2) {action} → 3) {action}
-- **Expected:** {observable result — what proves the feature works}
-- **Covers:** {BRD-N / REQ-* IDs this walkthrough exercises}
-
-_(Repeat one block per screen/menu until every feature in the BRD feature catalog is covered. This is the human UAT script AND the map the verifier/smoke use to decide what to exercise.)_
-
-## Prerequisites
-- .NET {N} SDK
-- {OtherRuntime — e.g. Node 20 for Playwright, PostgreSQL 16, etc. — one line each, only if actually required}
-
-## Setup / Deployment steps (runbook — one command per line, in order)
+## Known limitations
 
-Numbered, terse, copy-pasteable. No narrative. Omit any step that doesn't apply (no "N/A" placeholders).
+- {one line each, with the REQ or feedback id}
 
-1. `git clone <repo> && cd <repo>`
-2. `dotnet restore`
-3. {database setup — one line per SQL file in lexicographic order, or a single DbUp `dotnet run --project src/{AppName}.Db` step. Include the test-user seed step if one exists.}
-4. `dotnet build`
-5. {run the backend — one command, e.g. `dotnet run --project src/{AppName}.Api --urls http://localhost:5100`}
-6. {run the frontend — one command, e.g. `dotnet run --project src/{AppName}.Web --urls http://localhost:5099`}
-7. Open `http://localhost:5099` in a browser; log in as a Test user from the table above.
+## Platform notes
 
-## Test (automated)
-```bash
-dotnet test
-```
-{Add `npx playwright test` ONLY if the repo has Playwright tests checked in.}
+{Only when the app runs on more than one platform.}
 
-## Smoke checklist (quick capability pass)
-- [ ] {one tight line per top-level BRD capability — 5-10 boxes max; each a user action using a Test user above, e.g. "Log in as Admin (user 1), open the dashboard"}
+## How to call it
 
-## Known limitations
-- {TR-NNN — short title — see docs/{AppName}-TrBlazeUI-Feedback.md (or TR-RAG-NNN → docs/{AppName}-TechieRag-Feedback.md)}
-- {`Blocked` (library-gap) REQ-* items from the checklist Status tables, one line each}
+{Libraries only. How to install and register the package, then one call example per public service or component. The maintainer's map of each service is in the DevGuide.}