@techierathore/techieflow 1.0.3 → 1.1.0

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

@@ -58,3 +58,9 @@ If `/trblazeui` or `/techierag` is missing: run `dotnet build` (the NuGet target
 Under Claude Code, if `/flow-master *render-workflow-docs <App>` returns "Unknown command", use `/TechieFlow:agents:flow-master *render-workflow-docs <App>` instead. (Under OpenCode `/flow-master` is the registered agent name — there is no fuller form to fall back to.)
 
 After the agent is loaded, every TechieFlow-native agent (analyst, architect, flow-master, verifier) accepts `*command args` style invocations. trblazeui and techierag are free-form personas — normally `flow-master *build-phase <App>` calls them as sub-agents, but you can also drive them directly with prompts like `Implement REQ-UI-* from docs/<App>-Checklist.md to match the mockups in docs/mockups/.`
+
+How to talk to me:
+1. Rate your confidence. Tag any claim you are not sure of: [Certain] with evidence, [Likely] a strong inference, [Guessing] filling a gap. If most of a reply is guessing, say so in the first line.
+2. Uncomfortable answer first. If there is something I will not want to hear, it is the first sentence, not the third paragraph.
+3. No warm-up. No "great question", no "there are several ways to look at this", no restating my question. Start with the most useful sentence.
+4. Disagree with structure: "I disagree because [reason]. I would do [alternative]. The risk in your approach is [downside]." Then do what I decide.

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

@@ -25,9 +25,11 @@ rule: mockup-links
      Size and requirement cap: Small up to 10 screens, one role, 50 requirements; Medium up to 20 screens,
      100 requirements; Large is split into phases, each phase its own BRD. Every routed page is a screen;
      dialogs, tabs and panels are regions of their page and are listed under it.
-     Large project: one BRD per phase, phase 1 in docs/{App}-BRD.md, phase n in docs/{App}-Pn-BRD.md; the
-     header gains a row "| Phase | n of m |", Size is the phase's own size (Small or Medium), and BRD-N
-     runs on from the previous phase's last id. The phase plan is docs/{App}-Phases.md.
+     Large project: one BRD per phase, phase 1 in docs/{App}-BRD.md from this template, phase n in
+     docs/{App}-Pn-BRD.md from app-phase-brd-tmpl.md, which carries only that phase's screens and
+     requirements; this file keeps the whole application's scope, users, non-functionals, constraints
+     and risks. The header gains a row "| Phase | n of m |", Size is the phase's own size (Small or
+     Medium), and BRD-N runs on from the previous phase's last id. The phase plan is docs/{App}-Phases.md.
      Mermaid: quote every label (A["Order (v2)"]); never use `end` as a node id. -->
 
 # {App} — Business Requirements

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

@@ -0,0 +1,65 @@
+<!-- tf-schema
+doc: brief
+file: docs/{App}-Brief.md
+header: App, Date
+section: What it is | required | max 150
+section: Who it is for | required | max 150
+section: Must do | required
+section: Out of scope | required | max 150
+section: Open questions | optional | max 150
+rule: brief-must-do
+rule: no-glossary
+target-lines: 60
+max-lines: 120
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     The brief is the input to day-1: `*day1-greenfield` and `*day1-brownfield` read it
+     and turn it into the Architecture, the BRD and the mockups. Its whole job is to be
+     ONE PAGE the owner can read and correct in two minutes, before anything expensive
+     is built on it.
+
+     It replaced a 221-line inherited template (2026-09-08) whose twelve sections —
+     executive summary, problem statement, proposed solution, goals and metrics, KPIs,
+     post-MVP vision, expansion opportunities — produced a document nobody read and
+     nothing checked. What the framework's own review says a brief is: "a one-page
+     brief: product, users, must-do, out of scope". That is what this template holds.
+
+     Each "Must do" line becomes one or more BRD items at day-1, so write them as
+     things the product does, one per line, numbered. Not features to build: outcomes
+     a user gets. If a line needs a paragraph to explain it, it is two lines.
+
+     "Open questions" is where a decision the owner has not taken goes, so day-1 asks
+     rather than assumes. An empty brief with three honest open questions is worth more
+     than a full one built on guesses. -->
+
+# {App} — Brief
+
+| | |
+|---|---|
+| App | {App} |
+| Date | {YYYY-MM-DD} |
+
+## What it is
+
+{Two or three sentences, at most 150 words. What the product does, in the words you
+would use to a person who has never heard of it. No technology.}
+
+## Who it is for
+
+{Who uses it and what they are trying to get done. Name each role. At most 150 words.}
+
+## Must do
+
+1. {One thing the product does, as an outcome a user gets.}
+2. {Another.}
+3. {Another.}
+
+## Out of scope
+
+{What this is deliberately not doing, so day-1 does not build it. At most 150 words.}
+
+## Open questions
+
+{A decision not yet taken, one per line, so day-1 asks instead of assuming. Delete the
+section when there are none.}

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

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

