@techierathore/techieflow 1.0.4 → 1.1.0

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, 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.
+- **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

package/.tfcore/utils/tf-assets-browser.mjs

@@ -0,0 +1,96 @@
+// TechieFlow — the documents tf-assets.sh grades, fetched through a signed-in browser
+// (AppManager TF-011, 2026-09-14). Driven by tf-assets.sh when --login-path is given; run that.
+//
+// tf-assets reads what a page DECLARES and fetches each asset. It fetched the page with a bare HTTP
+// request, and an app whose sign-in lives in the page's own connection answers 401 to every bare
+// request: "declared 0, graded 0" on every path. Here each path is opened in a browser tab that
+// signed in through the page's form (tf-login.mjs), judged by what it draws, and its document — the
+// head with every stylesheet and script it declares — handed back for grading. The assets themselves
+// are still fetched one by one by tf-assets.sh, so a 404 stays observable.
+//
+//   node tf-assets-browser.mjs --base URL --paths "/a,/b" --login-path /login --user U --password P
+//        [--storage-state file] [--cookie 'k=v'] --json-out <file>
+// Writes {"login": {...}, "pages": {"/a": {"status": 401, "reached": "…", "signed_out": false,
+// "url": "...", "html": "<!doctype…"}}}. Exit 0 always except a usage error (3).
+
+import { chromium } from 'playwright';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { signIn, reach } from './tf-login.mjs';
+
+const argv = process.argv.slice(2);
+const arg = (name, dflt = null) => { const i = argv.indexOf(name); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : dflt; };
+const BASE = (arg('--base') || '').replace(/\/$/, '');
+const PATHS = (arg('--paths', '/') || '').split(',').map((p) => p.trim()).filter(Boolean).map((p) => (p.startsWith('/') ? p : '/' + p));
+const OUT = arg('--json-out');
+const COOKIE = arg('--cookie'); const STORAGE = arg('--storage-state');
+const LOGIN_OPTS = { base: BASE, loginPath: arg('--login-path'), user: arg('--user'), password: arg('--password'), settle: 1500, renderWait: 5000 };
+// Lekhak TF-006: a desktop head, attached over its DevTools port. Its pages and assets are served by
+// the embedded browser itself, so no request from outside can fetch them: each path is opened by
+// pushState, and every asset the document declares is fetched from inside the page, its status and
+// size handed back beside the document ("fetched").
+const CDP = arg('--cdp') || '';
+if ((!BASE && !CDP) || !OUT) { console.error('usage: tf-assets-browser.mjs --base URL|--cdp URL --paths /a,/b [--login-path /login --user U --password P] --json-out file'); process.exit(3); }
+
+if (CDP) {
+  let b, page;
+  try {
+    b = await chromium.connectOverCDP(CDP, { timeout: 15000 });
+    const c = b.contexts()[0]; page = c && c.pages()[0];
+  } catch (e) { page = null; }
+  mkdirSync(dirname(resolve(OUT)), { recursive: true });
+  if (!page) { writeFileSync(resolve(OUT), JSON.stringify({ unreachable: true, cdp: CDP })); process.exit(0); }
+  const pages = {};
+  let origin = '';
+  for (const p of PATHS) {
+    let status = 200, error = '', html = '', url = '', fetched = {};
+    try {
+      await page.evaluate((r) => { history.pushState({}, '', r); window.dispatchEvent(new PopStateEvent('popstate', { state: {} })); }, p);
+      await page.waitForTimeout(LOGIN_OPTS.settle);
+      url = page.url(); origin = origin || new URL(url).origin;
+      html = await page.content();
+      fetched = await page.evaluate(async () => {
+        const out = {};
+        const urls = [...document.querySelectorAll('link[href]')].filter((l) => /stylesheet|preload|modulepreload|icon/i.test(l.rel)).map((l) => l.href)
+          .concat([...document.querySelectorAll('script[src]')].map((s) => s.src));
+        for (const u of [...new Set(urls)]) {
+          if (!/^https?:/i.test(u)) continue;
+          try { const r = await fetch(u, { cache: 'no-store' }); const buf = await r.arrayBuffer(); out[u] = { status: r.status, bytes: buf.byteLength }; }
+          catch (e) { out[u] = { status: null, bytes: 0, error: String(e.message || e).slice(0, 120) }; }
+        }
+        return out;
+      });
+    } catch (e) { status = 0; error = e.message.split('\n')[0]; }
+    pages[p] = { status, document_status: status, url, reached: 'opened inside the attached app (pushState)', signed_out: false, error, html, fetched };
+  }
+  await b.close().catch(() => {});   // disconnects; the app keeps running
+  writeFileSync(resolve(OUT), JSON.stringify({ login: null, cdp: CDP, origin, pages }));
+  process.exit(0);
+}
+
+const browser = await chromium.launch();
+const ctxOpts = { ignoreHTTPSErrors: true };
+if (STORAGE && existsSync(STORAGE)) ctxOpts.storageState = STORAGE;
+const ctx = await browser.newContext(ctxOpts);
+if (COOKIE) {
+  const u = new URL(BASE);
+  for (const pair of COOKIE.split(';')) {
+    const [name, ...v] = pair.trim().split('=');
+    if (name && v.length) await ctx.addCookies([{ name: name.trim(), value: v.join('='), domain: u.hostname, path: '/' }]);
+  }
+}
+const page = await ctx.newPage();
+const login = await signIn(page, LOGIN_OPTS);
+const pages = {};
+for (const p of PATHS) {
+  const nav = await reach(page, LOGIN_OPTS, p);
+  let html = '';
+  if (nav.status && nav.status < 400 && !nav.signedOut) {
+    try { html = await page.content(); } catch (e) { html = ''; }
+  }
+  pages[p] = { status: nav.status, document_status: nav.document_status ?? nav.status, url: nav.url || '',
+               reached: nav.reached || '', signed_out: !!nav.signedOut, error: nav.error || '', html };
+}
+await browser.close();
+mkdirSync(dirname(resolve(OUT)), { recursive: true });
+writeFileSync(resolve(OUT), JSON.stringify({ login, pages }));

