@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/templates/v4custom/build-invocation-ladder.md

@@ -1,190 +1,27 @@
 # Build invocation ladder
 
-When any task says "run `dotnet build`" / "run `dotnet test`" / "run `dotnet run`", **never accept "command not found" or "workload missing" as a stopping condition**. The right way to invoke `dotnet` depends on the host platform. **Detect the platform FIRST, then use that platform's ladder.**
+**Building, testing and running is a script since Sitting 4b (2026-09-05):** `bash .tfcore/utils/tf-build.sh [build|test|run] [<target>]`. It detects the host (macOS, native Linux, native Windows, WSL, OpenCode Docker), decides whether the target has a MAUI head, tries the invocation rungs in order (`dotnet`, `~/.dotnet/dotnet`, `winrun`, `cmd.exe /c dotnet`, `powershell.exe dotnet`), stops at the first that works, and prints one verdict line: `PASS … via <rung>`, `FAIL … real errors` (the code is wrong: fix it), or `NOT-RUN … tried: …` (the host is wrong: never a project blocker). `bash .tfcore/utils/tf-build.sh probe` prints the host and the rungs without building. The full output of every attempt is under `tests/.artifacts/build/`. Copy the verdict line into the status log row or the Remark.
 
-## 0. Platform detection — do this ONCE per session, then cache it
+Two facts the script cannot change: a MAUI iOS or Mac Catalyst head builds only on a Mac (prepare the source and the on-Mac commands; never substitute another head as "the" deliverable), and a workload missing on macOS is installed once with `sudo dotnet workload install <id>` by the owner.
 
-Run a single probe to classify the host:
+## Reaching the running UI after a green build
 
