@techierathore/techieflow 1.0.4 → 1.1.1

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
@@ -92,8 +94,9 @@ One item per thing the verifier will test. Each names its screen, links the mock
 | BRD-{N} | Performance | {…} | perf-budget: p95 load <= 2000ms @ concurrency 1 |
 | BRD-{N} | Security | {…} | {…} |
 | BRD-{N} | Logging | {from the Stack answer set} | {…} |
+| BRD-{N} | Zoom (a desktop head drawn in a web view) | Cmd/Ctrl+=, - and 0 zoom 50% to 300% in 10% steps; the level is kept across restarts | zoom-check: keys · zoom-check: kept |
 
-The `perf-budget:` measure is machine-read by the verifier, in exactly this form: `perf-budget: <p50|p95|max> <ttfb|load> <= <N>ms [@ concurrency <N>]`. Write one only where the owner stated a number.
+The `perf-budget:` measure is machine-read by the verifier, in exactly this form: `perf-budget: <p50|p95|max> <ttfb|load> <= <N>ms [@ concurrency <N>]`. Write one only where the owner stated a number. The zoom row is for an app whose desktop head draws its screens in a web view (the stack's coding standards say how), and is deleted otherwise; its two checklist rows end `zoom-check: keys` and `zoom-check: kept`, which the verifier grades with `tf-verify-zoom.sh`.
 
 ## 7. Development status
 

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

@@ -45,6 +45,8 @@ rule: checklist-rows
 | REQ-UI-001 | {short name} | Not Started | 0% | — | [view](#d-req-ui-001) |
 | REQ-FN-001 | {short name} | Not Started | 0% | — | [view](#d-req-fn-001) |
 | REQ-NFR-001 | {short name} | Not Started | 0% | — | [view](#d-req-nfr-001) |
+| REQ-NFR-002 | Zoom with the OS keys (web-view desktop head only) | Not Started | 0% | — | [view](#d-req-nfr-002) |
+| REQ-NFR-003 | Zoom level kept (web-view desktop head only) | Not Started | 0% | — | [view](#d-req-nfr-003) |
 
 **Status values:** `Not Started` · `In Progress` · `Implemented` · `Verified` · `Done (pre-existing)` · `Needs re-verify` · `PARTIAL` · `FAIL` · `Blocked` · `Owner-UAT` · `N/A`. `Owner-UAT` marks a row only the owner can close, by following the UsageGuide test plan; the verifier cannot reach it from this machine.
 
@@ -63,3 +65,12 @@ rule: checklist-rows
 <a id="d-req-nfr-001"></a>
 - **REQ-NFR-001** — {the requirement}. *BRD:* BRD-{N}
   - *Acceptance:* When {the measurement is taken}, then {the value within its limit}; perf-budget: p95 load <= 2000ms @ concurrency 1
+
+<!-- A desktop head drawn in a web view carries these two rows (the stack's coding standards say how it zooms); delete them otherwise. -->
+<a id="d-req-nfr-002"></a>
+- **REQ-NFR-002** — Zoom with the OS keys. *BRD:* BRD-{N}
+  - *Acceptance:* When a user presses Cmd+= (Mac) or Ctrl+= (Windows) three times on {first screen}, then the page is drawn at 130%; zoom-check: keys
+
+<a id="d-req-nfr-003"></a>
+- **REQ-NFR-003** — The zoom level is kept. *BRD:* BRD-{N}
+  - *Acceptance:* When a user zooms to 130% on {first screen} and restarts the app, then it opens at 130%; zoom-check: kept

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-phases-tmpl.md

@@ -13,7 +13,8 @@ rule: phases-table
      phases and are never reused, so the ranges never overlap. An item added to an earlier phase after a
      later phase exists takes the next free id and the row gets a second range: "BRD-1 to BRD-73, BRD-111 to BRD-118". Every screen sits in exactly one phase;
      the screens of a phase are exactly the "### Screen:" entries of that phase's UIDesign.
-     Status is planned, building or done. The phase being worked is appPhase in core-config.yaml
+     Status is planned, building, done or kept-whole. kept-whole is only for a phase finished before the
+     size cap that the owner chose to keep as one document: its cap and word maximum then WARN, not FAIL. The phase being worked is appPhase in core-config.yaml
      (bash .tfcore/utils/tf-day1-files.sh {App} --phase N); handoff moves it on.
      tf-doc-check.sh --app {App} refuses a screen in two phases, an id in two phases, a BRD id outside
      its phase's range, and a phase row without its BRD file. -->

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.
@@ -48,6 +48,8 @@ The same slug function MUST produce the `id="..."` on each heading AND the `href
 
 The MD inline TOC and the HTML sidebar TOC use the SAME slug. The heading `id` uses the SAME slug. No exceptions.
 
+**A second id, GitHub's.** A markdown table of contents written by hand links to the id GitHub gives the heading: digits kept, punctuation dropped, spaces to hyphens, a repeat suffixed `-1`, `-2` (`### 3.7 Group Service (GroupSvc)` → `#37-group-service-groupsvc`). When that id differs from the slug above, the heading also carries `<a id="{github-id}"></a>`, so those links land too (AppManager TF-029). A heading with no slug (H1, H5, H6) carries the GitHub id as its own.
+
 ---
 
 ## 2. CSS (inline at top of `<head>`, verbatim)
@@ -216,6 +218,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 +493,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-appium.mjs

@@ -0,0 +1,179 @@
+// tf-appium.mjs — the few WebDriver calls a native head needs, over Node's own fetch (no package).
+// Used by tf-verify-native.mjs; an acceptance test of a native head may import it too:
+//   import { openSession, parseSource } from '<repo>/.tfcore/utils/tf-appium.mjs';
+//   const s = await openSession(process.env.APPIUM_URL, { bundleId: process.env.TF_BUNDLE_ID, appPath: process.env.TF_APP_PATH });
+//   await s.click(await s.find('accessibility id', 'save'));  …  await s.close();
+// Every control is found inside the app under test by its AutomationId (the accessibility
+// identifier); nothing here types or clicks at a screen position. Type into a field with
+// `await s.type(el, 'text')`, the one way a Blazor Hybrid form on a Mac took the text.
+
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+
+const W3C_EL = 'element-6066-11e4-a52e-4f735466cecf';
+
+async function call(base, method, path, body) {
+  const r = await fetch(base + path, {
+    method, headers: { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal: AbortSignal.timeout(300000),
+  });
+  const j = await r.json().catch(() => ({ value: { message: `HTTP ${r.status}, not JSON` } }));
+  if (!r.ok || (j.value && j.value.error)) throw new Error((j.value && j.value.message || `HTTP ${r.status}`).split('\n')[0]);
+  return j.value;
+}
+
+// A session on the Mac Catalyst app (mac2), by its .app path when known: by bundle id alone mac2
+// answered "could not be found" for a build outside /Applications that macOS had not registered
+// (Lekhak TF-003; seen again 2026-10-07). skipAppKill: the app is tf-verify-boot.sh's to stop, so
+// ending the session leaves it running for the next check.
+export async function openSession(url, { bundleId, appPath = '', automationName = 'Mac2', platformName = 'mac', extra = {} } = {}) {
+  const base = url.replace(/\/$/, '');
+  const which = appPath ? { 'appium:appPath': appPath } : { 'appium:bundleId': bundleId };
+  const v = await call(base, 'POST', '/session', { capabilities: { alwaysMatch: {
+    platformName, 'appium:automationName': automationName, ...which,
+    'appium:skipAppKill': true, 'appium:newCommandTimeout': 300, ...extra } } });
+  const sp = `/session/${v.sessionId}`;
+  const s = {
+    id: v.sessionId,
+    call: (m, p, b) => call(base, m, sp + p, b),
+    source: () => s.call('GET', '/source'),
+    find: async (using, value, from = null) => Object.values(await s.call('POST', from ? `/element/${from}/element` : '/element', { using, value }))[0],
+    findAll: async (using, value, from = null) => (await s.call('POST', from ? `/element/${from}/elements` : '/elements', { using, value })).map((e) => e[W3C_EL] || Object.values(e)[0]),
+    click: (el) => s.call('POST', `/element/${el}/click`, {}),
+    // Typing into a field. A Blazor Hybrid form on a Mac kept its @bind empty or half filled when the
+    // value was set through Accessibility, through mac2's "set value", or by key events posted to the
+    // process ("The text must have valid value", Lekhak TF-026). What reached it: a click on the field,
+    // then W3C key actions, a key down and up per character.
+    type: async (el, text) => {
+      await s.click(el);
+      const actions = [...String(text)].flatMap((c) => [{ type: 'keyDown', value: c }, { type: 'keyUp', value: c }]);
+      await s.call('POST', '/actions', { actions: [{ type: 'key', id: 'keyboard', actions }] });
+      await s.call('DELETE', '/actions').catch(() => {});
+    },
+    shot: (el) => s.call('GET', el ? `/element/${el}/screenshot` : '/screenshot'),
+    close: () => call(base, 'DELETE', sp).catch(() => {}),
+  };
+  return s;
+}
+
+// What the app shows first, for tf-verify-boot.sh: BOOTED only when a mac2 session opens and the app
+// has a window of its own that is not a system dialog (Lekhak TF-026: BOOTED was printed while no
+// session could open, and once while the app's only window was macOS's "quit unexpectedly while
+// reopening windows" dialog). That dialog is answered Don't Reopen, which only skips restoring old
+// windows, and the answer is reported. The window alone is saved to `shot`. Never throws.
+export async function firstScreen(url, { bundleId = '', appPath = '', shot = '', wait = 30000 } = {}) {
+  let s;
+  try { s = await openSession(url, { bundleId, appPath }); }
+  catch (e) { return { ok: false, stage: 'session', reason: e.message }; }
+  const sleep = (ms) => new Promise((ok) => setTimeout(ok, ms));
+  const DIALOG = new Set(['Dialog', 'Sheet', 'SystemDialog']);
+  const LEAF = new Set(['Button', 'TextField', 'SecureTextField', 'TextView', 'Image', 'CheckBox', 'Switch', 'Slider', 'PopUpButton',
+    'ComboBox', 'Link', 'RadioButton', 'SegmentedControl', 'Stepper', 'DatePicker', 'ProgressIndicator', 'Cell']);
+  const out = { ok: false, stage: 'window', dismissed: '' };
+  try {
+    for (const t0 = Date.now(); Date.now() - t0 < wait; await sleep(500)) {
+      const nodes = parseSource(await s.source());
+      const label = (n) => n.title || n.label || '';
+      const reopen = nodes.find((n) => n.type === 'Button' && /^don.t reopen$/i.test(label(n)));
+      if (reopen && !out.dismissed) {
+        const el = await s.find('-ios predicate string', `elementType == 9 AND (title BEGINSWITH[c] 'Don' OR label BEGINSWITH[c] 'Don')`).catch(() => null);
+        if (el) { await s.click(el); out.dismissed = 'macOS asked to reopen the windows of a run that did not quit; answered Don\'t Reopen'; continue; }
+      }
+      const dialog = nodes.find((n) => DIALOG.has(n.type)) || reopen;
+      const win = nodes.find((n) => n.type === 'Window' && n.w >= 200 && n.h >= 150 && !descendants(nodes, n.i).some((d) => DIALOG.has(d.type)));
+      // drawn: text or a control in the window's content, as tf-verify-native counts it: what sits
+      // directly on the window (its title, its three buttons) and the bars are not content. A web view
+      // took about eight seconds to draw its first page; until then the window is blank.
+      const chrome = (n) => n.parent === win.i || ['TabBar', 'Toolbar', 'NavigationBar', 'MenuBar', 'Menu'].some((t) => {
+        for (let p = n.i; p >= 0; p = nodes[p].parent) if (nodes[p].type === t) return true;
+        return false; });
+      const drawn = win && descendants(nodes, win.i).some((n) => !chrome(n) && (n.type === 'StaticText' ? !!label(n).trim() || !!(n.value || '').trim() : LEAF.has(n.type)));
+      if (win && !dialog && drawn) {
+        out.ok = true; out.window = { w: win.w, h: win.h };
+        if (shot) {
+          await sleep(500);   // the first frame of a web view fades in
+          // the window alone (TF-027: mac2's element shot is a crop of the display, banners included)
+          if (appPath && windowShot(appPid(appPath), shot)) out.shot = shot;
+          else {
+            const el = await s.find('-ios predicate string', 'elementType == 4').catch(() => null);
+            if (el) { const { writeFileSync } = await import('node:fs'); writeFileSync(shot, Buffer.from(await s.shot(el), 'base64')); out.shot = shot; }
+          }
+        }
+        return out;
+      }
+      out.reason = dialog ? `the app shows a dialog, not its first screen: "${(label(dialog) || dialog.type).slice(0, 80)}"`
+        : win ? 'the app\'s window is on view but blank (no text, no control)' : 'the app has no window of its own on view';
+    }
+    out.reason = `${out.reason || 'no window'} after ${Math.round(wait / 1000)} s`;
+    return out;
+  } catch (e) { return { ...out, reason: `Appium: ${e.message}` }; }
+  finally { await s.close(); }
+}
+
+// The page source (XCUIElementType… XML) as a flat list of nodes with their parent index, so a
+// caller can walk a subtree without an XML package.
+export function parseSource(xml) {
+  const un = (s) => s.replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&#10;/g, '\n').replace(/&amp;/g, '&');
+  const nodes = []; const stack = [];
+  const re = /<(\/?)(XCUIElementType\w+)([^>]*?)(\/?)>/g; let m;
+  while ((m = re.exec(xml))) {
+    if (m[1]) { stack.pop(); continue; }
+    const a = {}; let am; const are = /(\w+)="([^"]*)"/g;
+    while ((am = are.exec(m[3]))) a[am[1]] = un(am[2]);
+    const n = { i: nodes.length, type: m[2].replace('XCUIElementType', ''), id: a.identifier || '', label: a.label || '', value: a.value || '',
+      title: a.title || '', x: +a.x || 0, y: +a.y || 0, w: +a.width || 0, h: +a.height || 0, parent: stack.length ? stack[stack.length - 1] : -1, kids: [] };
+    if (n.parent >= 0) nodes[n.parent].kids.push(n.i);
+    nodes.push(n);
+    if (!m[4]) stack.push(n.i);
+  }
+  return nodes;
+}
+
+export function descendants(nodes, i) {
+  const out = []; const todo = [...nodes[i].kids];
+  while (todo.length) { const k = todo.shift(); out.push(nodes[k]); todo.push(...nodes[k].kids); }
+  return out;
+}
+
+// --- the app's own window, through macOS rather than mac2 (Lekhak TF-027) ---------------------------
+// mac2 cannot resize a window, and its element screenshot is a crop of the display, so a notification
+// banner over the window landed in every picture. macOS itself does both: System Events resizes the
+// window (the app's minimum size still holds, and the size it really took is returned), and
+// screencapture -l takes the window alone by its window number.
+const run = (cmd, args) => { try { return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20000 }).trim(); } catch { return ''; } };
+
+// the pid of the app running from this .app (a mac2 session starts it again under a new pid)
+export function appPid(appPath) {
+  const out = run('pgrep', ['-f', `${appPath.replace(/\/$/, '')}/Contents/MacOS/`]);
+  return parseInt(out.split('\n')[0], 10) || 0;
+}
+
+// { id, x, y, w, h } of the app's largest normal window on view, or null
+export function macWindow(pid) {
+  if (!pid) return null;
+  const js = `ObjC.import('CoreGraphics');
+    const l = ObjC.deepUnwrap(ObjC.castRefToObject($.CGWindowListCopyWindowInfo($.kCGWindowListOptionOnScreenOnly | $.kCGWindowListExcludeDesktopElements, 0)));
+    JSON.stringify(l.filter((w) => w.kCGWindowOwnerPID == ${pid} && w.kCGWindowLayer == 0)
+      .map((w) => ({ id: w.kCGWindowNumber, x: w.kCGWindowBounds.X, y: w.kCGWindowBounds.Y, w: w.kCGWindowBounds.Width, h: w.kCGWindowBounds.Height })))`;
+  try { return JSON.parse(run('osascript', ['-l', 'JavaScript', '-e', js]) || '[]').sort((a, b) => b.w * b.h - a.w * a.h)[0] || null; }
+  catch { return null; }
+}
+
+// sets the front window's size; returns the size it took ({ w, h }), or null when macOS refused
+// (the terminal needs Accessibility, as mac2 does)
+export function resizeWindow(pid, w, h) {
+  if (!pid) return null;
+  const tell = `tell application "System Events" to tell (first process whose unix id is ${pid})`;
+  run('osascript', ['-e', `${tell} to set size of window 1 to {${w}, ${h}}`]);
+  const got = run('osascript', ['-e', `${tell} to get size of window 1`]).split(/,\s*/).map(Number);
+  return got.length === 2 && got.every((n) => n > 0) ? { w: got[0], h: got[1] } : null;
+}
+
+// the window alone, by its window number; true when the file was written
+export function windowShot(pid, file) {
+  const win = macWindow(pid);
+  if (!win) return false;
+  run('screencapture', ['-x', '-o', '-l', String(win.id), file]);
+  try { return statSync(file).size > 0; } catch { return false; }
+}

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 }));