package/.tfcore/utils/tf-assets.sh

@@ -3,6 +3,13 @@
 #
 #   bash .tfcore/utils/tf-assets.sh --base http://localhost:5099 \
 #        --paths "/,/login,/export" --cookie 'AuthCookie=<value>'
+#   An app whose sign-in lives in the page and sets no cookie (AppManager TF-011):
+#        --login-path /login --user <u> --password <p>   (or --storage-state <file>)
+#   opens each path in a browser that signed in through the form and grades the
+#   document it drew; `pages[].reached` says how a 401 page was reached.
+#   A desktop head (Lekhak TF-006): --cdp http://<host>:9223 in place of --base attaches to the app,
+#   opens each path by pushState and fetches every declared asset from inside the page, because
+#   nothing outside the embedded browser can reach the files it serves.
 #
 # WHAT IT ASKS, and it is the only question no other gate asks:
 #
@@ -50,8 +57,10 @@
 
 set -uo pipefail
 
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 BASE=""; PATHS="/"; TIMEOUT=20; LABEL=""; OUT=""; EXTERNAL=0; MINBYTES=1
 HDRS=""   # newline-separated "K: V" pairs (--header, repeatable; --cookie is sugar)
+COOKIE=""; LOGIN_PATH=""; USER=""; PASS=""; STORAGE=""; CDP=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --base)             BASE="${2:-}"; shift 2 ;;
@@ -62,18 +71,44 @@ while [[ $# -gt 0 ]]; do
     --min-bytes)        MINBYTES="${2:-}"; shift 2 ;;
     --include-external) EXTERNAL=1; shift ;;
     --header)           HDRS="${HDRS}${2:-}"$'\n'; shift 2 ;;