package/.tfcore/templates/v4custom/app-library-feedback-tmpl.md

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

package/.tfcore/templates/v4custom/app-phase-brd-tmpl.md

@@ -0,0 +1,94 @@
+<!-- tf-schema
+doc: brd
+file: docs/{App}-P{n}-BRD.md
+header: App, Kind, Size, Status, Date
+section: Summary | required | max 200
+section: Screens and flow | required
+section: Requirements | required
+section: Non-functional requirements | optional
+section: Development status | required
+section: Where the rest lives | required
+budget: S 6000 8000 | M 10000 15000 | L 10000 15000
+rule: brd-ledger
+rule: screens-table
+rule: mockup-links
+rule: phase-pointer
+-->
+<!-- Authoring notes (agent only; never visible text).
+     A phase BRD is phase 2 onward of a Large project. Phase 1 is docs/{App}-BRD.md, written from
+     app-brd-tmpl.md, and it holds everything that belongs to the whole application: Scope, Users and
+     roles, the Non-functional requirements that apply everywhere, the Context diagram, Constraints and
+     assumptions, and Risks. A phase BRD never repeats them: two copies of the same fact become two
+     answers the day one of them is amended (TfLens TF-024, 2026-09-11). It holds this phase's screens,
+     this phase's requirements, and a "Where the rest lives" table that links back to phase 1.
+     "Non-functional requirements" is here only when this phase adds its own, for example a speed
+     budget on one of its screens; its ids run on like every other item.
+     The header carries "| Phase | n of m |" (the checker refuses the file without it). Size is the
+     phase's own size, Small or Medium. BRD-N runs on from the previous phase's last id and is never
+     renumbered. Sections and order are fixed by the schema above; the order is the whole-project
+     BRD's, with the sections a phase does not carry left out. -->
+
+# {App} — Business Requirements — Phase {n}: {Phase name}
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small or Medium (this phase on its own) |
+| Phase | {n} of {m} |
+| Status | Draft, Approved |
+| Date | {YYYY-MM-DD} |
+
+## 1. Summary
+
+{What this phase adds, for whom, and why it comes at this point. At most 200 words.}
+
+## 2. Screens and flow
+
+One row per routed page this phase adds; dialogs are written exactly as in the phase-1 BRD.
+
+| Screen | Route | Role | Mockup | Fields |
+|---|---|---|---|---|
+| {Screen name} | `/route` | {Role} | [mockup](mockups/{screen-slug}.html) | {field, field, field} |
+
+**Primary journey:**
+1. {The user opens … and …}
+
+## 3. Requirements
+
+One item per thing the verifier will test, grouped under a `###` heading per screen. Same rules as the phase-1 BRD: an acceptance line is at most 30 words, target 20, and holds one behaviour.
+
+### {Screen name}
+
+{One plain sentence: what this screen does, for whom.}
+
+- **BRD-{N}** — {Title}. *Screen:* {Screen name} · *Mockup:* [mockup](mockups/{screen-slug}.html)
+  - *Acceptance:* When {actor} {does what} on {screen}, then {a result a browser robot can observe}.
+
+## 4. Non-functional requirements
+
+Only what this phase adds. The ones that apply to the whole application are in the phase-1 BRD.
+
+| Id | Area | Requirement | Measure |
+|---|---|---|---|
+| BRD-{N} | Performance | {…} | perf-budget: p95 load <= 2000ms @ concurrency 1 |
+
+## 5. Development status
+
+Written by the status gate after every build, verify and handoff; not by hand.
+
+**Snapshot as of {YYYY-MM-DD}.** Live per-requirement status: `PROJECT-STATUS.md` and the Requirements Status table in `docs/{App}-P{n}-Checklist.md`.
+
+| Screen | Requirements | Verified | Open | Status |
+|---|---|---|---|---|
+| {Screen} | {n} | {n} | {n} | Planned, In progress, Partial, Done |
+
+## 6. Where the rest lives
+
+| What | Where |
+|---|---|
+| Scope, users and roles, the context diagram | [phase 1 BRD]({App}-BRD.md) |
+| Non-functional requirements for the whole application | [phase 1 BRD]({App}-BRD.md) |
+| Constraints, assumptions and risks | [phase 1 BRD]({App}-BRD.md) |
+| Every phase, its screens and its BRD range | [{App}-Phases.md]({App}-Phases.md) |
+| This phase's work list | [{App}-P{n}-Checklist.md]({App}-P{n}-Checklist.md) |

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

