@techierathore/techieflow 1.0.0

package/.claude/commands/TechieFlow/tasks/fix-issues.md

@@ -0,0 +1,134 @@
+# fix-issues
+
+The single front door for fixing bugs the owner found by running the app — UI layout, broken rendering, wrong data, or logic. You drop **a folder of screenshots (+ an optional description file)**; flow-master reproduces each issue, triages where it lives, fans the fix out to the right builder, re-verifies, and updates the docs. **You never invoke the UI / functional / RAG agents yourself — flow-master calls them as sub-agents.**
+
+## Why this exists
+
+When the verifier passes but the running UI is still broken (overlapping controls, blank screens, wrong behavior), the owner needs ONE command to hand a pile of evidence to and have it fixed end-to-end — not to choreograph trblazeui, techierag, and the verifier by hand. `*fix-issues` is that command. It is generic: a bug can be anywhere (layout, data, logic, RAG), so it triages first and routes second. (Analysis WITHOUT fixing — "log these UAT bugs, don't fix yet" — is `*triage-issues`, not this task; see §0.)
+
+## Inputs
+
+- `{AppName}` (required; or resolve from `core-config.yaml`).
+- `{Folder}` (required) — a path to a folder the owner filled with **screenshots** of the broken screens and, optionally, a **description file** (`bugs.md` / `README.md` / `notes.txt`) naming what's wrong on each (e.g. "Dashboard: KPI cards overlap the chart; Clients list shows count 16 but rows are blank"). If `{Folder}` is omitted, ask once for the folder path. (Screenshots-in-a-folder is the intended evidence channel — do not require the owner to describe bugs in chat.)
+
+## SEQUENTIAL Execution
+
+### 0. Scope guard — was a FIX actually requested?
+
+**`*fix-issues` fixes.** If the owner's words ask only to **analyze / triage / log / document** the bugs, update the checklist, or re-verify other features — and do NOT ask for a fix — STOP: execute `.tfcore/tasks/triage-issues.md` instead (same evidence channel, docs-only deliverable) and let the owner decide about fixing afterwards. "Analyze these bugs" is NEVER permission to edit code.
+
+### 1. Ingest the evidence
+
+- List the folder. **Read every screenshot** (vision) and the description file if present. Build a working list of issues: `{ id, screen/route guess, role guess, symptom, evidence-image }`.
+- For each issue, classify a first-guess **kind**: `layout` (overlap/clip/off-viewport/unstyled), `render-empty` (blank table/chart/value), `data/logic` (wrong values, failed action), `rag` (bad/empty AI answer). Final classification happens after repro (§3).
+- If the description names screens/roles, use them; otherwise infer the screen from the screenshot (match against the DevGuide screen list / routes).
+
+### 2. Boot the app (per `_smoke-test-policy.md` + `verify-phase.md §Local-only`)
+
+- Boot the app yourself via the build-invocation-ladder; bring up dependent services (DB/LLM/API) in dependency order for a multi-service stack. "Can't run on Linux / it's multi-service / it targets Windows" are BANNED excuses; escalate per `verify-phase.md §3a` (rung #4 Windows-side → another port → ask the owner only as a last resort). Never propose a cloud deploy.
+- Resolve a test login from `docs/{AppName}-UsageGuide.md` / the DB — never auto-create a random user.
+
+### 3. Reproduce each issue live with Playwright
+
+For each issue, log in as the relevant role, navigate to the screen, and **reproduce the symptom**:
+- Take a fresh screenshot at desktop + a mobile width and compare to the owner's evidence.
+- Apply the **data render gate** (`verify-phase.md §4a`) and the **visual-truth gate** (`§4b`): is the control blank? do controls overlap / clip / sit off-viewport? is it unstyled?
+- Settle the issue's **kind** from what you observe (not just the owner's guess), and map it to the owning screen + `REQ-*` in `docs/{AppName}-Checklist.md` (use the DevGuide screen→REQ map). If an issue can't be reproduced, note it (maybe environment/data-specific) and ask the owner rather than guessing a fix.
+
+Echo a triage table before fixing:
+```
+Issue 1 → REQ-UI-007 (Dashboard) — kind: layout (KPI cards overlap chart @ both widths) → /trblazeui
+Issue 2 → REQ-FN-014 (Clients)   — kind: render-empty (grid 16 count, 0 rows)         → flow-master (data) 
+Issue 3 → REQ-RAG-003 (Assistant)— kind: rag (empty answer)                            → /techierag
+```
+
+### 4. Fan out the fixes to the right builder (flow-master calls them — the owner does not)
+
+In ONE turn, route each issue to its builder as a sub-agent, in parallel where they don't share files:
+- **`layout` / UI** → invoke **`/trblazeui`** as a sub-agent: fix the Razor/CSS/component so it renders correctly and matches the mockup (greenfield) / intended layout; cite the REQ + the symptom + the screenshot. Page-layout fixes are trblazeui's job.
+- **`render-empty` / `data` / `logic`** → spawn a **builder subagent** (`tf-builder` if the harness registers it, otherwise the harness's general subagent — Claude Code `Agent` tool / OpenCode `task` tool): fix the binding/guard/column-mapping/service/query so the control actually renders its data (the `verify-phase §4a` failure modes — undeclared params, column→property mismatch, throwing computed getters, null guards).
+- **`rag`** → invoke **`/techierag`** as a sub-agent: fix the RAG flow (ingestion/search/prompt/provider config).
+- Each sub-agent tags its fix with the `[REQ-*]` tag in the checklist Remarks (**NEVER a git commit — git is manual; agents never run git/gh**), logs any library gap to the owning feedback file, and returns `{ reqsFixed[], filesChanged[], notes[] }`. Every sub-agent prompt MUST carry the two standing rules from `build-phase.md §3` verbatim (no git; smoke it yourself — library agents don't read `.tfcore/` tasks). Wait for all to return.
+
+### 5. Re-smoke (data + visual) then re-verify the affected REQs
+
+- Rebuild (invocation ladder). Re-smoke each fixed screen yourself: data renders AND it looks right at desktop + mobile (per `_smoke-test-policy.md` — both gates). If a fix didn't take, loop back to §4 for that issue.
+- Chain the verifier: read `.tfcore/tasks/verify-phase.md` and run it inline scoped to the affected REQ IDs (skip its §0 question — scope is known). It applies §4a + §4b and writes verdicts into `docs/{AppName}-Checklist.md`.
+
+### 6. Update the docs (status gate)
+
+- **Checklist:** the verifier already wrote verdicts; confirm each fixed REQ is `Verified` (or note why not).
+- **DevGuide:** refresh the affected screens' observed render/visual status + Known issues (the verifier's §6b does this; if a screen wasn't in scope, update it via `*devguide {AppName} --update`).
+- **PROJECT-STATUS (FINAL GATE, per `_status-update-gate.md`):** update `PROJECT-STATUS.md` AND re-render `PROJECT-STATUS.html` — open requirements, a verification-log row, next command. A markdown-only update is incomplete.
+- **Never run git.** Investigate by reading working-tree files at `file:line`, never a diff.
+
+### 6a. Emit the run record — and CLOSE the misses you fixed
+
+Same turn as the status gate. Doctrine: `.tfcore/tasks/_metrics-emit-gate.md`; schema `.tfcore/telemetry/SCHEMA.md` §2 + §5.5. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` at §1, before you ingest anything.
+
+**Emit the run record FIRST.** The `miss-fix` records below carry no numbers of their own — they name this run, and `tf-emit.sh` copies its token window. A `miss-fix` emitted before its run record finds nothing and is costed `none`.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"fix-issues","mode":"fix",
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":["REQ-UI-009"],"reqs_count":1,
+ "subagents":["trblazeui"],"files_written":<n>,"build_result":"pass"}
+JSON
+```
+
+`mode` is always `"fix"` here — that is the whole point of this command. The verifier chained in §5 emits its own `gates.jsonl` and `misses.jsonl` records; do not emit those yourself.
+
+**Then one `miss-fix` per REQ you repaired.** This is what makes "what did that miss cost to fix" answerable at all:
+
+```bash
+for REQ in REQ-UI-009 REQ-FN-014; do
+  MID=$(bash .tfcore/utils/tf-emit.sh --open-miss "$REQ" | cut -d' ' -f1)
+  [ -z "$MID" ] && continue          # no open miss for this REQ — nothing to close
+  FA=$(bash .tfcore/utils/tf-emit.sh --next-fix-attempt "$MID")
+  cat <<JSON | bash .tfcore/utils/tf-emit.sh misses
+{"kind":"miss-fix","miss_id":"$MID","req_id":"$REQ",
+ "fix_run_id":"<the §1 start timestamp>","fix_cmd":"fix-issues",
+ "fix_attempt":$FA,"verdict_after":"<the verifier's verdict>","reopened":false}
+JSON
+done
+```
+
+- **`verdict_after` is the verifier's verdict from §5, not your assessment of your own fix.** `Verified` only where the verifier actually wrote it. A miss closed on the fixer's word is the same failure as a self-attested `Verified`.
+- **A REQ with no open miss is normal** — the owner reported something the gates never recorded as a miss. Open one first (`--next-miss-id`, `found_by:"owner"`, per `triage-issues` §6a) and then close it in the same run, so the defect has both a cause and a cost.
+- **Write no token, dollar, or `cost_attribution` field.** `tf-emit.sh` copies the window from `fix_run_id` and derives the attribution from that run's `reqs_touched` — `sole` when this fix touched one REQ, `shared:<n>` when it touched several. That distinction is the whole reason the cost figure can be defended, and it is not yours to assert (constraint 10).
+
+**Telemetry has no veto:** a failed emit never changes the outcome and is not worth reporting.
+
+### 7. HALT — report
+
+```
+# Fix-issues — {AppName}
+Evidence: {Folder} ({S} screenshots, {desc|no} description)
+Issues: {N} triaged → {u} UI/layout, {d} data/render, {r} RAG, {x} could-not-reproduce
+Fixed + re-verified: {f} REQs now Verified  |  Still open: {o} (reason)
+Docs: checklist + DevGuide + PROJECT-STATUS updated (+ HTML re-rendered)
+Next: {if open issues → re-run *fix-issues with the still-broken shots / *verify all ; else "all reported issues fixed and re-verified"}
+```
+
+## Hard rules
+
+- **A fix must be ASKED for.** Analyze/log/document-only requests route to `.tfcore/tasks/triage-issues.md` (§0) — never start fixing on an analysis request.
+- **One front door, flow-master routes.** The owner runs only `*fix-issues`; flow-master calls trblazeui / techierag / its own subagents. Never tell the owner to invoke a builder agent themselves.
+- **Triage from what you OBSERVE, not just the owner's words.** Reproduce live before fixing; classify by the actual data + visual gates.
+- **Both gates before "fixed".** A fix is done only when the screen renders its data AND looks right (no overlap/clip/off-viewport), confirmed by re-smoke + the verifier.
+- **Boot the app yourself**, incl. multi-service stacks; asking the owner to run it is the last resort. Never propose a cloud deploy.
+- **Use documented test users; never auto-create random ones.**
+- **Status gate is the last action** — PROJECT-STATUS `.md` AND `.html`. Never run git.
+
+## Output Checklist
+
+- [ ] Evidence folder ingested — screenshots read (vision) + description parsed; issue list built
+- [ ] App booted (incl. dependent services); documented test user used
+- [ ] Each issue reproduced live and triaged (kind + owning REQ) — triage table echoed
+- [ ] Fixes fanned out to the right builder (trblazeui / flow-master subagent / techierag) — owner did NOT invoke any agent
+- [ ] Re-smoked (data + visual) and verifier re-run on the affected REQs (verdicts in the checklist)
+- [ ] DevGuide affected screens refreshed; PROJECT-STATUS.md + .html updated (status gate)
+- [ ] `runs.jsonl` record emitted with `cmd:"fix-issues"`, `mode:"fix"` (§6a) — **before** the miss-fix records, so the token window exists to copy
+- [ ] One `misses.jsonl` `miss-fix` per repaired REQ that had an open miss, carrying the verifier's verdict — no token/cost/attribution field written by hand
+- [ ] Report printed with fixed vs still-open counts

package/.claude/commands/TechieFlow/tasks/generate-html.md

@@ -0,0 +1,115 @@
+# generate-html
+
+Convert one or more **human-readable** markdown files to self-contained HTML using the shared shell. Use this when you need to render documents that `*render-workflow-docs` does not cover (the UsageGuide, the DevGuide, library-feedback docs, ad-hoc design notes, legacy/archived docs). Note: suffixed doc variants like `-v2` are banned by the collision policy (day1-brownfield §1.6) — superseded docs live unmodified in `docs/OldDocs/`.
+
+**NEVER render the checklist to HTML.** The `*-Checklist.md` (and its Requirements Status table) is an **AI-agent working document** — agents read it in markdown. An HTML mirror just burns tokens and drifts from the source. If asked to render a `*-Checklist.md`, decline and explain it's an agent doc; if a stale `*-Checklist.html` exists from before this rule, the user may delete it.
+
+## Why this exists
+
+`*render-workflow-docs` only renders the three canonical files (`{App}-BRD.md`, `{App}-Architecture.md`, `PROJECT-STATUS.md`). When the user has additional or versioned docs, this task accepts explicit paths.
+
+## Invocation forms
+
+```
+*generate-html @path/to/file.md
+*generate-html @path/to/file1.md @path/to/file2.md @path/to/file3.md
+*generate-html @docs/SomeFolder/
+```
+
+(Or via the slash-command wrapper: `/TechieFlow:tasks:generate-html @path/to/file.md` in Claude Code; `/techieflow:tasks:generate-html path/to/file.md` in OpenCode. **The `@` sigil is Claude Code's file-mention; under OpenCode type the plain path WITHOUT `@`** — an `@file` in an OpenCode prompt inlines the entire file into context, wasting tokens. This task accepts both forms and treats them identically.)
+
+Note: the `@` prefix is Claude Code's file-mention sigil. OpenCode treats a leading `@` as file-content-inclusion, so pass plain paths there.
+
+- **Single file:** convert that one MD to a sibling HTML.
+- **Multiple files:** convert each. List separated by spaces. Each becomes a sibling HTML.
+- **Directory:** convert every `*.md` directly inside that directory. **Non-recursive** — do not descend into subdirectories. If the user wants subdirectories included, they can pass each subdir as another argument.
+
+If no arguments are passed, HALT and tell the user: `Usage: *generate-html @<path-to-md-or-dir> [@<more-paths>]`.
+
+## Inputs
+
+- One or more `@`-prefixed paths (the `@` is Claude Code's file-mention sigil; strip it when resolving the actual path).
+- Paths may be absolute or relative to project root.
+
+## SEQUENTIAL Execution
+
+### 1. Resolve the input set
+
+For each argument:
+- Strip leading `@`.
+- If the path ends with `/` or is a directory: use the Read tool to read each `*.md` directly under that directory (non-recursive, no subdirs).
+- Otherwise: treat as a single file path.
+- Skip any path that doesn't exist; emit a one-line note for each skip and continue with the rest. Do not HALT unless ZERO paths resolve.
+
+If ZERO paths resolve, HALT with: `No markdown files found at the given paths. Check the paths and retry.`
+
+Echo a one-line summary: `Rendering N markdown file(s): file1.md, file2.md, ...`.
+
+### 2. For each MD, build the HTML
+
+**Run the renderer. Do NOT hand-author HTML.**
+
+```bash
+bash .tfcore/utils/tf-render-html.sh docs/{AppName}-BRD.md PROJECT-STATUS.md
+```
+
+It takes one or more `.md` paths, writes a sibling `.html` for each, and implements `html-render-shell.md` in full — §1 slugs (with dedupe), §2 CSS, §3 skeleton + flash-free theme script, §4 heading anchors *and* hand-written `<a id="…"></a>` anchors preserved verbatim, §5 mermaid toolbar wrapper, §5.5 label self-check, §6 escaped code blocks, §6b agent-note strip, §7 JS, §8 inline + sidebar TOC (sidebar only above 6 H2s). It reads the CSS and JS **out of the spec file at render time**, so the output cannot drift from the spec.
+
+Hand-authoring the HTML through the Write tool is no longer the path: it cost 75–80k output tokens per phase for documents whose content barely changed, produced non-reproducible output, and risked silent truncation on large files (TfLens TF-003, 2026-08-27). Reserve it for the case where the renderer genuinely cannot express something — and report that as a framework defect rather than hand-rolling around it.
+
+**Read the output.** The renderer prints one line per file (size, H2 count, sidebar yes/no, diagram count, notes stripped) and warns on `⚠ mermaid §5.5` for an unquoted flowchart label or a reserved `end` node id. Those warnings are about the **source `.md`** — fix the diagram in the markdown and re-render; never edit the generated HTML.
+
+**It refuses to render a checklist** (`*-Checklist.md`, exit 2) — that ban is now mechanical, not just prose.
+
+Read `.tfcore/templates/v4custom/html-render-shell.md` when you need to understand or change the shell; it remains the specification. You do not need to read it just to render.
+
+For each MD file:
+
+1. **Read** the source MD content.
+2. **Extract title** from the first `#` heading; if none, derive from the filename (humanize: replace `-` and `_` with spaces, title-case).
+3. **Build the heading list** (every `##`, `###`, `####`): for each, compute the slug per shell §1, attach an `id` to the heading, and decorate with the anchor link `<a class="anchor-link" href="#{slug}">#</a>`. Dedupe slugs by appending `-2`, `-3`, ... when a slug already exists in the doc.
+4. **Decide TOC mode:**
+   - If H2 count > 6: render with sidebar TOC (no `no-toc` class).
+   - Otherwise: render with `no-toc` class on `.layout` and omit the `<nav class="side">` block.
+   - **Always** render the inline `.toc-inline` block at the top of `<main>` when H2 count ≥ 2.
+5. **If the MD source already contains a `## Table of Contents` section**, replace it inline with the inline `.toc-inline` HTML block (don't double-render). Use the same slugs you assigned in step 3 so links work.
+6. **Convert body markdown** to HTML:
+   - Paragraphs, bold/italic, links, lists, tables, blockquotes — standard markdown → HTML.
+   - Code fences: `` ```mermaid `` → §5 `<div class="diagram">` wrapper with toolbar buttons; any other code fence → §6 `<pre><code class="language-{lang}">{escaped}</code></pre>`.
+   - Inline code: `<code>...</code>`.
+   - HTML comments in source (`<!-- ... -->`): pass through.
+   - **Agent-facing authoring notes NEVER render as visible text.** The doc templates carry drafting-agent instructions (the "Depth mandate", "Mermaid mandate", "read before drafting" notes, how-to-use-this-template guidance) as HTML comments, which pass through invisibly. If the source MD still carries such a note as a **visible** blockquote or paragraph — text addressed to the drafting/authoring AGENT rather than to the document's human reader (typical in docs generated from pre-2026-07 templates) — **OMIT it from the rendered HTML** and, if you are also allowed to edit the MD, convert it to an HTML comment there. List every such omission in the output summary. Reader-facing blockquotes (a DevGuide's verification-status banner or Purpose note, a UsageGuide's test-user rules, etc.) stay.
+7. **Assemble** using the §3 skeleton, with §2 CSS inlined verbatim in `<head>`, and §7 JS inlined verbatim at end of `<body>`. The mermaid + svg-pan-zoom CDN scripts go just before the JS.
+8. **Write** the output to `{same-dir}/{basename}.html` (replace `.md` with `.html`). If the file already exists, overwrite.
+
+### 3. Validate (mental review — no shell-out)
+
+Per shell §9 checklist, for each rendered file confirm:
+- CSS palette and JS pasted verbatim.
+- Every TOC entry's `href` matches an existing heading `id`.
+- Every mermaid fence wrapped in `.diagram` with all 6 toolbar buttons.
+- Sidebar present iff H2 count > 6.
+- No external resource references except the two CDN scripts.
+
+**Mermaid validity pass (do this for EVERY diagram — it is the #1 reported bug).** Apply the shell §5.5 self-check to each mermaid block before emitting it:
+- Each node/edge/subgraph label that contains anything other than letters, digits, and spaces (i.e. has `(` `)` `/` `&` `:` `,` `[` `]` `{` `}` `#` `@` `<` `>` `|` `"` etc.) MUST be wrapped in double quotes, with the quotes INSIDE the shape brackets (`API["ASP.NET API (v2)"]`, `DB[("SQL Server")]`).
+- No node id is a reserved word (lowercase `end`).
+- If you find a bare label in the source MD, **fix it in the emitted HTML** (quote it) rather than copying through a diagram you know will throw "Syntax error" in the browser. Note any such fix in the output summary so the author can also fix the MD source.
+
+Do NOT shell out to an HTML validator. Do NOT `wc -c` the files. Do NOT `du`.
+
+### 4. Output summary
+
+Print one line per rendered file: the absolute output path. End with: `Open each in a browser to confirm Mermaid renders correctly and copy buttons / diagram toolbars work.`
+
+## Output Checklist
+
+- [ ] Every input MD has a sibling HTML produced
+- [ ] Each HTML is self-contained (no broken local refs)
+- [ ] Sidebar TOC present only when H2 count > 6
+- [ ] Inline TOC present when H2 count ≥ 2
+- [ ] Every heading has an id matching the TOC link
+- [ ] Mermaid diagrams have working toolbar (zoom, fit, 1:1, fullscreen, popout)
+- [ ] Mermaid validity pass done (shell §5.5): every non-trivial label double-quoted, no `end` node ids, bare labels fixed not emitted
+- [ ] No agent-facing authoring note (Depth/Mermaid mandate, template how-to) rendered as visible text — leaked ones omitted and reported
+- [ ] Copy buttons present on every `<pre>` (added by JS, no need to inject manually)

package/.claude/commands/TechieFlow/tasks/handoff-phase.md

@@ -0,0 +1,126 @@
+# handoff-phase
+
+Final-phase wrap-up: usage doc + status refresh + library-feedback consolidation + HTML re-render.
+
+## Purpose
+
+After the checklist's Requirements Status table is green (or `Blocked` library-gap items accepted), produce the artifacts the user needs to ship and the artifacts future-you needs to resume.
+
+**Run-once-per-UAT-cycle guard:** handoff *produces* the UAT bundle — it runs BEFORE owner UAT, once. If the PROJECT-STATUS Verification log already has a READY-FOR-UAT handoff row for the current cycle and the only open rows are documented owner-run UAT, there is nothing for this task to add: say so and point at the UsageGuide UAT plan instead of re-running. Execute anyway ONLY when the owner explicitly invoked `*handoff-phase` themselves, or when substantive doc-affecting work landed after the last handoff (then note in the Verification log row what changed). Agents never *suggest* a repeat handoff while non-terminal rows remain (`_status-update-gate.md` item 5, UAT tier).
+
+## Inputs
+
+- `{AppName}` argument (required; or resolve from core-config.yaml).
+
+## SEQUENTIAL Execution
+
+### 1. Finalize `docs/{AppName}-UsageGuide.md`
+
+The Usage Guide was created at day-1 (`day1-*` §7.4) from `.tfcore/templates/v4custom/app-usageguide-tmpl.md`. **Update it in place — do not create a new doc.** (If it's missing — a project that predates this step — create it now from that template.) At handoff, bring every section up to ship-reality and **TERSELY**. Hard rules:
+
+- **Test-users table:** reconcile with the database — every account that actually exists now is marked `Created? = ✅`; drop or mark any planned ⬜ account that was never created. This table is what UAT logs in with, so it must match the live DB.
+- **Screen-by-screen test plan:** ensure every shipped feature has a walkthrough block; remove blocks for cut features.
+
+Below, "populate" means refresh these sections of the existing doc. Hard rules:
+
+- **No narrative prose anywhere.** No "this app uses Blazor Server because…", no caveats, no explanations. The deployment-steps section must look like a runbook — one command per line, numbered in execution order.
+- **Skip any step that doesn't apply.** If the repo has no SQL migrations, omit the database-setup step entirely — do not leave "N/A" placeholders or "// not applicable" comments.
+- **No optional steps in the numbered list.** The numbered deployment-steps section is the minimum sufficient set of commands to go from `git clone` to a running app. Anything optional goes in "Known limitations" or a separate doc.
+
+Detection sources for each section:
+
+- **Prerequisites**: SDK version from `global.json` / `.csproj` `<TargetFramework>`. Add a one-line entry for each external runtime the build/test commands depend on (Node only if Playwright tests exist; Postgres/SQL Server/etc. only if migrations exist; MAUI workload only if there's a MAUI project). One line each. No prose.
+- **Deployment steps**: detect in this order and emit one numbered step per command:
+  1. `git clone <repo>` (always)
+  2. `dotnet restore` (always)
+  3. SQL migrations — scan `database/`, `db/migrations/`, `src/*Db/Scripts/`, and any DbUp project's `<EmbeddedResource>` paths. List `.sql` files in lexicographic order, one per line. If a DbUp project exists, prefer `dotnet run --project src/{AppName}.Db` as a single step instead of listing each SQL file.
+  4. `dotnet build`
+  5. Backend run — find the API/service startup project. One `dotnet run --project ... --urls http://localhost:5100` line.
+  6. Frontend run — find the Web/UI startup project. One `dotnet run --project ... --urls http://localhost:5099` line.
+  7. "Open http://localhost:5099 in a browser."
+  - For MAUI: replace step 5/6 with `winrun "dotnet build src/{AppName}.Maui"` then `winrun "dotnet run --project src/{AppName}.Maui"`.
+  - If frontend and backend are the same project (Blazor Server-only): collapse steps 5+6 into one.
+- **Test**: `dotnet test`. Add `npx playwright test` ONLY if the repo has Playwright tests checked in.
+- **Smoke checklist**: one checkbox per top-level BRD capability (5–10 max). Each line is a user action, not a technical step ("Log in as admin and load the dashboard" — NOT "verify JWT validation").
+- **Known limitations**: pull every `Blocked` REQ row from the checklist Status table + every entry from the per-library feedback files (`docs/{AppName}-TrBlazeUI-Feedback.md`, `docs/{AppName}-TechieRag-Feedback.md`). One line each. Cross-reference to issue IDs (TR-NNN, TR-RAG-NNN).
+
+**If you find yourself writing more than one line per numbered step, you're doing it wrong** — the user has explicitly called out that the deployment steps got polluted with "unnecessary details" in past runs. Strip aggressively.
+
+### 2. Update `PROJECT-STATUS.md` (per `.tfcore/tasks/_status-update-gate.md`)
+
+- `current_phase: Handoff` (the user manually sets `Released` after UAT passes — §5)
+- `last_updated`: today
+- `last_verified_build: PASS` (you just verified — confirm with `dotnet build` if uncertain)
+- `last_verified_date`: today
+- "Where I am": one paragraph — "All REQ-* verified; awaiting UAT per usage doc."
+- "Next command to run": `Manual UAT per docs/{AppName}-UsageGuide.md smoke checklist.`
+- "Open requirements": list any REQ-* not `Verified` in the checklist Status table (`Blocked`-by-library or deferred). Empty if all clear.
+- "Library feedback summary": refresh counts from the consolidated library-feedback doc (§4 below)
+- "Standards compliance": copy from the latest verifier run (recorded in the checklist Status table Remarks / prior PROJECT-STATUS entry)
+- Append a "Verification log" row for the handoff (Result = ship-readiness verdict; Status table column → `docs/{AppName}-Checklist.md#requirements-status`)
+- **BRD §4 Development status** — per the gate's item 9, roll the now-final checklist statuses up into the BRD §4 table (at handoff, most features should land on `Done`). If the BRD has no §4 section (legacy), say so and point the user at `*refresh-status {AppName}` to add it. The re-render in §3 picks up the change.
+
+### 2a. Emit the run record (telemetry)
+
+Same turn as the status/PROJECT-STATUS write. Doctrine + the ten constraints: `.tfcore/tasks/_metrics-emit-gate.md`. Schema: `.tfcore/telemetry/SCHEMA.md` §2. Stamp `started` with `date -u +%Y-%m-%dT%H:%M:%SZ` as your FIRST action of this task — it cannot be reconstructed at the end.
+
+```bash
+cat <<'JSON' | bash .tfcore/utils/tf-emit.sh runs
+{"kind":"run","app":"{AppName}","cmd":"handoff-phase","mode":null,
+ "started":"<start>","ended":"<now>","duration_s":<n>,
+ "reqs_touched":[],"reqs_count":0,
+ "subagents":[],"files_written":<n>,"build_result":"not-run"}
+JSON
+```
+
+`reqs_touched` carries REQ IDs only — never requirement text — and `[]` is correct when this task touched no specific REQ. **Telemetry has no veto:** if the emit fails, the phase still succeeded; do not retry, do not diagnose, do not mention it.
+
+### 3. Re-render the HTMLs
+
+Invoke `render-workflow-docs {AppName}` as a subtask. Specifically:
+- `docs/{AppName}-BRD.html` — always re-render (do NOT mtime-compare with bash; the Write tool is cheap and a stale HTML is worse than a redundant re-render)
+- `docs/{AppName}-Architecture.html` — if implementation revealed "as-built" deltas from "Target", update Architecture.md first, then re-render. Set status to "Current (post-implementation)" or "Current + planned target" as appropriate.
+- `PROJECT-STATUS.html` — always re-render (just updated in §2)
+
+Then re-render the **Usage Guide** (updated in §1) and the **DevGuide** (refreshed in §3a) via `.tfcore/tasks/generate-html.md`: `docs/{AppName}-UsageGuide.md` (+ the DevGuide — `docs/{AppName}-DevGuide.md` if single, or every file under `docs/devguides/` if split) → sibling `.html`. **Do NOT render the checklist to HTML** — it is an AI-agent working document kept in markdown only; its Status table stays accurate in markdown.
+
+### 3a. Refresh the Developer Guide
+
+Run `.tfcore/tasks/devguide.md` for `{AppName}` (`*devguide {AppName}`) so the screen-by-screen code map reflects the final as-built code — this is the doc a human developer uses to chase bugs and verify the AI-generated code from page → control → service → data-access → stored proc. If a DevGuide already exists, an incremental `--update` is enough (remap only changed screens). It produces `docs/{AppName}-DevGuide.md` (single) — or, for a large app, an index + per-role files under `docs/devguides/` — and their `.html`; §3 above already lists them in the re-render set.
+
+### 4. Consolidate the per-library feedback files
+
+For EACH of `docs/{AppName}-TrBlazeUI-Feedback.md` and `docs/{AppName}-TechieRag-Feedback.md` (and any other `docs/{AppName}-{LibName}-Feedback.md`) that exists — they are separate files because each goes to a different team:
+- Deduplicate entries (same expected/actual pair = duplicate; merge them).
+- Sort by severity: blocker → major → minor → nice-to-have.
+- Ensure each entry has all the schema fields (Severity, Repro, Expected, Actual, Encountered in, Workaround, Suggested fix). Fill in missing ones from context if possible.
+- Refresh the file's summary block:
+  ```markdown
+  ## Summary
+  - {N blockers, M majors, P minors, Q nice-to-haves}
+  - Last consolidated: {today}
+  ```
+- If a legacy combined `docs/{AppName}-Library-Feedback.md` exists (pre-split projects), split its sections into the per-library files first, then archive it to `docs/OldDocs/`.
+
+If no feedback file exists (no library issues encountered), skip this step.
+
+### 5. Output summary + ship-readiness verdict
+
+Deliver:
+- "✔ {AppName} is ready for UAT." OR
+- "⚠ {AppName} has {N} `Blocked` (library-gap) items — see docs/{AppName}-TrBlazeUI-Feedback.md / docs/{AppName}-TechieRag-Feedback.md before UAT."
+
+Then explicitly tell the user:
+1. Open `docs/{AppName}-UsageGuide.md` and run the smoke checklist.
+2. Hand each per-library feedback file to its team (or file as GitHub issues against that library's repo): `docs/{AppName}-TrBlazeUI-Feedback.md` → TrBlazeUI team, `docs/{AppName}-TechieRag-Feedback.md` → TechieRag team. The library teams use this same framework, so the file drops straight into their flow.
+3. After UAT passes, manually update `PROJECT-STATUS.md`: `current_phase: Released`.
+4. For end-user / external documentation, run `*productguide {AppName}` (flow-master) — it builds a screenshot-illustrated, task-oriented user manual (MD + HTML) from the DevGuide's screen map + captured screenshots. On-demand; re-run with `--update` as the UI evolves.
+
+## Output Checklist
+
+- [ ] `docs/{AppName}-UsageGuide.md` finalized — Test-users table reconciled with the DB (created accounts ✅) + screen-by-screen plan current + prereqs/build/run/test/smoke; its `.html` re-rendered
+- [ ] Developer Guide generated/refreshed (`*devguide {AppName}`) — screen-by-screen code map (page→control→service→data-access→proc) + its `.html`
+- [ ] `PROJECT-STATUS.md` updated with handoff phase + UAT next-step
+- [ ] `docs/{AppName}-BRD.html`, `docs/{AppName}-Architecture.html`, `PROJECT-STATUS.html`, the UsageGuide + DevGuide HTML re-rendered (the checklist is NOT rendered to HTML — markdown only)
+- [ ] Per-library feedback files consolidated, one per library (if applicable; legacy combined file split + archived)
+- [ ] Ship-readiness verdict delivered with explicit next steps

package/.claude/commands/TechieFlow/tasks/index-docs.md

@@ -0,0 +1,173 @@
+# Index Documentation Task
+
+## Purpose
+
+This task maintains the integrity and completeness of the `docs/index.md` file by scanning all documentation files and ensuring they are properly indexed with descriptions. It handles both root-level documents and documents within subfolders, organizing them hierarchically.
+
+## Task Instructions
+
+You are now operating as a Documentation Indexer. Your goal is to ensure all documentation files are properly cataloged in the central index with proper organization for subfolders.
+
+### Required Steps
+
+1. First, locate and scan:
+   - The `docs/` directory and all subdirectories
+   - The existing `docs/index.md` file (create if absent)
+   - All markdown (`.md`) and text (`.txt`) files in the documentation structure
+   - Note the folder structure for hierarchical organization
+
+2. For the existing `docs/index.md`:
+   - Parse current entries
+   - Note existing file references and descriptions
+   - Identify any broken links or missing files
+   - Keep track of already-indexed content
+   - Preserve existing folder sections
+
+3. For each documentation file found:
+   - Extract the title (from first heading or filename)
+   - Generate a brief description by analyzing the content
+   - Create a relative markdown link to the file
+   - Check if it's already in the index
+   - Note which folder it belongs to (if in a subfolder)
+   - If missing or outdated, prepare an update
+
+4. For any missing or non-existent files found in index:
+   - Present a list of all entries that reference non-existent files
+   - For each entry:
+     - Show the full entry details (title, path, description)
+     - Ask for explicit confirmation before removal
+     - Provide option to update the path if file was moved
+     - Log the decision (remove/update/keep) for final report
+
+5. Update `docs/index.md`:
+   - Maintain existing structure and organization
+   - Create level 2 sections (`##`) for each subfolder
+   - List root-level documents first
+   - Add missing entries with descriptions
+   - Update outdated entries
+   - Remove only entries that were confirmed for removal
+   - Ensure consistent formatting throughout
+
+### Index Structure Format
+
+The index should be organized as follows:
+
+```markdown
+# Documentation Index
+
+## Root Documents
+
+### [Document Title](./document.md)
+
+Brief description of the document's purpose and contents.
+
+### [Another Document](./another.md)
+
+Description here.
+
+## Folder Name
+
+Documents within the `folder-name/` directory:
+
+### [Document in Folder](./folder-name/document.md)
+
+Description of this document.
+
+### [Another in Folder](./folder-name/another.md)
+
+Description here.
+
+## Another Folder
+
+Documents within the `another-folder/` directory:
+
+### [Nested Document](./another-folder/document.md)
+
+Description of nested document.
+```
+
+### Index Entry Format
+
+Each entry should follow this format:
+
+```markdown
+### [Document Title](relative/path/to/file.md)
+
+Brief description of the document's purpose and contents.
+```
+
+### Rules of Operation
+
+1. NEVER modify the content of indexed files
+2. Preserve existing descriptions in index.md when they are adequate
+3. Maintain any existing categorization or grouping in the index
+4. Use relative paths for all links (starting with `./`)
+5. Ensure descriptions are concise but informative
+6. NEVER remove entries without explicit confirmation
+7. Report any broken links or inconsistencies found
+8. Allow path updates for moved files before considering removal
+9. Create folder sections using level 2 headings (`##`)
+10. Sort folders alphabetically, with root documents listed first
+11. Within each section, sort documents alphabetically by title
+
+### Process Output
+
+The task will provide:
+
+1. A summary of changes made to index.md
+2. List of newly indexed files (organized by folder)
+3. List of updated entries
+4. List of entries presented for removal and their status:
+   - Confirmed removals
+   - Updated paths
+   - Kept despite missing file
+5. Any new folders discovered
+6. Any other issues or inconsistencies found
+
+### Handling Missing Files
+
+For each file referenced in the index but not found in the filesystem:
+
+1. Present the entry:
+
+   ```markdown
+   Missing file detected:
+   Title: [Document Title]
+   Path: relative/path/to/file.md
+   Description: Existing description
+   Section: [Root Documents | Folder Name]
+
+   Options:
+
+   1. Remove this entry
+   2. Update the file path
+   3. Keep entry (mark as temporarily unavailable)
+
+   Please choose an option (1/2/3):
+   ```
+
+2. Wait for user confirmation before taking any action
+3. Log the decision for the final report
+
+### Special Cases
+
+1. **Sharded Documents**: If a folder contains an `index.md` file, treat it as a sharded document:
+   - Use the folder's `index.md` title as the section title
+   - List the folder's documents as subsections
+   - Note in the description that this is a multi-part document
+
+2. **README files**: Convert `README.md` to more descriptive titles based on content
+
+3. **Nested Subfolders**: For deeply nested folders, maintain the hierarchy but limit to 2 levels in the main index. Deeper structures should have their own index files.
+
+## Required Input
+
+Please provide:
+
+1. Location of the `docs/` directory (default: `./docs`)
+2. Confirmation of write access to `docs/index.md`
+3. Any specific categorization preferences
+4. Any files or directories to exclude from indexing (e.g., `.git`, `node_modules`)
+5. Whether to include hidden files/folders (starting with `.`)
+
+Would you like to proceed with documentation indexing? Please provide the required input above.

package/.claude/commands/TechieFlow/tasks/kb-mode-interaction.md

@@ -0,0 +1,75 @@
+# KB Mode Interaction Task
+
+## Purpose
+
+Provide a user-friendly interface to the TechieFlow knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (\*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+
+Announce entering KB mode with a brief, friendly introduction.
+
+### 2. Present Topic Areas
+
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with TechieFlow
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How TechieFlow implements Agile methodologies
+7. **Configuration** - Customizing TechieFlow for your needs
+8. **Best Practices** - Tips for effective TechieFlow usage
+
+Or ask me about anything else related to TechieFlow!
+
+### 3. Respond Contextually
+
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+
+When user is done or wants to exit KB mode:
+
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with \*kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: \*kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full TechieFlow knowledge base. I can help you with detailed information about any aspect of TechieFlow.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with TechieFlow
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How TechieFlow implements Agile methodologies
+7. **Configuration** - Customizing TechieFlow for your needs
+8. **Best Practices** - Tips for effective TechieFlow usage
+
+Or ask me about anything else related to TechieFlow!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]