-    --cookie)           HDRS="${HDRS}Cookie: ${2:-}"$'\n'; shift 2 ;;
-    -h|--help)          sed -n '2,48p' "$0"; exit 0 ;;
+    --cookie)           HDRS="${HDRS}Cookie: ${2:-}"$'\n'; COOKIE="${2:-}"; shift 2 ;;
+    # a sign-in the page keeps for itself sets no cookie (AppManager TF-011): the pages are then
+    # opened in a browser that signed in through the form, the same options tf-verify-screens takes
+    --login-path)       LOGIN_PATH="${2:-}"; shift 2 ;;
+    --user)             USER="${2:-}"; shift 2 ;;
+    --password)         PASS="${2:-}"; shift 2 ;;
+    --storage-state)    STORAGE="${2:-}"; shift 2 ;;
+    --cdp)              CDP="${2:-}"; shift 2 ;;   # a desktop head over its DevTools port (Lekhak TF-006)
+    -h|--help)          sed -n '2,56p' "$0"; exit 0 ;;
     *) echo "unknown argument: $1" >&2; exit 3 ;;
   esac
 done
 
-[[ -n "$BASE" ]] || { printf '%s\n' \
-  "usage: tf-assets.sh --base URL [--paths /,/login] [--cookie 'k=v'] [--include-external]" \
+[[ -n "$BASE" || -n "$CDP" ]] || { printf '%s\n' \
+  "usage: tf-assets.sh --base URL|--cdp URL [--paths /,/login] [--cookie 'k=v'] [--include-external]" \
+  "                    [--login-path /login --user U --password P] [--storage-state file]" \
   "                    [--json-out tests/.artifacts/assets/REQ-NFR-015.json]" >&2; exit 3; }
 command -v python3 >/dev/null 2>&1 || { echo '{"status":"no-python3"}'; exit 3; }
 
-TF_BASE="$BASE" TF_PATHS="$PATHS" TF_TIMEOUT="$TIMEOUT" TF_LABEL="$LABEL" TF_OUT="$OUT" \
+# ---- the documents, through a signed-in browser when a sign-in is given (TF-011) --------------
+DOCS=""
+if [[ -n "$CDP" ]]; then
+  if ! command -v node >/dev/null 2>&1 || ! node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null; then
+    echo '{"status":"no-playwright","note":"--cdp needs node and playwright (verify-phase §1 installs the verify environment)"}'; exit 3
+  fi
+  DOCS="$(mktemp "${TMPDIR:-/tmp}/tmp.XXXXXXXXXX")" && mv "$DOCS" "$DOCS.json" && DOCS="$DOCS.json"
+  node "$HERE/tf-assets-browser.mjs" --cdp "$CDP" --paths "$PATHS" --json-out "$DOCS" >&2 || { echo '{"status":"browser-failed"}'; rm -f "$DOCS"; exit 3; }
+elif [[ -n "$LOGIN_PATH" || -n "$STORAGE" ]]; then
+  if ! command -v node >/dev/null 2>&1 || ! node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null; then
+    echo '{"status":"no-playwright","note":"--login-path needs node and playwright (verify-phase §1 installs the verify environment)"}'; exit 3
+  fi
+  DOCS="$(mktemp "${TMPDIR:-/tmp}/tmp.XXXXXXXXXX")" && mv "$DOCS" "$DOCS.json" && DOCS="$DOCS.json"   # only GNU mktemp takes a suffix option
+  node "$HERE/tf-assets-browser.mjs" --base "$BASE" --paths "$PATHS" --json-out "$DOCS" \
+       ${LOGIN_PATH:+--login-path "$LOGIN_PATH"} ${USER:+--user "$USER"} ${PASS:+--password "$PASS"} \
+       ${STORAGE:+--storage-state "$STORAGE"} ${COOKIE:+--cookie "$COOKIE"} >&2 || { echo '{"status":"browser-failed"}'; rm -f "$DOCS"; exit 3; }
+fi
+
+TF_CDP="$CDP" TF_BASE="$BASE" TF_PATHS="$PATHS" TF_TIMEOUT="$TIMEOUT" TF_LABEL="$LABEL" TF_OUT="$OUT" TF_DOCS="$DOCS" \
 TF_HEADERS="$HDRS" TF_EXTERNAL="$EXTERNAL" TF_MINBYTES="$MINBYTES" python3 - <<'PY'
 import html.parser, json, os, ssl, sys, urllib.error, urllib.request
 from urllib.parse import urljoin, urlsplit
@@ -85,6 +120,34 @@ LABEL    = os.environ.get("TF_LABEL") or None
 OUT      = os.environ.get("TF_OUT") or None
 EXTERNAL = os.environ.get("TF_EXTERNAL") == "1"
 MINBYTES = int(os.environ.get("TF_MINBYTES") or 1)
+# the documents a signed-in browser fetched, by path (TF-011); empty when none was asked for
+DOCS = {}
+LOGIN = None
+if os.environ.get("TF_DOCS"):
+    try:
+        _d = json.load(open(os.environ["TF_DOCS"], encoding="utf-8"))
+        DOCS, LOGIN = _d.get("pages", {}), _d.get("login")
+    except Exception:
+        DOCS = {}
+    try:
+        os.remove(os.environ["TF_DOCS"])
+    except Exception:
+        pass
+# an attached desktop head (TF-006): the assets were fetched inside the page, by URL
+CDP = os.environ.get("TF_CDP") or ""
+FETCHED = {}
+if CDP:
+    try:
+        _d
+    except NameError:
+        _d = {}
+    if _d.get("unreachable") or not DOCS:
+        print(json.dumps({"status": "unreachable", "base": CDP, "label": LABEL,
+                          "note": "the desktop head's DevTools port did not answer — a `build` gate problem, not an assets result"}, indent=2))
+        raise SystemExit(2)
+    BASE = (_d.get("origin") or "").rstrip("/")
+    for _pg in DOCS.values():
+        FETCHED.update(_pg.get("fetched") or {})
 
 HEADERS = []
 for line in (os.environ.get("TF_HEADERS") or "").splitlines():
@@ -145,6 +208,11 @@ class AssetParser(html.parser.HTMLParser):
 def fetch(url, want_body=True):
     """Return (status, nbytes, error). Never raises — a transport failure is a
     finding, not a crash, and the caller needs every path's result."""
+    if CDP:
+        f = FETCHED.get(url)
+        if f is None:
+            return None, 0, "not fetched inside the attached app", b""
+        return f.get("status"), f.get("bytes", 0), f.get("error"), b""
     req = urllib.request.Request(url, headers={"User-Agent": UA})
     for k, v in HEADERS:
         req.add_header(k, v)
@@ -193,7 +261,7 @@ def fetch_page(url):
 
 
 # --- reachability first: an unreachable base is a `build` problem, not an assets one
-probe_status, _, probe_err = fetch_page(BASE + "/")
+probe_status, _, probe_err = (200, b"", None) if CDP else fetch_page(BASE + "/")
 if probe_status is None:
     print(json.dumps({"status": "unreachable", "base": BASE, "error": probe_err,
                       "label": LABEL, "note": "app not reachable — this is a `build` "
@@ -207,7 +275,23 @@ graded_assets = 0
 
 for p in PATHS:
     page_url = BASE + (p if p.startswith("/") else "/" + p)
-    status, body, err = fetch_page(page_url)
+    extra = {}
+    doc = DOCS.get(p if p.startswith("/") else "/" + p)
+    if doc is not None:
+        # the document as the signed-in browser drew it (TF-011). A page that stayed signed out is
+        # an auth wall: nothing of it is graded, like a redirect to the sign-in page.
+        if doc.get("signed_out"):
+            redirected += 1
+            pages.append({"path": p, "status": doc.get("document_status"), "assets": [], "declared": 0,
+                          "graded": 0, "failed": 0, "redirected": True, "auth_wall": True, "url": doc.get("url")})
+            continue
+        status, body, err = (doc.get("status") or None), (doc.get("html") or "").encode("utf-8"), (doc.get("error") or None)
+        if status and status < 400 and body:
+            status = 200
+        if doc.get("reached"):
+            extra = {"document_status": doc.get("document_status"), "reached": doc["reached"]}
+    else:
+        status, body, err = fetch_page(page_url)
     if status is None:
         pages.append({"path": p, "status": None, "error": err, "assets": [],
                       "declared": 0, "graded": 0, "failed": 0})
@@ -269,16 +353,16 @@ for p in PATHS:
 
     pages.append({"path": p, "status": status, "declared": len(rows),
                   "graded": sum(1 for r in rows if r.get("graded")),
-                  "failed": failed, "assets": rows})
+                  "failed": failed, "assets": rows, **extra})
 
 # Every path turned away = nothing was graded. Reporting "0 findings" there would be
 # a PASS on a screen the harness never saw — the same false green tf-perf.sh's exit 4
 # exists to prevent, and the same shape as TF-011's ungradeable-looks-clean failure.
 if PATHS and redirected == len(PATHS):
-    out = {"status": "redirected", "base": BASE, "label": LABEL, "pages": pages,
-           "findings": [], "note": "every path answered 3xx — nothing was graded. "
-           "Present a session with --cookie / --header and re-run. Grade the REQ "
-           "ASSETS-UNMEASURED (auth wall); never record this as a pass."}
+    out = {"status": "redirected", "base": BASE, "label": LABEL, "pages": pages, "login": LOGIN,
+           "findings": [], "note": "every path answered 3xx or stayed signed out — nothing was graded. "
+           "Present a session with --cookie / --header, or --login-path/--user/--password, and re-run. "
+           "Grade the REQ ASSETS-UNMEASURED (auth wall); never record this as a pass."}
     print(json.dumps(out, indent=2))
     if OUT:
         os.makedirs(os.path.dirname(os.path.abspath(OUT)), exist_ok=True)
@@ -294,6 +378,7 @@ out = {
     "findings_n": len(findings),
     "findings": findings,
     "pages": pages,
+    "login": LOGIN,
     "include_external": EXTERNAL,
     # An assets run that graded nothing is UNGRADEABLE, not clean. Said out loud in
     # the payload so a consumer cannot read `findings_n: 0` as coverage.

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

@@ -16,8 +16,9 @@ docs/<App>-BRD.md (Screen | Requirements | Verified | Open | Status) with a
 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.
+Partial (some terminal, some open), In progress (started, none terminal), Not applicable
+(every row N/A). Terminal = Verified, Done (pre-existing). An N/A row is left out of the counts,
+never counted as verified (AppManager TF-018). Blocked is counted as open.
 
 Python 3 standard library only. Exit 0 written or nothing to do, 2 could not run.
 """
@@ -27,7 +28,9 @@ import re
 import subprocess
 import sys
 
-TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+# norm() drops a bracketed tail, so "Done (pre-existing)" arrives as "done" and was counted open (AppManager TF-003)
+TERMINAL = {"verified", "done", "done (pre-existing)"}
+NA = {"n/a"}
 NOT_STARTED = {"not started"}
 
 
@@ -80,6 +83,8 @@ def table(rows, screen_of):
         if s not in per:
             per[s] = {"n": 0, "v": 0, "ns": 0}
             order.append(s)
+        if status in NA:
+            continue
         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
@@ -87,7 +92,9 @@ def table(rows, screen_of):
     for s in order:
         d = per[s]
         open_n = d["n"] - d["v"]
-        if open_n == 0:
+        if d["n"] == 0:
+            st = "Not applicable"
+        elif open_n == 0:
             st = "Done"
         elif d["ns"] == d["n"]:
             st = "Planned"
@@ -153,7 +160,9 @@ def main(argv):
     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")
+    na = sum(1 for _, s in rows if s in NA)
+    print(f"tf-brd-status: {brd_rel} Development status {how}: {screens} screens, {verified} of {len(rows) - na} "
+          f"requirements verified" + (f", {na} not applicable" if na else ""))
     if render:
         script = os.path.join(root, ".tfcore", "utils", "tf-render-html.sh")
         if os.path.isfile(script):