@@ -0,0 +1,60 @@
+<!-- tf-schema
+doc: uidesign
+file: docs/{App}-P{n}-UIDesign.md
+header: App, Kind, Size
+section: Screens | required
+section: Where the rest lives | required
+entries: Screens | Screen:
+per-entry: 250 400
+rule: entry-mockup
+rule: entry-regions-table
+rule: entry-fields-table
+rule: entry-states
+rule: mockup-links
+rule: phase-pointer
+-->
+<!-- Authoring notes (agent only; never visible text).
+     A phase UIDesign is phase 2 onward of a Large project. Phase 1 is docs/{App}-UIDesign.md, written
+     from app-uidesign-tmpl.md, and it holds everything the whole application shares: the UI library
+     and theme in its header, the Design system, the one Click-through flow across every phase (the
+     mockup folder is one set), and the Branding guide. A phase UIDesign never repeats them — two
+     copies become two answers the day one changes (owner, 2026-09-11, after TfLens TF-024). It holds
+     one `### Screen: Name (/route)` per screen in this phase's row of docs/{App}-Phases.md, written
+     exactly as in phase 1, and a "Where the rest lives" table linking back to the phase-1 UIDesign.
+     A new screen that changes the flow is added to phase 1's Click-through flow, not drawn here.
+     The header carries "| Phase | n of m |" (the checker refuses the file without it). -->
+
+# {App} — UI Design — Phase {n}: {Phase name}
+
+| | |
+|---|---|
+| App | {App} |
+| Kind | app or library |
+| Size | Small or Medium (this phase on its own) |
+| Phase | {n} of {m} |
+
+## Screens
+
+### Screen: {Name} (`/route`)
+
+**Mockup:** [mockups/{screen-slug}.html](mockups/{screen-slug}.html) · **Roles:** {who reaches it} · **BRD:** BRD-{N}
+
+| Region | Control | Shows or binds |
+|---|---|---|
+| {Main list} | {control} | {…} |
+
+| Field | Type | Required | Validation |
+|---|---|---|---|
+| {Title} | text | yes | {1 to 120 characters} |
+
+**Dialogs opened here:** {Dialog name: fields …; or "none"}
+
+**States:** empty: {…} · loading: {…} · error: {…}
+
+## Where the rest lives
+
+| What | Where |
+|---|---|
+| UI library, theme and the design system | [phase 1 UI design]({App}-UIDesign.md) |
+| The click-through flow across every phase | [phase 1 UI design]({App}-UIDesign.md) |
+| This phase's requirements | [{App}-P{n}-BRD.md]({App}-P{n}-BRD.md) |

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

