npm - @techierathore/techieflow - Versions diffs - 1.0.1 → 1.0.3 - Mend

@techierathore/techieflow 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (178) hide show

package/.claude/commands/TechieFlow/agents/analyst.md +0 -5
package/.claude/commands/TechieFlow/agents/architect.md +0 -6
package/.claude/commands/TechieFlow/agents/flow-master.md +41 -215
package/.claude/commands/TechieFlow/agents/verifier.md +23 -64
package/.claude/commands/TechieFlow/tasks/_metrics-emit-gate.md +24 -117
package/.claude/commands/TechieFlow/tasks/_smoke-test-policy.md +20 -84
package/.claude/commands/TechieFlow/tasks/_status-update-gate.md +10 -74
package/.claude/commands/TechieFlow/tasks/_yolo-mode.md +20 -58
package/.claude/commands/TechieFlow/tasks/amend-docs.md +20 -143
package/.claude/commands/TechieFlow/tasks/build-phase.md +14 -224
package/.claude/commands/TechieFlow/tasks/day1-brownfield.md +31 -505
package/.claude/commands/TechieFlow/tasks/day1-greenfield.md +28 -213
package/.claude/commands/TechieFlow/tasks/deploy-checklist.md +19 -0
package/.claude/commands/TechieFlow/tasks/devguide.md +10 -219
package/.claude/commands/TechieFlow/tasks/fix-issues.md +10 -129
package/.claude/commands/TechieFlow/tasks/log-miss.md +19 -158
package/.claude/commands/TechieFlow/tasks/metrics-report.md +1 -1
package/.claude/commands/TechieFlow/tasks/mockups.md +12 -117
package/.claude/commands/TechieFlow/tasks/refresh-status.md +9 -130
package/.claude/commands/TechieFlow/tasks/split-brd.md +10 -126
package/.claude/commands/TechieFlow/tasks/triage-and-fix.md +14 -0
package/.claude/commands/TechieFlow/tasks/triage-issues.md +11 -152
package/.claude/commands/TechieFlow/tasks/verify-phase.md +36 -572
package/.opencode/plugin/techieflow.js +39 -12
package/.tfcore/agents/analyst.md +0 -5
package/.tfcore/agents/architect.md +0 -6
package/.tfcore/agents/flow-master.md +41 -215
package/.tfcore/agents/verifier.md +23 -64
package/.tfcore/core-config.yaml +10 -0
package/.tfcore/hooks/block-git.sh +4 -4
package/.tfcore/hooks/guard-artifacts.sh +2 -2
package/.tfcore/hooks/guard-build.sh +76 -0
package/.tfcore/hooks/guard-db.sh +90 -0
package/.tfcore/hooks/guard-metrics.sh +56 -0
package/.tfcore/hooks/guard-status-html.sh +116 -71
package/.tfcore/hooks/guard-status.sh +43 -16
package/.tfcore/hooks/guard-verify.sh +70 -48
package/.tfcore/hooks/sweep-artifacts.sh +2 -2
package/.tfcore/install-manifest.yaml +0 -18
package/.tfcore/routing.yaml +25 -14
package/.tfcore/standards/coding-standards-core.md +61 -0
package/.tfcore/standards/coding-standards-dotnet.md +93 -0
package/.tfcore/tasks/_metrics-emit-gate.md +24 -117
package/.tfcore/tasks/_smoke-test-policy.md +20 -84
package/.tfcore/tasks/_status-update-gate.md +10 -74
package/.tfcore/tasks/_yolo-mode.md +20 -58
package/.tfcore/tasks/amend-docs.md +20 -143
package/.tfcore/tasks/build-phase.md +14 -224
package/.tfcore/tasks/day1-brownfield.md +31 -505
package/.tfcore/tasks/day1-greenfield.md +28 -213
package/.tfcore/tasks/deploy-checklist.md +19 -0
package/.tfcore/tasks/devguide.md +10 -219
package/.tfcore/tasks/fix-issues.md +10 -129
package/.tfcore/tasks/log-miss.md +19 -158
package/.tfcore/tasks/metrics-report.md +1 -1
package/.tfcore/tasks/mockups.md +12 -117
package/.tfcore/tasks/refresh-status.md +9 -130
package/.tfcore/tasks/split-brd.md +10 -126
package/.tfcore/tasks/triage-and-fix.md +14 -0
package/.tfcore/tasks/triage-issues.md +11 -152
package/.tfcore/tasks/verify-phase.md +36 -572
package/.tfcore/telemetry/SCHEMA.md +43 -7
package/.tfcore/telemetry/tf-metrics.sh +152 -17
package/.tfcore/templates/project-brief-tmpl.yaml +1 -1
package/.tfcore/templates/stack-defaults/dotnet.md +35 -0
package/.tfcore/templates/stack-questions.md +77 -0
package/.tfcore/templates/v4custom/app-agents-md-tmpl.md +3 -4
package/.tfcore/templates/v4custom/app-architecture-tmpl.md +107 -115
package/.tfcore/templates/v4custom/app-brd-tmpl.md +108 -184
package/.tfcore/templates/v4custom/app-checklist-tmpl.md +48 -73
package/.tfcore/templates/v4custom/app-claude-md-tmpl.md +1 -1
package/.tfcore/templates/v4custom/app-coding-standards-tmpl.md +52 -0
package/.tfcore/templates/v4custom/app-deployment-checklist-tmpl.md +86 -0
package/.tfcore/templates/v4custom/app-devguide-tmpl.md +69 -146
package/.tfcore/templates/v4custom/app-phases-tmpl.md +35 -0
package/.tfcore/templates/v4custom/app-productguide-tmpl.md +38 -35
package/.tfcore/templates/v4custom/app-project-status-tmpl.md +63 -73
package/.tfcore/templates/v4custom/app-uidesign-tmpl.md +62 -37
package/.tfcore/templates/v4custom/app-usageguide-tmpl.md +69 -54
package/.tfcore/templates/v4custom/build-invocation-ladder.md +17 -180
package/.tfcore/templates/v4custom/build-subagent-prompt.md +17 -0
package/.tfcore/templates/v4custom/metrics-report-template.md +2 -2
package/.tfcore/user-guide.md +0 -23
package/.tfcore/utils/__pycache__/tf-brd-status.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-checklist-edit.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-codex-bind.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-codex-telemetry.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-day1-files.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-devguide-list.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-doc-check.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-log-miss.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-misses-md.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-mockups-locate.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-opencode-audit.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-perf-grade.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-render-html.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-split-brd.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-status-facts.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-triage.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-verify-list.cpython-312.pyc +0 -0
package/.tfcore/utils/__pycache__/tf-verify-verdict.cpython-312.pyc +0 -0
package/.tfcore/utils/tf-brd-status.py +176 -0
package/.tfcore/utils/tf-brd-status.sh +19 -0
package/.tfcore/utils/tf-build-list.py +191 -0
package/.tfcore/utils/tf-build-list.sh +20 -0
package/.tfcore/utils/tf-build.sh +143 -0
package/.tfcore/utils/tf-cdp-relay.ps1 +64 -0
package/.tfcore/utils/tf-checklist-edit.py +133 -0
package/.tfcore/utils/tf-day1-files.py +208 -0
package/.tfcore/utils/tf-day1-files.sh +20 -0
package/.tfcore/utils/tf-devguide-list.py +249 -0
package/.tfcore/utils/tf-devguide-list.sh +18 -0
package/.tfcore/utils/tf-doc-check.py +1267 -0
package/.tfcore/utils/tf-doc-check.sh +29 -0
package/.tfcore/utils/tf-emit.sh +203 -13
package/.tfcore/utils/tf-fix-close.sh +83 -0
package/.tfcore/utils/tf-goal.sh +193 -62
package/.tfcore/utils/tf-harness.sh +4 -9
package/.tfcore/utils/tf-log-miss.py +197 -0
package/.tfcore/utils/tf-log-miss.sh +14 -0
package/.tfcore/utils/tf-misses-md.py +211 -0
package/.tfcore/utils/tf-misses-md.sh +13 -0
package/.tfcore/utils/tf-mockups-locate.py +66 -0
package/.tfcore/utils/tf-mockups-locate.sh +18 -0
package/.tfcore/utils/tf-opencode-audit.py +23 -7
package/.tfcore/utils/tf-perf-grade.py +97 -0
package/.tfcore/utils/tf-perf-grade.sh +12 -0
package/.tfcore/utils/tf-phase.sh +74 -0
package/.tfcore/utils/tf-routing-bind.sh +10 -5
package/.tfcore/utils/tf-routing.sh +6 -7
package/.tfcore/utils/tf-split-brd.py +304 -0
package/.tfcore/utils/tf-split-brd.sh +22 -0
package/.tfcore/utils/tf-status-evidence.sh +68 -0
package/.tfcore/utils/tf-status-facts.py +309 -0
package/.tfcore/utils/tf-status-facts.sh +20 -0
package/.tfcore/utils/tf-triage.py +243 -0
package/.tfcore/utils/tf-triage.sh +16 -0
package/.tfcore/utils/tf-verify-boot.sh +250 -0
package/.tfcore/utils/tf-verify-emit.sh +110 -0
package/.tfcore/utils/tf-verify-env.sh +88 -0
package/.tfcore/utils/tf-verify-list.py +270 -0
package/.tfcore/utils/tf-verify-list.sh +13 -0
package/.tfcore/utils/tf-verify-screens.mjs +283 -0
package/.tfcore/utils/tf-verify-screens.sh +22 -0
package/.tfcore/utils/tf-verify-tests.sh +123 -0
package/.tfcore/utils/tf-verify-verdict.py +283 -0
package/.tfcore/utils/tf-verify-verdict.sh +15 -0
package/.tfcore/utils/tf-yolo.sh +59 -0
package/README.md +114 -1149
package/docs/TechieFlow-Installation.md +27 -7
package/opencode.jsonc +13 -33
package/package.json +4 -7
package/scripts/install.mjs +73 -46
package/scripts/npm-cleanup.mjs +137 -0
package/scripts/npm-postinstall.mjs +49 -0
package/.claude/commands/TechieFlow/tasks/advanced-elicitation.md +0 -117
package/.claude/commands/TechieFlow/tasks/author-brd.md +0 -79
package/.claude/commands/TechieFlow/tasks/document-project.md +0 -343
package/.claude/commands/TechieFlow/tasks/execute-checklist.md +0 -86
package/.claude/commands/TechieFlow/tasks/index-docs.md +0 -173
package/.claude/commands/TechieFlow/tasks/kb-mode-interaction.md +0 -75
package/.claude/commands/TechieFlow/tasks/shard-doc.md +0 -185
package/.codex/config.toml +0 -46
package/.codex/hooks.json +0 -63
package/.codex/rules/techieflow.rules +0 -8
package/.tfcore/hooks/codex-adapter.py +0 -248
package/.tfcore/tasks/advanced-elicitation.md +0 -117
package/.tfcore/tasks/author-brd.md +0 -79
package/.tfcore/tasks/document-project.md +0 -343
package/.tfcore/tasks/execute-checklist.md +0 -86
package/.tfcore/tasks/index-docs.md +0 -173
package/.tfcore/tasks/kb-mode-interaction.md +0 -75
package/.tfcore/tasks/shard-doc.md +0 -185
package/.tfcore/utils/tf-codex-bind.py +0 -196
package/.tfcore/utils/tf-codex-telemetry.py +0 -60
package/WORKFLOW.html +0 -1986
package/scripts/test-install.mjs +0 -505
package/scripts/validate.mjs +0 -163

package/WORKFLOW.html DELETED Viewed