-| Probe result | Platform | Ladder to use |
-|---|---|---|
-| `uname` → `Darwin` | **macOS** (Claude Code / OpenCode native, or via Terminal) | §A — dotnet in PATH, MAUI/iOS native via Xcode |
-| `uname` → `Linux` **and** `/proc/version` contains `microsoft` / `WSL` | **WSL-on-Windows** (the reference machine) | §B — the WSL↔Windows interop ladder |
-| `TF_OPENCODE_DOCKER=1` (or `uname` → `Linux`, no `microsoft` in `/proc/version`, and `/usr/local/bin/winrun` exists with `TF_WINDOWS_APP_PATH` set) | **OpenCode Docker on Windows** | §E — .NET in container, Windows head through SSH bridge |
-| `uname` → `Linux`, no `microsoft` in `/proc/version`, and no Docker bridge | **native Linux** | §A (Linux notes) — standard .NET only; Windows/Apple heads are unavailable |
-| `uname` not found / shell is `cmd`/`PowerShell`; paths look like `C:\…` | **native Windows** (Claude Code / OpenCode on Windows, not WSL) | §C — dotnet in PATH, MAUI native |
-
-One-liner to detect: `uname -a 2>/dev/null || echo windows` — `Darwin…` = macOS, `…microsoft…`/`…WSL…` = WSL, plain `Linux` = native Linux, `windows` (uname absent) = native Windows.
-
-> The §B WSL ladder below was the framework's original default because the owner's primary machine is WSL-on-Windows (`WORKFLOW.html §0`). It is **one platform's** ladder, not the universal one. A plain native Linux process has no Windows interop, but OpenCode Docker is a deliberate exception: when `/usr/local/bin/winrun` and `TF_WINDOWS_APP_PATH` are present, use §E and probe the SSH bridge. Never report `cmd.exe` missing inside the container; it is expected not to exist there.
-
----
-
-## A. macOS / native Linux — `dotnet` is in `PATH`
-
-→ **Start (and stay) at rung #1: `dotnet build`.** The .NET SDK installer puts `dotnet` on the `PATH`; there is no interop layer.
-
-- **Non-MAUI projects** (Web, API, library, console, test): `dotnet build` / `dotnet test` / `dotnet run` directly.
-- **MAUI on macOS:** builds natively once the workload + toolchains are installed — `sudo dotnet workload install maui`. **`sudo` is REQUIRED on macOS**: the SDK lives in root-owned `/usr/local/share/dotnet`, so any `dotnet workload install/update` (and SDK updates) without it fails with `Inadequate permissions. Run the command with elevated privileges.` — that error is a sudo signal, NEVER a project blocker. iOS / Mac Catalyst targets require **Xcode** (and `xcode-select --install`); Android targets require the **Android SDK + a JDK** (`sudo dotnet workload install maui-android`). With those present, `dotnet build -t:Run -f net9.0-maccatalyst` (or `-f net9.0-ios`) just works — no `cmd.exe`.
-- **MAUI on native Linux:** this framework's Docker image installs no MAUI workloads. Windows MAUI Blazor Desktop uses §E; mobile/iOS/Mac Catalyst work belongs on a native Mac. Do not install or report `maui-tizen` as a Docker prerequisite.
-- If `dotnet build` fails with `NETSDK1178` / "workload not installed", the fix is `dotnet workload install <id>` — with `sudo` on macOS (root-owned SDK dir; see above) — a one-time setup step the user runs, not a rung change; there is no other rung on this platform. If the user reports `Inadequate permissions` from a workload/SDK command, give them the exact `sudo` form of the same command.
-
----
-
-## B. WSL-on-Windows (the reference machine) — WSL ↔ Windows interop ladder
-
-The owner's machine is set up per `WORKFLOW.html §0` and has BOTH:
-
-- **WSL-side .NET** at `$HOME/.dotnet/dotnet` (rung #2) — *replace with your own WSL dotnet path if different*. Compiles non-MAUI projects green.
-- **Windows-side .NET** with full workloads — including MAUI / iOS / Android — reachable via `cmd.exe /c "dotnet …"` (rung #4) or the `winrun` bridge (rung #3). Compiles MAUI/iOS/Android workloads green.
-
-Both are PERMANENT setups — you are NEVER reporting "MAUI cannot build on WSL" or "MAUI workloads missing" as a project blocker. Those are environment-config misunderstandings, not project issues. If a build fails because the workload isn't where you tried, you are on the wrong rung — switch rungs.
-
-### The WSL ladder — try until one works
+A green build is half of a verify. The verifier, the DevGuide and every smoke drive the running UI to check that data shows and the screen looks right. The driver depends on the head; the build does not change:
 
-| # | Command | Works when |
-|---|---------|------------|
-| 1 | `dotnet build` | dotnet is in WSL `$PATH` (rare on this machine) |
-| 2 | `~/.dotnet/dotnet build` (or `$HOME/.dotnet/dotnet build`) | dotnet is WSL-installed but not in PATH (the user's default — confirmed present) |
-| 3 | `winrun "dotnet build"` | user's WSL→Windows helper at `$HOME/bin/winrun` |
-| 4 | `cmd.exe /c "dotnet build"` | Windows-side .NET 10 (full workloads — MAUI, iOS, Android, etc.) — works for any `/mnt/c/...` project |
-| 5 | `powershell.exe -Command "dotnet build"` | same as #4 with PowerShell |
-
-Each candidate is a SINGLE bash command — no `for`/`if`/loops — so each matches the project's `.claude/settings.json` allow patterns (`Bash(dotnet *)`, `Bash(cmd.exe *)`, `Bash(powershell.exe *)`, `Bash(winrun *)`).
-
-## How to PICK the right rung (§B / WSL only — READ THIS, most failures come from skipping it)
-
-> The rest of this document (rung selection, symptom escalation, probe order, banned-blocker list) is **§B WSL-specific detail**. On macOS / native Windows / native Linux there is a single rung (`dotnet build`), so skip ahead to §C if you're on native Windows; macOS/Linux is fully covered by §A above.
-
-The right starting rung depends on **what you are building**:
-
-### A. Single .csproj — non-MAUI (Web, API, library, console, test project)
-→ **Start at rung #2.** If it works, stay there for the session.
-
-### B. Single .csproj — MAUI / iOS / Android / .NET MAUI Hybrid
-Detect: `<UseMaui>true</UseMaui>`, `<TargetFramework>` contains `-android` / `-ios` / `-maccatalyst` / `-windows10`, or the SDK is `Microsoft.NET.Sdk.Maui`.
-→ **Skip rungs #1–#2 entirely.** Start at rung #4 (or #3 if you prefer the `winrun` wrapper). MAUI workloads ONLY live on the Windows side per the user's setup.
-
-### C. Solution / multi-project build (`.sln` or `.slnx`) — MIXED projects
-**Do this BEFORE picking a rung.** Scan the solution file's project entries:
-
-1. Read the `.sln` / `.slnx` file (use the `Read` tool — single call).
-2. For each `<Project Path="…" />` (slnx) or `Project("…") = "…", "…\X.csproj"` line (sln), look at the .csproj path. Then quickly grep each `.csproj` for `<UseMaui>` or MAUI SDK references.
-3. **If ANY project in the solution is MAUI/iOS/Android → the SOLUTION-level build needs the Windows side. Start at rung #4.** Do NOT try rung #2 on the slnx — it will fail with `NETSDK1178` or `Microsoft.iOS.Sdk missing` or similar workload errors, and that failure is a wasted attempt, not a project blocker.
-4. **If NO project is MAUI** → start at rung #2.
-
-### D. Per-project build to isolate a failure
-If a solution-level build fails on the right rung, fall back to building each project individually:
-- Non-MAUI projects (Web/API/library) on rung #2 (faster).
-- MAUI/iOS/Android projects on rung #4.
-- Aggregate the results in your status report. This isolates which projects compile clean and which have real code-level issues.
-
-## Symptom-based auto-escalation (catch the wrong-rung-by-error pattern)
-
-If a build fails with ANY of these errors, you are on the WRONG RUNG — escalate immediately, do NOT log it as a project blocker:
-
-| Error code / message | Meaning | Action |
+| Head | Runtime driver | Where it runs |
 |---|---|---|
-| `NETSDK1178` ("workload missing") | MAUI/iOS/Android workload not installed at the dotnet you're calling | Switch to rung #4 (`cmd.exe /c "dotnet build ..."`) |
-| `Microsoft.iOS.Sdk` / `Microsoft.Android.Sdk` / `Microsoft.MacCatalyst.Sdk` missing | Same as above | Rung #4 |
-| `error : Workload ID '...' not recognized` | Workload definition missing at the dotnet you're calling | Rung #4 |
-| `error : Microsoft.WindowsAppSDK ... not found` | WinUI / WinAppSDK workload missing on WSL side | Rung #4 |
-| `command not found: dotnet` | Wrong rung (not the right thing) | Next rung |
-| Real C# compile errors (CS####), missing references in source code | This IS a project issue | Log as Known blocker; stay on the rung |
-
-**Rule of thumb:** Workload/SDK errors → rung change. Source-code errors → project blocker.
-
-## Probe order (optional, single commands)
-
-If you want to detect availability before building (do this once per session, cache the result):
-
-1. `ls $HOME/.dotnet/dotnet 2>/dev/null` — fastest WSL probe
-2. `cmd.exe /c "where dotnet"` — fastest Windows probe (confirms rung #4 is available)
-3. `cmd.exe /c "dotnet workload list"` — see which workloads Windows-side has (one-time check)
-
-## Recording the result
-
-After a successful build (any rung):
-- `last_verified_build: PASS`
-- `last_verified_date: {today YYYY-MM-DD}`
-- Note which rung was used in the PROJECT-STATUS verification-log row or Remarks (e.g. `built via rung #4`).
-
-After a failed build that's NOT a workload/wrong-rung issue (real CS#### errors):
-- `last_verified_build: FAIL`
-- `last_verified_date: {today YYYY-MM-DD}`
-- Add to "Known blockers" with one-line error summary AND which rung was used.
-
-After all rungs genuinely failed (probed all 5, none could find dotnet at all):
-- `last_verified_build: not-run`
-- `last_verified_date: {today YYYY-MM-DD}`
-- Add to "Known blockers": "Tried ladder rungs 1-5; no dotnet found in WSL PATH, ~/.dotnet/, winrun, cmd.exe, or powershell.exe. User needs to install .NET SDK or expose it to WSL PATH."
-
-## What NEVER goes into Known blockers (banned escape-hatch entries)
-
-These are NOT blockers — they are signals you used the wrong rung. If you find yourself writing one, you skipped this doc:
-
-- ❌ "MAUI build cannot run on WSL"
-- ❌ "Microsoft.iOS.Sdk workload missing"
-- ❌ "Microsoft.Android.Sdk workload missing"
-- ❌ "NETSDK1178 — workload not installed"
-- ❌ "WSL doesn't have the MAUI workload"
-- ❌ "dotnet not in PATH"
-- ❌ Anything that boils down to "I tried the wrong rung and it failed"
-
-The user has the bridge set up. Their projects build green on the right rung. Document what RUNG produced the working build, not what failed on the wrong one.
-
-## What NOT to do
-
-- Do NOT report `last_verified_build: not-run` because rung #1 failed. That is a lazy escape. Try rungs 2-5 first.
-- Do NOT wrap the probe in `if [ -x ... ]; then ... else ... fi` — that triggers a permission prompt. Run probes as plain single commands.
-- Do NOT log workload-missing / NETSDK1178 / wrong-rung errors as "Known blockers". They are wrong-rung errors. Switch and retry.
-- Do NOT claim ".NET is unavailable on this system" unless ALL five rungs failed AND your probe commands also failed. Even then, report which rungs you tried verbatim.
-- **Do NOT let a host limitation cancel a cross-OS deliverable.** A MAUI Mac Catalyst / iOS head genuinely cannot be built from Windows/WSL (`-r osx-arm64` only cross-compiles *plain* .NET — a Catalyst `.app` needs Xcode's toolchain, macOS only; `NETSDK1005`/`NETSDK1139`/a maccatalyst TFM guarded by `IsOSPlatform('OSX')` is that fact surfacing, not a failure). That is a **rung-selection fact, never a reason to drop the native head, declare it impossible, or quietly substitute another head** (e.g. a web-head publish) as "the" deliverable. The app's BuildAndRun guide documents the owner-run on-Mac path — prepare the source + the exact on-Mac commands, state plainly "the Catalyst `.app` is built on the Mac per the guide §<n> (one command, owner-run)", and treat any substitute you can build locally as a *complement*, offered alongside, never a silent replacement.
-
----
-
-## C. Native Windows (Claude Code / OpenCode running on Windows, not inside WSL)
-
-→ **Use rung #1: `dotnet build`.** You are already on the Windows side, so there is no interop bridge — `cmd.exe`/`winrun`/`/home/...` from §B do NOT apply.
-
-- **Non-MAUI** projects: `dotnet build` / `dotnet test` / `dotnet run` directly.
-- **MAUI**: builds natively here. Windows (`net9.0-windows10…`) and Android heads build directly once `dotnet workload install maui` has been run. **iOS / Mac Catalyst heads require a paired Mac** (Apple's toolchain only runs on macOS) — building those from Windows needs a Mac build host; absence of one is a genuine platform limitation, not a wrong-rung error.
-- Paths in commands use the project's actual location (e.g. `C:\src\App\App.sln`). Single commands, no `if/for` wrappers (same permission-prompt reason as §B).
-- `NETSDK1178` / "workload not installed" → run `dotnet workload install <id>` once; there is no alternate rung to switch to.
-
-## D. Runtime-observe leg — reaching the RUNNING UI after a green build
-
-Building is only half of "verify". Once a head builds green, the verifier / devguide OBSERVE / smoke gates must **drive the running UI** to apply the data-render (§4a) and visual-truth (§4b) gates. The driver depends on the head — this is the runtime counterpart to the build rungs above, and it does NOT change how anything builds:
-
-| Head | Build (above) | **Runtime driver** | Where it runs |
-|------|---------------|--------------------|---------------|
-| Blazor | rung #1/#2 | headless **Playwright** (system Chromium) | WSL |
-| MAUI **Windows** | §B rung #4 / §C native | **FlaUI / Appium-Windows** | Windows side |
-| MAUI **Android** | §B rung #4 / §A/§C native | **Appium** (`uiautomator2`) → emulator/device | Windows host (SDK + emulator); WSL drives over HTTP |
-| MAUI **iOS** | paired Mac (Xcode) | **Appium** (`xcuitest`) → iOS Simulator | LAN Mac; WSL drives over HTTP |
-| MAUI **Mac Catalyst** | paired Mac (Xcode) | **Appium** (`mac2`) → the running .app | LAN Mac; WSL drives over HTTP |
-
-**Appium is the native analogue of Playwright** — same WebDriver protocol, returns a `base64` screenshot (visual-truth) + an element tree with `rect`/text (data-render). So the gates' assertions are identical; only the driver differs.
-
-- The endpoints live in `core-config.yaml → runtimeVerification.appium` (per app, opt-in). The WSL side needs only the **HTTP url** — no `adb`, emulator, or Xcode inside WSL.
-- **Android** runs entirely on the Windows host; the verifier boots the emulator + Appium itself via the registry `launch` command (you may launch it through `winrun`), then drives it over `http://localhost:4723` (Win11 mirrored networking) — booting it yourself, never asking the owner, is the same rule as the build ladder.
-- **iOS / Mac Catalyst** depend on the **LAN Mac being up**. `curl http://<mac>:4723/status` first; if unreachable, that head degrades to `⚠ STATIC-ONLY` (a session dependency, like "stack down"), never a faked `Verified`.
-- One-time host setup (Android SDK + AVD + Appium on Windows; Xcode + Appium + xcuitest/mac2 on the Mac; the `.wslconfig` mirrored-networking switch) is **`WORKFLOW.html §0b`**.
-- **Input discipline (all native heads, esp. MAUI Windows):** bind the driver to the app under test by identity — the **PID you launched → its top-level window handle** (Appium Windows `appium:appTopLevelWindow` / FlaUI `Application.Attach(pid)`) or the app **package/bundle id** on mobile — and interact **element-by-element via `AutomationId`** inside that bound window. NEVER global keyboard/mouse injection (FlaUI `Keyboard.Type`, coordinate clicks, `SendKeys`): it lands in whatever window has focus, not the app. Full rules: `verify-phase.md §3b`.
-
-## E. OpenCode Docker on Windows — host bridge
-
-> **FALLBACK ONLY (since 2026-08-20).** OpenCode's primary deployment is native WSL — the same distro as Claude Code, using the §B ladder like any other WSL process (`docs/OpenCode-Deployment-Guide.md`). This section applies only when the Docker container is deliberately in use (`TF_OPENCODE_DOCKER=1`); nothing here concerns a WSL OpenCode session.
-
-An OpenCode Linux container is not WSL: `/proc/version` does not expose Windows interop, and `cmd.exe` cannot be installed into it. The framework Dockerfile uses the .NET 10 SDK and deliberately installs no MAUI workloads. Standard .NET projects build and test in the container. For a Windows MAUI Blazor Desktop target, use the image's `winrun` wrapper, which sends the command over SSH to the Windows host and starts it in `TF_WINDOWS_APP_PATH`. Mobile/iOS/Mac Catalyst builds and runtime tests belong on a native Mac.
+| Blazor | headless Playwright (system Chromium) | WSL |
+| MAUI Windows | FlaUI or Appium-Windows | Windows side |
+| MAUI Android | Appium (`uiautomator2`) against the emulator or a device | Windows host runs the SDK and emulator; WSL drives it over HTTP |
+| MAUI iOS | Appium (`xcuitest`) against the simulator | the LAN Mac; WSL drives it over HTTP |
+| MAUI Mac Catalyst | Appium (`mac2`) against the running app | the LAN Mac; WSL drives it over HTTP |
 
-- Probe: `test -x /usr/local/bin/winrun && test -n "$TF_WINDOWS_SSH_USER" && test -n "$TF_WINDOWS_APP_PATH"` followed by `winrun "dotnet --info"`. The first checks configuration; the second proves the SSH bridge actually works. The Docker launcher may mount `/root/.ssh` read-only; `winrun` copies the key to a writable `/tmp` file with mode `0600` and maintains host trust in `/tmp`, so do not attempt to `chmod` the mounted key.
-- Build: `winrun "dotnet build -c Release"`.
-- Do not report missing `cmd.exe` as a code blocker when the bridge probe succeeds.
-- Do not check for or install `maui-tizen` in the container. The image intentionally contains no MAUI workloads.
-- If the bridge is absent or SSH fails, report the exact setup failure and mark only the Windows head `STATIC-ONLY`; continue Linux-compatible builds and Appium HTTP verification.
-- For private feeds, use the Docker-specific user config mounted at `/root/.nuget/NuGet/NuGet.Config`. A Windows `%AppData%\NuGet\NuGet.Config` may contain DPAPI-encrypted credentials that cannot be decrypted in Linux. Never put the Docker config in the repository.
+Appium is the native analogue of Playwright: the same WebDriver protocol, a screenshot and an element tree with positions and text, so the checks are identical and only the driver differs.
 
-## Recording the result (all platforms)
+- The endpoints are in `core-config.yaml → runtimeVerification.appium`, per app and opt-in. WSL needs only the HTTP URL.
+- Android runs on the Windows host: the verifier boots the emulator and Appium itself through the registry `launch` command (through `winrun` if needed), then drives `http://localhost:4723`. Booting it yourself, never asking the owner, is the same rule as the build.
+- iOS and Mac Catalyst need the LAN Mac up: `curl http://<mac>:4723/status` first; unreachable means that head is `⚠ STATIC-ONLY`, a session dependency like a stopped database, never a faked `Verified`.
+- One-time host setup (Android SDK, AVD and Appium on Windows; Xcode, Appium, `xcuitest` and `mac2` on the Mac; the `.wslconfig` mirrored-networking switch): `WORKFLOW.html §0b`.
+- Bind the driver to the app under test by identity, the PID you launched and its top-level window or the package or bundle id on mobile, and interact element by element through `AutomationId`. Never global keyboard or mouse injection, which lands in whichever window has focus. Full rules: `verify-phase.md §3b`.
 
-After a successful build, note **which platform + invocation** produced it (e.g. "built on macOS via `dotnet build` (rung #1)", "built on WSL via `cmd.exe /c` (rung #4)") in the PROJECT-STATUS verification-log row or Remarks — so a reader on a different machine knows what to expect. The §B "what NEVER goes into Known blockers" list applies to WSL specifically; on §A/§C the equivalent non-blocker is "workload not yet installed — run `dotnet workload install`", which is a one-time user setup step, not a project defect.
+**Dependent services are yours to start.** When the feature needs more than one process (a database, an API, a web front end, a model endpoint), a service that is down is something you start, not a blocker you hand to the owner. Read each dependent project's configuration for its port and URL, then start each one yourself in dependency order (data stores and endpoints first, then APIs, then the front end). Only when a service on another machine does not answer does that head degrade to `⚠ STATIC-ONLY`, and the report says which host and which probe.

package/.tfcore/templates/v4custom/build-subagent-prompt.md

@@ -0,0 +1,17 @@
+<!-- build-subagent-prompt.md — the prompt build-phase gives every cluster sub-agent.
+     Filled by tf-build-list.sh --prompts: {App} {Cluster} {Builder} {Section} {Rows} {Mockups} {Checklist}.
+     Library agents (trblazeui, techierag) never read .tfcore/ tasks, so the two standing rules
+     reach them only through this text. Keep it short; the rows carry the detail. -->
+You are building cluster {Cluster} of {App} ({Section}) as the {Builder}. Implement exactly these rows, nothing else:
+
+{Rows}
+
+Read first: `docs/{App}-Coding-Standards.md` (and the standard files it names under `.tfcore/standards/`), `docs/{App}-Architecture.md` for module boundaries, and the mockups: {Mockups}. Build a UI row to match its mockup control for control, with the same `data-testid` anchors. Use only controls the UI library's reference lists (`.trblazeui/TrBlazeUI-AI-Reference.md`, `.techierag/TechieRag-AI-Reference.md`); a control or feature the library lacks goes as an entry into `docs/{App}-<Library>-Feedback.md` and the row becomes `Blocked`, never a workaround.
+
+Two standing rules:
+1. Git is manual. Never run `git` or `gh` for any purpose. Record your row ids in the checklist Remarks (`[REQ-…]`), not in commits.
+2. Smoke it yourself before you return: `bash .tfcore/utils/tf-build.sh` must PASS, then boot the app and open every screen you touched with headless Playwright (or the native driver the ladder names); the data must show and nothing may overlap; use a test user from `docs/{App}-UsageGuide.md`, never an invented one. A green compiler is not a smoke.
+
+Unit tests for every FN, RAG and NFR row go under `tests/unit/`. Run-generated files go under `tests/.artifacts/`, never at the repository root.
+
+When done, set each row in `{Checklist}` to `Implemented` (smoke passed) or `PARTIAL` / `FAIL` with a one-line Remark, and return: rows implemented, files changed, tests added, library gaps logged, and the exact smoke you ran.

package/.tfcore/templates/v4custom/html-render-shell.md

@@ -23,7 +23,7 @@ Each rendered HTML file is:
 - A **single self-contained `.html` file**, no external CSS, no external JS except the two `<script>` tags below (mermaid + svg-pan-zoom from jsdelivr CDN).
 - Sibling to the source MD (same filename, `.html` extension).
 - **Light + dark theme with a persisted toggle** (§2 + §3 + §7). Default is chosen by **time of day** on first open — light between 07:00 and 19:00 local, softened dark otherwise — then the user's explicit toggle choice (saved in `localStorage` as `tf-theme`) wins on every later visit. Light is a **warm off-white** (never harsh bright white); dark is a softened near-black. Monospace for code/pre, sans for body.
-- **Only human-readable docs are ever rendered to HTML** (BRD, Architecture, UsageGuide, DevGuide, PROJECT-STATUS). The **checklists are AI-agent working documents — never render them to HTML** (they are read by agents in markdown; an HTML mirror just wastes tokens and drifts). If you are about to emit a `*-Checklist.html`, STOP — that is banned.
+- **Only human-readable docs are ever rendered to HTML** (BRD, Architecture, UsageGuide, DevGuide, ProductGuide, PROJECT-STATUS, a Decision Request, a feedback file). **An agent working document is never rendered to HTML** — it is read in markdown, and an HTML mirror wastes tokens and drifts from the source. Two are banned by name, and `tf-render-html.py` refuses both with exit 2: the **requirements checklist** `{App}-Checklist.md`, and the **miss log** `{App}-Misses.md`. If you are about to emit a `*-Checklist.html` or a `*-Misses.html`, STOP — that is banned. The test for anything else: if the only reader is an agent, it stays markdown.
 - Working anchor links from any auto-generated or hand-written TOC to its target heading.
 - Copy buttons on every **code** `<pre>` — but NOT on `pre.mermaid` (a button injected there corrupts the diagram source mermaid reads → "Syntax error"; mermaid blocks get copy/export from their own diagram toolbar).
 - Mermaid toolbar on every rendered diagram.

package/.tfcore/templates/v4custom/metrics-report-template.md

@@ -99,7 +99,7 @@ pooled deliberately.*
 | Tokens per `Verified` REQ | {n} |
 | Commit cadence | {n} commits/active day over {n} days |
 
-**Cost in USD is not reported here.** Claude Code transcripts and Codex usage
+**Cost in USD is not reported here.** Claude Code transcripts and usage
 payloads carry token counts but no per-message dollar cost, and this framework runs
 on subscriptions where marginal per-token cost is not the real unit. Multiplying
 tokens by a rate card would be an estimate presented as a measurement, so the row
@@ -192,7 +192,7 @@ than the worst. Read it as a question to investigate, never as a ranking to rout
 | Unattributable (`none` — no usable token window) | {n} | — |
 
 **Dollars.** {Either: "$X per miss — MEASURED, from {n} OpenCode records." Or:
-"No measured dollars. Claude Code and Codex carry `cost_usd: null` permanently —
+"No measured dollars. Claude Code carries `cost_usd: null` permanently —
 no cost source exists on either, and pricing tokens from a rate card here would be
 an estimate presented as a measurement. Tokens are the honest figure."}
 

package/.tfcore/user-guide.md

@@ -235,29 +235,6 @@ TechieFlow integrates with OpenCode via a project-level `opencode.jsonc`/`openco
     }
     ```
 
-### Codex (CLI & Web)
-
-TechieFlow's full build/runtime workflow is supported in local Codex CLI, IDE,
-and desktop sessions. The scaffold/update scripts install `.codex/` project
-config, custom agents, hooks and rules plus reusable workflows under
-`.agents/skills/`. Trust the repository and review `/hooks` after installation
-or a hook update.
-
-Codex loads the root `AGENTS.md`. Invoke `$techieflow-build`,
-`$techieflow-verify`, `$techieflow-refresh-status`, or name the skill in plain
-language. Literal Claude/OpenCode `*command` and slash names are vocabulary
-aliases, not Codex command registrations.
-
-For an unattended local run:
-
-```bash
-bash .tfcore/utils/tf-goal.sh --harness codex . "<goal>"
-```
-
-Codex cloud cannot automatically reach local `winrun`, Appium hosts, NuGet
-credentials, or already-running services. It is static-only unless equivalent
-infrastructure is explicitly provisioned.
-
 ## Special Agents
 
 There are two TechieFlow agents — in the future they'll be consolidated into a single Flow-Master.

package/.tfcore/utils/tf-brd-status.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""tf-brd-status.py — rewrite the BRD's "Development status" table from the checklist.
+
+    bash .tfcore/utils/tf-brd-status.sh <App> [--no-render] [--phase N]
+
+On a Large project the pair is the phase being worked: --phase N, else appPhase in
+.tfcore/core-config.yaml (phase 1 is docs/<App>-BRD.md and -Checklist.md, phase n is
+docs/<App>-Pn-BRD.md and docs/<App>-Pn-Checklist.md).
+
+Reads docs/<App>-Checklist.md: every REQ row of the Requirements Status table, and
+the "## Page: …" section its detail entry sits under, which names the screen.
+Writes one row per screen into the "Development status" section of
+docs/<App>-BRD.md (Screen | Requirements | Verified | Open | Status) with a
+"Snapshot as of <today>" line, inserting the section before "Context diagram"
+(or at the end) when the BRD has none. Touches nothing else in the BRD. Then
+re-renders docs/<App>-BRD.html through tf-render-html.sh unless --no-render.
+
+Status per screen: Done (every row terminal), Planned (no row started),
+Partial (some terminal, some open), In progress (started, none terminal).
+Terminal = Verified, Done (pre-existing), N/A. Blocked is counted as open.
+
+Python 3 standard library only. Exit 0 written or nothing to do, 2 could not run.
+"""
+import datetime
+import os
+import re
+import subprocess
+import sys
+
+TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+NOT_STARTED = {"not started"}
+
+
+def die(msg):
+    print(f"tf-brd-status: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def read(path):
+    with open(path, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def norm(raw):
+    s = raw.strip().strip("`* ").lower()
+    return re.sub(r"\s*\(.*$", "", s).strip()
+
+
+def screen_name(heading):
+    h = heading.strip()
+    h = re.sub(r"^(?:\d+[.)]\s*)?(?:page|screen)\s*:\s*", "", h, flags=re.I)
+    h = re.sub(r"\s*\(`?/[^)]*`?\)\s*$", "", h)  # trailing (`/route`)
+    return h.strip("` ").strip() or heading.strip()
+
+
+def parse_checklist(text):
+    rows = []
+    for line in text.splitlines():
+        if re.match(r"^\s*\|\s*`?REQ-", line):
+            cells = [c.strip() for c in line.strip().strip("|").split("|")]
+            if len(cells) >= 3:
+                rows.append((cells[0].strip("`* "), norm(cells[2])))
+    screen_of = {}
+    current = "Other"
+    for line in text.splitlines():
+        m = re.match(r"^##\s+(.+)$", line)
+        if m:
+            current = screen_name(m.group(1))
+            continue
+        for a in re.findall(r"<a id=['\"]d-(req-[a-z]+-\d+)['\"]", line, flags=re.I):
+            screen_of[a.upper()] = current
+    return rows, screen_of
+
+
+def table(rows, screen_of):
+    per = {}
+    order = []
+    for rid, status in rows:
+        s = screen_of.get(rid.upper(), "Unmapped")
+        if s not in per:
+            per[s] = {"n": 0, "v": 0, "ns": 0}
+            order.append(s)
+        per[s]["n"] += 1
+        per[s]["v"] += 1 if status in TERMINAL else 0
+        per[s]["ns"] += 1 if status in NOT_STARTED else 0
+    out = ["| Screen | Requirements | Verified | Open | Status |", "|---|---|---|---|---|"]
+    for s in order:
+        d = per[s]
+        open_n = d["n"] - d["v"]
+        if open_n == 0:
+            st = "Done"
+        elif d["ns"] == d["n"]:
+            st = "Planned"
+        elif d["v"] > 0:
+            st = "Partial"
+        else:
+            st = "In progress"
+        out.append(f"| {s} | {d['n']} | {d['v']} | {open_n} | {st} |")
+    return "\n".join(out), len(order)
+
+
+def write_section(brd_text, app, body):
+    """Replace the body of the Development status section, or insert the section."""
+    sec = re.compile(r"(?ms)^(##\s+(?:\d+[.)]\s*)?Development status[^\n]*\n)(.*?)(?=^## |\Z)")
+    m = sec.search(brd_text)
+    if m:
+        return brd_text[:m.start()] + m.group(1) + "\n" + body + "\n\n" + brd_text[m.end():], "updated"
+    heading = "## Development status\n"
+    ctx = re.search(r"(?m)^##\s+(?:\d+[.)]\s*)?Context diagram", brd_text)
+    if ctx:
+        return brd_text[:ctx.start()] + heading + "\n" + body + "\n\n" + brd_text[ctx.start():], "inserted"
+    return brd_text.rstrip("\n") + "\n\n" + heading + "\n" + body + "\n", "appended"
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    app = argv[1]
+    render = "--no-render" not in argv
+    root = os.getcwd()
+    phase = None
+    if "--phase" in argv:
+        i = argv.index("--phase")
+        if i + 1 >= len(argv) or not argv[i + 1].isdigit() or int(argv[i + 1]) < 1:
+            die("--phase needs a number from 1 upwards")
+        phase = int(argv[i + 1])
+    if phase is None:
+        cfg = os.path.join(root, ".tfcore", "core-config.yaml")
+        m = re.search(r"(?m)^appPhase:\s*(\d+)", read(cfg)) if os.path.isfile(cfg) else None
+        phase = int(m.group(1)) if m else 1
+    pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+    cl_rel, brd_rel = f"docs/{pfx}Checklist.md", f"docs/{pfx}BRD.md"
+    cl = os.path.join(root, cl_rel)
+    brd = os.path.join(root, brd_rel)
+    if not os.path.isfile(cl):
+        print(f"tf-brd-status: {cl_rel} does not exist yet; nothing to do")
+        return 0
+    if not os.path.isfile(brd):
+        die(f"{brd_rel} does not exist")
+    rows, screen_of = parse_checklist(read(cl))
+    if not rows:
+        die(f"{cl_rel} has no REQ rows in its Requirements Status table")
+    tbl, screens = table(rows, screen_of)
+    today = datetime.date.today().isoformat()
+    body = (
+        "Written by the status gate after every build, verify and handoff; not by hand.\n\n"
+        f"**Snapshot as of {today}.** Live per-requirement status: `PROJECT-STATUS.md` and the "
+        f"Requirements Status table in `{cl_rel}`.\n\n" + tbl
+    )
+    text = read(brd)
+    new_text, how = write_section(text, app, body)
+    with open(brd, "w", encoding="utf-8") as f:
+        f.write(new_text)
+    verified = sum(1 for _, s in rows if s in TERMINAL)
+    print(f"tf-brd-status: {brd_rel} Development status {how}: {screens} screens, {verified} of {len(rows)} requirements verified")
+    if render:
+        script = os.path.join(root, ".tfcore", "utils", "tf-render-html.sh")
+        if os.path.isfile(script):
+            rc = subprocess.call(["bash", script, os.path.relpath(brd, root)], cwd=root)
+            if rc != 0:
+                print(f"tf-brd-status: the HTML render exited {rc}; run bash .tfcore/utils/tf-render-html.sh {brd_rel} by hand", file=sys.stderr)
+                return 1
+            print(f"tf-brd-status: rendered {brd_rel[:-3]}.html")
+        else:
+            print("tf-brd-status: .tfcore/utils/tf-render-html.sh not found at its literal path; HTML not rendered", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except Exception as e:
+        die(str(e))

package/.tfcore/utils/tf-brd-status.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# tf-brd-status.sh — rewrite the BRD's "Development status" table from the checklist.
+#
+#   bash .tfcore/utils/tf-brd-status.sh MyApp            # writes the table, re-renders the BRD HTML
+#   bash .tfcore/utils/tf-brd-status.sh MyApp --no-render
+#
+# One row per screen (Screen | Requirements | Verified | Open | Status) with a
+# "Snapshot as of <today>" line, computed from docs/MyApp-Checklist.md. Nothing
+# else in the BRD is touched. Step 5 of _status-update-gate.md; the Stop hook
+# refuses to end a turn while the BRD is older than the checklist.
+#
+# Thin wrapper over tf-brd-status.py. Python 3 standard library only.
+set -uo pipefail
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-brd-status: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-brd-status.py" "$@"