@@ -21,8 +21,10 @@ rule: mockup-links
      already shows. Use only controls that exist in the UI library's catalogue; a missing control goes
      to the library feedback file, not into a workaround. The set of screens must equal the BRD's
      Screens and flow table. For a library, this document is optional.
-     Large project: one UIDesign per phase (docs/{App}-UIDesign.md, docs/{App}-P2-UIDesign.md, …) with a
-     header row "| Phase | n of m |"; its screens are exactly that phase's row in docs/{App}-Phases.md.
+     Large project: one UIDesign per phase with a header row "| Phase | n of m |"; its screens are exactly
+     that phase's row in docs/{App}-Phases.md. Phase 1 is this template and keeps what every phase shares
+     (library, theme, design system, the one click-through flow, branding); phase n is
+     docs/{App}-Pn-UIDesign.md from app-phase-uidesign-tmpl.md, screens only, linking back here.
      The mockup folder stays one click-through set across every phase. -->
 
 # {App} — UI Design

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

@@ -1,5 +1,5 @@
 <!-- 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}.
+     Filled by tf-build-list.sh --prompts: {App} {Cluster} {Builder} {Section} {Rows} {Mockups} {Checklist} {UsageGuide}.
      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:
@@ -10,7 +10,7 @@ Read first: `docs/{App}-Coding-Standards.md` (and the standard files it names un
 
 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.
+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 `{UsageGuide}`, 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.
 

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). **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. Three are banned by name, and `tf-render-html.py` refuses all three with exit 2: the **requirements checklist** `{App}-Checklist.md`, the **miss log** `{App}-Misses.md`, and an **upstream feedback file** `{App}-{Upstream}-Feedback.md`. If you are about to emit a `*-Checklist.html`, a `*-Misses.html` or a `*-Feedback.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.
@@ -216,6 +216,8 @@ The trailing `<a class="anchor-link">` lets users grab a deep link by hovering.
 
 **Preserve hand-written anchors.** Some source docs place explicit non-heading anchors like `<a id="d-req-ui-001"></a>` directly above a list item, and a table cell links to them with `[view](#d-req-ui-001)`. This is how the Requirements Status table's **Details** column jumps to each REQ's detail entry. Emit every such `<a id="...">` verbatim in the HTML and keep the matching `href="#..."` link intact — do NOT drop them, renumber them, or run them through the heading-slug function. Dropping them silently breaks the Details links (the exact class of bug the user keeps reporting).
 
+**Links to sibling documents open their HTML (2026-09-29).** A relative link to a `.md` file is written with `.html` when that page's HTML already sits beside the rendered page, or is written by the same render run; its `#anchor` is kept. Otherwise it stays `.md`: a markdown file with no rendered twin (an agent document, the checklist, the miss log, a feedback file) is never pointed at an HTML page that does not exist. Web links, absolute paths and `#anchor`-only links are never changed. So render a split guide's index together with its pages, or after them, and its links open the rendered pages.
+
 ---
 
 ## 5. Mermaid block conversion
@@ -489,7 +491,7 @@ The inline `<div class="toc-inline">` mirrors the MD Table of Contents. When the
 
 - [ ] CSS palette matches §2 verbatim (themed `:root` light + `html[data-theme="dark"]` overrides; no hardcoded hex colors reintroduced in the body rules)
 - [ ] Page skeleton matches §3 — flash-free theme-init `<script>` in `<head>` + the `#themeToggle` button present; §7 JS wires the toggle and Mermaid's theme follows `data-theme`
-- [ ] This is a human-readable doc (BRD / Architecture / UsageGuide / DevGuide / PROJECT-STATUS) — NOT a checklist (checklists are never rendered to HTML)
+- [ ] This is a human-readable doc (BRD / Architecture / UsageGuide / DevGuide / PROJECT-STATUS) — NOT a checklist, miss log or feedback file (those are never rendered to HTML)
 - [ ] Every H2/H3/H4 has `id="{slug}"` matching §1 algorithm
 - [ ] Every TOC entry (MD inline AND HTML inline/sidebar) uses the same slug
 - [ ] Every mermaid fence is wrapped in `<div class="diagram">` with the §5 toolbar