@@ -1,1986 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<title>TechieFlow: Solo-Dev Delivery Workflow — Claude Code + OpenCode + Codex</title>
-<style>
-  :root{
-    --bg:#0f1115; --panel:#161a22; --panel2:#1c2230; --line:#2a3142;
-    --ink:#e6e8ee; --muted:#9aa3b2; --accent:#7cc4ff; --accent2:#a6e3a1;
-    --warn:#f9c74f; --danger:#f38ba8; --ok:#a6e3a1;
-    --mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;
-    --sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
-  }
-  *{box-sizing:border-box}
-  html,body{margin:0;padding:0;background:var(--bg);color:var(--ink);font-family:var(--sans);line-height:1.5;font-size:15px}
-  a{color:var(--accent);text-decoration:none}
-  a:hover{text-decoration:underline}
-  code{font-family:var(--mono);font-size:13px;background:#0a0d13;color:#e6e8ee;padding:1px 5px;border-radius:4px;border:1px solid var(--line)}
-  pre{font-family:var(--mono);font-size:12.5px;background:#0a0d13;border:1px solid var(--line);border-radius:8px;padding:12px 14px;overflow:auto;color:#d8dde8;position:relative}
-  pre code{background:none;border:none;padding:0}
-  .copy{position:absolute;top:8px;right:8px;background:#1c2230;color:#9aa3b2;border:1px solid var(--line);border-radius:6px;padding:3px 8px;font-size:11px;font-family:var(--sans);cursor:pointer}
-  .copy:hover{color:var(--accent);border-color:var(--accent)}
-  pre.mermaid{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px 14px;text-align:center;color:var(--ink);overflow:auto;line-height:1.3}
-  .dcap{font-size:14px;color:var(--accent);font-weight:700;margin:18px 0 4px}
-  .dnote{font-size:12.5px;color:var(--muted);margin:0 0 6px}
-  .layout{display:grid;grid-template-columns:260px 1fr;min-height:100vh}
-  nav.side{position:sticky;top:0;height:100vh;overflow-y:auto;border-right:1px solid var(--line);background:var(--panel);padding:18px 14px}
-  nav.side h1{font-size:14px;margin:0 0 4px;letter-spacing:.5px;color:var(--ink)}
-  nav.side .sub{font-size:11.5px;color:var(--muted);margin-bottom:14px}
-  nav.side ol{list-style:none;padding:0;margin:0;counter-reset:n}
-  nav.side ol li{counter-increment:n;font-size:13px;margin:2px 0}
-  nav.side ol li a{display:block;padding:5px 8px;color:var(--ink);border-radius:6px}
-  nav.side ol li a::before{content:counter(n,decimal-leading-zero);color:var(--muted);font-family:var(--mono);font-size:11px;margin-right:8px}
-  nav.side ol li a:hover{background:var(--panel2);text-decoration:none}
-  nav.side .group{font-size:11px;color:var(--muted);text-transform:uppercase;letter-spacing:.7px;margin:14px 8px 4px}
-  main{padding:32px 40px 80px;max-width:1100px}
-  h2{font-size:22px;margin:32px 0 10px;padding-bottom:6px;border-bottom:1px solid var(--line);scroll-margin-top:16px}
-  h3{font-size:17px;margin:22px 0 6px;color:#cfd5e3;scroll-margin-top:16px}
-  h4{font-size:14px;margin:14px 0 4px;color:var(--accent)}
-  p{margin:6px 0 10px}
-  .lede{color:var(--muted);font-size:14px;margin-top:-4px}
-  .panel{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:14px 18px;margin:10px 0}
-  .panel.warn{border-color:#5a4a1a;background:#241d10}
-  .panel.ok{border-color:#2f5a2f;background:#13211a}
-  .panel.danger{border-color:#5a2a3a;background:#241016}
-  .grid2{display:grid;grid-template-columns:1fr 1fr;gap:14px}
-  .grid3{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}
-  table{border-collapse:collapse;width:100%;font-size:13.5px;margin:8px 0}
-  table.quickref-legacy{display:none}
-  th,td{border:1px solid var(--line);padding:8px 10px;text-align:left;vertical-align:top}
-  th{background:var(--panel2);color:#cfd5e3;font-weight:600}
-  tr:nth-child(even) td{background:#13171f}
-  .badge{display:inline-block;font-size:11px;padding:2px 7px;border-radius:999px;background:#1c2230;border:1px solid var(--line);color:var(--muted);font-family:var(--mono)}
-  .badge.cmd{color:var(--accent);border-color:#274d6e}
-  .badge.agent{color:#c4b5fd;border-color:#3a335a}
-  .badge.task{color:#fcd34d;border-color:#564218}
-  .badge.file{color:#86efac;border-color:#1f4a2a}
-  .tabs{display:flex;gap:0;border-bottom:1px solid var(--line);margin:14px 0 0}
-  .tabs button{background:none;color:var(--muted);border:none;border-bottom:2px solid transparent;padding:10px 16px;font:inherit;cursor:pointer}
-  .tabs button.active{color:var(--accent);border-color:var(--accent)}
-  .tabpanel{display:none;padding:16px 0}
-  .tabpanel.active{display:block}
-  .flow{display:flex;flex-direction:column;gap:6px;margin:14px 0}
-  .step{display:grid;grid-template-columns:38px 1fr;gap:12px;align-items:start;background:var(--panel2);border:1px solid var(--line);border-radius:8px;padding:10px 12px}
-  .step .num{font-family:var(--mono);font-size:16px;font-weight:700;color:var(--accent);background:#0d2030;border:1px solid #274d6e;border-radius:8px;width:38px;height:38px;display:flex;align-items:center;justify-content:center}
-  .step .body h4{margin:0 0 4px;color:var(--ink);font-size:14.5px}
-  .step .body p{margin:2px 0;font-size:13.5px;color:#cfd5e3}
-  .step .body .cmds{margin-top:6px}
-  .arrow{display:flex;justify-content:center;color:var(--muted);font-size:18px;font-family:var(--mono)}
-  .kbd{font-family:var(--mono);background:#0a0d13;border:1px solid var(--line);padding:1px 5px;border-radius:4px;font-size:12px;color:#cfd5e3}
-  hr{border:none;border-top:1px solid var(--line);margin:24px 0}
-  .toc-mini{background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:8px 14px;font-size:13px;color:var(--muted);margin:8px 0 16px}
-  .toc-mini a{color:#cfd5e3}
-  details{border:1px solid var(--line);border-radius:8px;background:var(--panel);padding:8px 14px;margin:8px 0}
-  details > summary{cursor:pointer;color:var(--ink);font-weight:600;font-size:14px}
-  details[open] > summary{margin-bottom:8px}
-  .pain{display:grid;grid-template-columns:1fr 1fr;gap:10px;background:var(--panel2);border:1px solid var(--line);border-radius:8px;padding:10px 14px;margin:8px 0}
-  .pain .p{color:#f0b4be}
-  .pain .s{color:#bce6c4}
-  .pain h4{margin:0 0 4px}
-  .small{font-size:12.5px;color:var(--muted)}
-  ul.tight,ol.tight{margin:6px 0;padding-left:22px}
-  ul.tight li,ol.tight li{margin:2px 0}
-  .anchor-link{color:var(--muted);font-weight:400;font-size:0.85em;margin-left:8px;opacity:0;transition:opacity .15s}
-  h2:hover .anchor-link,h3:hover .anchor-link{opacity:1}
-  .pill{display:inline-block;font-size:11px;padding:2px 8px;border-radius:999px;background:#0d2030;color:var(--accent);font-family:var(--mono);border:1px solid #274d6e;margin-right:6px}
-  .pill.ok{background:#13211a;color:var(--ok);border-color:#2f5a2f}
-  .pill.warn{background:#241d10;color:var(--warn);border-color:#5a4a1a}
-  .pill.once{background:#241016;color:#f38ba8;border-color:#5a2a3a}
-  .audience{display:inline-block;font-size:10.5px;padding:1px 6px;border-radius:4px;font-family:var(--mono);margin-left:6px;vertical-align:middle}
-  .audience.h{background:#162a18;color:#86efac;border:1px solid #1f4a2a}
-  .audience.a{background:#1c1731;color:#c4b5fd;border:1px solid #3a335a}
-  .placeholder{color:#f9c74f;font-family:var(--mono);font-size:13px;background:#241d10;padding:0 5px;border-radius:3px;border:1px solid #5a4a1a}
-  @media(max-width:900px){.layout{grid-template-columns:1fr}nav.side{position:static;height:auto}}
-</style>
-</head>
-<body>
-<div class="layout">
-<nav class="side">
-  <h1>TechieFlow: Solo-Dev Delivery Framework</h1>
-  <div class="sub">Custom workflow for Claude Max + WSL / macOS</div>
-  <div class="group">Quick reference</div>
-  <ol>
-    <li><a href="#ataglance">Process at a glance (flowcharts)</a></li>
-  </ol>
-  <div class="group">One-time</div>
-  <ol>
-    <li><a href="#wsl-bootstrap">WSL bootstrap (once, ever)</a></li>
-    <li><a href="#mac-bootstrap">macOS bootstrap (once, ever)</a></li>
-    <li><a href="#device-bootstrap">Device-host bootstrap (MAUI Android/iOS/Mac)</a></li>
-  </ol>
-  <div class="group">Start here</div>
-  <ol>
-    <li><a href="#overview">Overview &amp; principles</a></li>
-    <li><a href="#painpoints">Pain points → solutions</a></li>
-    <li><a href="#scaffolding">Scaffolding a project</a></li>
-    <li><a href="#naming">File-naming convention</a></li>
-    <li><a href="#structure">Project structure</a></li>
-    <li><a href="#docs">Doc artifacts &amp; audiences</a></li>
-  </ol>
-  <div class="group">Workflows</div>
-  <ol>
-    <li><a href="#flows">Brownfield / Greenfield</a></li>
-    <li><a href="#resume">Resuming a cold project</a></li>
-  </ol>
-  <div class="group">Operate</div>
-  <ol>
-    <li><a href="#libraries">Custom library agents</a></li>
-    <li><a href="#standards-enforcement">Coding standards enforcement</a></li>
-    <li><a href="#wsl-runtime">MAUI from WSL / macOS</a></li>
-    <li><a href="#permissions">Permissions (yolo-except-git-writes)</a></li>
-  </ol>
-  <div class="group">Reference</div>
-  <ol>
-    <li><a href="#agents">Agent cheat sheet</a></li>
-    <li><a href="#quickref">Command reference</a></li>
-    <li><a href="#faq">FAQ &amp; gotchas</a></li>
-    <li><a href="#platforms">Running on macOS / Windows / Linux</a></li>
-    <li><a href="#telemetry">Development telemetry</a> &middot; <a href="#misses">misses &amp; rework cost</a> &middot; <a href="#telemetry-gotchas">gotchas</a></li>
-    <li><a href="#model-routing">Model routing (per-phase tiers)</a></li>
-    <li><a href="#team-edition">Team edition — the AI-First Playbook</a></li>
-  </ol>
-</nav>
-<main>
-<h1 style="margin:0 0 4px;font-size:28px">TechieFlow: Solo-Dev Delivery Workflow</h1>
-<div class="lede">Compressed TechieFlow process for one-person teams. Two flows (brownfield + greenfield), human-readable BRD + Architecture with Mermaid, project-specific coding standards every agent follows, automated verification via <code>verifier</code>, your own library agents (<code>trblazeui</code>, <code>techierag</code>) baked in, zero-friction permissions.</div>
-<div class="toc-mini">
-  <span class="pill">Root</span> <code>/Volumes/MacD/MyCode/TechieFlow</code> (macOS) · <code>/mnt/c/3AIGenCode/TechieFlow</code> (WSL) &nbsp;·&nbsp;
-  <span class="pill">Harness</span> Claude Code + OpenCode + Codex &nbsp;·&nbsp;
-  <span class="pill">Stack</span> .NET / Blazor / MAUI / TrBlazeUI / TechieRag
-</div>
-<!-- ============================================================ -->
-<!-- PROCESS AT A GLANCE — quick-reference flowcharts             -->
-<!-- ============================================================ -->
-<h2 id="ataglance">Process at a glance — flowcharts <span class="pill">quick reference</span><span class="anchor-link"><a href="#ataglance">#</a></span></h2>
-<p class="lede" style="font-size:15px">The whole process on one screen. Each box is the exact command to run (agent + <code>*task</code>); the deep sections (<a href="#flows">§7</a>, <a href="#resume">§8</a>) explain each step. Loops mean "repeat until the gate passes".</p>
-<div class="dcap">A · Greenfield — new app from scratch</div>
-<pre class="mermaid">
-flowchart TD
-  A["scaffold-greenfield.sh ."] --> B["/analyst *day1-greenfield"]
-  B --> M["/analyst *mockups (auto-run at day-1)"]
-  M --> C{"Approve BRD + Architecture + mockups"}
-  C -->|"approved"| D["/analyst *split-brd  (creates the one Checklist)"]
-  D --> E["/flow-master *build-phase  (calls trblazeui + techierag)"]
-  E --> F["/verifier *verify all  (data + visual gates)"]
-  F --> G{"All REQ Verified?"}
-  G -->|"bugs found"| X["/flow-master *fix-issues {App} {screenshots-folder}"]
-  X --> F
-  G -->|"UAT/prod bugs — log, don't fix yet"| T["/flow-master *triage-issues {App} {evidence}"]
-  T --> X
-  G -->|"yes"| H["/flow-master *handoff-phase"]
-</pre>
-<div class="dcap">B · Brownfield — existing app</div>
-<pre class="mermaid">
-flowchart TD
-  A["scaffold-brownfield.sh ."] --> B["/analyst *day1-brownfield  (reverse-doc + DevGuide)"]
-  B --> C{"Was a dev plan migrated into the Checklist?"}
-  C -->|"no"| D["/analyst *split-brd  (creates the Checklist)"]
-  C -->|"yes"| E["/flow-master *build-phase"]
-  D --> E
-  E --> F["/verifier *verify all"]
-  F --> G{"All REQ Verified?"}
-  G -->|"bugs found"| X["/flow-master *fix-issues {App} {screenshots-folder}"]
-  X --> F
-  G -->|"UAT/prod bugs — log, don't fix yet"| T["/flow-master *triage-issues {App} {evidence}"]
-  T --> X
-  G -->|"yes"| H["/flow-master *handoff-phase"]
-</pre>
-<div class="dcap">C · Which command next? — the Build to Verify to Handoff ladder</div>
-<p class="dnote">Pick the next command from the <em>weakest</em> open REQ in the Checklist. When in doubt, build.</p>
-<pre class="mermaid">
-flowchart TD
-  S{"Weakest open REQ in the Checklist?"}
-  S -->|"any REQ unbuilt (Planned / In Progress / PARTIAL), or built but not testable yet"| B["/flow-master *build-phase {App}"]
-  S -->|"all built and testable, some not yet Verified"| V["/verifier *verify all {App}"]
-  S -->|"all REQ Verified"| H["/flow-master *handoff-phase {App}"]
-</pre>
-<div class="dcap">D · Recovering a cold / interrupted project</div>
-<pre class="mermaid">
-flowchart LR
-  A["Session died mid-phase — PROJECT-STATUS is stale"] --> B["/flow-master *refresh-status {App}"]
-  B --> C["Rebuilds status from Checklist + files on disk + a fresh build"]
-  C --> D["Prints the exact next command to resume"]
-</pre>
-<div class="dcap">E · Library project (TrBlazeUI / TechieRag) — docs and DevGuide</div>
-<p class="dnote">A NuGet library is a first-class project: same doc set as an app, DevGuide driven by its demo/sample app.</p>
-<pre class="mermaid">
-flowchart TD
-  A["Library repo (TrBlazeUI / TechieRag)"] --> B["/analyst *day1-brownfield  (docs + PROJECT-STATUS)"]
-  B --> C["/analyst *split-brd  (the Checklist)"]
-  C --> D["/flow-master *devguide --update"]
-  D --> E["UI-component library: component-by-component"]
-  D --> G["Service / SDK library: service-by-service"]
-</pre>
-<!-- ============================================================ -->
-<h2 id="wsl-bootstrap">0. WSL bootstrap — <span class="pill once">DO ONCE, EVER</span><span class="anchor-link"><a href="#wsl-bootstrap">#</a></span></h2>
-<p><strong>Run this once per WSL distro.</strong> Installs headless-Chromium system libs + the MAUI bridge.</p>
-<div class="panel ok"><strong>On macOS: skip this section — your one-time setup is <a href="#mac-bootstrap">§0a</a> instead.</strong> There is no <code>winrun</code> bridge on a Mac (<code>dotnet</code> and MAUI run natively) and Playwright's Chromium needs no apt libraries.</div>
-<pre><code class="lang-bash">sudo apt-get update && sudo apt-get install -y \
-  libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 \
-  libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libpango-1.0-0 \
-  libcairo2 libasound2 libgtk-3-0 libx11-xcb1
-mkdir -p ~/bin && cat > ~/bin/winrun << 'SH'
-#!/usr/bin/env bash
-WINPATH=$(wslpath -w "$PWD")
-powershell.exe -NoProfile -Command "cd '$WINPATH'; $*"
-SH
-chmod +x ~/bin/winrun
-grep -q 'HOME/bin' ~/.bashrc || echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc</code></pre>
-<div class="panel ok"><strong>Verify:</strong> open a new WSL terminal and run <code>which winrun</code> → <code>/home/&lt;you&gt;/bin/winrun</code>.</div>
-<h3 id="opencode-wsl">OpenCode in WSL — the primary path (since 2026-08-20)</h3>
-<p>OpenCode runs <strong>natively inside the same WSL distro as Claude Code</strong> — OpenCode's own docs recommend WSL over native Windows, and inside WSL it gets the entire runtime harness above (<code>winrun</code>, headless Chromium, Appium) for free. Full rationale, probe evidence, and the crash playbook: <code>docs/OpenCode-Deployment-Guide.md</code>.</p>
-<pre><code class="lang-bash">curl -fsSL https://opencode.ai/install | bash
-grep -q '.opencode/bin' ~/.bashrc || echo 'export PATH="$HOME/.opencode/bin:$PATH"' &gt;&gt; ~/.bashrc
-opencode auth login</code></pre>
-<div class="panel warn"><strong>The PATH line matters:</strong> WSL's Windows-interop otherwise resolves <code>opencode</code> to the Windows npm shim (<code>AppData\Roaming\npm\opencode</code>) — the native-Windows Bun build that breaks on large repos. Verify with <code>type -a opencode</code> (the <code>~/.opencode/bin</code> entry must come first).</div>
-<p>The framework side is automatic: the scaffold/update scripts deploy <code>.opencode/plugin/techieflow.js</code> — the guard bridge that runs the same <code>.tfcore/hooks/</code> guards Claude Code runs (git ban, PROJECT-STATUS shape, Verified ledger) plus session telemetry with real dollar cost — and a framework-owned <code>.opencode/opencode.jsonc</code> into every app. Check with <code>opencode agent list</code> (the six TechieFlow agents must appear).</p>
-<div class="panel ok"><strong>Large repos:</strong> the failure historically blamed on Bun is a <code>/mnt/c</code> (9p filesystem) pathology — OpenCode's snapshot walk can take minutes there, while the identical repo on WSL-native ext4 boots in seconds. Typical apps on <code>/mnt/c</code> are fine; genuinely large repos belong on ext4 (or see the watcher tuning in the deployment guide).</div>
-<div class="panel warn"><strong>Everything below is the FALLBACK path (Docker), kept in case WSL ever reproduces the native-Windows crash — skip it on the WSL path.</strong> OpenCode in Docker on Windows is different from WSL: a Linux container cannot execute Windows <code>cmd.exe</code> or see the Windows .NET workloads. Do not install a fake <code>cmd.exe</code>. The supplied <code>docs/Dockerfile</code> uses the .NET 10 SDK and deliberately installs no MAUI workloads. Build standard .NET apps in the container; build Windows MAUI Blazor Desktop heads through its SSH-backed <code>winrun</code> bridge to the Windows host. Build and test mobile, iOS, and Mac Catalyst heads natively on a Mac.</div>
-<h3 id="opencode-docker">Containerized OpenCode — one-time Windows host bridge (fallback only)</h3>
-<p>This bridge is only required when the container must build or run a Windows-host project (for example, a Windows MAUI head). Blazor/Linux-compatible projects do not need it. The first command uses Windows Update and can take several minutes, but it should not remain at <code>Operation [Running]</code> indefinitely.</p>
-<p>Run each command separately in an <strong>elevated PowerShell</strong> window. Do not paste the whole block while the first command is still running:</p>
-<pre><code class="lang-powershell">$cap = Get-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-$cap.State
-if ($cap.State -ne 'Installed') {
-    Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-}
-Get-Service sshd -ErrorAction SilentlyContinue
-Start-Service sshd
-Set-Service -Name sshd -StartupType Automatic
-if (-not (Get-NetFirewallRule -Name OpenSSH-Server-In-TCP -ErrorAction SilentlyContinue)) {
-    New-NetFirewallRule -Name OpenSSH-Server-In-TCP -DisplayName "OpenSSH Server (sshd)" -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22
-}</code></pre>
-<p>If <code>Add-WindowsCapability</code> is still running after about 10 minutes, press <kbd>Ctrl+C</kbd>. It has not reached the SSH commands. Check the servicing state and Windows Update source, then retry:</p>
-<pre><code class="lang-powershell">Get-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0
-Get-WinEvent -LogName 'Microsoft-Windows-DISM/Operational' -MaxEvents 20 | Format-Table TimeCreated,Id,LevelDisplayName,Message -Wrap
-Get-Service wuauserv,bits,TrustedInstaller | Format-Table Name,Status,StartType
-# Optional: use Settings &gt; System &gt; Optional features &gt; View features and install
-# "OpenSSH Server" if the capability command cannot obtain its payload.</code></pre>
-<p>When the capability reports <code>Installed</code>, open a <strong>normal</strong> PowerShell window as the same non-administrator Windows user that will run the launcher. Copy and paste this as <strong>one complete line</strong>. It is safe to run again:</p>
-<pre><code class="lang-powershell">$ssh="$env:USERPROFILE\.ssh"; New-Item -ItemType Directory -Force $ssh | Out-Null; if (-not (Test-Path "$ssh\opencode-docker")) { ssh-keygen -t ed25519 -f "$ssh\opencode-docker" -N "" }; $publicKey=(Get-Content "$ssh\opencode-docker.pub" -Raw).Trim(); $auth="$ssh\authorized_keys"; if (-not (Test-Path $auth)) { Set-Content -Path $auth -Value $publicKey } elseif ((Get-Content $auth) -notcontains $publicKey) { Add-Content -Path $auth -Value $publicKey }</code></pre>
-<p>Verify the bridge before starting Docker. This test deliberately disables password fallback. A successful test prints the Windows host's <code>dotnet --info</code> output and never asks for a password:</p>
-<pre><code class="lang-powershell">ssh -o BatchMode=yes -o PreferredAuthentications=publickey -o PasswordAuthentication=no -i "$env:USERPROFILE\.ssh\opencode-docker" "$env:USERNAME@localhost" powershell.exe -NoProfile -NonInteractive -Command "dotnet --info"</code></pre>
-<p>If the test reports <code>Permission denied (publickey)</code>, do not enter your VPS password or Windows password. Public-key authentication was not accepted. Check whether the account is an Administrator:</p>
-<pre><code class="lang-powershell">whoami /groups | Select-String 'S-1-5-32-544'</code></pre>
-<p>If that prints a result, Windows OpenSSH reads administrator keys from <code>C:\ProgramData\ssh\administrators_authorized_keys</code> instead of the profile file. In an elevated PowerShell window, install the same public key there and apply the required permissions:</p>
-<pre><code class="lang-powershell">$auth="$env:ProgramData\ssh\administrators_authorized_keys"; $publicKey=(Get-Content "$env:USERPROFILE\.ssh\opencode-docker.pub" -Raw).Trim(); New-Item -ItemType Directory -Force (Split-Path $auth) | Out-Null; if (-not (Test-Path $auth)) { Set-Content -Path $auth -Value $publicKey } elseif ((Get-Content $auth) -notcontains $publicKey) { Add-Content -Path $auth -Value $publicKey }; icacls $auth /inheritance:r /grant "Administrators:F" /grant "SYSTEM:F"</code></pre>
-<p>Retry the SSH command after that. If the account is not an Administrator, keep using the profile <code>authorized_keys</code> file and inspect the SSH log instead of entering a password:</p>
-<pre><code class="lang-powershell">Get-WinEvent -LogName 'OpenSSH/Operational' -MaxEvents 20 | Format-Table TimeCreated,Id,Message -Wrap</code></pre>
-<p>Keep <code>Dockerfile</code> and <code>opencode-docker.cmd</code> in <code>%USERPROFILE%\\.opencode-docker-config</code>. Build the image once from that folder, then put that folder on <code>PATH</code> so the command is available in every application PowerShell:</p>
-<pre><code class="lang-powershell">Set-Location "$env:USERPROFILE\.opencode-docker-config"
-docker build --pull --no-cache -t my-opencode-dotnet .
-# Only if an app actually targets Tizen:
-# docker build --pull --no-cache --build-arg INSTALL_TIZEN=true -t my-opencode-dotnet .</code></pre>
-<p>From the application folder, run <code>opencode-docker.cmd</code>. It uses the existing <code>my-opencode-dotnet</code> image, gives each app its own OpenCode data directory, mounts NuGet and SSH credentials read-only, and passes the Windows app path to the bridge:</p>
-<pre><code class="lang-powershell">opencode-docker.cmd</code></pre>
-<p>The equivalent expanded container command is:</p>
-<pre><code class="lang-powershell">docker run --rm -it `
-  -v "${USERPROFILE}\.opencode-docker\nuget:/root/.nuget/NuGet:ro" `
-  -v "${USERPROFILE}\.ssh:/root/.ssh:ro" `
-  -v "${PWD}:/workspace" -w /workspace `
-  -e TF_WINDOWS_SSH_HOST=host.docker.internal `
-  -e TF_WINDOWS_SSH_USER="$env:USERNAME" `
-  -e TF_WINDOWS_SSH_KEY=/root/.ssh/opencode-docker `
-  -e TF_WINDOWS_APP_PATH="C:\\path\\to\\app" `
-  -e TF_OPENCODE_DOCKER=1 `
-  my-opencode-dotnet opencode</code></pre>
-<p>Inside the container use <code>dotnet build</code> and <code>dotnet test</code> for standard .NET projects. Use <code>winrun "dotnet --info"</code> as the bridge probe, then <code>winrun "dotnet build -c Release"</code> for the Windows MAUI Blazor Desktop head. <code>TF_WINDOWS_APP_PATH</code> is the Windows path to the same app mounted as <code>/workspace</code>. Mobile, iOS, and Mac Catalyst builds and runtime UI tests are outside this Windows container setup and should run on a Mac.</p>
-<p>The SSH directory is intentionally mounted read-only. Docker Desktop may expose the mounted key with Linux mode <code>0777</code>, which OpenSSH rejects, and the mounted directory cannot accept a new <code>known_hosts</code> file. The image's <code>winrun</code> wrapper copies the key to writable <code>/tmp/opencode-docker/</code> with mode <code>0600</code> and creates its writable host-trust file there. Do not try to <code>chmod</code> the mounted key from inside the container.</p>
-<!-- ============================================================ -->
-<h2 id="mac-bootstrap">0a. macOS bootstrap — <span class="pill once">DO ONCE, EVER</span><span class="anchor-link"><a href="#mac-bootstrap">#</a></span></h2>
-<p><strong>Run this once per Mac.</strong> The native equivalent of §0: everything the agents need to build, run, and <em>see</em> your apps on macOS. There is no <code>winrun</code> bridge to install — <code>dotnet</code>, Playwright, and Appium all run natively — but the machine still needs its toolchain once.</p>
-<pre><code class="lang-bash"># 1. Xcode Command Line Tools — provides git AND python3 (the framework's
-#    guard-status/guard-verify hooks silently fail open without python3)
-xcode-select --install
-# If full Xcode is installed (required for MAUI iOS / Mac Catalyst builds),
-# accept its license once or python3/git error out with a license prompt:
-sudo xcodebuild -license accept
-# 2. Homebrew (skip if `brew --version` already works)
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-# 3. The toolchain: .NET SDK + Node.js (Node powers Playwright and Appium)
-brew install dotnet-sdk node
-# 4. MAUI workload — only if any of your apps ships a MAUI head.
-#    sudo is REQUIRED on macOS: the SDK lives in root-owned /usr/local/share/dotnet,
-#    so without it this (and any `dotnet workload update` / SDK update) fails with
-#    "Inadequate permissions. Run the command with elevated privileges."
-sudo dotnet workload install maui</code></pre>
-<div class="panel ok"><strong>Playwright — nothing for you to do.</strong> The verifier <strong>self-provisions</strong> it per project the first time it runs (<code>verify-phase.md §1</code>, also used by every self-smoke): it creates <code>package.json</code> if missing, runs <code>npm install -D @playwright/test</code> + <code>npx playwright install chromium</code>, and writes a minimal <code>playwright.config.ts</code>. The only machine-level prerequisite is <strong>Node</strong> (step 3 above). The Chromium download is cached once under <code>~/Library/Caches/ms-playwright</code> and shared by every project, so only the first project ever pays it — and unlike WSL there are no system libraries to install.</div>
-<div class="panel ok"><strong>Verify:</strong> <code>dotnet --info</code> prints an SDK, <code>node --version</code> answers, and <code>python3 --version</code> answers <em>without</em> an Xcode-license error. The agents handle everything else per project.</div>
-<div class="panel"><strong>MAUI native-UI testing</strong> (Android emulator / iOS Simulator / Mac Catalyst): continue with <a href="#device-bootstrap">§0b</a> — on a Mac-native setup every piece of it (Android Studio + emulator, Appium + drivers, the Simulator) runs on this same machine, and all endpoints are <code>http://localhost:4723</code>.</div>
-<!-- ============================================================ -->
-<h2 id="device-bootstrap">0b. Device-host bootstrap (MAUI Android / iOS / Mac Catalyst) — <span class="pill once">DO ONCE PER HOST</span><span class="anchor-link"><a href="#device-bootstrap">#</a></span></h2>
-<h3>What this is, in plain words</h3>
-<p>The AI does its own testing of every app it builds. For a <strong>website</strong> app it can already "see" the screens — it opens the site in an invisible browser, looks at each page, and checks that everything shows up and looks right. But when an app runs on a <strong>phone, tablet, or as a Mac desktop program</strong>, the AI has no window into it: it can confirm the app <em>compiles</em>, but it can't <em>see</em> what the running app looks like. That is the gap this setup closes — without it, the AI might report "all good" while the real phone screen has buttons on top of each other, text cut off, or empty lists.</p>
-<div class="panel"><strong>The analogy:</strong> think of the AI as a quality inspector. For websites it already has a screen to watch. This one-time setup gives it a <strong>video feed and a remote control for a phone (and a Mac)</strong> so it can tap around the real app, take screenshots, and catch a broken-looking screen — the same way it already does for websites. You set up the camera and remote <em>once</em>; after that the AI uses them by itself every time it tests.</div>
-<div class="panel warn"><strong>Do you even need this?</strong> Only if the app runs on <strong>phones/tablets (Android or iPhone/iPad)</strong> or as a <strong>Mac desktop program</strong>. If your app is a normal <strong>website</strong> (Blazor), you can skip this whole section — website testing already works out of the box. You can also set up just the parts you need: only Android, or only Apple, or both.</div>
-<h3>A few words you'll see</h3>
-<table>
-  <tr><th>Word</th><th>What it means here</th></tr>
-  <tr><td><strong>Appium</strong></td><td>The free tool that acts as the "remote control" — it lets the AI tap buttons and read the screen of a phone or Mac app.</td></tr>
-  <tr><td><strong>Emulator</strong> / <strong>Simulator</strong></td><td>A pretend phone that runs <em>on your computer</em> in a window, so you don't need a physical phone plugged in. "Emulator" = Android; "Simulator" = iPhone/iPad.</td></tr>
-  <tr><td><strong>AVD</strong></td><td>"Android Virtual Device" — one specific pretend Android phone you've created (e.g. a Pixel running Android 14).</td></tr>
-  <tr><td><strong>SDK</strong></td><td>The official toolkit from Google (Android) or Apple (iPhone) for building and running their apps.</td></tr>
-  <tr><td><strong>WSL</strong></td><td>The Linux environment inside your Windows PC where the AI (Claude Code) actually runs.</td></tr>
-  <tr><td><strong>Endpoint / URL</strong></td><td>An address like <code>http://localhost:4723</code> that the AI uses to reach the remote control. <code>localhost</code> means "this same computer".</td></tr>
-  <tr><td><strong>Terminal</strong> / <strong>PowerShell</strong></td><td>A text window where you type commands. On Windows it's "PowerShell" or "Terminal"; on Mac it's the "Terminal" app; inside WSL it's your Ubuntu window.</td></tr>
-</table>
-<h3>What you'll need first</h3>
-<ul>
-  <li><strong>For Android testing:</strong> a Windows PC, plus <strong>Android Studio</strong> (the free Google app — the easiest way to get the Android toolkit, a pretend phone, and the emulator all at once) and <strong>Node.js</strong> (free, from <code>nodejs.org</code> — it provides the <code>npm</code> command used to install Appium).</li>
-  <li><strong>For iPhone / iPad / Mac-desktop testing:</strong> a <strong>Mac computer on the same Wi-Fi/network</strong> as your PC, with <strong>Xcode</strong> (free from the Mac App Store) and <strong>Node.js</strong>. This is the same Mac used to build Apple apps.</li>
-  <li>Permission to install software (you may be asked for your password), and an internet connection for the downloads.</li>
-</ul>
-<div class="panel"><strong>How the pieces fit:</strong> the pretend phone and its remote control run <em>where that platform lives</em> — Android on your <strong>Windows PC</strong>, iPhone/iPad and Mac-desktop on the <strong>Mac</strong>. The AI just needs the <em>address</em> to reach each one; it never needs the phone tools installed in its own Linux environment. Builds are unaffected — this only adds the AI's ability to <em>watch</em> the running app.</div>
-<div class="panel"><strong>Running Claude Code natively on a Mac?</strong> Then everything in this section collapses onto the one machine: Android Studio + the emulator + Appium run locally, and the "paired Mac" for iPhone/iPad and Mac-desktop testing <em>is this same machine</em>. Do Step 3 (and Step 2's Android pieces if the app has an Android head) in the Mac's own Terminal, skip the WSL mirrored-networking step entirely, and use <code>http://localhost:4723</code> for every head in <code>core-config.yaml</code> — no fixed LAN address needed.</div>
-<h3>Step 1 — let the AI reach the Android remote control (Windows only, once)</h3>
-<p>By default the AI's Linux environment and the rest of Windows don't share the same network address. Turning on "mirrored networking" makes them share <code>localhost</code>, so the AI can reach the Android remote control with a simple address. Create or edit the file <code>.wslconfig</code> in your user folder (its full path is <code>%UserProfile%\.wslconfig</code> — paste that into the File Explorer address bar) and put these two lines in it:</p>
-<pre><code class="lang-ini">[wsl2]
-networkingMode=mirrored</code></pre>
-<p>Save it, then open <strong>PowerShell</strong> (click Start, type "PowerShell", press Enter) and run <code>wsl --shutdown</code>. Close and reopen your WSL window. <span class="small">(Skip this step if you're only setting up Apple testing.)</span></p>
-<h3>Step 2 — set up the Android pretend-phone + remote control (on the Windows PC)</h3>
-<p><strong>Easiest way (clicking):</strong> install <strong>Android Studio</strong>, open its <em>Device Manager</em>, and click "Create device" to make a pretend phone (e.g. a Pixel with Android 14). Android Studio installs the Android toolkit for you. Then install the remote control by opening <strong>PowerShell</strong> and running the two <code>appium</code> lines below.</p>
-<p><strong>Command way (does the same thing):</strong> in <strong>PowerShell</strong>:</p>
-<pre><code class="lang-powershell"># create a pretend Android phone (an "AVD")
-sdkmanager "system-images;android-34;google_apis;x86_64"
-avdmanager create avd -n Pixel_API_34 -k "system-images;android-34;google_apis;x86_64"
-# install the remote control (Appium) and its Android adapter
-npm install -g appium
-appium driver install uiautomator2</code></pre>
-<p>Finally, save a tiny helper file named <code>start-android-verify.ps1</code> (the AI runs this itself to switch the phone + remote control on when it tests). It contains:</p>
-<pre><code class="lang-powershell">Start-Process emulator -ArgumentList "-avd Pixel_API_34 -no-snapshot -no-boot-anim"
-Start-Process appium   -ArgumentList "--address 0.0.0.0 --port 4723"</code></pre>
-<p class="small">If you used a different phone name in Android Studio, use that name instead of <code>Pixel_API_34</code> here and in the settings file in Step 4.</p>
-<h3>Step 3 — set up Apple (iPhone/iPad + Mac desktop) testing (on the Mac)</h3>
-<p>On the <strong>Mac</strong> (which must be on the same network as your PC), open the <strong>Terminal</strong> app and install the remote control plus the Apple adapters:</p>
-<pre><code class="lang-bash">npm install -g appium
-appium driver install xcuitest      # for the iPhone/iPad simulator
-appium driver install mac2          # for the Mac desktop app
-appium --address 0.0.0.0 --port 4723   # start the remote control (leave this running while testing)</code></pre>
-<p>Give the Mac a <strong>fixed network address</strong> so the AI always finds it (in your Wi-Fi router, reserve an IP for the Mac — search "DHCP reservation" for your router model). Note that address down; you'll put it in Step 4. <span class="small">(Skip this step if you're only setting up Android.)</span></p>
-<h3>Step 4 — tell the app where the remote controls are</h3>
-<p>Each app keeps its settings in a file called <code>core-config.yaml</code>. Add a <code>runtimeVerification.appium</code> section listing only the platforms <em>this</em> app runs on. The AI reads this automatically; if a platform isn't listed (or can't be reached), the AI simply marks that platform's screens "not visually checked" rather than pretending they passed.</p>
-<p class="small"><strong>WSL-on-Windows setup (Android on this PC, Apple on the LAN Mac):</strong></p>
-<pre><code class="lang-yaml">runtimeVerification:
-  appium:
-    android:     { url: http://localhost:4723, avd: Pixel_API_34, launch: 'winrun "powershell -File start-android-verify.ps1"' }
-    ios:         { url: http://192.168.1.50:4723, simulator: "iPhone 15" }
-    maccatalyst: { url: http://192.168.1.50:4723 }</code></pre>
-<p class="small"><strong>macOS-native setup (everything on this Mac — no winrun, no LAN address):</strong></p>
-<pre><code class="lang-yaml">runtimeVerification:
-  appium:
-    android:     { url: http://localhost:4723, avd: Pixel_API_34 }
-    ios:         { url: http://localhost:4723, simulator: "iPhone 15" }
-    maccatalyst: { url: http://localhost:4723 }</code></pre>
-<p class="small">Use the block for the machine the AI runs on. On WSL: replace <code>192.168.1.50</code> with your Mac's actual address from Step 3 and keep <code>localhost</code> for Android (that's "this PC"). Remove any platform the app doesn't have.</p>
-<div class="panel ok"><strong>Check it works:</strong> in your WSL window, type <code>curl http://localhost:4723/status</code> (Android) and <code>curl http://&lt;your-mac-address&gt;:4723/status</code> (Apple); on a Mac-native setup it's <code>curl http://localhost:4723/status</code> for everything. If you see something containing <code>"ready":true</code>, the remote control is reachable — you're done. From now on the AI turns the pretend phone on, takes screenshots, and checks each screen by itself; you don't run anything.</div>
-<div class="panel warn"><strong>If something doesn't work:</strong>
-<ul class="small">
-  <li><strong>"command not found" for <code>sdkmanager</code>/<code>avdmanager</code>/<code>emulator</code>:</strong> these come with Android Studio but may not be on your command path — easiest fix is to create the pretend phone by clicking inside Android Studio's Device Manager instead.</li>
-  <li><strong>"command not found" for <code>npm</code> or <code>appium</code>:</strong> install <strong>Node.js</strong> first (from <code>nodejs.org</code>), then re-run the <code>npm install -g appium</code> line.</li>
-  <li><strong>The <code>curl</code> check fails for Android:</strong> make sure Step 1 (mirrored networking) was done and you reopened WSL, and that the emulator + Appium are actually running (run <code>start-android-verify.ps1</code> once to start them).</li>
-  <li><strong>The <code>curl</code> check fails for Apple:</strong> confirm the Mac is on and on the same Wi-Fi, that <code>appium</code> is still running in its Terminal window, and that you used the Mac's correct address.</li>
-  <li><strong>The AI says a screen is "STATIC-ONLY":</strong> that just means it couldn't reach that platform's remote control this time (e.g. the Mac was off) — it's being honest, not failing. Bring the device host up and ask it to verify again.</li>
-</ul></div>
-<p class="small"><strong>One more thing for whoever writes the app's screens:</strong> each important button, list, and value should be given a stable name (an <code>AutomationId</code>) so the AI can find it reliably — this is part of the coding standards (see §10). The AI handles this when it builds; you don't need to.</p>
-<!-- ============================================================ -->
-<h2 id="overview">1. Overview &amp; principles<span class="anchor-link"><a href="#overview">#</a></span></h2>
-<div class="grid3">
-  <div class="panel">
-    <h4>Compress, don't expand</h4>
-    <p class="small">No story-by-story TechieFlow. One BRD + one Architecture + one Coding-Standards doc (all human-readable) feed the unified <code>build-phase</code> — which reads ONE AI-only doc (the app Checklist) and calls the library agents (<code>/trblazeui</code>, <code>/techierag</code>) as sub-agents.</p>
-  </div>
-  <div class="panel">
-    <h4>Verify, don't trust</h4>
-    <p class="small">The <code>build-phase</code> self-smokes (data + visual) and then chains <code>verifier</code>. Headless Playwright + <code>dotnet test</code>, with a data-render gate AND a visual-truth gate. Verdicts written into the checklist's Requirements Status table.</p>
-  </div>
-  <div class="panel">
-    <h4>Standards enforced from day 1</h4>
-    <p class="small">Every project has <code>docs/&lt;APP&gt;-Coding-Standards.md</code>. Every implementation agent prompt references it. <code>CLAUDE.md</code> at project root pins it for auto-load.</p>
-  </div>
-</div>
-<div class="panel ok">
-  <strong>Core idea:</strong> Requirements get IDs (<code>REQ-UI-*</code>, <code>REQ-FN-*</code>, <code>REQ-RAG-*</code>, <code>REQ-NFR-*</code>) in ONE checklist. Implementing agents reference IDs in commits and follow <code>&lt;APP&gt;-Coding-Standards.md</code>. <code>verifier</code> maps IDs → test evidence (data + visual gates), written into the checklist's single Requirements Status table. Nothing is "done" until every row in that table is green.
-</div>
-<!-- ============================================================ -->
-<h2 id="painpoints">2. Pain points → solutions<span class="anchor-link"><a href="#painpoints">#</a></span></h2>
-<div class="pain">
-  <div class="p"><h4>1. Agents miss requirements; verify-fix loop is exhausting</h4></div>
-  <div class="s"><h4>→ <code>verifier</code> mandatory + ID-driven; chain in same prompt</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>2. WSL has no GUI browser; Playwright MCP eats context</h4></div>
-  <div class="s"><h4>→ Headless Playwright CLI from §0 bootstrap</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>3. Can't build/run MAUI from WSL</h4></div>
-  <div class="s"><h4>→ <code>winrun</code> WSL→Windows bridge (§9)</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>4. Hard to scan markdown on cold re-entry</h4></div>
-  <div class="s"><h4>→ <code>&lt;APP&gt;-BRD.html</code> + <code>&lt;APP&gt;-Architecture.html</code> + <code>PROJECT-STATUS.html</code> with Mermaid (§6 + §11)</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>5. <code>npx techieflow install</code> grabs v6, breaks customizations</h4></div>
-  <div class="s"><h4>→ <code>scaffold-brownfield.sh</code> / <code>scaffold-greenfield.sh</code> copy your v4 setup (§3)</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>6. Claude Code prompts every Bash; <code>*yolo</code> doesn't help; a VM goal run waits days on delete prompts, git-read blocks and usage limits</h4></div>
-  <div class="s"><h4>→ Pre-built <code>.claude/settings.json</code> (§12)</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>7. Generated code uses inconsistent style across projects</h4></div>
-  <div class="s"><h4>→ <code>&lt;APP&gt;-Coding-Standards.md</code> per project, referenced in every impl prompt; <code>CLAUDE.md</code> pin</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>8. Agents excuse themselves from smoke-testing ("can't run on Linux / it targets Windows / it's MAUI / Playwright needs a GUI")</h4></div>
-  <div class="s"><h4>→ <code>_smoke-test-policy.md</code>: those are <strong>banned excuses</strong> — headless Playwright + the Windows/MAUI bridge are already set up (§0). Every change is self-smoked by the agent before the verifier; the user is asked to boot only after the build ladder genuinely fails. "It runs" means controls <strong>render their data</strong>, not just HTTP 200.</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>9. Smoke/verify runs pollute the DB with random throwaway test users</h4></div>
-  <div class="s"><h4>→ <code>_smoke-test-policy.md</code>: use the canonical test accounts in <code>&lt;APP&gt;-UsageGuide.md</code> (or look them up in the DB via the connection string); never auto-create — ask the owner to confirm, then record the account in the UsageGuide.</h4></div>
-</div>
-<div class="pain">
-  <div class="p"><h4>10. The data + visual gates only reached Blazor + the MAUI Windows head — Android/iOS/Mac-desktop screens were build-only (never run/observed)</h4></div>
-  <div class="s"><h4>→ <strong>Appium runtime bridge (§0b)</strong>: the verifier drives MAUI <strong>Android</strong> (emulator on the Windows host), <strong>iOS</strong> (Simulator on a LAN Mac), and <strong>Mac Catalyst</strong> (same Mac) over an HTTP WebDriver endpoint that returns the same screenshot + element tree, so the §4a/§4b gates run unchanged. Endpoints live in <code>core-config.yaml → runtimeVerification.appium</code>; an unreachable host degrades that head to <code>⚠ STATIC-ONLY</code>, never a faked pass.</h4></div>
-</div>
-<!-- ============================================================ -->
-<h2 id="scaffolding">3. Scaffolding a new project — copy, don't npm-install<span class="anchor-link"><a href="#scaffolding">#</a></span></h2>
-<div class="callout info"><strong>Codex adapter.</strong> Both scaffolders and the updater deploy <code>.codex/</code> (config, custom agents, hooks and rules) and <code>.agents/skills/</code> (TechieFlow workflows). Trust the repository and review <code>/hooks</code> after installation. Invoke <code>$techieflow-build</code>, <code>$techieflow-verify</code>, or another generated skill. Use <code>tf-goal.sh --harness codex</code> for unattended local work; full winrun/Appium verification requires a local Codex environment.</div>
-<p>You have a customized v4 setup. <code>npx techieflow install</code> would fetch v6 and lose your customizations. Use the scaffold script:</p>
-<p>Three scripts: two scaffolders (one per flow) plus an updater for projects scaffolded earlier. All are idempotent (scaffolders use rsync <code>--ignore-existing</code> — existing files preserved on re-run; the updater force-refreshes framework files including <code>.claude/settings.json</code>, see <a href="#update-framework">below</a>).</p>
-<h3>Brownfield (existing app) — <code>scaffold-brownfield.sh</code></h3>
-<p class="small"><strong>WSL (Windows):</strong></p>
-<pre><code class="lang-bash">cd /path/to/existing-app
-/mnt/c/3AIGenCode/TechieFlow/scaffold-brownfield.sh .</code></pre>
-<p class="small"><strong>macOS:</strong></p>
-<pre><code class="lang-bash">cd /path/to/existing-app
-/Volumes/MacD/MyCode/TechieFlow/scaffold-brownfield.sh .</code></pre>
-<p>Adds <code>.tfcore/</code>, <code>.claude/commands/</code>, <code>.opencode/</code>, <code>.codex/</code>, <code>.agents/skills/</code>, <code>WORKFLOW.html</code>, <code>opencode.jsonc</code>, and <code>.claude/settings.json</code>. <strong>Does NOT touch</strong> existing <code>src/</code>, <code>tests/</code>, or other <code>docs/</code> contents. Warns (non-blocking) if no <code>.csproj</code>/<code>.sln</code> found within 4 levels. Refuses if the target directory doesn't exist (use greenfield script for that). (No <code>.opencode/command/TechieFlow/</code> mirror is deployed — OpenCode loads agents/tasks from <code>opencode.jsonc</code> <code>{file:./.tfcore/...}</code> references instead.)</p>
-<h3>Greenfield (new app) — <code>scaffold-greenfield.sh</code></h3>
-<p class="small"><strong>WSL (Windows):</strong></p>
-<pre><code class="lang-bash">mkdir /path/to/my-new-app && cd /path/to/my-new-app
-git init
-/mnt/c/3AIGenCode/TechieFlow/scaffold-greenfield.sh .</code></pre>
-<p class="small"><strong>macOS:</strong></p>
-<pre><code class="lang-bash">mkdir /path/to/my-new-app && cd /path/to/my-new-app
-git init
-/Volumes/MacD/MyCode/TechieFlow/scaffold-greenfield.sh .</code></pre>
-<p class="small"><strong>Then, on either machine:</strong></p>
-<pre><code class="lang-bash">dotnet new sln -n MyNewApp
-dotnet new blazor -n MyNewApp.Web -o src/MyNewApp.Web
-dotnet sln add src/MyNewApp.Web
-dotnet add src/MyNewApp.Web package TrBlazeUI    # if UI involved
-dotnet add src/MyNewApp.Web package TechieRag    # if AI/RAG involved
-dotnet build                                      # deploys library agent files</code></pre>
-<p>Same framework drop as brownfield, plus creates empty <code>src/</code>, <code>tests/playwright/</code>, <code>tests/unit/</code> folders ready for use.</p>
-<div class="panel">
-  <strong>What neither script creates:</strong> per-project doc files (BRD, Architecture, Coding Standards, the Checklist, etc.). Those are produced by <code>/analyst</code> on day 1 of the workflow (§7 step 1). Both scripts also exclude the library-deployed agent files (<code>trblazeui.md</code>, <code>techierag.md</code>) — those land via <code>dotnet build</code> after you add the NuGet packages.
-</div>
-<h3 id="update-framework">Updating an already-scaffolded project — <code>update-framework.sh</code></h3>
-<p>When the reference framework repo (WSL: <code>/mnt/c/3AIGenCode/TechieFlow</code> · macOS: <code>/Volumes/MacD/MyCode/TechieFlow</code>) evolves (new tasks, updated templates, agent fixes), pull those changes into an existing project with the updater. Unlike the scaffolders (<code>--ignore-existing</code>: never touch a file that's already there), the updater <strong>force-overwrites framework files</strong> and preserves everything that contains your work product. The scripts self-locate — invoke whichever machine's copy you're on and it uses itself as the source.</p>
-<p class="small"><strong>WSL (Windows):</strong></p>
-<pre><code class="lang-bash"># Preview what would change (recommended first):
-/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/your-app --dry-run
-# Apply:
-/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/your-app
-# Or run from inside the project (defaults to $PWD):
-cd /path/to/your-app
-/mnt/c/3AIGenCode/TechieFlow/update-framework.sh</code></pre>
-<p class="small"><strong>macOS:</strong></p>
-<pre><code class="lang-bash"># Preview what would change (recommended first):
-/Volumes/MacD/MyCode/TechieFlow/update-framework.sh /path/to/your-app --dry-run
-# Apply:
-/Volumes/MacD/MyCode/TechieFlow/update-framework.sh /path/to/your-app
-# Or run from inside the project (defaults to $PWD):
-cd /path/to/your-app
-/Volumes/MacD/MyCode/TechieFlow/update-framework.sh</code></pre>
-<p>Note: the script is NOT on your PATH — always invoke it with the full path shown above (a bare <code>update-framework.sh</code> gives <em>"command not found"</em>). Optional alias — WSL: <code>echo "alias update-framework.sh='/mnt/c/3AIGenCode/TechieFlow/update-framework.sh'" &gt;&gt; ~/.bashrc</code> · macOS (zsh): <code>echo "alias update-framework.sh='/Volumes/MacD/MyCode/TechieFlow/update-framework.sh'" &gt;&gt; ~/.zshrc</code>.</p>
-<table>
-  <tr><th>Force-overwritten (framework — reference repo wins)</th><th>Preserved (your work product — never touched)</th></tr>
-  <tr>
-    <td><code>.tfcore/{tasks,templates,agents,checklists,data,utils,workflows,agent-teams}/</code><br>
-        <code>.claude/commands/TechieFlow/</code> subtree<br>
-        <code>.claude/commands/*.md</code> top-level commands (generate-html etc.)<br>
-        <code>.opencode/command/*.md</code> top-level commands (generate-html etc.)<br>
-        <code>WORKFLOW.html</code><br>
-        <code>.claude/settings.json</code> (refreshed to canonical config by default; old file → <code>settings.json.bak</code>; <code>--keep-permissions</code> to skip; <code>settings.local.json</code> never touched)</td>
-    <td><code>docs/</code>, <code>src/</code>, <code>tests/</code><br>
-        <code>PROJECT-STATUS.md</code>, <code>CLAUDE.md</code>, <code>.editorconfig</code><br>
-        <code>.tfcore/core-config.yaml</code><br>
-        <code>opencode.jsonc</code><br>
-        <code>.claude/{trblazeui,techierag}.md</code> + <code>.opencode/command/{trblazeui,techierag}.md</code> (NuGet-deployed)</td>
-  </tr>
-</table>
-<p>The scaffolders and the updater also <strong>ensure the project's <code>.gitignore</code> ignores the deployed framework copies</strong> (<code>.tfcore/</code>, <code>.claude/</code>, <code>.opencode/</code>, <code>.codex/</code>, <code>.agents/skills/</code>, <code>/CLAUDE.md</code>, <code>/WORKFLOW.html</code>, <code>/opencode.jsonc</code>, <code>/.tf-scaffold-note.txt</code>) — everything the framework drops into an app is a <em>copy</em> (source of truth: the reference repo, or the NuGet package for the library personas) and must never be committed in the app repo. The step is append-only and idempotent: your own <code>.gitignore</code> entries are respected, nothing is removed. Note git never <em>un</em>tracks a file just because it became ignored — if a framework file was committed before the entry existed, run <code>git rm -r --cached &lt;path&gt;</code> once yourself (git is manual in TechieFlow; agents never run it).</p>
-<p>They also manage a second block — <strong>agent test-harness &amp; log artifacts</strong> (<code>node_modules/</code>, <code>/package.json</code>, <code>/package-lock.json</code>, <code>tests/.artifacts/</code>, <code>test-results/</code>, <code>test-results-*/</code>, <code>/scripts-*/</code>, <code>playwright-report/</code>, <code>.verify/</code>, <code>logs/</code>, <code>/docs/.last-verify.json</code>, <code>.DS_Store</code>). These are machine-generated by the verifier's npm/Playwright self-provisioning (verify-phase §1) and the standing Serilog default, and are fully regenerable — <strong>you should never have to triage them at commit time</strong>. verify-phase §1 also self-heals the block whenever it provisions, so even a project scaffolded before this block existed gets it on its next verify. <code>playwright.config.ts</code> deliberately stays <em>tracked</em> — committed test suites depend on it. Same caveat as above: already-tracked artifacts need a one-time <code>git rm -r --cached &lt;path&gt;</code> from you.</p>
-<p><strong>Where test artifacts live — <code>tests/.artifacts/</code>, never the repo root</strong> (rule added 2026-08-10). Screenshots, traces, videos and Playwright/Appium output are <em>failure evidence with a session lifetime</em>, not work product: they exist so a verify run can cite a path in a checklist Remark, and Playwright wipes the directory at the start of the next run. verify-phase §1 now pins <code>outputDir: './tests/.artifacts/test-results'</code> in <code>playwright.config.ts</code> — creating the config if absent and <strong>editing it if it lacks the setting</strong> — and bans the two habits that used to litter app repos: a repo-root <code>test-results/</code>, and per-cluster siblings like <code>test-results-cluster-a/</code> from a fan-out passing <code>--output test-results-&lt;slug&gt;</code>. Those siblings were the real damage: <code>test-results/</code> does not match <code>test-results-cluster-a/</code>, so they were never ignored, they surfaced untracked at every commit, and they accumulated one directory per run (TechieBlog reached fourteen). If a parallel run genuinely needs isolation, the only permitted form is a subfolder — <code>--output tests/.artifacts/&lt;slug&gt;</code>. The bare <code>test-results/</code> and the <code>test-results-*/</code> glob stay in the ignore block purely to cover legacy trees; a compliant run writes neither, and verify-phase §1 deletes any it finds at the repo root on its next pass. Deliberately tracked screenshots — the DevGuide's reviewed set under <code>docs/screenshots/&lt;APP&gt;/</code> — are untouched by all of this.</p>
-<p><strong>The rule covers the harness too, not just its output</strong> (extended 2026-08-10). The first version of this rule pinned where the <em>tools write</em> and said nothing about where the agent <em>puts the scripts it writes</em> — so the next fan-out stopped creating <code>test-results-cluster-a/</code> and created <code>scripts-cluster-b/</code> instead: same defect, different noun, same four untracked folders in your commit view. A throwaway smoke/verify/load/cleanup script an agent authors for a run is scratch, and it now lands in <strong><code>tests/.artifacts/harness/</code></strong>, named per cluster <em>inside</em> that folder. Two things follow. Your project's own <strong><code>scripts/</code></strong> — release, publish, dev-setup scripts you track and own — is off limits to agents in both directions: nothing writes a run harness into it, and no sweep ever deletes it (the ignore entry is <code>/scripts-*/</code>, which requires the hyphen and the root anchor, so plain <code>scripts/</code> can never match). And a harness that does <code>import { chromium } from 'playwright'</code> drives the <strong>library</strong>, not the test runner — it never loads <code>playwright.config.ts</code>, so <code>outputDir</code> does not apply and nothing wipes what it writes; such a script must place its own captures under <code>tests/.artifacts/</code> and must never hardcode an absolute path. The general lesson, worth stating because the first fix missed it: a location rule has to name the <em>class of thing</em> (everything this run generates that is not a deliverable), not the specific filenames a tool happened to default to.</p>
-<div class="panel warn">
-  <strong>After every update: restart Claude Code</strong> in that project. New/changed tasks and agents under <code>.claude/commands/TechieFlow/</code> are only registered as skills at session start — without a restart, a freshly-synced command like <code>/TechieFlow:tasks:generate-html</code> won't resolve.
-</div>
-<!-- ============================================================ -->
-<h2 id="naming">4. File-naming convention — <span class="placeholder">&lt;APP&gt;</span> prefix<span class="anchor-link"><a href="#naming">#</a></span></h2>
-<p>Every per-project document filename starts with the application name. Examples from the user's existing projects: <code>AppManager-Coding-Standards.md</code>, <code>AstroLyfe-Coding-Standards.md</code>. Same convention applies to every doc:</p>
-<table>
-  <tr><th>Pattern</th><th>Example for app "AppManager"</th><th>Example for app "AstroLyfe"</th></tr>
-  <tr><td><code>&lt;APP&gt;-BRD.md</code> / <code>.html</code></td><td><code>AppManager-BRD.md</code></td><td><code>AstroLyfe-BRD.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-Architecture.md</code> / <code>.html</code></td><td><code>AppManager-Architecture.md</code></td><td><code>AstroLyfe-Architecture.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-Coding-Standards.md</code></td><td><code>AppManager-Coding-Standards.md</code></td><td><code>AstroLyfe-Coding-Standards.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-Checklist.md</code> (ONE per app — all REQ-UI/FN/RAG/NFR-*)</td><td><code>AppManager-Checklist.md</code></td><td><code>AstroLyfe-Checklist.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-UIDesign.md</code> (greenfield mockups spec)</td><td><code>AppManager-UIDesign.md</code></td><td><code>AstroLyfe-UIDesign.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-&lt;Library&gt;-Feedback.md</code> (one per library)</td><td><code>AppManager-TrBlazeUI-Feedback.md</code></td><td><code>AstroLyfe-TechieRag-Feedback.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-UsageGuide.md</code></td><td><code>AppManager-UsageGuide.md</code></td><td><code>AstroLyfe-UsageGuide.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-DevGuide.md</code> (developer code-map)</td><td><code>AppManager-DevGuide.md</code></td><td><code>AstroLyfe-DevGuide.md</code></td></tr>
-  <tr><td><code>&lt;APP&gt;-ProductGuide.md</code> (end-user how-to manual)</td><td><code>AppManager-ProductGuide.md</code></td><td><code>AstroLyfe-ProductGuide.md</code></td></tr>
-</table>
-<p>Throughout this document, <span class="placeholder">&lt;APP&gt;</span> is a placeholder. When you paste a prompt to an agent, substitute it with your actual application name (no spaces; use PascalCase to match the user's two existing samples).</p>
-<p>Files that stay generic (not <code>&lt;APP&gt;</code>-prefixed):</p>
-<ul class="tight">
-  <li><code>PROJECT-STATUS.md</code> / <code>.html</code> — one per repo, project-name is in its content</li>
-  <li><code>CLAUDE.md</code> — Claude Code's auto-loaded session memory; one per repo</li>
-  <li><code>WORKFLOW.html</code> — this file; identical across projects</li>
-</ul>
-<!-- ============================================================ -->
-<h2 id="structure">5. Project structure<span class="anchor-link"><a href="#structure">#</a></span></h2>
-<pre><code>your-app/                              ← e.g. AppManager/
-├── PROJECT-STATUS.md                  ← /analyst (day 1)
-├── PROJECT-STATUS.html                ← /flow-master after each phase
-├── CLAUDE.md                          ← /analyst (day 1) — pins coding standards
-├── WORKFLOW.html                      ← from scaffold
-│
-├── .tfcore/                        ← from scaffold (your customized v4)
-├── .claude/
-│   ├── commands/TechieFlow/...              ← from scaffold
-│   ├── settings.json                  ← from scaffold (yolo-except-git-writes)
-│   ├── trblazeui.md                   ← from `dotnet build` (TrBlazeUI NuGet)
-│   └── techierag.md                   ← from `dotnet build` (TechieRag NuGet)
-├── .opencode/command/
-│   ├── generate-html.md                ← from scaffold
-│   ├── trblazeui.md                   ← from dotnet build
-│   └── techierag.md                   ← from dotnet build
-├── .trblazeui/TrBlazeUI-AI-Reference.md   ← from dotnet build
-├── .techierag/TechieRag-AI-Reference.md   ← from dotnet build
-│
-├── .editorconfig                      ← /analyst (day 1) — machine-checkable subset of coding standards
-│
-├── docs/
-│   ├── &lt;APP&gt;-BRD.md                ← /analyst — humans + AI
-│   ├── &lt;APP&gt;-BRD.html              ← /flow-master renders BRD.md → humans
-│   ├── &lt;APP&gt;-Architecture.md       ← /analyst — humans + AI (both flows!)
-│   ├── &lt;APP&gt;-Architecture.html     ← /flow-master renders Architecture.md → humans
-│   ├── &lt;APP&gt;-Coding-Standards.md   ← /analyst (day 1) — ALL agents follow this
-│   ├── &lt;APP&gt;-Checklist.md          ← /analyst (*split-brd) — ONE checklist, all REQ-UI/FN/RAG/NFR-* — AI
-│   ├── &lt;APP&gt;-UIDesign.md           ← /analyst (*mockups, greenfield) — per-screen spec + component map — humans
-│   ├── &lt;APP&gt;-UIDesign.html         ← rendered for humans
-│   ├── mockups/                    ← /analyst (*mockups, greenfield) — rendered *.html screens (TrBlazeUI-styled)
-│   ├── screenshots/&lt;APP&gt;/          ← /flow-master (*devguide OBSERVE — any built app) — per-screen *.png (DevGuide + Product Guide source)
-│   ├── &lt;APP&gt;-TrBlazeUI-Feedback.md ← agents log TrBlazeUI issues — one file PER library
-│   ├── &lt;APP&gt;-TechieRag-Feedback.md ← agents log TechieRag issues — each goes to its team
-│   ├── &lt;APP&gt;-UsageGuide.md  ← /flow-master — humans
-│   ├── &lt;APP&gt;-UsageGuide.html       ← /flow-master — rendered for humans
-│   ├── &lt;APP&gt;-DevGuide.md           ← /flow-master (*devguide) — humans (small app: single doc)
-│   ├── &lt;APP&gt;-DevGuide.html         ← /flow-master — rendered for humans
-│   ├── devguides/                  ← large app: split per-role DevGuide (index + &lt;APP&gt;-DevGuide-&lt;Role&gt;.md/.html)
-│   ├── &lt;APP&gt;-ProductGuide.md       ← /flow-master (*productguide) — END USERS / external (small app: single doc)
-│   ├── &lt;APP&gt;-ProductGuide.html     ← /flow-master — rendered for end users
-│   └── productguides/              ← large app: split per-role Product Guide (index + &lt;APP&gt;-ProductGuide-&lt;Role&gt;.md/.html)
-│
-├── tests/{playwright,unit}/  …
-└── src/  …</code></pre>
-<!-- ============================================================ -->
-<h2 id="docs">6. Doc artifacts &amp; audiences<span class="anchor-link"><a href="#docs">#</a></span></h2>
-<p class="small"><strong>Agent-facing authoring notes never render.</strong> The doc templates carry drafting-agent instructions (the "Depth mandate" / "Mermaid mandate" notes) as HTML comments, so they are invisible in both the generated <code>.md</code> and the rendered HTML — the human reader must never see them. Docs generated from pre-2026-07 templates may still show them as visible blockquotes; the next HTML render strips them automatically (<code>html-render-shell.md §6b</code>).</p>
-<table>
-  <tr><th>File</th><th>Audience</th><th>Format</th><th>Created by</th><th>Purpose</th></tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-BRD.md</code></td>
-    <td><span class="audience h">H</span> <span class="audience a">AI</span></td>
-    <td>MD + Mermaid</td>
-    <td><code>/analyst</code></td>
-    <td>Business Requirements — the WHY.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-BRD.html</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>Self-contained HTML</td>
-    <td><code>/flow-master</code></td>
-    <td>Browseable BRD for stakeholders / future-you.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-Architecture.md</code></td>
-    <td><span class="audience h">H</span> <span class="audience a">AI</span></td>
-    <td>MD + Mermaid</td>
-    <td><code>/analyst</code> (both flows)</td>
-    <td>Brownfield: current architecture + planned deltas. Greenfield: target architecture.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-Architecture.html</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>Self-contained HTML</td>
-    <td><code>/flow-master</code></td>
-    <td>Browseable architecture diagrams.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-Coding-Standards.md</code></td>
-    <td><span class="audience h">H</span> <span class="audience a">AI</span></td>
-    <td>Markdown</td>
-    <td><code>/analyst</code> (day 1)</td>
-    <td>Every implementation agent follows this. Pinned by CLAUDE.md.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-Checklist.md</code></td>
-    <td><span class="audience a">AI</span></td>
-    <td>Markdown w/ <code>REQ-UI-*</code>, <code>REQ-FN-*</code>, <code>REQ-RAG-*</code>, <code>REQ-NFR-*</code></td>
-    <td><code>/analyst</code> (<code>*split-brd</code>)</td>
-    <td>The ONE checklist — every REQ class in a single Requirements Status table. Input for <code>*build-phase</code> (which routes REQ-UI-* to <code>/trblazeui</code> and REQ-RAG-* to <code>/techierag</code> as sub-agents). Scopes (<code>*verify ui|functional|all</code>) filter this one table by REQ prefix. Agent-only working doc — never rendered to HTML.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-UIDesign.md</code> + <code>.html</code><br><code>docs/mockups/*.html</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>MD + HTML</td>
-    <td><code>/analyst</code> (<code>*mockups</code>, greenfield)</td>
-    <td>Per-screen UI Design Spec with a <code>region → TrBlazeUI control</code> component map + rendered TrBlazeUI-styled mockups. Approved with the BRD + Architecture before build; what <code>/trblazeui</code> builds from; the verifier's visual baseline (§4b).</td>
-  </tr>
-  <tr>
-    <td><code>PROJECT-STATUS.md</code> + <code>.html</code></td>
-    <td><span class="audience h">H</span> <span class="audience a">AI</span></td>
-    <td>MD + HTML</td>
-    <td><code>/analyst</code> then <code>/flow-master</code></td>
-    <td>Single source of "where am I".</td>
-  </tr>
-  <tr>
-    <td><code>CLAUDE.md</code></td>
-    <td><span class="audience a">AI</span></td>
-    <td>Markdown</td>
-    <td><code>/analyst</code> (day 1)</td>
-    <td>Auto-loaded by Claude Code; points to coding standards, BRD, Architecture.</td>
-  </tr>
-  <tr>
-    <td><code>.editorconfig</code></td>
-    <td><span class="audience a">AI</span> (toolchain)</td>
-    <td>EditorConfig</td>
-    <td><code>/analyst</code> (day 1)</td>
-    <td>Machine-checkable subset of coding standards (file-scoped namespace, async suffix, no-underscore field naming rule).</td>
-  </tr>
-  <tr>
-    <td>Requirements Status table (inside the one checklist)</td>
-    <td><span class="audience a">AI</span> <span class="audience h">H</span></td>
-    <td>MD table</td>
-    <td>build agents + <code>/verifier</code></td>
-    <td>Per-REQ status/%/remarks — single source of truth; REQ ID → PASS/FAIL/Blocked evidence.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-TrBlazeUI-Feedback.md</code><br><code>docs/&lt;APP&gt;-TechieRag-Feedback.md</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>Markdown</td>
-    <td>All implementing agents</td>
-    <td>Issues to ship back to each library's team — <strong>one file per library</strong> (separate codebases, separate teams; each file is handed to its owning team, who use this same framework to fix them).</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-UsageGuide.md</code> + <code>.html</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>MD + HTML</td>
-    <td><code>/flow-master</code></td>
-    <td>Final handoff: install, run, test, smoke checklist.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-DevGuide.md</code> + <code>.html</code><br><small>(large apps: split per role into <code>docs/devguides/&lt;APP&gt;-DevGuide-{Role}.md</code> + index)</small></td>
-    <td><span class="audience h">H</span></td>
-    <td>MD + HTML</td>
-    <td><code>/flow-master</code> (<code>*devguide</code>)</td>
-    <td>Developer reference: every screen → control → service method → stored procedure, grouped by user role. Used to trace bugs and verify AI-generated code. Auto-generated at handoff; re-runnable anytime. See <a href="#docs">§6</a>.</td>
-  </tr>
-  <tr>
-    <td><code>docs/&lt;APP&gt;-ProductGuide.md</code> + <code>.html</code><br><small>(large apps: split per role into <code>docs/productguides/&lt;APP&gt;-ProductGuide-{Role}.md</code> + index)</small></td>
-    <td><span class="audience h">H</span> (end users / external)</td>
-    <td>MD + HTML</td>
-    <td><code>/flow-master</code> (<code>*productguide</code>)</td>
-    <td>End-user how-to manual: what each screen is for and how to do each task, illustrated with the screenshots captured for the DevGuide. The user-facing sibling of the DevGuide (same screens, different audience). On-demand; <code>--update</code> refreshes changed screens; always emits MD + HTML. See <a href="#docs">§6</a>.</td>
-  </tr>
-  <tr>
-    <td><code>.tfcore/TOKEN-GUIDE.md</code></td>
-    <td><span class="audience h">H</span></td>
-    <td>Markdown</td>
-    <td>framework (ships with scaffold)</td>
-    <td>Token-efficiency guide — where AI tokens go and how to keep usage low. See <a href="#quickref">§14</a>.</td>
-  </tr>
-</table>
-<div class="panel">
-  <strong>Mermaid in HTML.</strong> <code>/flow-master</code> renders BRD.html and Architecture.html as self-contained HTML with <code>&lt;script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"&gt;&lt;/script&gt;</code> and <code>mermaid.initialize({startOnLoad:true, theme:'dark'})</code>. ```mermaid fences in the MD become SVG diagrams in the HTML.
-</div>
-<!-- ============================================================ -->
-<h2 id="flows">7. Workflows<span class="anchor-link"><a href="#flows">#</a></span></h2>
-<div class="panel ok">
-  <strong>No paste-and-substitute friction:</strong> every workflow step below is wrapped as a proper TechieFlow task that takes <code>{AppName}</code> as an argument. Run <code>/analyst *day1-brownfield TrTools</code> and the analyst executes the full multi-step task with the right file paths and templates already wired up. The agent will ask for the app name only if you forget to pass it.
-  <br><br>
-  The task files live in <code>.tfcore/tasks/</code>: <code>day1-brownfield.md</code>, <code>day1-greenfield.md</code>, <code>mockups.md</code>, <code>render-workflow-docs.md</code>, <code>split-brd.md</code>, <code>build-phase.md</code> (the ONE unified build), <code>verify-phase.md</code>, <code>fix-issues.md</code>, <code>triage-issues.md</code>, <code>devguide.md</code>, <code>handoff-phase.md</code>. Open any of them to see exactly what the agent will do.
-</div>
-<div class="panel warn">
-  <strong>If <code>*&lt;command&gt;</code> says "I don't have that command":</strong> Claude Code cached the old agent persona. Two things to check:
-  <ol class="tight">
-    <li>Re-run the scaffold for this project: <code>scaffold-brownfield.sh .</code> or <code>scaffold-greenfield.sh .</code>. It includes a force-sync step that copies agent files from <code>.tfcore/agents/</code> to <code>.claude/commands/TechieFlow/agents/</code> (the path Claude Code actually loads).</li>
-    <li><strong>Restart Claude Code</strong> in this project so it re-scans skills. The slash-command registry only refreshes at startup.</li>
-  </ol>
-  Rule of thumb: edit agent files only in <code>.tfcore/agents/</code>; the scaffold force-mirrors them to <code>.claude/commands/TechieFlow/agents/</code>. Never edit the harness copy directly — it'll be overwritten next scaffold.
-</div>
-<div class="tabs">
-  <button class="active" data-tab="bf">Brownfield (existing app)</button>
-  <button data-tab="gf">Greenfield (new app)</button>
-</div>
-<!-- BROWNFIELD -->
-<div class="tabpanel active" id="tab-bf">
-<div class="panel">
-  <strong>Prereq:</strong> ran <code>scaffold-brownfield.sh</code> in the project root.
-  <br><span class="small"><strong>Typical agent invocations:</strong> 4–6 (day-1, split-brd, build-phase ×1–2, handoff). <strong>Manual checkpoints:</strong> 2 (BRD/Architecture/Standards + DevGuide-screenshot review, final UAT).</span>
-</div>
-<div class="flow">
-  <div class="step">
-    <div class="num">1</div>
-    <div class="body">
-      <h4>Reverse-doc + create all six day-1 deliverables</h4>
-      <p>Produces, in ONE bulk pass (no per-section/per-requirement confirmation): <code>&lt;APP&gt;-Architecture.md</code>, <code>&lt;APP&gt;-BRD.md</code> (feature catalog + BRD ledger), <code>&lt;APP&gt;-Coding-Standards.md</code>, <code>.editorconfig</code>, <code>PROJECT-STATUS.md</code>, <code>CLAUDE.md</code>, the <code>&lt;APP&gt;-UsageGuide.md</code>, and — because brownfield already has built code — the screen-by-screen <code>&lt;APP&gt;-DevGuide.md</code> (§7.6) — <strong>plus the HTML render of every doc</strong> (no separate render step). Updates <code>core-config.yaml</code> with the app-specific doc paths.</p>
-      <p class="cmds"><span class="badge cmd">/analyst</span> <span class="badge task">*day1-brownfield TrTools</span></p>
-      <p class="small">Substitute <code>TrTools</code> with your app name. Asks at most twice: app name (if omitted) and which existing docs to harvest (<code>all</code> = default / a selection / extra paths / drafting instructions). It never asks merge-vs-new: deliverables are always written fresh at canonical names and pre-existing/superseded docs are archived to <code>docs/OldDocs/</code>. If a dev/phase plan exists, it's migrated into the one <code>&lt;APP&gt;-Checklist.md</code> in the same run (completed phases pre-marked Done — skip step 3 below). <strong>Brownfield-only:</strong> because the repo already has built code, it also generates the screen-by-screen <strong>DevGuide</strong> (§7.6 — the as-built page → control → service → data-access → proc map). The DevGuide's OBSERVE pass boots the app, <strong>captures a screenshot of every screen</strong> to <code>docs/screenshots/&lt;APP&gt;/</code>, embeds them, and presents an <strong>owner visual-review gate</strong> ("here is how each screen renders — what needs to change?") — the brownfield counterpart to greenfield mockups. (Commonly <code>STATIC-ONLY</code> at day-1 until the stack is up; found defects land in the one checklist.) Greenfield day-1 has no code, so instead it produces UI <strong>mockups</strong> (§7.10). Task: <code>.tfcore/tasks/day1-brownfield.md</code>.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">2</div>
-    <div class="body">
-      <h4>Review the rendered HTMLs — manual checkpoint (≈15 min)</h4>
-      <p class="small">No command — day-1 already rendered everything. Open <code>&lt;APP&gt;-BRD.html</code> (business intent right?), <code>&lt;APP&gt;-Architecture.html</code> (matches what you want?), <code>PROJECT-STATUS.html</code> (next command correct?), skim Coding Standards. Cheapest catch-mistakes point. Edit the <code>.md</code> sources directly for anything wrong, then re-render just those files: <code>/generate-html @docs/&lt;APP&gt;-BRD.md</code> (see <a href="#docs">§6</a>).</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">3</div>
-    <div class="body">
-      <h4>Split BRD into the one Checklist</h4>
-      <p class="cmds"><span class="badge cmd">/analyst</span> <span class="badge task">*split-brd TrTools</span></p>
-      <p class="small">Every BRD-N maps to one or more REQ-UI-*/REQ-FN-*/REQ-RAG-*/REQ-NFR-* in the single <code>docs/&lt;APP&gt;-Checklist.md</code> (one Requirements Status table), each back-linked to its source BRD. Each <code>REQ-UI-*</code> cites the mockup screen it realizes (greenfield). Task: <code>.tfcore/tasks/split-brd.md</code>.</p>
-      <p class="small"><strong>Manual checkpoint:</strong> read the checklist, adjust if needed.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">4</div>
-    <div class="body">
-      <h4>Build phase — ONE unified build (chains self-smoke + verifier)</h4>
-      <p class="cmds"><span class="badge cmd">/flow-master</span> <span class="badge task">*build-phase TrTools</span></p>
-      <p class="small">There is no longer a separate UI / RAG / functional build. <code>*build-phase</code> reads the one checklist, clusters ALL open REQs, and fans them out — <strong>calling <code>/trblazeui</code> (REQ-UI-*, building from the approved mockups) and <code>/techierag</code> (REQ-RAG-*) as sub-agents</strong>, and building REQ-FN-* / REQ-NFR-* itself. It then <strong>self-smokes (data + visual)</strong> and auto-chains <code>/verifier</code>. You never invoke <code>/trblazeui</code> or <code>/techierag</code> directly — flow-master orchestrates them. Task: <code>.tfcore/tasks/build-phase.md</code>.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">5</div>
-    <div class="body">
-      <h4 id="verify">Verify loop (until green)</h4>
-      <p><code>*build-phase</code> self-chains <code>/verifier</code>, which writes verdicts into the one checklist's Requirements Status table and applies BOTH gates — the <strong>data-render gate</strong> (§4a: every control renders its data) AND the <strong>visual-truth gate</strong> (§4b: no overlap, every control in-viewport and non-zero-size at desktop + mobile, screenshot inspected, diffed against the mockup when one exists). A REQ is <code>Verified</code> only if acceptance passes AND data renders AND the screen looks right.</p>
-      <p><strong>The performance gate (§4c, added 2026-08-10) — opt-in by declaring a number.</strong> Render and visual say nothing about <em>speed</em>: a page that shows every control perfectly and takes nine seconds passed every gate the framework had. §4c closes that, and it is deliberately the narrowest of the four. It grades a REQ <strong>only</strong> if that REQ's acceptance criteria carry a machine-read budget line:</p>
-      <pre><code>perf-budget: p95 load &lt;= 2000ms @ concurrency 1
-perf-budget: p95 ttfb &lt;= 500ms  @ concurrency 50</code></pre>
-      <p>No line, no gate — and that is the correct outcome, not a gap to fill. A threshold you never agreed to would produce failures you never asked for, and the first false failure is the moment gate verdicts stop being believed. Measurement is the shipped harness <code>.tfcore/utils/tf-perf.sh</code> (TTFB and full-load p50/p95/max at graded concurrency, warm-up discarded, per-path breakdown so you can see <em>which</em> page is slow).</p>
-      <table>
-      <thead><tr><th>Measured vs budget</th><th>Verdict</th><th>Effect</th></tr></thead>
-      <tbody>
-      <tr><td>≤ budget</td><td><code>PERF-OK</code></td><td>gate passes</td></tr>
-      <tr><td>&gt; budget, ≤ budget × 1.25</td><td><code>PERF-MARGINAL</code></td><td><strong>never blocks <code>Verified</code></strong> — a dated remark, so drift is visible before it becomes a failure</td></tr>
-      <tr><td>&gt; budget × 1.25</td><td><code>PERF-FAIL</code></td><td>→ <code>Needs re-verify</code></td></tr>
-      </tbody>
-      </table>
-      <p>The gate <strong>refuses to fail</strong> a REQ on a Debug build, on fewer than 20 samples behind the p95, when errors occurred during the run, or on a visibly contended host — each becomes <code>PERF-UNMEASURED</code> with the reason stated, because a wrong perf failure costs more than a missing one. MAUI native heads are not perf-gated (no HTTP surface; app-launch and frame timing are a different discipline with different tooling). Write budgets in the BRD §11 Performance NFR; <code>*split-brd</code> copies the line verbatim into the REQ, and <code>*metrics</code> reports the gate's catch rate against how many records actually <em>ran</em> it, never against the whole distribution (<code>SCHEMA.md</code> §3.5).</p>
-      <p class="small">If Vidur reports misses, just re-run <code>/flow-master *build-phase TrTools</code> — it detects FIX mode and fans out repair subagents (layout/visual fixes route back to <code>/trblazeui</code>). Or re-verify a scope directly with <code>/TechieFlow:agents:verifier *verify ui|functional|all</code> (it filters the one table by REQ prefix). Loop until green; <code>Blocked</code> (library-gap) items pass through. Vidur also runs the <strong>standards-compliance grep checks</strong> from <code>&lt;APP&gt;-Coding-Standards.md</code> §"Enforcement".</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">6</div>
-    <div class="body">
-      <h4>Handoff: usage doc + dev guide + status + library-feedback consolidation + HTML refresh</h4>
-      <p class="cmds"><span class="badge cmd">/flow-master</span> <span class="badge task">*handoff-phase TrTools</span></p>
-      <p class="small">Produces UsageGuide doc (test users + test plan + setup), runs <code>*devguide</code> (§3a — generates the screen-by-screen Developer Guide documenting the code as-built, capturing a screenshot of every screen), sets PROJECT-STATUS phase to Handoff, re-renders human-facing HTMLs (BRD, Architecture, UIDesign, UsageGuide, DevGuide, PROJECT-STATUS — <strong>not</strong> the checklist), consolidates each per-library feedback file with summary counts. It also points owners at <code>*productguide &lt;APP&gt;</code> (<a href="#docs">§6</a>) — the optional end-user how-to manual, built from the same screens + screenshots the DevGuide just captured. Task: <code>.tfcore/tasks/handoff-phase.md</code>.</p>
-      <p class="small"><strong>Manual checkpoint:</strong> 15-min UAT against the smoke checklist. Then hand each <code>&lt;APP&gt;-&lt;Library&gt;-Feedback.md</code> to its team / file as GitHub issues (§9.2). <strong>Found a bug after shipping?</strong> Drop screenshots into a folder and run <code>*fix-issues</code> (§7.11) — or <code>*triage-issues</code> (§7.12) to analyze + log it in the checklist first, without fixing.</p>
-    </div>
-  </div>
-</div>
-</div><!-- /tab-bf -->
-<!-- GREENFIELD -->
-<div class="tabpanel" id="tab-gf">
-<div class="panel">
-  <strong>Prereq:</strong> scaffold + <code>dotnet new sln/blazor</code> + library NuGets + <code>dotnet build</code> (deploys library agent files).
-</div>
-<div class="flow">
-  <div class="step">
-    <div class="num">1</div>
-    <div class="body">
-      <h4>Brief + BRD + Architecture + Coding-Standards + CLAUDE.md + PROJECT-STATUS + .editorconfig</h4>
-      <p class="cmds"><span class="badge cmd">/analyst</span> <span class="badge task">*day1-greenfield MyNewApp</span></p>
-      <p class="small">Asks once for the concept (ANY length — sentence, bullets, half-baked notes) and once for optional harvest paths / drafting instructions, then produces the day-1 artifacts in bulk — including a TARGET architecture with stack defaults (Blazor Server + TrBlazeUI + TechieRag-if-AI + SQLite-for-dev) and the UI <strong>mockups</strong> (<code>docs/&lt;APP&gt;-UIDesign.md</code> + <code>docs/mockups/*.html</code>, §7.10) — <strong>plus the HTML render of every doc</strong> (no separate render step). Substitute <code>MyNewApp</code> with your actual app name. Task: <code>.tfcore/tasks/day1-greenfield.md</code>.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">2</div>
-    <div class="body">
-      <h4>Review the rendered HTMLs AND the mockups — manual checkpoint (approve before build)</h4>
-      <p>No command — day-1 already rendered everything. Read the BRD/Architecture HTMLs AND open <code>docs/mockups/*.html</code> + <code>docs/&lt;APP&gt;-UIDesign.md</code>: this is the visual design the UI will be built to match, so flag any screen that's wrong NOW. Edit the <code>.md</code> sources and re-render with <code>/generate-html @docs/file.md</code>, or run <code>*mockups &lt;APP&gt; --update</code>. The BRD + Architecture + mockups are <strong>approved together</strong> before any build.</p>
-      <p class="small">This is your last cheap chance to redirect before code gets written.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">3–6</div>
-    <div class="body">
-      <h4>Split BRD → Build phase → Verify → Handoff</h4>
-      <p>Identical to brownfield steps 3–6. Same prompts, same one checklist, same unified <code>*build-phase</code> (which builds REQ-UI-* from your approved mockups via <code>/trblazeui</code>), same data + visual gates, same standards-compliance discipline.</p>
-    </div>
-  </div>
-</div>
-</div><!-- /tab-gf -->
-<h3 id="evolving-docs">7.9 Evolving the day-1 docs (the concept/requirements changed)</h3>
-<p>Day-1 produces a first-pass BRD + Architecture, but a project keeps moving — the greenfield concept is still being discussed, or a requirement shifts mid-development. You do <strong>not</strong> have to hand-edit and hope, and you should <strong>not</strong> silently let the docs drift out of date. Pick by how big the change is:</p>
-<table>
-  <thead><tr><th>Situation</th><th>Command</th><th>What it does</th></tr></thead>
-  <tbody>
-    <tr>
-      <td><strong>Concept/requirements evolved</strong> — add / reword / drop features, a new integration, a stack tweak — but most of the docs are still right</td>
-      <td><code>*amend-docs &lt;APP&gt; "&lt;what changed&gt;"</code><br><span class="small">(analyst or flow-master)</span></td>
-      <td>Surgically amends the BRD + Architecture <strong>in place</strong>: appends new <code>BRD-N</code> (IDs are append-only — modified IDs are edited in place, removed ones struck through, never renumbered), updates the feature catalog + §4 Development-status, ripples new/changed REQs into the checklist (appends new rows, flags modified ones for re-verify — never blindly re-splits), re-renders the HTML, and runs the status gate. Confirms the parsed change-set once, then applies in bulk. <strong>Preserves every unchanged section</strong> — no <code>OldDocs</code> archive.</td>
-    </tr>
-    <tr>
-      <td><strong>Pure additions</strong> and you want to confirm each requirement one at a time</td>
-      <td><code>*create-brd &lt;APP&gt; &lt;topic&gt;</code> → <code>author-brd</code><br><span class="small">(analyst)</span></td>
-      <td>Interactive, per-item elicitation; appends confirmed <code>BRD-N</code> to the existing BRD. (<code>*amend-docs</code> defers to this for the additive part if you ask.)</td>
-    </tr>
-    <tr>
-      <td><strong>"What's built" view</strong> is what you want refreshed (not the requirements)</td>
-      <td>automatic, or <code>*refresh-status &lt;APP&gt;</code></td>
-      <td>The status gate already re-derives <code>PROJECT-STATUS</code> + the BRD §4 rollup at the end of every build/verify/handoff. <code>*refresh-status</code> rebuilds them on demand (see §8a).</td>
-    </tr>
-    <tr>
-      <td><strong>Full pivot</strong> — most of the BRD/Architecture is now wrong</td>
-      <td>re-run <code>*day1-greenfield</code> / <code>*day1-brownfield</code></td>
-      <td>The §1.6 collision policy archives the old docs to <code>docs/OldDocs/</code> and writes fresh. Use this only for a wholesale redo, never for an incremental change (it would discard unchanged content + history).</td>
-    </tr>
-    <tr>
-      <td><strong>You just hand-edited a <code>.md</code></strong></td>
-      <td><code>/generate-html @docs/&lt;file&gt;.md</code></td>
-      <td>Re-renders that one doc's HTML so the human-readable view isn't stale.</td>
-    </tr>
-  </tbody>
-</table>
-<p class="small">Rule of thumb: <strong>amend, don't regenerate.</strong> <code>*amend-docs</code> is the default for an evolving project; re-running day-1 is the escape hatch for a true restart. After amending, if new requirements were added to an already-split project, run <code>*split-brd</code> (or the build phase the report points at) to carry them into the build.</p>
-<h3 id="mockups">7.10 Greenfield UI mockups (<code>*mockups</code>)</h3>
-<p>A greenfield app has no code, so its UI is built freehand from prose — which is exactly why a new app's UI comes out broken (overlapping controls, wrong layout, nothing to verify against). The analyst produces <strong>mockups at day-1</strong> to give the build an approved visual contract and the verifier a baseline to diff against:</p>
-<p class="cmds"><span class="badge cmd">/analyst</span> <span class="badge task">*mockups MyNewApp</span></p>
-<p>Reads the TrBlazeUI component catalog FIRST (so it designs only with controls that exist), then produces <code>docs/&lt;APP&gt;-UIDesign.md</code> — a per-screen spec with a <code>region → TrBlazeUI control</code> component map — plus rendered <code>docs/mockups/*.html</code> styled to look like TrBlazeUI, one per key screen from the BRD §9 feature catalog. Auto-run inside <code>*day1-greenfield</code>; re-runnable with <code>*mockups &lt;APP&gt; --update</code> to refresh only changed screens after an <code>*amend-docs</code> that added UI. The mockups are approved alongside the BRD + Architecture, are what <code>/trblazeui</code> builds from, and are the image the visual-truth gate (<a href="#quickref">§4b</a>) diffs the live screen against. <strong>Mockups are greenfield only</strong> — a greenfield app has no code to screenshot yet, so its mockups are the pre-build visual contract; brownfield already has built code and instead reviews real screenshots in the DevGuide's OBSERVE pass (§7.6). Note this is about <em>mockups</em>, not screenshots: once a greenfield app is built, its DevGuide OBSERVE pass captures real per-screen screenshots exactly like brownfield (<a href="#docs">§6</a>). Task: <code>.tfcore/tasks/mockups.md</code>.</p>
-<h3 id="fix-issues">7.11 Fixing issues you found by running the app (<code>*fix-issues</code>)</h3>
-<p>When the verifier passed but the running UI is still broken — overlapping controls, blank screens, wrong data — there is ONE front door:</p>
-<p class="cmds"><span class="badge cmd">/flow-master</span> <span class="badge task">*fix-issues MyApp ./bugshots</span></p>
-<p>Drop a folder of <strong>screenshots</strong> (plus an optional <code>bugs.md</code> describing what's wrong on each) and flow-master: reads every screenshot (vision), reproduces each issue live with Playwright, triages it (layout / data / logic / RAG), and <strong>fans the fix out to the right builder</strong> — <code>/trblazeui</code> for layout, its own subagents for data/logic, <code>/techierag</code> for RAG. <strong>You never invoke a builder agent yourself — flow-master calls them as sub-agents.</strong> It then re-smokes (data + visual) and re-verifies the affected REQs, and updates the DevGuide + the one checklist + PROJECT-STATUS. This is the answer to "the verifier passed but the UI is broken — who do I call?". Task: <code>.tfcore/tasks/fix-issues.md</code>. Only want the bugs <em>analyzed and logged</em>, not fixed? That's <code>*triage-issues</code> (§7.12).</p>
-<h3 id="triage-issues">7.12 Analyzing UAT / production bugs WITHOUT fixing (<code>*triage-issues</code>)</h3>
-<p>Bugs found at UAT or in production usually need a <strong>plan and a paper trail before anyone touches code</strong>: which REQs regressed, what's a brand-new defect, what still passes. <code>*fix-issues</code> is the wrong tool for that moment — its deliverable is fixed code. The analyze-only front door is:</p>
-<p class="cmds"><span class="badge cmd">/flow-master</span> <span class="badge task">*triage-issues MyApp ./uat-bugs</span> &nbsp;·&nbsp; add <code>verify</code> to also regression-re-verify sibling features</p>
-<p>Hand it a folder of screenshots <em>and/or a written bug list</em> (UAT reports often arrive as prose). Flow-master reproduces each issue live with Playwright and delivers <strong>documentation only</strong>: regressed REQs are demoted to <code>Needs re-verify</code> with a dated <code>⚠ UAT bug</code> remark, unspecified defects become new <code>Planned</code> REQ rows with acceptance criteria, the DevGuide's known-issues lines are refreshed, and PROJECT-STATUS's "Next command" points at <code>*fix-issues {App} {folder}</code> naming the REQ IDs. With the optional <code>verify</code> argument it also EXECUTES a scoped verify-phase over the affected screens' sibling REQs ("check the rest still works"). <strong>It never edits <code>src/</code> or <code>tests/</code> and never spawns a builder sub-agent</strong> — fixing is a separate decision you make afterwards by running <code>*fix-issues</code>. Task: <code>.tfcore/tasks/triage-issues.md</code>.</p>
-<!-- ============================================================ -->
-<h2 id="resume">8. Resuming a cold project<span class="anchor-link"><a href="#resume">#</a></span></h2>
-<p>Two flavours of resume. Pick by asking one question: <strong>do you trust <code>PROJECT-STATUS.md</code>?</strong></p>
-<div class="panel warn">
-  <strong>8a. The session BROKE mid-phase → run <code>*refresh-status</code> first.</strong>
-  <p>If the last session died in the middle of a build or verify — lost internet, model access revoked/changed mid-run, terminal killed, agent crashed — then the mandatory status gate never ran. <code>PROJECT-STATUS.md</code> is now <em>stale or wrong</em>: it may point at an old "Next command", undercount work that landed after its last write, or claim a passing build that's since broken. Do NOT trust it. Run the recovery command, which rebuilds PROJECT-STATUS from <em>ground-truth evidence</em> (the checklist Requirements Status table + what's actually in the working tree, including file modification times + a fresh <code>dotnet build</code> — no git; git is manual in this framework) and tells you the exact command to resume with:</p>
-  <p class="cmds"><span class="badge cmd">/TechieFlow:agents:flow-master</span> <code>*refresh-status &lt;APP&gt;</code> &nbsp;—&nbsp; OpenCode: <code>/flow-master *refresh-status &lt;APP&gt;</code> &nbsp;·&nbsp; add <code>verify</code> to also re-run the verifier on any REQ whose true state is ambiguous.</p>
-  <p style="margin-bottom:0">It never edits source code — it only reconstructs status. When it finishes, follow its "next command", then drop into the clean flow below. This is the answer to "an experimental model lost access mid-development and I don't know where it left things."</p>
-</div>
-<p><strong>8b. Clean cold resume</strong> (you came back to a project whose last phase <em>did</em> finish and wrote PROJECT-STATUS): trust the file and walk the four steps.</p>
-<div class="flow">
-  <div class="step">
-    <div class="num">1</div>
-    <div class="body">
-      <h4>Open three HTML files in browser</h4>
-      <p><code>PROJECT-STATUS.html</code> (where am I), <code>&lt;APP&gt;-BRD.html</code> (why was I doing this), <code>&lt;APP&gt;-Architecture.html</code> (what's the shape). &lt; 5 min.</p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">2</div>
-    <div class="body">
-      <h4>"What changed" check</h4>
-      <pre><code class="lang-bash">cd /path/to/project
-git log --oneline -20 && git status
-dotnet build</code></pre>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">3</div>
-    <div class="body">
-      <h4>Re-verify</h4>
-      <p class="cmds"><span class="badge cmd">/verifier</span> → <em>"Re-verify the checklist's Requirements Status table and run standards-compliance greps from docs/&lt;APP&gt;-Coding-Standards.md. Note regressions."</em></p>
-    </div>
-  </div>
-  <div class="arrow">↓</div>
-  <div class="step">
-    <div class="num">4</div>
-    <div class="body">
-      <h4>Execute the "Next command" from <code>PROJECT-STATUS.md</code></h4>
-    </div>
-  </div>
-</div>
-<div class="panel warn">
-  <strong>Discipline:</strong> every phase (build, verify, handoff) ends with <code>/flow-master</code> updating PROJECT-STATUS. Never skip it. And when a run is cut off before it can — <code>*refresh-status &lt;APP&gt;</code> (§8a) is the safety net that rebuilds it from evidence.
-</div>
-<!-- ============================================================ -->
-<h2 id="libraries">9. Custom library agents — routing rules<span class="anchor-link"><a href="#libraries">#</a></span></h2>
-<p><code>/trblazeui</code> and <code>/techierag</code> are <strong>library agents</strong> — flow-master calls them as <strong>sub-agents</strong> during <code>*build-phase</code> and <code>*fix-issues</code> (and the analyst calls <code>/trblazeui</code> for its component catalog during <code>*mockups</code>). You drive the build/fix through flow-master; it routes each REQ cluster to the right builder by its prefix.</p>
-<table>
-  <tr><th>Trigger</th><th>Routed (by <code>*build-phase</code> / <code>*fix-issues</code>) to</th><th>Reads (besides &lt;APP&gt;-Coding-Standards.md)</th></tr>
-  <tr><td><code>REQ-UI-*</code> — UI work (pages, components, forms, dashboards)</td><td><code>/trblazeui</code> (sub-agent) — builds from the mockups</td><td><code>.trblazeui/TrBlazeUI-AI-Reference.md</code> + the Checklist + <code>docs/mockups/*.html</code></td></tr>
-  <tr><td><code>REQ-RAG-*</code> — AI/RAG/LLM (embedding, vector store, chat, tools)</td><td><code>/techierag</code> (sub-agent)</td><td><code>.techierag/TechieRag-AI-Reference.md</code> + the Checklist</td></tr>
-  <tr><td><code>REQ-FN-*</code> / <code>REQ-NFR-*</code> — backend / business logic / data / APIs / non-functional</td><td><code>/flow-master</code> own subagents</td><td>the Checklist + Architecture</td></tr>
-  <tr><td>Reverse-doc, BRD/Architecture/Standards, requirements splitting, mockups</td><td><code>/analyst</code></td><td>codebase / brief</td></tr>
-  <tr><td>Verification of any scope (data + visual gates)</td><td><code>/verifier</code></td><td>the Checklist + DevGuide + running app + standards grep checks</td></tr>
-  <tr><td>Unified build / fix-issues / HTML renders / status / handoff / consolidation</td><td><code>/flow-master</code></td><td>everything</td></tr>
-</table>
-<h3 id="add-library">9.1 Adding a new custom library agent</h3>
-<ol class="tight">
-  <li>Library's NuGet adds an MSBuild target that copies on consumer build: <code>.&lt;libname&gt;/&lt;LibName&gt;-AI-Reference.md</code>, <code>.claude/&lt;libname&gt;.md</code>, <code>.opencode/command/&lt;libname&gt;.md</code>.</li>
-  <li>Agent file's frontmatter: <code>description</code>, <code>mode: primary</code>, <code>tools</code>. Body: load reference doc on activation + REQUIRED READING clause for <code>docs/&lt;APP&gt;-Coding-Standards.md</code>.</li>
-  <li>Add routing row to the table above.</li>
-  <li>The new library gets its OWN feedback file — <code>&lt;APP&gt;-&lt;LibName&gt;-Feedback.md</code> with its own issue-ID prefix, from the shared template. Never share a feedback file between libraries.</li>
-  <li>Update <code>build-phase</code>'s cluster-routing (and <code>fix-issues</code>'s triage) to route the new ID prefix to the new sub-agent.</li>
-</ol>
-<h3 id="library-feedback">9.2 Library issue tracking flow</h3>
-<ol class="tight">
-  <li>Implementing agents log on encounter — into the OWNING library's file (<code>&lt;APP&gt;-TrBlazeUI-Feedback.md</code> for TR-NNN, <code>&lt;APP&gt;-TechieRag-Feedback.md</code> for TR-RAG-NNN). Clause baked into §7 prompts.</li>
-  <li>Verifier escalates library bugs → <code>Blocked</code> status in the checklist's Requirements Status table + entry in that library's feedback file.</li>
-  <li><code>/flow-master</code> consolidates each file separately at handoff: dedupe, severity sort, summary header (splits + archives any legacy combined <code>&lt;APP&gt;-Library-Feedback.md</code>).</li>
-  <li>You hand each file to its team — they use this same framework, so the file drops straight into their flow — or file as GitHub issues: <code>gh issue create --repo your-org/TrBlazeUI --title "…" --body-file …</code></li>
-</ol>
-<!-- ============================================================ -->
-<h2 id="standards-enforcement">10. Coding standards — how enforcement actually works<span class="anchor-link"><a href="#standards-enforcement">#</a></span></h2>
-<p>"Every agent follows the standards" is achieved through <strong>three layered mechanisms</strong>. None alone is sufficient; all three together close the gaps.</p>
-<div class="grid3">
-  <div class="panel">
-    <h4>1. Prompt-level (every session)</h4>
-    <p class="small">Every implementation prompt in §7 starts with "REQUIRED READING: docs/&lt;APP&gt;-Coding-Standards.md". The agent loads it before writing any code. Cross-harness reliable.</p>
-  </div>
-  <div class="panel">
-    <h4>2. <code>CLAUDE.md</code> auto-load</h4>
-    <p class="small">Claude Code auto-loads <code>CLAUDE.md</code> at project root into every session. It says "Always follow docs/&lt;APP&gt;-Coding-Standards.md before any code write." Catches even direct user prompts that forgot the boilerplate.</p>
-  </div>
-  <div class="panel">
-    <h4>3. <code>.editorconfig</code> + verifier greps</h4>
-    <p class="small">Machine-checkable rules go in <code>.editorconfig</code> (Roslyn enforces in the IDE / build). Non-checkable rules (a/v prefixes, test-name underscores) become grep patterns the verifier runs in the verify pass.</p>
-  </div>
-</div>
-<div class="panel">
-  <strong>Standing standard — Serilog file logging in EVERY .NET app (2026-07-09).</strong> Every executable head — Blazor web, API, MAUI, desktop, console/CLI, background service — wires <strong>Serilog with a rolling file sink</strong> (<code>logs/&lt;app&gt;-.log</code>, daily rolling; MAUI/desktop root it in the per-app data dir) at startup, logs unhandled exceptions, and exposes app logging only through <code>ILogger&lt;T&gt;</code> (class libraries reference logging abstractions, never Serilog). This is baked in end-to-end so you never have to ask: the BRD template carries a standing Observability NFR, day-1 always emits it (brownfield marks it <code>Done (pre-existing)</code> when an equivalent stack is already wired), <code>*split-brd</code> turns it into a <code>REQ-NFR-*</code> row, the coding-standards §Logging block carries the wiring recipe, and <code>*build-phase</code> wires Serilog into any new head it scaffolds even when no REQ names logging.</div>
-<div class="panel">
-  <strong>Standing standard — the primary head carries the PRODUCT name (2026-07-10).</strong> The product's primary executable head project is named exactly <code>&lt;APP&gt;</code> (<code>src/&lt;APP&gt;/&lt;APP&gt;.csproj</code>); a single-head product's one head IS <code>&lt;APP&gt;</code>. <strong><code>&lt;APP&gt;.App</code> is banned</strong> — "App" says nothing the product name doesn't. Secondary heads of a multi-head product take a <em>descriptive</em> dotted suffix (<code>&lt;APP&gt;.Api</code>, <code>&lt;APP&gt;.Desktop</code>, <code>&lt;APP&gt;.Cli</code>); satellites keep their conventional names (<code>&lt;APP&gt;.Core</code>, <code>&lt;APP&gt;UI</code> RCL, <code>&lt;APP&gt;.Core.Tests</code>). Baked into the coding-standards canonical block (day1-brownfield §4 → "Project &amp; solution naming") and <code>*build-phase</code> §3 (scaffold-time rule; an existing <code>&lt;APP&gt;.App</code> gets a rename REQ, never propagated).</div>
-<p>The grep patterns belong inside <code>docs/&lt;APP&gt;-Coding-Standards.md</code> under an "Enforcement" section. Sample grep block (already in §11.3 template):</p>
-<pre><code class="lang-bash"># Forbidden field forms
-grep -rE "private(\s+readonly)?\s+\w+\s+_[a-z]" src/    # underscore prefix
-# Instance field must start with `obj` (not bare PascalCase, not _underscore)
-grep -rE "private(\s+readonly)?\s+\w+\s+(?!obj)[A-Z]\w+\s*[;=]" src/ | grep -v "static\|const"
-# Forbidden test-method form
-grep -rE "public\s+(async\s+)?Task\s+\w+_\w+\s*\(" tests/
-# Parameter without a-prefix (heuristic; grep catches "(string Foo" but not all cases)
-grep -rE "\(\s*\w+\s+[A-Z]\w+\s*[,)]" src/</code></pre>
-<!-- ============================================================ -->
-<h2 id="wsl-runtime">11. MAUI builds &amp; runs — from WSL (bridged) or macOS (native)<span class="anchor-link"><a href="#wsl-runtime">#</a></span></h2>
-<p class="small"><strong>WSL (Windows) — bridge every dotnet call to the Windows side via <code>winrun</code> (§0):</strong></p>
-<pre><code class="lang-bash">cd /mnt/c/path/to/maui-project
-winrun "dotnet build -c Release"
-winrun "dotnet test"
-winrun "dotnet build -t:Run -f net9.0-windows10.0.19041.0"</code></pre>
-<p class="small"><strong>macOS — no bridge; dotnet runs natively (ladder §A):</strong></p>
-<pre><code class="lang-bash">cd /path/to/maui-project
-dotnet build -c Release
-dotnet test
-dotnet build -t:Run -f net9.0-maccatalyst      # desktop head on Mac = Mac Catalyst
-dotnet build -t:Run -f net9.0-android          # Android head (emulator via Android Studio)</code></pre>
-<p>On macOS the Windows head (<code>net9.0-windows…</code>) can't build — the Mac desktop head is <strong>Mac Catalyst</strong>, and iOS builds natively too (Xcode required, <a href="#platforms">§16</a>). The <code>winrun</code> lines apply only inside WSL.</p>
-<p>For verifier on a MAUI <strong>Windows</strong> app: <em>"This is a MAUI Windows app. Build/run/test via `winrun`. UI automation: FlaUI or Appium-Windows-driver Windows-side, NOT Playwright. Output evidence the same as Blazor projects."</em> On a Mac the equivalent prompt names the <strong>Catalyst</strong> head and the local <code>mac2</code> Appium driver instead.</p>
-<h3>Mobile &amp; Mac-desktop heads — runtime-observe over Appium</h3>
-<p>The §4a data-render and §4b visual-truth gates reach the MAUI <strong>Android / iOS / Mac Catalyst</strong> heads through an <strong>Appium</strong> WebDriver endpoint — the native analogue of Playwright (same screenshot + element-tree evidence, so the gates run unchanged). One-time host setup is <a href="#device-bootstrap">§0b</a>; the per-head driver map lives in <code>build-invocation-ladder.md §D</code>. <strong>Builds don't change</strong> — on WSL, Android still builds via <code>cmd.exe</code> (ladder rung #4) and iOS/Catalyst on the paired Mac; on a Mac-native setup all three build locally with plain <code>dotnet build</code> and the Appium endpoints are all <code>localhost</code>. This is purely how the verifier reaches the <em>running</em> UI after a green build.</p>
-<table>
-  <thead><tr><th>Head</th><th>Where it runs (WSL setup)</th><th>Appium driver</th><th>WSL reaches it via</th><th>macOS-native reaches it via</th></tr></thead>
-  <tbody>
-    <tr><td>MAUI Android</td><td>emulator on the Windows host (Android SDK)</td><td><code>uiautomator2</code></td><td><code>http://localhost:4723</code> (mirrored networking); verifier boots emulator + Appium itself</td><td><code>http://localhost:4723</code> — emulator + Appium run on the Mac itself</td></tr>
-    <tr><td>MAUI iOS</td><td>Simulator on a LAN Mac</td><td><code>xcuitest</code></td><td><code>http://&lt;mac-ip&gt;:4723</code>; Mac must be up or head is <code>⚠ STATIC-ONLY</code></td><td><code>http://localhost:4723</code> — local Simulator (Xcode)</td></tr>
-    <tr><td>MAUI Mac Catalyst</td><td>the same LAN Mac (desktop .app)</td><td><code>mac2</code></td><td><code>http://&lt;mac-ip&gt;:4723</code></td><td><code>http://localhost:4723</code> — the .app runs right here</td></tr>
-    <tr><td>MAUI Windows</td><td>Windows side</td><td>FlaUI / Appium-Windows (unchanged)</td><td><code>winrun</code> / <code>cmd.exe</code></td><td>n/a — this head doesn't exist on a Mac</td></tr>
-  </tbody>
-</table>
-<p>Selectors target each control's <code>AutomationId</code> (a coding standard, §10). A head with no registered endpoint in <code>core-config.yaml → runtimeVerification.appium</code>, or an unreachable host, is stamped <code>⚠ STATIC-ONLY</code> for that head — never a faked <code>Verified</code>.</p>
-<div class="panel warn">
-  <strong>Window binding &amp; input discipline (all native heads, especially MAUI Windows):</strong> the driver session is bound to the app under test <em>by identity</em> — the PID the agent launched → that process's top-level window handle (Appium Windows <code>appium:appTopLevelWindow</code> / FlaUI <code>Application.Attach(pid)</code>), or the app package/bundle id on mobile — and every interaction is <strong>element-scoped via <code>AutomationId</code> inside that bound window</strong>, with focus verified before input and handles re-resolved after dialogs. Global keyboard/mouse injection (FlaUI <code>Keyboard.Type</code>, coordinate clicks, <code>SendKeys</code>) is <strong>banned</strong>: it types into whatever window happens to hold focus — historically, a completely different window than the app. Full rules: <code>verify-phase.md §3b</code>.
-</div>
-<!-- ============================================================ -->
-<h2 id="permissions">12. Permissions (yolo-except-git-writes)<span class="anchor-link"><a href="#permissions">#</a></span></h2>
-<div class="panel warn">
-  <strong>TechieFlow's <code>*yolo</code> IS the permission switch now (2026-08-21):</strong> <code>*yolo</code> — or the word YOLO in any command, an active Claude Code <code>/goal</code>, or a <code>tf-goal.sh</code> run — writes the flag <code>.tfcore/.session/yolo.json</code>; the PreToolUse hook reads it and stops asking for deletes/<code>sudo</code>, allows read-only git, and the agent runs to completion with no pauses. Git <strong>writes</strong> stay denied in every mode. Rule: <code>.tfcore/tasks/_yolo-mode.md</code>; details in §12a below.
-</div>
-<p>The pre-built config <strong>auto-allows</strong> Read/Glob/Grep/Edit/Write/MultiEdit and <strong>all Bash</strong> (bare <code>"Bash"</code>) — so create/update/<strong>move</strong> run with zero prompts. <strong>Deletes and <code>sudo</code> ask via the hook</strong> (<em>not</em> a settings <code>ask</code> rule — Claude Code honours a settings <code>ask</code> even in bypass mode and even when a hook says allow, so it could never be switched off). <strong>Denies</strong> catastrophic <code>rm -rf</code> root/home paths <strong>and every <code>git</code>/<code>gh</code> WRITE subcommand</strong> (<code>commit|push|add|reset|checkout|switch|restore|merge|rebase|stash|clean|pull|fetch|…</code>, <code>gh pr|issue|repo|release create|merge|close|…</code>) — git is manual in TechieFlow; agents never write it, so it is a hard deny in every permission mode. Precedence is <code>deny → ask → hook → allow</code>. <em>(Cross-project tip: to let a session work in another app's folder without per-path prompts, add that root to <code>permissions.additionalDirectories</code> in this project's settings.json — keep those machine-specific paths out of any shared template.)</em></p>
-<div class="panel warn">
-  <strong>The git ban is TWO layers, because prefix rules alone leak.</strong> <code>Bash(git commit*)</code> is a literal prefix match — it never sees <code>cd src &amp;&amp; git commit</code> or <code>echo done; git add -A</code>, which the bare <code>"Bash"</code> allow would wave straight through. That is exactly how agents kept "accidentally" running git during status updates. So the config also wires a <strong>PreToolUse hook</strong> — <code>.tfcore/hooks/block-git.sh</code> — that parses every Bash call (compound forms, <code>bash -c</code>, <code>eval</code>, <code>$(…)</code>, wrappers like <code>sudo</code>/<code>env</code>/<code>xargs</code>) and classifies each <code>git</code>/<code>gh</code> node as <strong>read</strong> (<code>status</code>/<code>log</code>/<code>diff</code>/<code>show</code>/<code>blame</code>/<code>grep</code>/<code>branch</code>/<code>tag -l</code>/<code>stash list</code>/<code>remote -v</code>/<code>config --get</code>, <code>gh pr list|view</code>) or <strong>write</strong> (everything else). Writes are blocked always; reads are blocked outside YOLO and allowed in YOLO. The block message carries the local-evidence recipe (checklist tables + working-tree files + fresh build) so the agent continues correctly instead of flailing. You still run git yourself: in a separate terminal, or by typing <code>!git …</code> in the session (user-typed bang commands bypass agent tool permissions).
-</div>
-<div class="panel warn">
-  <strong>Why bare <code>"Bash"</code> and NOT a per-command list:</strong> a <code>Bash(prefix *)</code> rule is a literal prefix match. On WSL the agent can't call plain <code>dotnet</code> (not in PATH) — it calls <code>~/.dotnet/dotnet build</code>, <code>cmd.exe /c "dotnet build"</code>, <code>dotnet dev-certs</code>, or compound <code>cd … &amp;&amp; …</code>, none of which match an enumerated <code>Bash(dotnet *)</code>. The old list-everything config prompted ~100× in a single UI phase. Allowing all Bash and restricting only deletes/sudo (ask) and git/gh (deny + hook) is immune to command-path variants.
-</div>
-<details>
-  <summary>Config (canonical version in scaffold-brownfield.sh / scaffold-greenfield.sh)</summary>
-<pre><code class="lang-json">{
-  "permissions": {
-    "defaultMode": "acceptEdits",
-    "allow": [
-      "Bash",
-      "Edit", "Write", "MultiEdit", "NotebookEdit",
-      "Read", "Glob", "Grep", "TodoWrite", "WebFetch", "WebSearch", "Task"
-    ],
-    "ask": [],
-    "deny": [
-      "Bash(rm -rf /)", "Bash(rm -rf /*)", "Bash(rm -rf ~)", "Bash(rm -rf ~/*)",
-      "Bash(git commit*)", "Bash(git push*)", "Bash(git add*)", "Bash(git reset*)",
-      "Bash(git checkout*)", "Bash(git switch*)", "Bash(git restore*)", "Bash(git merge*)",
-      "… every other git WRITE subcommand (rebase, cherry-pick, revert, clean, pull, fetch, init, clone, …) …",
-      "Bash(gh pr create*)", "Bash(gh pr merge*)", "Bash(gh issue create*)", "… every gh WRITE verb …"
-    ]
-  },
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Bash",
-        "hooks": [ { "type": "command",
-                     "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/block-git.sh\"" } ] },
-      { "matcher": "Write|Edit|MultiEdit",
-        "hooks": [ { "type": "command",
-                     "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-status.sh\"" },
-                   { "type": "command",
-                     "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-verify.sh\"" } ] }
-    ]
-  }
-}</code></pre>
-</details>
-<div class="panel">
-  <strong>PROJECT-STATUS shape is enforced mechanically too (2026-07-09).</strong> A second PreToolUse hook — <code>.tfcore/hooks/guard-status.sh</code>, matcher <code>Write|Edit|MultiEdit</code> — blocks any write to <code>PROJECT-STATUS.md</code> that violates the crisp fixed-shape snapshot rule: an H2 outside the template's section set (per-run dated sections like <code>## *verify all — coverage matrix (DATE)</code> are the classic disease), a heading naming a command run, a paragraph stuffed into <code>current_phase:</code>, or a full-file write past ~120 lines. The block message tells the agent exactly how to reshape (overwrite the template sections in place, ONE Verification-log row per run, detail into the checklist Remarks). Same philosophy as the git ban: prose rules kept failing, so the harness enforces it. See <code>.tfcore/tasks/_status-update-gate.md</code>.
-</div>
-<div class="panel">
-  <strong><code>Verified</code> verdicts are enforced mechanically too (2026-07-10).</strong> A third PreToolUse hook — <code>.tfcore/hooks/guard-verify.sh</code>, matcher <code>Write|Edit|MultiEdit</code> — blocks any write to a <code>*-Checklist.md</code> that <em>introduces</em> a <code>Verified</code> status cell unless a same-day run ledger <code>docs/.last-verify.json</code> exists, which only an <em>executed</em> <code>verify-phase</code> run writes (verify-phase §6: boot → scoped tests → §4a data-render + §4b visual-truth gates → ledger → verdicts). This exists because a build orchestrator did its own smoke and wrote the <code>Verified</code> verdicts itself (TrSetup, 2026-07-09) — self-attestation the "chain the verifier" prose didn't stop. A self-smoke's ceiling is <code>Implemented</code> (<code>_smoke-test-policy.md §"Smoke is NOT verify"</code>); <code>*refresh-status</code> may reconcile a lagging Status column to a row's <em>pre-existing</em> dated verdict by writing the ledger with <code>"mode":"reconcile"</code>. Demotions (e.g. <code>Verified → Needs re-verify</code>) are never blocked.
-</div>
-<div class="panel">
-  <strong>Existing project still prompting?</strong> Just run the normal framework update — <code>update-framework.sh</code> now <strong>refreshes <code>settings.json</code> to this config by default</strong>, so every app stays in sync without any special flag:
-  <p class="small"><strong>WSL (Windows):</strong></p>
-  <pre><code class="lang-bash">/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/app</code></pre>
-  <p class="small"><strong>macOS:</strong></p>
-  <pre><code class="lang-bash">/Volumes/MacD/MyCode/TechieFlow/update-framework.sh /path/to/app</code></pre>
-  It's idempotent (skips the write when already current), backs up any differing old file to <code>settings.json.bak</code>, and never touches <code>settings.local.json</code>. Restart Claude Code afterward. To opt out for a deliberately locked-down project, add <code>--keep-permissions</code>.
-</div>
-<!-- ============================================================ -->
-<h3 id="yolo">12a. YOLO / goal mode — "I've given you all the permissions; run until it's done" (2026-08-21)<span class="anchor-link"><a href="#yolo">#</a></span></h3>
-<p><code>*yolo</code> used to be agent-side only (skip elicitation) and the owner still got prompted for every delete and blocked on every git read — which is how a VM goal run took <strong>3 days</strong>, mostly waiting for a human. Now <code>*yolo</code>, the word <strong>YOLO</strong> anywhere in a command, an active Claude Code <strong><code>/goal</code></strong>, or a <code>tf-goal.sh</code> run all mean the same thing, defined in <code>.tfcore/tasks/_yolo-mode.md</code>:</p>
-<table>
-  <thead><tr><th></th><th>Normal</th><th>YOLO</th></tr></thead>
-  <tbody>
-    <tr><td><code>rm</code> / <code>rmdir</code> / <code>sudo</code></td><td>hook asks</td><td><strong>allowed, no prompt</strong> (catastrophic <code>rm -rf /</code>/<code>~</code> still denied)</td></tr>
-    <tr><td>git/gh <strong>reads</strong> (<code>status</code>/<code>log</code>/<code>diff</code>/<code>blame</code>, <code>gh pr view</code>)</td><td>blocked</td><td><strong>allowed</strong></td></tr>
-    <tr><td>git/gh <strong>writes</strong> (<code>commit</code>/<code>push</code>/<code>add</code>/<code>reset</code>/<code>checkout</code>/<code>stash</code>/<code>tag</code>, <code>gh pr create|merge</code>)</td><td>blocked</td><td><strong>blocked — always</strong></td></tr>
-    <tr><td>Elicitation, phase-boundary pauses, "confirm the BRD-N list", "ask once" questions</td><td>pause</td><td><strong>decide the default, record it, continue</strong></td></tr>
-    <tr><td>Build pass scope</td><td>whole checklist (§2b)</td><td>whole checklist <strong>+ automatic FIX loop</strong> on verifier FAIL rows (build-phase §6c, ≤5 cycles)</td></tr>
-    <tr><td>Turn ending</td><td>may hand back</td><td><strong>only</strong> when the goal is complete (<code>tf-yolo.sh done complete</code>) or every remaining REQ is owner-gated (<code>done blocked</code>)</td></tr>
-  </tbody>
-</table>
-<div class="panel">
-  <strong>Mechanics.</strong> The flag is <code>.tfcore/.session/yolo.json</code> (<code>bash .tfcore/utils/tf-yolo.sh on|off|status</code>; never committed). <code>block-git.sh</code> reads it (plus <code>TF_YOLO=1</code> and the hook payload's <code>permission_mode</code> — Claude Code's <code>bypassPermissions</code>/<code>auto</code> count as YOLO); the OpenCode plugin reads the same flag and auto-approves its <code>rm */sudo *</code> asks via <code>permission.ask</code>. <strong>Why the delete prompt moved out of <code>settings.json</code>:</strong> Claude Code honours a settings <code>ask</code> rule <em>even in bypass mode and even when a hook says allow</em> — so as long as <code>Bash(rm *)</code> sat in <code>ask</code>, no mode could stop the prompt. A hook-issued <code>ask</code> can be withheld; a settings <code>ask</code> cannot.
-</div>
-<div class="panel warn">
-  <div class="panel warn"><strong>Codex permission difference.</strong> <code>.codex/hooks.json</code> routes shell and file changes through <code>.tfcore/hooks/codex-adapter.py</code>, and <code>.codex/rules/techieflow.rules</code> supplies command policy. Codex blocks every agent-issued <code>git</code> and <code>gh</code> command in normal and YOLO modes, including reads. <code>$techieflow-yolo</code> changes TechieFlow pause/delete behavior but never relaxes this boundary. Trust the repository and inspect <code>/hooks</code> after scaffold/update.</div>
-  <strong>Usage limits (5-hour / weekly).</strong> Nothing inside a session can wait a limit out, so the wait lives in a supervisor:
-  <pre><code class="lang-bash">bash .tfcore/utils/tf-goal.sh /path/to/App "Take MyApp to Handoff: build every open REQ, verify all, fix until every row is Verified."
-bash .tfcore/utils/tf-goal.sh --harness opencode --model opencode-go/kimi-k3 /path/to/App @goal.md
-bash .tfcore/utils/tf-goal.sh --resume /path/to/App      # after a reboot</code></pre>
-  It runs the goal headless (<code>claude -p --permission-mode bypassPermissions</code> / <code>opencode run --auto</code>), parses the reset time from the limit message (<code>resets 7pm (Asia/Kolkata)</code>, <code>resets in 2h 14m</code>, <code>usage limit reached|&lt;epoch&gt;</code>, weekly <code>resets Tue 3pm</code>), <strong>sleeps until reset + 15 min</strong> (<code>--buffer-min</code>), logs <code>RETRY AT …</code> to <code>.tfcore/.session/goal.log</code>, and <strong>resumes the same session</strong>. Crashes back off 2 → 30 min; an agent that stops without finishing is re-prompted; it exits only on the agent's sentinel (<code>0</code> complete, <code>3</code> owner-blocked, <code>4</code> max cycles). The agent's side of the bargain is the status gate — every phase ends with PROJECT-STATUS + checklist written, so a resume is lossless.
-</div>
-<div class="panel">
-  <strong>Build passes are whole-checklist, YOLO or not.</strong> The other 3-day culprit: build-phase runs that implemented a few REQs, wrote "next command: <code>*build-phase</code> for the remaining REQs" and stopped. <code>build-phase.md §2b</code> bans that ending — a pass is done when <strong>every</strong> working-list REQ is ≥ <code>Implemented</code> (or a logged <code>Blocked</code>/owner-gated blocker), the verifier has been chained, and (in YOLO) its FAIL rows have been looped. Long list ⇒ more sub-agent clusters, never a shorter pass. <code>_status-update-gate.md</code> item 5 carries the matching rule for the next-command line.
-</div>
-<h2 id="agents">13. Agent cheat sheet<span class="anchor-link"><a href="#agents">#</a></span></h2>
-<div class="panel">
-  <strong>These six are the COMPLETE agent roster.</strong> The stock TechieFlow story-flow agents (<code>dev</code>, <code>pm</code>, <code>po</code>, <code>qa</code>, <code>sm</code>, <code>ux-expert</code>) and their story tasks/templates/workflows were trimmed from the scaffold on 2026-06-12 — the compressed flow never used them, and several behaved wrongly in it (wrong stack assumptions, dated <code>docs/qa</code> outputs). They are no longer included; obtain a full story-by-story agent set separately if you ever need that classic flow.
-  <br><br>
-  <strong>Which agent when:</strong>
-  <ul class="tight">
-    <li>Starting or re-documenting a project → <code>/analyst</code> (day-1 tasks, mockups, split-brd).</li>
-    <li>Writing code → <code>/flow-master *build-phase</code> (the ONE unified build — it calls <code>/trblazeui</code> and <code>/techierag</code> as sub-agents; you don't invoke them directly).</li>
-    <li>Proving it works → <code>/verifier</code> (<code>*verify ui|functional|all</code> — filters the one checklist; data + visual gates).</li>
-    <li>Verifier passed but the running UI is broken → <code>/flow-master *fix-issues</code> (drop screenshots; it triages + routes the fix).</li>
-    <li>UAT / production bugs you want analyzed + logged in the checklist, NOT fixed yet → <code>/flow-master *triage-issues</code> (docs-only deliverable; fixing stays your call).</li>
-    <li>Developer code-map (screen → control → service → proc) → <code>/flow-master *devguide</code>.</li>
-    <li>End-user how-to manual (what each screen is for + how to do things) → <code>/flow-master *productguide</code>.</li>
-    <li>Docs/HTML/status/handoff chores → <code>/flow-master</code>.</li>
-    <li>Architecture deep-dive beyond what day-1 produced → <code>/architect</code> (optional).</li>
-  </ul>
-</div>
-<table>
-  <tr><th>Command</th><th>Role</th><th>Best for</th><th>Writes</th></tr>
-  <tr><td><code>/analyst</code></td><td>Chanakya, business analyst</td><td>Reverse-doc; BRD; Architecture; Coding Standards; <strong>mockups</strong> (<code>*mockups</code>, greenfield); the one Checklist (<code>*split-brd</code>); status init; .editorconfig; CLAUDE.md</td><td><code>&lt;APP&gt;-BRD.md</code>, <code>&lt;APP&gt;-Architecture.md</code>, <code>&lt;APP&gt;-Coding-Standards.md</code>, <code>&lt;APP&gt;-UIDesign.md</code> + <code>docs/mockups/*.html</code>, <code>&lt;APP&gt;-Checklist.md</code>, <code>PROJECT-STATUS.md</code>, <code>CLAUDE.md</code>, <code>.editorconfig</code></td></tr>
-  <tr><td><code>/trblazeui</code></td><td>Blazor + TrBlazeUI <strong>(library agent — called as a sub-agent by <code>*build-phase</code> / <code>*fix-issues</code>)</strong></td><td>REQ-UI-* per the mockups; reads coding standards</td><td><code>src/</code> (Razor), <code>&lt;APP&gt;-TrBlazeUI-Feedback.md</code></td></tr>
-  <tr><td><code>/techierag</code></td><td>TechieRag RAG/LLM <strong>(library agent — called as a sub-agent by <code>*build-phase</code> / <code>*fix-issues</code>)</strong></td><td>REQ-RAG-* items; reads coding standards</td><td><code>src/</code> (RAG services), <code>&lt;APP&gt;-TechieRag-Feedback.md</code></td></tr>
-  <tr><td><code>/flow-master</code></td><td>Madhav, master &amp; orchestrator</td><td>The single super-agent. Runs the <strong>unified <code>*build-phase</code></strong> (clusters all open REQs, calls <code>/trblazeui</code> + <code>/techierag</code> as sub-agents, builds REQ-FN-*/REQ-NFR-* itself, self-smokes data+visual, chains the verifier); the <strong><code>*fix-issues</code></strong> bug-fix front door (triages screenshots → routes the fix) and its analyze-only sibling <strong><code>*triage-issues</code></strong> (logs UAT/prod bugs in the checklist, never fixes); HTML renders, status refresh, consolidation, handoff doc; the screen-by-screen Developer Guide (<code>*devguide</code>) and the end-user Product Guide (<code>*productguide</code>)</td><td><code>src/</code>, <code>tests/unit/</code>, <code>&lt;APP&gt;-BRD.html</code>, <code>&lt;APP&gt;-Architecture.html</code>, <code>PROJECT-STATUS.md/html</code>, <code>&lt;APP&gt;-UsageGuide.md</code>, <code>&lt;APP&gt;-DevGuide.md/html</code>, <code>&lt;APP&gt;-ProductGuide.md/html</code>, <code>&lt;APP&gt;-Checklist.md</code> (verdicts), <code>&lt;APP&gt;-&lt;Library&gt;-Feedback.md</code> (per-library consolidation)</td></tr>
-  <tr><td><code>/verifier</code></td><td>Vidur, autonomous test runner</td><td>Verifying any scope + standards grep checks + the <strong>render gate (§4a)</strong> (every control listed in the DevGuide renders its data) AND the <strong>visual-truth gate (§4b)</strong> (no overlap, every control in-viewport and non-zero-size at desktop + mobile, screenshot inspected, diffed against the mockup when one exists) AND the <strong>perf gate (§4c)</strong> on any REQ declaring a <code>perf-budget:</code>. A REQ is <code>Verified</code> only if acceptance passes AND data renders AND the screen looks right. <code>Done (pre-existing)</code> gets the full sweep — stays Done only if it runtime-renders + looks right, else <code>Needs re-verify</code>. After each run Vidur writes verdicts to the one checklist AND refreshes the DevGuide's observed render/visual tags.</td><td><code>&lt;APP&gt;-Checklist.md</code> Requirements Status table (verdicts), DevGuide observed render/visual tags, <code>tests/playwright/*</code>, <code>&lt;APP&gt;-&lt;Library&gt;-Feedback.md</code> (on library bugs — the owning library's file)</td></tr>
-  <tr><td><code>/architect</code></td><td>Solutions architect</td><td>Optional deep arch dive; <code>/analyst</code> does basic architecture by default</td><td><code>&lt;APP&gt;-Architecture.md</code> (delegated by analyst, optional)</td></tr>
-</table>
-<!-- ============================================================ -->
-<h2 id="quickref">14. Full command reference<span class="anchor-link"><a href="#quickref">#</a></span></h2>
-<div class="panel warn">
-  <strong>Slash-command syntax — Claude Code vs OpenCode:</strong>
-  Claude Code registers TechieFlow-native agents under the path-derived namespace <code>TechieFlow:agents:&lt;name&gt;</code>. OpenCode registers the equivalent agents as <code>/flow-master</code>, <code>/flow-analyst</code>, <code>/flow-architect</code>, and <code>/flow-verifier</code>. Each command cell below is an exact, copyable command. Use the macOS framework path where applicable.
-</div>
-<table>
-  <tr><th>Goal</th><th>Command Purpose / Definition</th><th>Claude Command</th><th>OpenCode Command</th></tr>
-  <tr><td>Scaffold (brownfield)</td><td>Deploy the framework into an existing application.</td><td><pre><code>./scaffold-brownfield.sh /path/to/existing-app</code></pre></td><td><pre><code>./scaffold-brownfield.sh /path/to/existing-app</code></pre></td></tr>
-  <tr><td>Scaffold (greenfield)</td><td>Deploy the framework and starter folders into a new application.</td><td><pre><code>./scaffold-greenfield.sh /path/to/new-app</code></pre></td><td><pre><code>./scaffold-greenfield.sh /path/to/new-app</code></pre></td></tr>
-  <tr><td>Update framework</td><td>Force-refresh framework files in an existing project; preserves work product.</td><td><pre><code>/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/app</code></pre></td><td><pre><code>/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/app</code></pre></td></tr>
-  <tr><td>Render MD → HTML</td><td>Re-render one or more human-facing Markdown documents as HTML.</td><td><pre><code>/generate-html @docs/File.md</code></pre></td><td><pre><code>/generate-html @docs/File.md</code></pre></td></tr>
-  <tr><td>Day-1 brownfield</td><td>Reverse-document an existing app and create the day-1 deliverables, UsageGuide, and DevGuide.</td><td><pre><code>/TechieFlow:agents:analyst *day1-brownfield {AppName}</code></pre></td><td><pre><code>/flow-analyst *day1-brownfield {AppName}</code></pre></td></tr>
-  <tr><td>Day-1 greenfield</td><td>Create the BRD, Architecture, Coding Standards, status, CLAUDE.md, and UI mockups for a new app.</td><td><pre><code>/TechieFlow:agents:analyst *day1-greenfield {AppName}</code></pre></td><td><pre><code>/flow-analyst *day1-greenfield {AppName}</code></pre></td></tr>
-  <tr><td>Re-render workflow docs</td><td>Refresh the BRD, Architecture, and PROJECT-STATUS HTML documents.</td><td><pre><code>/TechieFlow:agents:flow-master *render-workflow-docs {AppName}</code></pre></td><td><pre><code>/flow-master *render-workflow-docs {AppName}</code></pre></td></tr>
-  <tr><td>Greenfield UI mockups</td><td>Create or update the per-screen UI design specification and TrBlazeUI-styled mockups.</td><td><pre><code>/TechieFlow:agents:analyst *mockups {AppName}</code></pre></td><td><pre><code>/flow-analyst *mockups {AppName}</code></pre></td></tr>
-  <tr><td>Split BRD → Checklist</td><td>Turn BRD items into the single Checklist with REQ-UI/FN/RAG/NFR requirements.</td><td><pre><code>/TechieFlow:agents:analyst *split-brd {AppName}</code></pre></td><td><pre><code>/flow-analyst *split-brd {AppName}</code></pre></td></tr>
-  <tr><td>Amend docs</td><td>Apply an incremental requirements or architecture change without regenerating unchanged documents.</td><td><pre><code>/TechieFlow:agents:analyst *amend-docs {AppName} "&lt;what changed&gt;"</code></pre></td><td><pre><code>/flow-analyst *amend-docs {AppName} "&lt;what changed&gt;"</code></pre></td></tr>
-  <tr><td>Build — unified phase</td><td>Build all open REQs, route UI/RAG work to library agents, self-smoke, and chain verification.</td><td><pre><code>/TechieFlow:agents:flow-master *build-phase {AppName}</code></pre></td><td><pre><code>/flow-master *build-phase {AppName}</code></pre></td></tr>
-  <tr><td>Fix issues</td><td>Reproduce screenshot-reported issues, route fixes, then re-smoke and re-verify.</td><td><pre><code>/TechieFlow:agents:flow-master *fix-issues {AppName} {folder}</code></pre></td><td><pre><code>/flow-master *fix-issues {AppName} {folder}</code></pre></td></tr>
-  <tr><td>Triage UAT/production bugs</td><td>Analyze and log bugs without editing code; optionally regression-verify sibling features.</td><td><pre><code>/TechieFlow:agents:flow-master *triage-issues {AppName} {evidence} [verify]</code></pre></td><td><pre><code>/flow-master *triage-issues {AppName} {evidence} [verify]</code></pre></td></tr>
-  <tr><td>Verify gates and standards</td><td>Run acceptance tests, standards greps, data-render, visual-truth, and applicable performance gates.</td><td><pre><code>/TechieFlow:agents:verifier *verify &lt;scope&gt;</code></pre></td><td><pre><code>/flow-verifier *verify &lt;scope&gt;</code></pre></td></tr>
-  <tr><td>End of session</td><td>Update project status and regenerate its HTML representation.</td><td><pre><code>/TechieFlow:agents:flow-master Update PROJECT-STATUS.md (phase, next, log); regenerate PROJECT-STATUS.html.</code></pre></td><td><pre><code>/flow-master Update PROJECT-STATUS.md (phase, next, log); regenerate PROJECT-STATUS.html.</code></pre></td></tr>
-  <tr><td>Final handoff</td><td>Generate the final UsageGuide, DevGuide, status, and library-feedback consolidation.</td><td><pre><code>/TechieFlow:agents:flow-master *handoff-phase {AppName}</code></pre></td><td><pre><code>/flow-master *handoff-phase {AppName}</code></pre></td></tr>
-  <tr><td>Generate / refresh Developer Guide</td><td>Map the implemented screens, observe the running app, and reconcile the Developer Guide.</td><td><pre><code>/TechieFlow:agents:flow-master *devguide {AppName}</code></pre></td><td><pre><code>/flow-master *devguide {AppName}</code></pre></td></tr>
-  <tr><td>Generate / refresh Product Guide</td><td>Generate the screenshot-illustrated, task-oriented manual for external users.</td><td><pre><code>/TechieFlow:agents:flow-master *productguide {AppName} [scope] [--update]</code></pre></td><td><pre><code>/flow-master *productguide {AppName} [scope] [--update]</code></pre></td></tr>
-  <tr><td>Token efficiency guide</td><td>Open the framework guidance for reducing unnecessary AI context and token usage.</td><td><pre><code>less .tfcore/TOKEN-GUIDE.md</code></pre></td><td><pre><code>less .tfcore/TOKEN-GUIDE.md</code></pre></td></tr>
-  <tr><td>Recover broken session</td><td>Rebuild PROJECT-STATUS from ground truth after an interrupted phase.</td><td><pre><code>/TechieFlow:agents:flow-master *refresh-status {AppName}</code></pre></td><td><pre><code>/flow-master *refresh-status {AppName}</code></pre></td></tr>
-  <tr><td>MAUI build + test</td><td>Build and test the MAUI project through the Windows bridge or natively on macOS.</td><td><pre><code>winrun "dotnet build &amp;&amp; dotnet test"</code></pre></td><td><pre><code>winrun "dotnet build &amp;&amp; dotnet test"</code></pre></td></tr>
-  <tr><td>Resume project</td><td>Check the working tree and perform a fresh build before continuing.</td><td><pre><code>git status &amp;&amp; dotnet build</code></pre></td><td><pre><code>git status &amp;&amp; dotnet build</code></pre></td></tr>
-  <tr><td>Log a miss (<a href="#misses">§17</a>)</td><td>Record one missed requirement as telemetry + a checklist line. No boot, no repro, no code.</td><td><pre><code>/TechieFlow:agents:flow-master *log-miss {AppName} "{what was missed}"</code></pre></td><td><pre><code>/flow-master *log-miss {AppName} "{what was missed}"</code></pre></td></tr>
-  <tr><td>Development telemetry report</td><td>Generate the aggregated development metrics report.</td><td><pre><code>/TechieFlow:agents:flow-master *metrics {AppName}</code></pre></td><td><pre><code>/flow-master *metrics {AppName}</code></pre></td></tr>
-  <tr><td>Telemetry quick look</td><td>Print the read-only telemetry report directly in the terminal.</td><td><pre><code>.tfcore/telemetry/tf-metrics.sh --report .</code></pre></td><td><pre><code>.tfcore/telemetry/tf-metrics.sh --report .</code></pre></td></tr>
-</table>
-<table class="quickref-legacy">
-  <tr><th>Goal</th><th>Command (Claude Code form)</th></tr>
-  <tr><td>Scaffold (brownfield)</td><td><code>./scaffold-brownfield.sh /path/to/existing-app</code> (or run from the template repo)</td></tr>
-  <tr><td>Scaffold (greenfield)</td><td><code>./scaffold-greenfield.sh /path/to/new-app</code> (or run from the template repo)</td></tr>
-  <tr><td>Update framework in existing project (<a href="#update-framework">§3</a>)</td><td>WSL: <code>/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/app</code> · macOS: <code>/Volumes/MacD/MyCode/TechieFlow/update-framework.sh /path/to/app</code> (add <code>--dry-run</code> to preview; restart Claude Code after)</td></tr>
-  <tr><td>Render any MD → HTML (ad-hoc)</td><td><code>/generate-html @docs/File.md</code> (multiple <code>@paths</code> ok; <code>@dir/</code> = top-level *.md, non-recursive; day-1 auto-renders its own docs — this is for re-renders after edits)</td></tr>
-  <tr><td>Day-1 brownfield (6 deliverables + UsageGuide + DevGuide)</td><td><code>/TechieFlow:agents:analyst *day1-brownfield {AppName}</code></td></tr>
-  <tr><td>Day-1 greenfield (6 deliverables)</td><td><code>/TechieFlow:agents:analyst *day1-greenfield {AppName}</code></td></tr>
-  <tr><td>Re-render BRD/Architecture/Status trio (day-1 renders these automatically)</td><td><code>/TechieFlow:agents:flow-master *render-workflow-docs {AppName}</code></td></tr>
-  <tr><td>Greenfield UI mockups (<a href="#mockups">§7.10</a>)</td><td><code>/TechieFlow:agents:analyst *mockups {AppName}</code> — per-screen UIDesign spec + TrBlazeUI-styled <code>docs/mockups/*.html</code>; auto-run at greenfield day-1; <code>--update</code> refreshes changed screens. The visual contract the build matches and the verifier diffs against.</td></tr>
-  <tr><td>Split BRD → the one Checklist</td><td><code>/TechieFlow:agents:analyst *split-brd {AppName}</code> — writes <code>docs/{AppName}-Checklist.md</code> (all REQ-UI/FN/RAG/NFR-* in one Requirements Status table).</td></tr>
-  <tr><td><strong>Amend docs as the project evolves</strong> (<a href="#evolving-docs">§7.9</a>)</td><td><code>/TechieFlow:agents:analyst *amend-docs {AppName} "&lt;what changed&gt;"</code> (or <code>/flow-master</code>) — surgically updates BRD + Architecture in place (append-only IDs), ripples to PROJECT-STATUS / BRD §4 / the checklist, re-renders. Incremental alternative to re-running day-1.</td></tr>
-  <tr><td><strong>Build — ONE unified phase</strong> (chains self-smoke + verifier)</td><td><code>/TechieFlow:agents:flow-master *build-phase {AppName}</code> (OpenCode: <code>/flow-master *build-phase {AppName}</code>) — clusters all open REQs, calls <code>/trblazeui</code> (REQ-UI-*, from the mockups) and <code>/techierag</code> (REQ-RAG-*) as sub-agents, builds REQ-FN-*/REQ-NFR-* itself, self-smokes (data + visual), then chains the verifier. Re-run for FIX mode on flagged REQs. (The old separate UI / RAG / functional build commands are dissolved into this one.)</td></tr>
-  <tr><td><strong>Fix issues found by running the app</strong> (<a href="#fix-issues">§7.11</a>)</td><td><code>/TechieFlow:agents:flow-master *fix-issues {AppName} {folder}</code> — drop a folder of screenshots (+ optional <code>bugs.md</code>); flow-master reproduces each with Playwright, triages (layout/data/logic/RAG), fans the fix to the right builder (trblazeui / its subagents / techierag), re-smokes + re-verifies, updates DevGuide + checklist + PROJECT-STATUS. The answer to "verifier passed but the UI is broken."</td></tr>
-  <tr><td><strong>Analyze + log UAT/production bugs WITHOUT fixing</strong> (<a href="#triage-issues">§7.12</a>)</td><td><code>/TechieFlow:agents:flow-master *triage-issues {AppName} {evidence} [verify]</code> — screenshots folder and/or a written bug list; flow-master reproduces each with Playwright, demotes regressed REQs to <code>Needs re-verify</code> (dated <code>⚠ UAT bug</code> remarks), adds new <code>Planned</code> rows for unspecified defects, optionally re-verifies sibling features (<code>verify</code>), updates DevGuide known-issues + PROJECT-STATUS (next command = the <code>*fix-issues</code> pointer). Never edits code — fixing stays your decision.</td></tr>
-  <tr><td>Verify + standards greps + data, visual &amp; perf gates</td><td><code>/TechieFlow:agents:verifier *verify &lt;scope&gt;</code> — scope is <code>ui</code> | <code>functional</code> | <code>all</code> | explicit REQ IDs; <strong>filters the one checklist by REQ prefix</strong> (no separate file). Runs standards-compliance greps, acceptance tests, the <strong>render gate</strong> (verify-phase §4a: every control renders its data) AND the <strong>visual-truth gate</strong> (§4b: no overlap, every control in-viewport and non-zero-size at desktop + mobile, screenshot inspected, mockup-diffed where one exists) and, for any REQ declaring a <code>perf-budget:</code>, the <strong>perf gate</strong> (§4c). A REQ is <code>Verified</code> only if acceptance passes AND data renders AND the screen looks right. <code>Done (pre-existing)</code> gets the full sweep. Verdicts land in the checklist; Vidur also refreshes the DevGuide's observed render/visual tags.</td></tr>
-  <tr><td>End-of-session</td><td><code>/TechieFlow:agents:flow-master Update PROJECT-STATUS.md (phase, next, log); regenerate PROJECT-STATUS.html.</code></td></tr>
-  <tr><td>Final handoff (incl. DevGuide)</td><td><code>/TechieFlow:agents:flow-master *handoff-phase {AppName}</code></td></tr>
-  <tr><td>Generate / refresh Developer Guide</td><td><code>/TechieFlow:agents:flow-master *devguide {AppName}</code> — generates <code>docs/{AppName}-DevGuide.md</code> + <code>.html</code> (split per role for large apps) via the 3-pass MAP → OBSERVE → RECONCILE model (§6). Add <code>--update</code> to refresh only changed screens. Stamped <code>⚠ STATIC-ONLY</code> if the app cannot be booted. Auto-run at handoff; re-runnable anytime. The DevGuide is the verifier's per-control test map — see §6.</td></tr>
-  <tr><td>Generate / refresh end-user Product Guide (<a href="#docs">§6</a>)</td><td><code>/TechieFlow:agents:flow-master *productguide {AppName} [scope] [--update]</code> — the screenshot-illustrated, task-oriented how-to manual for EXTERNAL users (what each screen is for + how to do things). Reuses the DevGuide's screen inventory + the screenshots under <code>docs/screenshots/&lt;APP&gt;/</code> (re-shoots any missing via the verifier render sweep); fans out per role, splitting large apps into <code>docs/productguides/</code>. <strong>Always emits MD + HTML.</strong> On-demand; <code>--update</code> refreshes only changed screens. The user-facing sibling of the DevGuide.</td></tr>
-  <tr><td>Token efficiency guide</td><td><code>.tfcore/TOKEN-GUIDE.md</code> — ships with every project. Explains where AI tokens go and the levers to keep usage low (don't load whole docs/repos; checklists markdown-only; fan out to subagents; incremental updates via <code>*amend-docs</code> / <code>*devguide --update</code>; recover with <code>*refresh-status</code> instead of re-running).</td></tr>
-  <tr><td><strong>Recover broken session</strong> (status stale/wrong)</td><td><code>/TechieFlow:agents:flow-master *refresh-status {AppName}</code> — rebuilds PROJECT-STATUS from ground truth (checklist tables + working-tree files &amp; mtimes + fresh build; no git — git is manual) when a phase died before its status gate ran. Add <code>verify</code> to re-verify ambiguous REQs. Never edits source. See §8a.</td></tr>
-  <tr><td>MAUI build+test</td><td>WSL: <code>winrun "dotnet build &amp;&amp; dotnet test"</code> · macOS: <code>dotnet build &amp;&amp; dotnet test</code> (native, no bridge — <a href="#wsl-runtime">§11</a>)</td></tr>
-  <tr><td>Resume cold project (status trustworthy)</td><td>Open <code>PROJECT-STATUS.html</code> + <code>&lt;APP&gt;-BRD.html</code> + <code>&lt;APP&gt;-Architecture.html</code> → <code>git status &amp;&amp; dotnet build</code> → <code>/TechieFlow:agents:verifier</code> re-verify → execute "Next command". If the last session was cut off mid-phase, run <code>*refresh-status</code> first (row above).</td></tr>
-  <tr><td>An agent missed something (<a href="#misses">§17</a>)</td><td><code>/TechieFlow:agents:flow-master *log-miss {AppName} "{what was missed}"</code> &mdash; a record + the checklist line, in seconds</td></tr>
-  <tr><td>Development telemetry report (<a href="#telemetry">§17</a>)</td><td><code>/TechieFlow:agents:flow-master *metrics {AppName}</code> &mdash; writes <code>docs/metrics/METRICS.md</code> + <code>.html</code></td></tr>
-  <tr><td>Telemetry, quick look in the terminal (<a href="#telemetry">§17</a>)</td><td><code>cd /path/to/app &amp;&amp; .tfcore/telemetry/tf-metrics.sh --report .</code> &mdash; read-only, no agent</td></tr>
-</table>
-<h3>Codex command equivalents</h3>
-<p>Codex exposes workflows as project skills rather than literal Claude/OpenCode slash commands. Type the <code>$techieflow-*</code> name with its arguments; scaffold/update generates these skills from <code>.tfcore/tasks/</code>.</p>
-<table>
-<tr><th>Workflow</th><th>Codex command</th></tr>
-<tr><td>Day 1</td><td><code>$techieflow-day1-brownfield {AppName}</code> / <code>$techieflow-day1-greenfield {AppName}</code></td></tr>
-<tr><td>Requirements</td><td><code>$techieflow-author-brd {AppName}</code> / <code>$techieflow-amend-docs {AppName} "&lt;change&gt;"</code></td></tr>
-<tr><td>Design / checklist</td><td><code>$techieflow-mockups {AppName}</code> / <code>$techieflow-split-brd {AppName}</code></td></tr>
-<tr><td>Build / verify</td><td><code>$techieflow-build {AppName}</code> / <code>$techieflow-verify all {AppName}</code></td></tr>
-<tr><td>Fix / triage</td><td><code>$techieflow-fix-issues {AppName} {evidence}</code> / <code>$techieflow-triage-issues {AppName} {evidence}</code></td></tr>
-<tr><td>Guides</td><td><code>$techieflow-devguide {AppName}</code> / <code>$techieflow-productguide {AppName}</code></td></tr>
-<tr><td>Handoff / recovery</td><td><code>$techieflow-handoff {AppName}</code> / <code>$techieflow-refresh-status {AppName}</code></td></tr>
-<tr><td>Rendering</td><td><code>$techieflow-render-workflow-docs {AppName}</code> / <code>$techieflow-generate-html @docs/File.md</code></td></tr>
-<tr><td>Metrics / YOLO</td><td><code>$techieflow-metrics-report {AppName}</code> / <code>$techieflow-yolo on|off|status</code></td></tr>
-<tr><td>Unattended goal</td><td><code>bash .tfcore/utils/tf-goal.sh --harness codex &lt;app-dir&gt; "&lt;goal&gt;"</code></td></tr>
-</table>
-<div class="panel warn"><strong>Codex boundary:</strong> trust the repository and review <code>/hooks</code>. Every agent-issued <code>git</code> and <code>gh</code> command stays forbidden even in YOLO. The supervisor uses <code>codex exec --json --sandbox workspace-write -c approval_policy="never"</code> and resumes its recorded session after limits or restarts.</div>
-<p><small>The trblazeui and techierag personas are NuGet-deployed to <code>.claude/&lt;name&gt;.md</code> and <code>.opencode/command/&lt;name&gt;.md</code>. Claude Code only scans <code>.claude/commands/</code>, so the scaffold/update scripts copy them to <code>.claude/commands/&lt;name&gt;.md</code> (the short <code>/trblazeui</code> <code>/techierag</code> forms then work). If the short form is missing: <code>dotnet build</code>, then re-run <code>update-framework.sh</code>. Library maintainers must update the package source files listed in <code>docs/TechieFlow-Library-Persona-Propagation.md</code>; consumer copies are not the source of truth.</small></p>
-<!-- ============================================================ -->
-<h2 id="faq">15. FAQ &amp; gotchas<span class="anchor-link"><a href="#faq">#</a></span></h2>
-<details>
-  <summary>Rendering docs to HTML burns enormous tokens every phase. Is the model really writing all that by hand?</summary>
-  <p><strong>It was, until 2026-08-27. It no longer should be.</strong> There was no renderer in the framework: <code>html-render-shell.md</code> was a 494-line prose specification, and both render tasks told the agent to implement it by hand (<em>&ldquo;Use the Write tool &mdash; never bash heredocs&rdquo;</em>). One phase that re-rendered four documents emitted ~300 KB of HTML, roughly <strong>75&ndash;80k output tokens</strong>, for documents whose content barely changed &mdash; and <code>PROJECT-STATUS.html</code> is mandatory at the end of <em>every</em> phase.</p>
-  <p>There is now one command:</p>
-  <pre><code class="language-bash">bash .tfcore/utils/tf-render-html.sh docs/MyApp-BRD.md PROJECT-STATUS.md</code></pre>
-  <p>It writes a sibling <code>.html</code> for each input and is dependency-free &mdash; Python 3 standard library only, no pandoc, no node, no pip. Crucially it <strong>extracts the §2 CSS, §3 theme script and §7 JS out of <code>html-render-shell.md</code> at render time</strong> rather than duplicating them, so the shell cannot drift from its own documentation: edit the spec and the next render picks it up.</p>
-  <p>Three problems went away with the tokens. <strong>Drift</strong> &mdash; hand-authored output was never reproducible, and the old instruction to &ldquo;verify each HTML mentally&rdquo; was self-review by the model that had just written it. <strong>Truncation</strong> &mdash; a 130 KB file emitted in one generation could silently cut off, and no gate read rendered output. <strong>An unenforceable rule</strong> &mdash; projects quietly wrote their own renderers instead, diverging from the shell.</p>
-  <p>The checklist ban is now <em>mechanical</em>: passing a <code>*-Checklist.md</code> is refused with exit 2 rather than depending on the agent remembering. The renderer also runs the §5.5 Mermaid self-check and warns about unquoted flowchart labels or a reserved <code>end</code> node id &mdash; those are defects in the <strong>source markdown</strong>; fix the diagram and re-render, never edit generated HTML.</p>
-  <p><code>html-render-shell.md</code> remains the specification. Read it to understand or change the shell &mdash; you no longer need to read it to render. Reported by the TfLens team as TF-003; it was a gap, not a regression (no task ever referenced a missing script).</p>
-</details>
-<details>
-  <summary>Does <code>update-framework.sh</code> update the root <code>opencode.jsonc</code>? Mine looks very old.</summary>
-  <p><strong>It does now &mdash; it did not until 2026-08-27, and that was a real defect.</strong> The 2026-08-20 two-file split moved framework config into the framework-owned <code>.opencode/opencode.jsonc</code> (refreshed every run, wins on conflicting keys) and demoted the root file to project-only keys: extra agents, MCP, LSP. It was then preserved unconditionally, forever.</p>
-  <p>A survey of all ten apps carrying the file found that <strong>none of them has any project-only content</strong> &mdash; no project agent, no project command, no <code>mcp</code> or <code>lsp</code> block. Nine held a 138&ndash;154 line copy of a template that had grown to 925 lines, and all nine were missing the <code>trblazeui</code>/<code>techierag</code> agent blocks. So the preserve rule protected nothing while guaranteeing the file rotted.</p>
-  <p>Worse, two apps still wired <code>build-ui-phase</code> / <code>build-rag-phase</code> / <code>build-functional-phase</code> &mdash; commands dissolved on 2026-06-26 &mdash; as <code>{file:}</code> references to task files that no longer exist. <strong>A dead <code>{file:}</code> ref hard-fails OpenCode&rsquo;s entire config load</strong>, so those repos were silently loading no framework agents or commands at all.</p>
-  <p>The root file now refreshes the same way <code>.claude/settings.json</code> does: replaced when nothing project-owned would be lost (old file kept as <code>opencode.jsonc.bak</code>), preserved &mdash; with the project-only keys named in the output &mdash; when there is, and every dead <code>{file:}</code> ref reported either way.</p>
-</details>
-<details>
-  <summary>An agent says a framework file &mdash; <code>tf-metrics.sh</code>, a task, a template &mdash; is &ldquo;not present anywhere in this tree&rdquo;. It obviously is. Why?</summary>
-  <p><strong>Because the framework is invisible to every default file-search tool, and until 2026-08-27 nothing told the agents that.</strong> Two independent filters stack, and you have to defeat both:</p>
-  <ul>
-    <li><code>.tfcore/</code>, <code>.claude/</code>, <code>.codex/</code>, <code>.opencode/</code> and <code>.agents/skills/</code> are <strong>hidden dot-directories</strong> &mdash; ripgrep (which backs the agents&rsquo; Grep tool) skips hidden paths by default.</li>
-    <li>They are also in the <strong>managed <code>.gitignore</code> block</strong> that the scaffolders write into every app (<a href="#scaffolding">§3</a>) &mdash; and ripgrep honours <code>.gitignore</code> by default too.</li>
-  </ul>
-  <p>So <code>rg --hidden</code> is <em>not</em> enough in an app repo; it takes <code>rg --hidden --no-ignore</code> (<code>rg -uu</code>). And because nothing under <code>.tfcore/</code> is <em>tracked</em> in an app, <code>git grep</code> and <code>git ls-files</code> return zero rows as well. An agent that globs for a filename gets nothing back and reasonably concludes the framework is not installed.</p>
-  <p><strong>This is not a bug to fix by un-ignoring the framework.</strong> The ignore block is deliberate and load-bearing &mdash; the deployed copies are re-synced from the template by <code>update-framework.sh</code> and must never be committed in an app (<a href="#scaffolding">§3</a>). The fix is on the agent side: every framework file has exactly one canonical path, and whatever needs it names that path, so existence is confirmed by <strong>reading the literal path</strong>, never by searching for the name. That rule now lives in <code>.tfcore/tasks/_status-update-gate.md</code> §&ldquo;The framework tree is INVISIBLE to search&rdquo; (a shared include, so it reaches every checklist-executing task), is restated in <a href="#verify">verify-phase</a>&rsquo;s verdict rules, and ships in the <code>AGENTS.md</code> / <code>CLAUDE.md</code> hard rules for new apps.</p>
-  <p><strong>Why it matters more than a wasted search:</strong> the false negative does not stay in the transcript. It gets written into a checklist Remarks cell, a BRD §4 status row, or a blocker &mdash; and the next agent reads it as established fact and inherits the conclusion. A verify pass can close a gate that was never actually blocked.</p>
-  <p><strong>When it really <em>is</em> missing:</strong> a fresh clone genuinely has no <code>.tfcore/</code>, because it was never committed. That repo needs <code>update-framework.sh &lt;repo&gt;</code> run once <em>on that machine</em> (see <a href="#platforms">§16</a>). One command &mdash; never a reason to reimplement what the missing file does.</p>
-</details>
-<details>
-  <summary>My repo root is full of <code>test-results/</code>, <code>test-results-cluster-a/</code> or <code>scripts-cluster-b/</code> folders. Why?</summary>
-  <p>That was a real defect, fixed 2026-08-10. Playwright writes run artifacts to <code>test-results/</code> by default, and a verify fan-out that wanted per-cluster isolation invented <em>siblings</em> — <code>test-results-cluster-a/</code>, <code>test-results-tr054/</code>, one per run, forever. The ignore block only carried the bare <code>test-results/</code>, which does <strong>not</strong> match the suffixed names, so they surfaced untracked at every commit — exactly the triage burden the block exists to prevent.</p>
-  <p>The fix: <a href="#verify">verify-phase</a> §1 now pins <code>outputDir: './tests/.artifacts/test-results'</code> in <code>playwright.config.ts</code> (creating the config if absent, <em>editing</em> it if it lacks the setting), bans repo-root artifact directories and <code>--output test-results-&lt;slug&gt;</code> outright, and permits isolation only as a subfolder (<code>--output tests/.artifacts/&lt;slug&gt;</code>). <code>tests/.artifacts/</code> is in the managed ignore block, and Playwright wipes it at the start of each run, so it stops growing. Legacy root-level dirs are deleted by verify-phase §1 on its next pass, or by you right now — they are pure machine output and fully regenerable.</p>
-  <p><strong>The <code>scripts-cluster-*/</code> variant was the same bug one layer up, fixed the same day.</strong> That first fix pinned where the tools <em>write</em> but never said where an agent should put the harness scripts it <em>authors</em>, so the next fan-out simply moved the litter: four <code>scripts-cluster-b|f|g|i/</code> folders holding hand-written <code>smoke-*.mjs</code>. Those scripts also imported the Playwright <em>library</em> directly, which bypasses <code>playwright.config.ts</code> entirely — so the <code>outputDir</code> pin could never have reached them, and one of them hardcoded an absolute path to a <code>test-results-cluster-b</code> it created itself. The rule now covers both halves: run harnesses go in <code>tests/.artifacts/harness/</code>, <code>/scripts-*/</code> is in the ignore block, and verify-phase §1 sweeps root-level <code>scripts-*/</code> alongside <code>test-results*/</code>. <strong>Your own <code>scripts/</code> folder is safe</strong> — the pattern requires the hyphen and the root anchor, and the sweep excludes it explicitly.</p>
-  <p><strong>What are the screenshots even for?</strong> Failure evidence with a session lifetime: <code>screenshot: 'only-on-failure'</code> means a passing run produces almost nothing, and the ones a failing run produces exist so §6 can cite a path in a checklist Remark <em>today</em>. They are never work product and never committed. The screenshots that <em>are</em> deliberately kept and tracked are the DevGuide's reviewed set under <code>docs/screenshots/&lt;APP&gt;/</code> — a different thing entirely.</p>
-</details>
-<details>
-  <summary><code>docs/metrics/commits.jsonl</code> appeared in every repo and it's empty. Bug?</summary>
-  <p>By design. <code>install-metrics.sh</code> seeds all five streams so every repo has the same shape and no writer has to check whether its file exists. Each then fills only when its event happens: <code>gates.jsonl</code> on the first <code>*verify</code>, <code>runs.jsonl</code> on the first framework command, <code>sessions.jsonl</code> when a session ends, and <code>commits.jsonl</code> on <strong>your first commit after telemetry was installed</strong>. Commit the empty files with everything else: a tracked empty stream makes the first record a one-line diff instead of a file appearing from nowhere. See <a href="#telemetry">§17</a>.</p>
-</details>
-<details>
-  <summary>I committed everything, and <code>commits.jsonl</code> immediately shows as modified again.</summary>
-  <p><strong>That repo is still on the retired <code>post-commit</code> hook.</strong> Run <code>update-framework.sh &lt;repo&gt;</code> on that machine; the refresh installs the <code>pre-commit</code> hook and removes the old one.</p>
-  <p>Why it happened: <code>post-commit</code> could only describe commit N once N existed, so its line could never be <em>inside</em> N. The file was dirty the instant every commit finished — permanently, with no reachable clean state, because committing the pending line creates a new commit whose record is then pending in turn. On a repo worked from two machines it also blocked <code>git pull</code> whenever that file had changed upstream.</p>
-  <p>Since 2026-08-11 the record is written <em>before</em> the commit is sealed and staged into it, so the tree is clean when the commit finishes. The lag is unchanged — HEAD is still the previous commit at that point, so commit N's own record ships in N+1 — but it is <em>committed</em> rather than <em>pending</em>. See <a href="#telemetry">§17</a>.</p>
-</details>
-<details>
-  <summary>So if I pull on another machine — or set the code up on a brand-new one — do I lose that last unpushed line?</summary>
-  <p><strong>No.</strong> That line describes a commit, and the commit itself <em>is</em> pushed. The other machine pulls it, and its hook walks <code>git log</code>, sees a commit the file doesn't carry, and writes the record. On a brand-new machine the same thing happens at a larger scale: <code>git log</code> holds the entire history, so one reconcile reproduces every record. This is exactly why the stream is maintained as a <em>projection of the log</em> rather than as an independent ledger — the log is the thing git already replicates, so it is the only thing that has to survive.</p>
-  <p>To fill a machine in immediately instead of waiting for its next commit: <code>.tfcore/telemetry/tf-metrics.sh --backfill-commits .</code></p>
-  <p><strong>The flip side, which is handled:</strong> the original machine also wrote that record locally. Once both versions are in the repo, <code>merge=union</code> keeps <em>both</em> — the same <code>sha</code> twice. That is the deliberate trade: union merge guarantees no record is ever dropped, and <code>tf-metrics.sh</code> de-duplicates commits on <code>sha</code> at read time (reporting how many it collapsed) so nothing is ever counted twice. Only <code>commits.jsonl</code> can duplicate this way; runs/gates/sessions record events that happen on one machine and can't be reconstructed elsewhere.</p>
-  <p>Since the record ships inside a commit rather than sitting pending afterwards, the file matches HEAD between commits — nothing to stage before a pull.</p>
-</details>
-<details>
-  <summary>I work on the same repo from two machines. How do I collect the telemetry from both?</summary>
-  <p><strong>You don't — it collects itself.</strong> The streams are tracked files, so they travel with <code>push</code>/<code>pull</code>. Two things make that work without friction, and the framework refresh sets up both:</p>
-  <ul>
-    <li><code>.gitattributes</code> gives <code>docs/metrics/*.jsonl</code> <strong><code>merge=union</code></strong>. Two machines appending to one append-only log would otherwise conflict on nearly every sync, and hand-resolving such a conflict is exactly how records get silently dropped. Union merge keeps <em>both</em> sides' lines. A record can end up duplicated or out of chronological order as a result — consumers sort on <code>ts</code> and de-duplicate commits on <code>sha</code>, so that costs nothing.</li>
-    <li>The <code>pre-commit</code> hook <strong>reconciles</strong> instead of appending one line: it records every commit reachable from <code>HEAD</code> that the file doesn't already carry, then stages that one file so the records ship inside the commit. Pull the other machine's work, commit here, and its history lands too. <code>git log</code> is itself an append-only log that push/pull already replicates; <code>commits.jsonl</code> is a projection of it.</li>
-  </ul>
-  <p>The one thing that does <em>not</em> travel is the hook: <code>.git/hooks/</code> is not part of the repository, so <strong>every clone needs its own</strong>. Run <code>update-framework.sh &lt;repo&gt;</code> once on each machine — <code>tf-metrics.sh --report</code> also warns when the clone you're standing in has no hook. To fill a machine's history immediately rather than waiting for a commit, run <code>.tfcore/telemetry/tf-metrics.sh --backfill-commits .</code> (idempotent — already-recorded shas are skipped).</p>
-</details>
-<details>
-  <summary>GitHub on Windows says: <em>"This file uses 'LF' line endings, but Git is configured to convert them to 'CRLF' the next time the file is checked out."</em></summary>
-  <p>That is <code>core.autocrlf=true</code> (the Git-for-Windows default) meeting a repo whose <code>.gitattributes</code> says only <code>* text=auto</code>. <code>text=auto</code> normalizes the <em>committed blob</em> to LF but still lets the <em>working tree</em> be smudged to CRLF on checkout — so the file on disk and the file Git will next write disagree, and Git tells you so. It's the same mechanism that CRLF-broke every <code>*.sh</code> in this framework (including the guard hooks) on 2026-07-11.</p>
-  <p>Fixed by pinning the working tree instead of leaving it to per-machine config. The scaffold/update scripts now manage a <code>.gitattributes</code> block in every repo:</p>
-<pre><code>* text=auto eol=lf
-*.bat text eol=crlf
-*.cmd text eol=crlf
-docs/metrics/*.jsonl text eol=lf merge=union</code></pre>
-  <p><code>eol=lf</code> pins the working tree to LF on macOS, WSL and native Windows alike; <code>*.bat</code>/<code>*.cmd</code> keep CRLF because the Windows command processor requires it. It matters most for <code>docs/metrics/*.jsonl</code>, which is appended to by machine — a log must never acquire mixed line endings.</p>
-  <p>Run <code>update-framework.sh &lt;repo&gt;</code> to get the block, then <strong>once per repo, yourself</strong>: <code>git add --renormalize . &amp;&amp; git commit -m "Normalize line endings"</code> so the committed blobs match the new rules. The script prints that reminder when it adds the block. (Agents can't run it — git is manual here.)</p>
-</details>
-<details>
-  <summary>What if the agent ignores the coding standards mid-implementation?</summary>
-  <p>The verifier's standards-compliance grep checks (§10, item 3) catch the most common violations and produce coverage misses. When you see a miss like <code>STANDARDS: underscore-field in src/Foo.cs:42</code> flagged in the checklist's Requirements Status table, tell the implementing agent: <em>"Fix the standards violations flagged in the Requirements Status table of docs/&lt;APP&gt;-Checklist.md per docs/&lt;APP&gt;-Coding-Standards.md."</em> Loop until clean.</p>
-</details>
-<details>
-  <summary>What if existing brownfield code doesn't use the <code>obj</code> field prefix?</summary>
-  <p>First: the prefix only applies if THIS project chose <code>obj</code> — the field prefix is a per-project day-1 decision recorded in <code>docs/&lt;APP&gt;-Coding-Standards.md</code> (e.g. AstroLyfe uses bare PascalCase, no prefix). If it did, the analyst flags it as standards drift in the day-1 output summary. You then either: (a) let the standards-compliance grep checks in the verify pass catch them and fold the fixes into the regular build loop (the implementing agent renames as it touches the file), or (b) explicitly ask flow-master for a one-shot rename pass: <em>"Rename every non-obj-prefixed instance field in src/ to use the obj prefix per docs/&lt;APP&gt;-Coding-Standards.md, in one commit per file."</em> Option (a) is lower-risk; option (b) is faster if you want a clean baseline.</p>
-</details>
-<details>
-  <summary>I want to change the coding standards mid-project. Will the agents pick it up?</summary>
-  <p>Yes — they read <code>docs/&lt;APP&gt;-Coding-Standards.md</code> on every invocation. Update the file, then in the next implementation prompt include <em>"NOTE: the coding standards file was updated; conform new code to it and flag any existing non-conforming areas in your output summary."</em></p>
-</details>
-<details>
-  <summary>Should the architecture document be updated as the code changes?</summary>
-  <p>Yes. For a deliberate change to scope/structure (new module, new flow, stack tweak), run <code>*amend-docs &lt;APP&gt; "&lt;what changed&gt;"</code> (<a href="#evolving-docs">§7.9</a>) — it amends Architecture.md (and the BRD) in place and re-renders. For incidental "as-built" drift discovered during implementation, the implementing agent notes it and <code>/flow-master</code> reconciles at handoff ("update Architecture.md to reflect 'as-built', then regenerate the HTML").</p>
-</details>
-<details>
-  <summary><code>scaffold-brownfield.sh</code> / <code>scaffold-greenfield.sh</code> re-run wiped my work?</summary>
-  <p>No for your work product — framework files copy with <code>rsync --ignore-existing</code>. EXCEPTION: the harness agent mirror under <code>.claude/commands/TechieFlow/agents/</code> is force-synced from <code>.tfcore/agents/</code> on every run — edit agents only in <code>.tfcore/agents/</code>. (The old <code>.opencode/command/TechieFlow/</code> mirror no longer exists — OpenCode loads agents/tasks from <code>opencode.jsonc</code> <code>{file:./.tfcore/...}</code> references.)</p>
-</details>
-<details>
-  <summary><code>*yolo</code> doesn't stop Bash prompts.</summary>
-  <p>It does now (2026-08-21, §12a). <code>*yolo</code> writes <code>.tfcore/.session/yolo.json</code>; the PreToolUse hook reads it and stops asking for <code>rm</code>/<code>rmdir</code>/<code>sudo</code> and allows read-only git. Still prompted? (1) The app's <code>.claude/settings.json</code> predates the change and still has <code>Bash(rm *)</code> under <code>ask</code> — run <code>update-framework.sh &lt;app&gt;</code>; a settings <code>ask</code> prompts in every mode, even bypass. (2) The agent forgot <code>tf-yolo.sh on</code> — type <code>*yolo</code> again or run it yourself. Git <strong>writes</strong> prompt for nobody — denied outright in every mode.</p>
-</details>
-<details>
-  <summary>My unattended goal run stopped on "You've hit your limit · resets …".</summary>
-  <p>Use the supervisor, not a bare session: <code>bash .tfcore/utils/tf-goal.sh &lt;app-dir&gt; "&lt;goal&gt;"</code> (§12a). It parses the reset time, sleeps until reset + 15 min, and resumes the same session; <code>--resume &lt;app-dir&gt;</code> continues after a reboot. Watch <code>.tfcore/.session/goal.log</code>.</p>
-</details>
-<details>
-  <summary><code>*build-phase</code> implemented a few REQs and told me to run it again for the rest.</summary>
-  <p>That ending is banned (build-phase §2b). Re-run it — FRESH/FIX detection picks up the open rows — and if it happens again, quote §2b back: a pass is done when every working-list REQ is ≥ <code>Implemented</code>; context pressure means more sub-agent clusters, not a shorter pass.</p>
-</details>
-<details>
-  <summary>Mermaid not rendering in BRD.html / Architecture.html.</summary>
-  <p>(1) Offline + CDN script blocked — inline mermaid.min.js instead. (2) Missing <code>mermaid.initialize</code> — check end of HTML. (3) Malformed code fence — confirm <code>```mermaid</code> on its own line and valid Mermaid syntax.</p>
-</details>
-<details>
-  <summary>Verifier says "Playwright not installed".</summary>
-  <p>Vidur self-heals browser binaries. If install fails: did you run §0?</p>
-</details>
-<details>
-  <summary>Agent implemented things <em>not</em> in the requirements doc.</summary>
-  <p><em>"Revert anything not tied to a REQ-* ID."</em> Add new REQ first if you actually want it.</p>
-</details>
-<details>
-  <summary>Slash command <code>/trblazeui</code> shows "no skill".</summary>
-  <p>Run <code>dotnet build</code> once to fire the TrBlazeUI NuGet deploy target. If still missing: <code>dotnet build -t:TrBlazeUIRedeployAgentFiles</code>. Restart Claude Code so it rescans skills.</p>
-</details>
-<details>
-  <summary>Should I commit the HTML files?</summary>
-  <p>Yes for all of <code>PROJECT-STATUS.html</code>, <code>&lt;APP&gt;-BRD.html</code>, <code>&lt;APP&gt;-Architecture.html</code>, <code>&lt;APP&gt;-&lt;Library&gt;-Feedback.md</code>. Browseable on GitHub without cloning, and they're the human-facing artifacts.</p>
-</details>
-<details>
-  <summary>Standard TechieFlow story-by-story flow — ever?</summary>
-  <p>Only with a second person. For solo + Claude Max, the compressed flow is strictly faster. The stock story-flow agents and tasks no longer ship with this scaffold (trimmed 2026-06-12) — obtain a full story-by-story agent set separately if that day comes.</p>
-</details>
-<details>
-  <summary>How do I keep token usage down?</summary>
-  <p>Read <code>.tfcore/TOKEN-GUIDE.md</code> (ships with every project). Key levers: don't load whole docs or repo trees into context; checklists stay markdown-only (never rendered to HTML — HTML adds weight with no AI benefit); fan work out to subagents instead of loading everything in one session; use <code>*amend-docs</code> and <code>*devguide --update</code> for incremental refreshes instead of re-running phases from scratch; use <code>*refresh-status</code> to recover a broken session instead of re-running the whole phase.</p>
-</details>
-<details>
-  <summary>A screen passed verification but was rendering blank OR was visually broken — how is it prevented now?</summary>
-  <p>Before the gates, verification only checked acceptance-test pass/fail (HTTP 200, no exception, element present). A screen could pass while its data table showed zero rows, or while every control rendered its data but the controls <strong>overlapped / sat off-screen / were clipped</strong> so the running app was unusable. Two gates close both holes:</p>
-  <ul class="tight">
-    <li><strong>Render gate (verify-phase §4a):</strong> the verifier asserts every control listed in the DevGuide actually renders its data — no blank table, no count-over-zero-rows, no empty chart.</li>
-    <li><strong>Visual-truth gate (§4b):</strong> it then asserts the screen LOOKS right — no control overlap, every control in-viewport and non-zero-size, checked at desktop + mobile widths, the screenshot inspected, and diffed against the mockup when one exists.</li>
-  </ul>
-  <p>A REQ is <code>Verified</code> only if acceptance passes AND data renders AND the screen looks right; otherwise it drops to <code>Needs re-verify</code> / <code>FAIL</code>. <code>Done (pre-existing)</code> is treated as an unverified migrated claim and gets the same sweep. The DevGuide's observed render/visual tags are refreshed each run, keeping DevGuide ⇄ Checklist ⇄ Verifier runtime-true.</p>
-</details>
-<details>
-  <summary>The verifier passed but the running UI is broken — who do I call?</summary>
-  <p><code>/TechieFlow:agents:flow-master *fix-issues {AppName} {folder}</code> (§7.11). Drop a folder of screenshots of the broken screens (optionally a <code>bugs.md</code> naming what's wrong on each). Flow-master reads them (vision), reproduces each issue live with Playwright, triages it (layout / data / logic / RAG), and <strong>fans the fix out to the right builder</strong> — <code>/trblazeui</code> for layout, its own subagents for data/logic, <code>/techierag</code> for RAG. You never invoke a builder agent yourself. It then re-smokes (data + visual), re-verifies the affected REQs, and updates the DevGuide + checklist + PROJECT-STATUS.</p>
-</details>
-<details>
-  <summary>I found bugs at UAT / in production — I want them analyzed and logged, but NOT fixed yet</summary>
-  <p><code>/TechieFlow:agents:flow-master *triage-issues {AppName} {evidence}</code> (§7.12). Same evidence channel as <code>*fix-issues</code> (a screenshots folder), plus it accepts a written bug list. Flow-master reproduces each issue live and delivers <strong>docs only</strong>: regressed REQs demoted to <code>Needs re-verify</code> with dated <code>⚠ UAT bug</code> remarks, new <code>Planned</code> REQ rows for unspecified defects, refreshed DevGuide known-issues, and a PROJECT-STATUS whose next command is the <code>*fix-issues</code> pointer naming the REQ IDs. Add <code>verify</code> to also regression-re-verify the affected screens' sibling REQs. It never edits <code>src/</code>/<code>tests/</code> and never spawns a builder — you decide when the fixing starts.</p>
-</details>
-<details>
-  <summary>How does a developer understand or verify the AI-generated code?</summary>
-  <p>Run <code>/TechieFlow:agents:flow-master *devguide {AppName}</code> (also auto-run at handoff). It produces <code>docs/{AppName}-DevGuide.md</code> + a styled <code>.html</code>: every screen grouped by user role, each with a flowchart tracing the full stack (Razor page → service → data-access → stored procedure/query), a Controls table (with observed render-status from the OBSERVE pass), and a Data-lineage table. Use it to find the right service method for a bug, confirm the correct stored procedure is called, or check that a control is bound to the right DTO property. Re-run with <code>--update</code> after implementing changes to refresh only the affected screens. See <a href="#docs">§6</a> for the full schema and the 3-pass generation model.</p>
-</details>
-<h2 id="platforms">16. Running on macOS / native Windows / Linux<span class="anchor-link"><a href="#platforms">#</a></span></h2>
-<p>This framework was built on the owner's <strong>WSL-on-Windows</strong> machine, so §0/§11 and the build-invocation ladder describe that setup. But the framework itself is <strong>portable</strong> — the agents, tasks, templates, and slash-commands are plain Markdown and run identically under Claude Code or OpenCode on <strong>macOS, native Windows, or native Linux</strong>. Only two things are environment-specific: how <code>dotnet</code> is invoked, and the runtime-verification bridges (headless Playwright for Blazor; the §0b Appium endpoints for MAUI Android/iOS/Mac-Catalyst; FlaUI/Appium-Windows for the MAUI Windows head). Here is what changes per platform.</p>
-<div class="panel">
-  <strong>What is the SAME everywhere:</strong> the <code>scaffold-*.sh</code> / <code>update-framework.sh</code> scripts (bash), all <code>/TechieFlow:*</code> slash commands, the day-1 → split → build → verify → handoff flow, every doc template, and the <code>.claude/settings.json</code> permission model. The scaffold scripts need <code>bash</code> + <code>rsync</code> + <code>realpath</code> (preinstalled on macOS 12.3+ and Linux; on native Windows run them from <strong>WSL or Git Bash</strong>).
-</div>
-<table>
-  <tr><th>Concern</th><th>WSL-on-Windows (reference)</th><th>macOS</th><th>native Windows</th><th>native Linux</th></tr>
-  <tr><td><code>dotnet</code> invocation</td><td>ladder §B: <code>~/.dotnet/dotnet</code>, <code>cmd.exe /c</code>, <code>winrun</code></td><td><strong>ladder §A: <code>dotnet build</code></strong> (in PATH)</td><td><strong>ladder §C: <code>dotnet build</code></strong> (in PATH)</td><td><strong>ladder §A: <code>dotnet build</code></strong> (in PATH)</td></tr>
-  <tr><td>MAUI iOS / Mac Catalyst</td><td>Windows side via <code>cmd.exe</code> (needs paired Mac for iOS)</td><td><strong>native</strong> — needs Xcode + <code>sudo dotnet workload install maui</code></td><td>needs a paired Mac build host</td><td>not supported (no Apple toolchain)</td></tr>
-  <tr><td>MAUI Android</td><td>Windows side via <code>cmd.exe</code></td><td>native — Android SDK + JDK</td><td>native — Android SDK + JDK</td><td>native — Android SDK + JDK</td></tr>
-  <tr><td>MAUI Windows head</td><td>Windows side via <code>cmd.exe</code></td><td>not supported</td><td>native</td><td>not supported</td></tr>
-  <tr><td>Browser verification (verifier)</td><td>headless Playwright CLI (§0 bootstrap)</td><td>Playwright with system Chromium</td><td>Playwright with system browser</td><td>headless Playwright CLI</td></tr>
-  <tr><td>Native UI verification (Android/iOS/Catalyst)</td><td><strong>Appium endpoints (§0b)</strong>: Android on Windows host, iOS/Catalyst on a LAN Mac</td><td>local Appium (Android emulator + iOS Sim + Catalyst, all native)</td><td>local Appium (Android emulator + Catalyst); iOS via the paired Mac's Appium</td><td>local Appium (Android only)</td></tr>
-  <tr><td>Scaffold scripts</td><td>run in WSL</td><td>run in Terminal (zsh/bash)</td><td>run in WSL or Git Bash</td><td>run in shell</td></tr>
-</table>
-<p>The agents resolve this automatically: the build-invocation ladder (<code>.tfcore/templates/v4custom/build-invocation-ladder.md</code>) now starts with a <strong>platform-detection probe</strong> (<code>uname -a</code> → <code>Darwin</code> = macOS, <code>…microsoft…</code> = WSL, plain <code>Linux</code> = native Linux, absent = native Windows) and picks ladder §A / §B / §C accordingly. On macOS/Windows/Linux there is a single rung — <code>dotnet build</code> — and a missing MAUI workload is fixed once with <code>dotnet workload install maui</code> (on macOS with <code>sudo</code>: the SDK dir <code>/usr/local/share/dotnet</code> is root-owned, and without it workload/SDK updates fail with <em>"Inadequate permissions. Run the command with elevated privileges."</em>), never logged as a project blocker.</p>
-<div class="panel ok"><strong>macOS quick start (Claude Code on Mac):</strong>
-<ol>
-  <li>Run the one-time <a href="#mac-bootstrap">§0a macOS bootstrap</a> — Xcode CLT/license, Homebrew, .NET SDK + Node, Playwright per project; <code>sudo dotnet workload install maui</code> (sudo required on macOS) + Xcode / Android SDK only for MAUI apps.</li>
-  <li>Scaffold as usual: <code>/path/to/TechieFlow/scaffold-brownfield.sh /path/to/your-app</code> (or <code>scaffold-greenfield.sh</code>).</li>
-  <li>Start Claude Code in the app folder and run <code>/TechieFlow:agents:analyst *day1-brownfield &lt;AppName&gt;</code> — identical to WSL.</li>
-</ol>
-The <code>winrun</code> bridge and <code>cmd.exe</code> rungs simply don't apply on Mac; the agents won't reach for them once <code>uname</code> reports <code>Darwin</code>.</div>
-<div class="panel ok"><strong>NuGet credentials for macOS:</strong> store the private GitHub Packages source in <code>$HOME/.nuget/NuGet/NuGet.Config</code> (for example <code>/Users/srkra/.nuget/NuGet/NuGet.Config</code>), not in the project. NuGet, Claude Code, and native OpenCode discover it automatically. Windows uses <code>%AppData%\NuGet\NuGet.Config</code>. OpenCode Docker mounts the Windows directory read-only at <code>/root/.nuget/NuGet</code>. A repository <code>nuget.config</code>, if needed for source mapping, must contain no PAT.</div>
-<div class="panel warn"><strong>Moving an existing project (or this framework repo) from Windows/WSL to a Mac:</strong>
-<ol>
-  <li><strong>Can't see <code>.tfcore/</code>, <code>.claude/</code>, <code>.opencode/</code> in Finder?</strong> Finder hides dot-files by default. Press <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>.</kbd> in any Finder window to toggle them on (the setting sticks), or run <code>defaults write com.apple.finder AppleShowAllFiles -bool true &amp;&amp; killall Finder</code>. The Terminal always sees them: <code>ls -la</code>. Nothing is missing just because Finder doesn't show it — check with <code>ls -la</code> first.</li>
-  <li><strong>Moved an APP repo via git (clone/pull)?</strong> Then the framework folders genuinely AREN'T there — every deployed framework copy (<code>.tfcore/</code>, <code>.claude/</code>, <code>.opencode/</code>, <code>/CLAUDE.md</code>, <code>/WORKFLOW.html</code>, <code>/opencode.jsonc</code>) is <em>gitignored by design</em> (they're copies; this repo is the source of truth). Re-deploy them: <code>ls -la</code> the app — if <code>.tfcore/</code> exists, run <code>/path/to/TechieFlow/update-framework.sh /path/to/app</code>; if it's absent, run <code>/path/to/TechieFlow/scaffold-brownfield.sh /path/to/app</code> (safe on an app with existing docs/code — it uses <code>--ignore-existing</code> and never touches <code>src/</code>, <code>docs/</code>, or tests). Add <code>--dry-run</code> to <code>update-framework.sh</code> to preview.</li>
-  <li><strong>Per-project gitignored files don't come back from a scaffold.</strong> <code>CLAUDE.md</code>, <code>.tfcore/core-config.yaml</code> customizations, and <code>.claude/settings.local.json</code> are per-project work product that git never carried. A plain <em>folder copy</em> from the old machine keeps them; a git clone loses them — copy them over from the Windows machine, or regenerate (<code>CLAUDE.md</code> comes back via day-1 / <code>*refresh-status</code>).</li>
-  <li><strong>Scripts won't execute (<code>permission denied</code>)?</strong> A copy through a Windows filesystem drops the executable bit. Fix once: <code>chmod +x /path/to/TechieFlow/*.sh /path/to/TechieFlow/.tfcore/hooks/*.sh</code> (or run them as <code>bash script.sh</code>). Hooks inside apps are invoked via <code>bash</code> so they don't need it, but the same <code>chmod</code> doesn't hurt.</li>
-  <li><strong>No path edits needed:</strong> since 2026-07-11 the three scripts locate the framework from their own directory (no hardcoded <code>/mnt/c/…</code>), and they run fine on macOS's stock <code>bash</code>/<code>rsync</code>.</li>
-  <li><strong>Afterwards, restart Claude Code</strong> in the app folder so the freshly deployed agent/task definitions and <code>settings.json</code> load.</li>
-</ol></div>
-<div class="panel"><strong>native Windows quick start (Claude Code / OpenCode on Windows, not WSL):</strong>
-<ol>
-  <li>Install the .NET SDK (winget / official installer); confirm <code>dotnet --info</code>.</li>
-  <li>For MAUI: <code>dotnet workload install maui</code>. Windows + Android heads build natively; <strong>iOS / Mac Catalyst need a paired Mac build host</strong>.</li>
-  <li>Run the scaffold scripts from <strong>WSL or Git Bash</strong> (they're bash). Then drive the framework from Claude Code on Windows normally — the ladder uses §C (<code>dotnet build</code>).</li>
-</ol></div>
-<div class="panel ok"><strong>OpenCode in a Windows Docker container:</strong> use the dedicated <a href="#opencode-docker">Containerized OpenCode host bridge</a> under §0. The container is Linux, so it uses the SSH-backed <code>winrun</code> wrapper rather than direct <code>cmd.exe</code> interop.</div>
-<div class="panel"><strong>native Linux quick start:</strong>
-<ol>
-  <li>Install the .NET SDK via your distro or the official script; confirm <code>dotnet --info</code>.</li>
-  <li>MAUI on Linux supports the <strong>Android</strong> head only (<code>net9.0-android</code>) — iOS / Mac Catalyst / Windows heads can't build without their toolchains (a genuine platform limit, not a wrong-rung error).</li>
-  <li>Scaffold and run exactly as on macOS (ladder §A).</li>
-</ol></div>
-<p><strong>Notes.</strong> The framework never <em>requires</em> MAUI — many apps are Blazor-only and build with plain <code>dotnet build</code> everywhere. The full per-platform <code>dotnet</code> invocation detail lives in <code>.tfcore/templates/v4custom/build-invocation-ladder.md</code> (what the agents read); this section is the human-facing summary.</p>
-<h2 id="telemetry">17. Development telemetry — what the framework measures about itself<span class="anchor-link"><a href="#telemetry">#</a></span></h2>
-<div class="panel ok"><strong>Full guide</strong> — annotated example records for every stream, the report walkthrough, how model/tokens/cost land on run records, and the FAQ: <code>docs/TechieFlow-Telemetry-Guide.md</code> (+ rendered <code>.html</code>) <em>in the TechieFlow framework repo</em>. Field-by-field contract: <code>.tfcore/telemetry/SCHEMA.md</code> (deployed in this app).</div>
-<p>TechieFlow already produced this evidence and used to throw it away. Every <code>*verify</code> run applies four separately-named gates to individually-identified requirements and writes verdicts into the Requirements Status table; <code>docs/.last-verify.json</code> recorded the run. Then the next run overwrote it, the table was mutated in place, and the history was gone. Telemetry keeps it.</p>
-<p><strong>Four questions, and nothing else:</strong></p>
-<ol>
-  <li><strong>First-pass rate</strong> — what fraction of REQs reach <code>Verified</code> on attempt 1?</li>
-  <li><strong>Gate catch distribution</strong> — of all failures, which gate caught them?</li>
-  <li><strong>Escape rate</strong> — what fraction of defects reached UAT/production (logged by <code>*triage-issues</code>) instead of being caught by a gate?</li>
-  <li><strong>Miss attribution and rework cost</strong> (added 2026-08-28) — <em>what</em> was missed, <em>which phase / agent / model</em> let it through, and <em>what did fixing it cost</em>?</li>
-</ol>
-<p>There is deliberately <strong>no cycle-time-per-feature</strong>. The unit of work here is <em>the run</em>, not the ticket.</p>
-<h3>Where it lands</h3>
-<p>Five append-only JSONL streams in <code>docs/metrics/</code>, <strong>tracked by version control on purpose</strong> — this is the project's own development history, and the one thing the framework cannot reconstruct afterwards.</p>
-<table>
-<thead><tr><th>File</th><th>One record per</th><th>Written by</th></tr></thead>
-<tbody>
-<tr><td><code>runs.jsonl</code></td><td>framework command run</td><td>each phase task, at completion (the status gate is the trigger)</td></tr>
-<tr><td><code>gates.jsonl</code></td><td>REQ verdict per verify run — <strong>the primary stream</strong></td><td><code>verify-phase</code> §6a, and <code>triage-issues</code> for escapes</td></tr>
-<tr><td><code>sessions.jsonl</code></td><td>agent session</td><td>the <code>SessionEnd</code> hook (<code>.tfcore/hooks/metrics-session.sh</code>)</td></tr>
-<tr><td><code>commits.jsonl</code></td><td>commit</td><td>your own <code>pre-commit</code> hook — never an agent</td></tr>
-<tr><td><code>misses.jsonl</code></td><td>a requirement or behaviour an agent <strong>missed</strong> (<code>miss</code>), what repairing it cost (<code>miss-fix</code>), and a field completed later (<code>miss-amend</code>)</td><td><code>verify-phase</code>, <code>build-phase</code>, <code>triage-issues</code>, <code>fix-issues</code>, <code>amend-docs</code>, <code>*log-miss</code></td></tr>
-</tbody>
-</table>
-<p>Schema, enums and every known limitation: <code>.tfcore/telemetry/SCHEMA.md</code>. Doctrine for agents: <code>.tfcore/tasks/_metrics-emit-gate.md</code>.</p>
-<h3>Setup — there isn't one</h3>
-<p>Telemetry rides the normal framework refresh. There is <strong>no separate install command</strong>:</p>
-<p><strong>on WSL/Linux:</strong></p>
-<pre><code>/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/YourApp
-</code></pre>
-<p><strong>on macOS:</strong></p>
-<pre><code>/Volumes/MacD/MyCode/TechieFlow/update-framework.sh /path/to/YourApp
-</code></pre>
-<p>That one command creates <code>docs/metrics/</code>, seeds the five streams, installs the <code>pre-commit</code> hook, and warns if an ignore rule would swallow the data. The scaffolds do the same on a fresh project. It is idempotent, so every later refresh keeps it current.</p>
-<p><strong>project_type is auto-detected once</strong> (a packable <code>.csproj</code> → <code>library</code>; <code>.razor</code>/<code>.xaml</code> present → <code>app</code>; no source → <code>docs</code>; this repo → <code>framework</code>), printed loudly, written to <code>core-config.yaml</code>, and then never guessed again — <code>core-config.yaml</code> is a preserved file, so your classification survives every refresh. Correct a wrong guess with:</p>
-<pre><code>.tfcore/telemetry/install-metrics.sh . --type app|library|docs|framework
-</code></pre>
-<p><strong>Nothing here invokes git.</strong> The hooks directory is found by reading the filesystem — installing a hook is a file copy, not a git operation — so <code>block-git.sh</code> is untouched and no permission prompt appears, whoever runs the refresh.</p>
-<h3>Updating the metrics — you don't</h3>
-<p>There is no "update metrics" step. The streams fill themselves as you work: every <code>*build-phase</code>, <code>*verify all</code>, <code>*fix-issues</code>, <code>*triage-issues</code>, <code>*handoff-phase</code> and day-1 run appends its own record as its last action, the <code>SessionEnd</code> hook adds a session, and your own commits add themselves. If you never think about telemetry again, it still accumulates.</p>
-<p>The only thing that needs doing per repo is the framework refresh you already run:</p>
-<pre><code>/mnt/c/3AIGenCode/TechieFlow/update-framework.sh /path/to/YourApp
-</code></pre>
-<h3>Viewing the metrics — two ways</h3>
-<p><strong>1. Quick look, in the terminal.</strong> No agent, no tokens, read-only — run it from inside the app repo:</p>
-<pre><code>cd /path/to/YourApp
-.tfcore/telemetry/tf-metrics.sh --report .
-</code></pre>
-<p>Prints first-pass rate, gate catch distribution, escape rate, rework ratio, batch size, throughput, commit cadence and the miss report — already segmented, with <code>insufficient data</code> wherever there are fewer than three supporting records.</p>
-<p><strong>2. The full report, as a document.</strong> Ask flow-master; it writes <code>docs/metrics/METRICS.md</code> and renders <code>docs/metrics/METRICS.html</code> (open that in a browser — it uses the same themed shell as your other docs):</p>
-<p><strong>Claude Code:</strong></p>
-<pre><code>/TechieFlow:agents:flow-master *metrics YourApp
-</code></pre>
-<p><strong>OpenCode:</strong></p>
-<pre><code>/flow-master *metrics YourApp
-</code></pre>
-<h3>Across several projects at once</h3>
-<pre><code>.tfcore/telemetry/tf-metrics.sh --rollup . /path/to/OtherApp /path/to/Third
-</code></pre>
-<p>Still segmented — <code>app</code> and <code>library</code> repos are reported side by side, never averaged together. Or hand the same paths to the command: <code>*metrics YourApp /path/to/OtherApp</code>.</p>
-<h3>Seeding history from what you already have (optional, once per repo)</h3>
-<p>Your repos have years of history the streams know nothing about. Two backfills can import some of it. <strong>Both are yours to run, never an agent's</strong> — and always preview with <code>--dry-run</code> first:</p>
-<pre><code>cd /path/to/YourApp
-.tfcore/telemetry/tf-metrics.sh --backfill-commits . --dry-run
-.tfcore/telemetry/tf-metrics.sh --backfill-commits .
-</code></pre>
-<p><strong>Commit backfill is trustworthy.</strong> It walks the commit log, which is itself an append-only log, so reconstructed commits are exactly as good as live ones and are reported together with them. This is also the reason the <code>pre-commit</code> hook is optional.</p>
-<pre><code>.tfcore/telemetry/tf-metrics.sh --backfill-gates . --dry-run
-</code></pre>
-<p><strong>Gate backfill is context, not evidence.</strong> It reads each REQ's current row in <code>&lt;APP&gt;-Checklist.md</code> plus any dated remarks. But that table is a snapshot that gets overwritten in place, not a log — a REQ that failed three times and then passed looks identical to one that passed first try. Every record it writes is stamped <code>backfilled: true</code> with an <code>inferred</code> list, is reported in its own separate column, and <strong>can never support a published first-pass rate</strong>. Useful for volume and shape; not for a number you would defend.</p>
-<h3>If a project is classified wrong</h3>
-<p>The refresh auto-detects <code>project_type</code> once and prints what it chose. If it guessed wrong — the giveaway is a library reported as though the visual gate could fire on it — correct it and it stays corrected:</p>
-<pre><code>.tfcore/telemetry/install-metrics.sh . --type app|library|docs|framework
-</code></pre>
-<h3>What to expect early on</h3>
-<p>The streams start empty, and the report refuses to invent numbers from thin data — you will see <code>insufficient data (n=…)</code> on most rows until roughly three verify runs have happened. That is the report working, not a fault. The first genuinely interesting reading usually comes after a build → verify → fix cycle or two.</p>
-<table>
-<thead><tr><th>You want to…</th><th>Run</th></tr></thead>
-<tbody>
-<tr><td>Turn telemetry on for a repo</td><td><code>update-framework.sh /path/to/YourApp</code> (nothing else)</td></tr>
-<tr><td>Glance at the numbers now</td><td><code>.tfcore/telemetry/tf-metrics.sh --report .</code></td></tr>
-<tr><td>Produce the readable report</td><td><code>*metrics YourApp</code> → <code>docs/metrics/METRICS.html</code></td></tr>
-<tr><td>Compare several projects</td><td><code>tf-metrics.sh --rollup . /path/to/OtherApp</code></td></tr>
-<tr><td>Import commit history</td><td><code>tf-metrics.sh --backfill-commits .</code></td></tr>
-<tr><td>Import checklist history</td><td><code>tf-metrics.sh --backfill-gates .</code> (context only)</td></tr>
-<tr><td>Fix a wrong classification</td><td><code>install-metrics.sh . --type library</code></td></tr>
-</tbody>
-</table>
-<h3 id="misses">Misses — the fourth question</h3>
-<p>A <code>gates.jsonl</code> record says a REQ <em>failed</em>. A <strong>miss</strong> record says <em>what was missed</em>, <em>which phase let it through</em>, and — through its <code>miss-fix</code> sibling — <em>what the repair cost</em>. It is the only stream that can hold a <strong>design-phase miss</strong> (&ldquo;the BRD never specified the export screen&rdquo;), because it is the only one not written by the verifier: by the time verification runs, a specification gap has either been papered over or built wrongly.</p>
-<div class="panel ok"><strong>The 20-second front door.</strong><br>
-<pre><code>/TechieFlow:agents:flow-master *log-miss {AppName} "the export button ignores the active date filter"
-/flow-master *log-miss {AppName} "..."          (OpenCode)          # add --fixed if it is already repaired</code></pre>
-It classifies what you said, attributes it, writes the <code>misses.jsonl</code> record <em>and</em> the checklist line (a demotion with a dated <code>⚠ miss</code> remark, or a new <code>Planned</code> row with acceptance when nothing owns it). <strong>It never boots the app, never reproduces, never edits code</strong> — <code>*triage-issues</code> does all three, which is right for UAT triage and far too heavy for one sentence. That friction is exactly why these misses used to be recorded nowhere at all.</div>
-<p>Everything else emits automatically: <code>verify-phase</code> on every failing gate, <code>build-phase</code> when a REQ turns out to be unbuildable as written, <code>triage-issues</code> on a UAT or production bug, <code>fix-issues</code> when it closes one.</p>
-<p><strong>One defect is one miss.</strong> A REQ that fails three verify passes collapses onto the record already open for it, so the miss count measures quality rather than retry patience. A new record is written only when the <em>kind</em> of failure changes — which is genuinely new information.</p>
-<p><strong>&ldquo;Open&rdquo; and &ldquo;live&rdquo; are deliberately different.</strong> A miss closed as <code>wont-fix</code> is a <em>decision</em>, not a backlog item, so the report does not count it as open — but the collapse check still treats it as a live defect, so a repeat failure on that REQ will not open a duplicate. Two questions, two predicates; making them agree would break one of them. <code>deferred</code> stays open, because postponed work is still work.</p>
-<h3>Which <em>practice</em> failed — <code>why_missed</code></h3>
-<p><code>miss_class</code> names the defect. <strong><code>why_missed</code> names the practice that let it through</strong>, and it is the more decision-changing of the two: it says whether your <em>specification</em> or your <em>verification</em> is the weak one. Ported from the AI-First-Playbook on 2026-08-28, whose <code>/analyze-fix</code> phase has always produced exactly this judgement in prose and then thrown it away.</p>
-<table>
-<thead><tr><th>Value</th><th>The practice that failed</th></tr></thead>
-<tbody>
-<tr><td><code>missing-checklist-item</code></td><td>No REQ or acceptance bullet covered the behaviour. The spec had a hole.</td></tr>
-<tr><td><code>insufficient-verify-method</code></td><td>Acceptance existed; the gate that ran could not catch this class of defect. The spec was fine, the test was too weak.</td></tr>
-<tr><td><code>code-audit-limitation</code></td><td><code>⚠ STATIC-ONLY</code> — no runtime bridge, so it was never observable.</td></tr>
-<tr><td><code>ambiguous-acceptance</code></td><td>Two honest readings; build and verifier took different ones.</td></tr>
-<tr><td><code>dependency-not-declared</code></td><td>The REQ depended on something no document stated.</td></tr>
-<tr><td><code>instruction-ignored</code></td><td><strong>A written framework rule existed and was not followed.</strong> TechieFlow's own addition — not a spec gap, not a weak gate, and no gate change fixes it.</td></tr>
-<tr><td><code>other</code></td><td>Nothing above fits. Do not stretch a label to avoid this.</td></tr>
-</tbody>
-</table>
-<div class="panel"><strong>Optional, and <code>null</code> is honest</strong> — many misses have no clear answer and a forced one is noise. <strong>But an escape without one wastes the most valuable record in the stream:</strong> something got past every gate, and <em>why nothing caught it</em> is the entire question. <code>--report</code> warns when an <code>owner</code> or <code>production</code> miss arrives with the field empty, and reports the distribution against <em>records that carry it</em>, never against all misses.</div>
-<h3>Completing a record without editing it — <code>miss-amend</code></h3>
-<p>A stream is append-only, so &ldquo;the correction is a new record, never an edit&rdquo; is the rule. That rule needs a record kind to name, and until 2026-08-28 this stream had none: a field left empty — most sharply a <code>why_missed</code> on a record written before the field existed — was unreachable. <strong>Reported by the TfLens team as TF-005</strong>, and fixed with a third kind rather than a licence to edit.</p>
-<pre><code>bash .tfcore/utils/tf-emit.sh --amend MISS-App-20260828-01 why_missed missing-checklist-item</code></pre>
-<ul>
-<li>It may fill a field that is <code>null</code>. It may <strong>never</strong> overwrite one that is not — including a value set by an earlier amend. So it <em>completes</em> a record rather than altering a fact, and a reader that ignores amendments entirely still sees nothing false, only less.</li>
-<li>Only closed-vocabulary <strong>judgements</strong> are amendable (<code>why_missed</code> today). Nothing the emitter derives — <code>origin_model</code>, <code>origin_confidence</code>, <code>cost_attribution</code>, tokens, dollars — ever is, and an <em>observation</em> about a finished run is never backfilled.</li>
-<li>It prints its refusal rather than failing quietly, and still exits 0: telemetry has no veto, and neither does a refused amend. A hand-written amend piped onto the stream faces the identical checks.</li>
-<li><strong>Never hand-edit a <code>.jsonl</code> stream.</strong> If no record kind can carry the correction you need, report it as a framework defect — which is exactly how this one arrived.</li>
-</ul>
-<div class="panel"><strong>A record written before a field existed is not &ldquo;unassessed&rdquo;.</strong> <code>why_missed</code> arrived on 2026-08-28; misses older than that had no field to fill, so they leave that field&rsquo;s denominator and <code>--report</code> states how many did. Same rule as a gate added mid-stream (§3.5 of the schema): never backfill a record with a verdict nobody made at the time.</div>
-<h3>What a miss costs — the honest version</h3>
-<table>
-<thead><tr><th>Harness</th><th>Tokens</th><th>Dollars</th></tr></thead>
-<tbody>
-<tr><td>OpenCode</td><td>yes</td><td><strong>real, measured</strong> — the provider's own per-message cost</td></tr>
-<tr><td>Claude Code</td><td>yes</td><td><strong>none — <code>cost_usd</code> is <code>null</code>, permanently</strong>: transcripts carry no cost</td></tr>
-<tr><td>Codex</td><td>yes</td><td>none — ChatGPT credits are never fabricated as <code>cost_usd</code></td></tr>
-</tbody>
-</table>
-<p>So &ldquo;how much money did that miss cost&rdquo; has a real answer only on OpenCode; elsewhere the answer is a token count. <strong>No rate card is ever applied to make a dollar figure appear.</strong> An estimate presented as a measurement poisons every comparison built on it.</p>
-<div class="panel warn"><strong>Two exclusions, both applied AND displayed.</strong><br>
-<strong>(1) Attribution.</strong> A miss's <code>origin_model</code> is <em>looked up</em> from <code>runs.jsonl</code>, never typed by an agent — and when the lookup fails, the model is forced to <code>null</code> and the record marked <code>inferred</code>. Only <code>linked</code> records feed a per-phase / per-agent / per-model figure. A per-model miss rate computed partly from guesses is a routing decision made on invented evidence, and nothing in the output would reveal it.<br><br>
-<strong>(2) Cost.</strong> A fix run that repaired three misses has <em>one</em> token window; dividing it three ways is arithmetic, not measurement. <code>cost_attribution</code> marks each record <code>sole</code>, <code>shared:n</code> or <code>none</code>, and the report shows measured and apportioned as separate columns — never one blended number. A miss fixed inline with no distinct run cannot be costed at all, and is printed as such rather than dropped.<br><br>
-Both exclusions are reported <em>with</em> the figures they bound: an exclusion you cannot see is indistinguishable from a bug.</div>
-<p>Escape rate keeps its existing definition and its existing source (<code>gates.jsonl</code> <code>gate:"escaped"</code>). The miss stream's own &ldquo;found by a human&rdquo; share sits <em>beside</em> it, never merged into it — one word cannot mean two things on one page.</p>
-<h3 id="telemetry-gotchas">Two things that trip people up</h3>
-<div class="panel ok"><strong>You do not need the commit hook to get metrics.</strong> Four of the five streams need <em>no</em> version-control hook at all: <code>runs</code>, <code>gates</code> and <code>misses</code> come from <code>tf-emit.sh</code> inside the phase tasks, and <code>sessions</code> from the Claude Code <code>SessionEnd</code> hook (or the OpenCode plugin) — neither of which is a version-control hook. Only <code>commits.jsonl</code> uses <code>.git/hooks/pre-commit</code>, and only for commit volume and cadence: nothing about <em>what was missed, who missed it, or what the fix cost</em> depends on it.<br><br>
-And even that hook is optional. <code>.tfcore/telemetry/tf-metrics.sh --backfill-commits .</code> reconstructs the identical records <em>perfectly</em> from the commit log at any time — that log is itself append-only, which is why commit records are the one backfill exempt from the live-vs-backfilled separation. The hook only makes it automatic.</div>
-<div class="panel warn"><strong>A greenfield project is born labelled <code>docs</code>, and that used to stick.</strong> The greenfield scaffold classifies the repo at scaffold time, when it genuinely <em>is</em> docs-only — the day-1 documents exist and <code>src/</code> does not — and the old &ldquo;auto-detected once, then never re-guessed&rdquo; rule froze it there. TfLens accumulated <strong>225 gate records, visual gates included, under a <code>project_type</code> whose own definition says gates cannot fire</strong>, and whose figures never pool with the apps it belongs beside.<br><br>
-Since <strong>2026-08-28</strong> a later <code>update-framework.sh</code> re-examines <code>docs</code> <em>alone</em> and <strong>only upgrades</strong>: once real heads or a published package appear, the tree has answered a question that was unanswerable at scaffold time. <code>app</code> / <code>library</code> / <code>framework</code> are never re-guessed, an owner's <code>--type</code> always wins, and a genuine docs repo never grows a head so it is never touched. Correct one by hand at any time:
-<pre><code>.tfcore/telemetry/install-metrics.sh . --type app</code></pre>
-<strong>Records written before a correction keep the old value.</strong> The streams are append-only and corrections happen at <em>read</em> time, never by rewriting history — so a reclassified project appears under <strong>both</strong> segments, which the provenance rule forbids pooling. <code>--report</code> states the split explicitly rather than letting one project look like two; read each segment as a <em>period</em> of the project, not the whole of it.</div>
-<div class="panel"><strong>Why some figures are never combined.</strong> The report will not print a single first-pass rate, gate catch distribution, or escape rate that pools <em>live</em> with <em>backfilled</em> records, or pools <code>app</code> with <code>library</code>/<code>docs</code> — not as a total row, not as an "overall" line. A backfilled attempt count is inferred from a status table that never recorded attempts, so a merged first-pass rate cannot be defended when someone asks how attempts were counted. A pooled gate distribution understates the visual gate, because library and docs projects never had screens to fail on. One indefensible figure contaminates every other number on the page. Commit-derived metrics are exempt — the commit log is a real append-only log, and commit volume is comparable across project types.</div>
-<div class="panel"><strong>The one-commit lag.</strong> At <code>pre-commit</code> time HEAD is still the <em>previous</em> commit, so the record for the commit you are making ships inside the <em>next</em> one. Metrics lag reality by a commit, and that is unavoidable in either direction — a record of commit N cannot predate N. What changed on 2026-08-11 is that the record is now <em>committed</em> rather than left <em>pending</em>: writing after the commit was sealed (the original <code>post-commit</code> design) left <code>commits.jsonl</code> permanently dirty with no reachable clean state. Because the hook <em>reconciles</em> from the log rather than appending a single line, the lag never becomes a <em>loss</em> either: whichever machine commits next writes the missing record.
-<br><br><strong>What it costs, stated plainly:</strong> the hook stages one file — <code>docs/metrics/commits.jsonl</code>, never a directory, never <code>-A</code> — into the commit you are making. On a partial commit (<code>git commit -- &lt;paths&gt;</code>) it writes the record but does <em>not</em> stage, so it cannot add a file to a commit you deliberately scoped down, and it can never fail your commit (every path exits 0). <a href="#permissions">Agents still never run git</a>: this is your own <code>git commit</code>, no agent path reaches it, and <code>block-git.sh</code> is unchanged.</div>
-<div class="panel"><strong>Several machines, one repo.</strong> The streams are tracked files, so they travel with push/pull. <code>.gitattributes</code> (managed by the scaffold/update scripts) gives <code>docs/metrics/*.jsonl</code> <code>merge=union</code> so two machines appending never conflict — hand-resolving a conflict in an append-only log is how records get silently dropped — and <code>eol=lf</code> so a machine-appended log never acquires mixed line endings. The <code>pre-commit</code> hook records every commit reachable from <code>HEAD</code> that the file lacks and stages it into the commit, so after a pull, your next commit picks up the other machine's history as well. The hook itself lives in <code>.git/hooks/</code> and therefore does <em>not</em> travel: run <code>update-framework.sh</code> once per clone, or <code>tf-metrics.sh --backfill-commits .</code> to fill that machine's history straight away.</div>
-<div class="panel"><strong>Privacy — assume every record could become public.</strong> Records carry IDs, counts, durations, verdicts and file paths <em>at most</em>. Never requirement text, prompt text, file contents, or commit subjects — only a commit's conventional-commit prefix (<code>feat</code>/<code>fix</code>/…) is kept, and the subject is discarded on the spot. <code>failure_class</code> is a closed vocabulary for exactly this reason. This framework is used on employer projects, and these files are append-only: a leaked field is not something you fix later.</div>
-<div class="panel"><strong>Telemetry has no veto.</strong> No metrics write can fail a build, block a tool call, abort a phase, or print an error. <code>tf-emit.sh</code> exits 0 unconditionally — missing directory, malformed JSON, absent <code>python3</code>, full disk — and the event is simply dropped. Same fail-open posture as the <code>guard-status</code> / <code>guard-verify</code> hooks. A telemetry bug must never cost you a working session.</div>
-<h2 id="model-routing">17b. Model routing — run cheap phases on cheap models<span class="anchor-link"><a href="#model-routing">#</a></span></h2>
-<div class="panel ok"><strong>Full guide</strong> — the complete phase AND persona/subagent tier tables, per-tier change recipes with examples, the TUI walkthrough, what gets generated under the hood, and troubleshooting: <code>docs/TechieFlow-Routing-Guide.md</code> (+ rendered <code>.html</code>) <em>in the TechieFlow framework repo</em>.</div>
-<p><strong>What it is, in one example.</strong> Without routing, day-1 architecture and re-rendering HTML cost the same per token. With routing ON, each phase gets a <strong>tier</strong>, each tier maps to a real model:</p>
-<table>
-<tr><th>Tier</th><th>Meant for</th><th>Claude</th><th>OpenCode (defaults — yours to change)</th><th>Codex</th></tr>
-<tr><td><code>frontier</code></td><td>expensive thinking: day-1, author-brd, amend-docs, fix-issues</td><td><code>opus</code></td><td><code>opencode-go/kimi-k3</code></td><td><code>gpt-5.6</code></td></tr>
-<tr><td><code>standard</code></td><td>everyday building: build, verify, mockups, split-brd, triage, devguide + builder subagents</td><td><code>sonnet</code></td><td><code>opencode-go/kimi-k2.7-code</code></td><td><code>gpt-5.6-terra</code></td></tr>
-<tr><td><code>economy</code></td><td>mechanical: metrics, renders, refresh-status, productguide, handoff</td><td><code>haiku</code></td><td><code>opencode-go/deepseek-v4-flash</code></td><td><code>gpt-5.6-luna</code></td></tr>
-</table>
-<p>Measured example (TechieBlog pilot): a complete <code>metrics-report</code> phase on economy — 14k output tokens, full report — cost <strong>$0.036</strong>. Builders stay on <code>standard</code> deliberately: a cheap builder that ships a blank table costs an entire verify-and-fix cycle.</p>
-<h3>Turn it on / off — one command</h3>
-<pre><code class="lang-bash">cd /path/to/YourApp
-bash .tfcore/utils/tf-routing.sh status     # read-only: the live tier/model/phase table
-bash .tfcore/utils/tf-routing.sh on         # enable — generates ~23 binding files
-bash .tfcore/utils/tf-routing.sh off        # disable — removes exactly those files</code></pre>
-<div class="panel warn"><strong>IMPORTANT — what you will (and won't) see in the TUI.</strong> Opening OpenCode looks <em>exactly the same as before</em>. That is deliberate: your normal chat runs on the default <code>build</code> agent, and routing never touches it — your conversation stays on the model YOU picked. Routing becomes visible in three places only: <strong>(1)</strong> run a phase command — <code>/techieflow:tasks:metrics-report YourApp</code> executes on the tier model and the footer shows it; <strong>(2)</strong> press <strong>Tab</strong> to a persona (<code>flow-master</code>, <code>flow-verifier</code>, …) — each carries its bound model; <strong>(3)</strong> the telemetry — every run lands in <code>docs/metrics/runs.jsonl</code> with declared tier, observed model, <code>routed: true/false</code>, tokens and (OpenCode) real cost.</div>
-<div class="panel warn"><strong>Verified gotcha:</strong> after a routed command, that TUI session <em>stays on the phase's model</em> — it does not bounce back. Pick your model from the model list or start a new session if you keep chatting. Claude Code is the mirror image: a <code>/tf:&lt;phase&gt;</code> wrapper's model lasts exactly one turn, then reverts automatically.</div>
-<h3>A concrete first run (safe even mid-UAT)</h3>
-<p><code>metrics-report</code> reads the telemetry streams and writes only <code>docs/metrics/METRICS.md</code> + <code>.html</code> — no code, no status, no checklist:</p>
-<pre><code>1. bash .tfcore/utils/tf-routing.sh on
-2. opencode
-3. /techieflow:tasks:metrics-report YourApp
-4. watch the footer: it runs on deepseek-v4-flash, not your chat model
-5. tail -1 docs/metrics/sessions.jsonl   →  "model":"opencode-go/deepseek-v4-flash","cost_usd":0.03…</code></pre>
-<h3>Changing the map — one command per change</h3>
-<pre><code class="lang-bash">bash .tfcore/utils/tf-routing.sh set-tier  mockups   frontier      # promote a phase
-bash .tfcore/utils/tf-routing.sh set-tier  verify-phase economy    # demote a phase
-bash .tfcore/utils/tf-routing.sh set-model standard opencode opencode-go/qwen3.7-max
-bash .tfcore/utils/tf-routing.sh set-model economy  claude   haiku
-bash .tfcore/utils/tf-routing.sh set-model standard codex    gpt-5.6-terra
-bash .tfcore/utils/tf-routing.sh bind      # re-apply after hand-editing routing.yaml</code></pre>
-<p>Claude takes aliases or full ids; OpenCode takes <code>provider/model</code> ids; Codex takes model slugs available to the installed Codex CLI. A skill in the main Codex conversation inherits the active model; generated custom agents and <code>tf-goal.sh --harness codex</code> are the pinned-model path.</p>
-<h3>Escalation — advisory, applied by you at launch</h3>
-<p><code>routing.yaml</code> also carries an <code>escalation:</code> block, shipped as <code>fix-issues: after_attempts: 2, tier: frontier</code> — "if the same REQs have been through <code>fix-issues</code> twice without reaching <code>Verified</code>, launch the third run on frontier". It is <strong>advisory</strong>: <code>bash .tfcore/utils/tf-emit.sh --next-run-attempt fix-issues &lt;REQ-IDs&gt;</code> reads the attempt history (the <code>attempt</code> field now stamped on every <code>runs.jsonl</code> record that touches REQs), <code>tf-routing.sh status</code> prints the policy, and <code>tf-routing.sh set-escalation &lt;phase&gt; &lt;attempts&gt; &lt;tier&gt;</code> tunes it. If the number exceeds the threshold, <em>you</em> launch the next run on the escalation tier (Claude: <code>/model opus</code> then the command; OpenCode: pick the model, then the command). Nothing ever switches a running phase's model — neither harness can (DECISIONS.md 2026-08-21; Routing Guide §6.4).</p>
-<h3>Reading the results</h3>
-<p>Each run's record shows declared vs observed: <code>"tier":"standard", "model":"opencode-go/kimi-k2.7-code", "routed":true, "tokens_out":42310, "cost_usd":0.41</code>. The deciding question after a couple of weeks: <strong>does the rework ratio rise on cheaper tiers?</strong> If standard builders hold the first-pass rate, demote more; if <code>mode:"fix"</code> re-entries climb, promote. Data corrects the map, not opinion.</p>
-<h3>FAQ</h3>
-<ul>
-  <li><strong>"I turned it on and the TUI looks the same."</strong> Expected — see the IMPORTANT panel. Run a phase command or Tab to a persona.</li>
-  <li><strong>"How do I make my normal chat cheaper too?"</strong> Not routing's job — pick a cheaper model in the TUI model list, or set <code>"model"</code> in <code>~/.config/opencode/opencode.jsonc</code>.</li>
-  <li><strong>"status says flag and bindings disagree."</strong> <code>bash .tfcore/utils/tf-routing.sh bind</code>.</li>
-  <li><strong>"Does update-framework.sh wipe my routing?"</strong> No — <code>routing.yaml</code> is preserved forever; refreshes re-generate your bindings from YOUR map (verified in the pilot).</li>
-  <li><strong>"What gets generated?"</strong> OpenCode: <code>.opencode/opencode.json</code>. Claude: <code>.claude/commands/tf/*.md</code> + <code>.claude/agents/tf-*.md</code>. Codex: <code>.codex/agents/*.toml</code> + <code>.agents/skills/techieflow-*/</code>. All are gitignored and regenerated from the preserved routing map.</li>
-</ul>
-<h2 id="team-edition">18. Team edition — the AI-First Playbook<span class="anchor-link"><a href="#team-edition">#</a></span></h2>
-<p>TechieFlow is the <strong>solo edition</strong>. Its team-scale sibling is the
-<strong><a href="https://github.com/techierathore/AI-First-Playbook">AI-First Development Playbook</a></strong> —
-the same philosophy (<em>spec-driven, independently verified, execution-proven AI development</em>), sized for
-an engineering team with QA, BA and business stakeholders instead of one developer and a portfolio.</p>
-<table>
-<thead><tr><th></th><th><strong>TechieFlow</strong> (this framework — solo edition)</th><th><strong><a href="https://github.com/techierathore/AI-First-Playbook">AI-First Playbook</a></strong> (team edition)</th></tr></thead>
-<tbody>
-<tr><td>Optimized for</td><td>One developer + AI, portfolio of ~8–10 apps</td><td>A team (~5–50 devs) on one large product</td></tr>
-<tr><td>Lifecycle</td><td>Compressed 5 phases — Day-1 → Split → Build → Verify → Handoff</td><td>10 steps, 4 gates, per-feature loop</td></tr>
-<tr><td>Unit of work</td><td>The <strong>run</strong> (hand a phase a checklist and go)</td><td>The <strong>feature</strong> (one living implementation checklist each)</td></tr>
-<tr><td>Checklist</td><td>One per app, all <code>REQ-UI/FN/NFR/RAG-*</code> rows in one table</td><td>One per feature</td></tr>
-<tr><td>Verifier</td><td>Playwright + Appium + <code>dotnet test</code>; data-render + visual-truth gates; hook-enforced verify ledger</td><td>Fresh-context verifier agent; execution-proven verdicts written inline</td></tr>
-<tr><td>Harness</td><td>Claude Code (<code>.tfcore/</code> + <code>.claude/</code>), OpenCode mirror</td><td>OpenCode + BMAD v4 personas</td></tr>
-<tr><td>Human docs</td><td>DevGuide, UsageGuide, ProductGuide</td><td>Developer-Flow-Guide, Business-Verification-Reference</td></tr>
-<tr><td>Also has</td><td>Telemetry (<a href="#telemetry">§17</a>), git ban + guard hooks, MAUI/Appium bridge, <code>*fix-issues</code> / <code>*triage-issues</code></td><td>Jira/Confluence integration, post-verification bug loop, team enablement &amp; onboarding material</td></tr>
-</tbody>
-</table>
-<p>Shared by both: markdown as the source of truth, Mermaid-only diagrams, HTML for human docs only,
-single-source-of-truth checklists, and <strong>"verify by executing, not by reading."</strong></p>
-<div class="panel"><strong>Which one do you want?</strong> If you are one person driving agents across several apps, stay here. If you are rolling a process out to a team — where the hard parts are onboarding, review gates and shared standards rather than raw throughput — start with the Playbook; it ships enablement and onboarding material this framework deliberately does not carry. The two are independent repos: nothing here depends on the Playbook, and nothing there depends on this.</div>
-<hr>
-<p class="small">Last revised 2026-08-28 (rev 2). Edit freely. When the workflow changes, update <code>README.md</code> and <code>WorkFlow-Context.md</code> (the durable cross-harness context document) too.</p>
-</main>
-</div>
-<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
-<script>
-  if (window.mermaid) {
-    mermaid.initialize({ startOnLoad: true, theme: 'dark', securityLevel: 'loose', flowchart: { useMaxWidth: true, htmlLabels: true } });
-  }
-</script>
-<script>
-  document.querySelectorAll('.tabs').forEach(group => {
-    const buttons = group.querySelectorAll('button');
-    const panels = group.parentElement.querySelectorAll('.tabpanel');
-    buttons.forEach(btn => {
-      btn.addEventListener('click', () => {
-        buttons.forEach(b => b.classList.remove('active'));
-        panels.forEach(p => p.classList.remove('active'));
-        btn.classList.add('active');
-        document.getElementById('tab-' + btn.dataset.tab).classList.add('active');
-      });
-    });
-  });
-  document.querySelectorAll('pre:not(.mermaid)').forEach(pre => {
-    const btn = document.createElement('button');
-    btn.className = 'copy';
-    btn.textContent = 'copy';
-    btn.addEventListener('click', () => {
-      const text = pre.querySelector('code') ? pre.querySelector('code').innerText : pre.innerText;
-      navigator.clipboard.writeText(text).then(() => {
-        btn.textContent = 'copied';
-        setTimeout(() => { btn.textContent = 'copy'; }, 1200);
-      });
-    });
-    pre.appendChild(btn);
-  });
-</script>
-</body>
-</html>