forma-arch 0.3.0 → 0.5.0

package/README.md

@@ -8,6 +8,9 @@ them.
 Forma is the companion to `arbiter`: arbiter governs the process, Forma shows the system and
 guarantees the picture matches reality.
 
+**[▶ Live demo](https://LucaDominici.github.io/forma/)** — forma's own architecture, generated by
+forma from this repo on every push to `main`.
+
 ## Why
 
 A hand-drawn architecture diagram is stale the moment code changes. Forma walks your source for the
@@ -29,10 +32,29 @@ npx forma-arch <command>        # or: npm i -D forma-arch
 | `forma check` | Deterministic drift check — **fails if the model no longer matches the code** |
 | `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`), or `--attach <file>` to inject a governed block into an existing doc |
 | `forma serve` | Open the live explorer at `http://localhost:4173` |
+| `forma verify` | Refresh status from live GitHub issues through your `gh` CLI — the **only** networked command |
+
+**Box text comes from your docs.** `gen` fills each box with the module's docstring (Python `"""…"""`, JS/TS leading block), else the directory `README.md`, else a mapped arc42 section — so the explorer shows meaning, not a list of symbols. On a flat directory of many `foo_*` files it also synthesizes a **component** layer, described from its children's docs (`--no-cluster` to disable; `--cluster-min <n>` = leaves before a container is clustered, default 8; `--group-min <n>` = files sharing a prefix before they become a component, default 3).
+
+**Programme state is curated, not guessed.** Code shows what exists, never how far along it is. Drop a `docs/architecture/c4-status.json` (`--status <path>` to move it) and `gen` decorates nodes by id with `status2`, `completion`, `statusWord`, `current`, `target`, `verify`, `issues` — never `func`, which belongs to the docs. `gen` validates the *form* (ids resolve, fields known, enums and issue numbers well-shaped) and never the prose; `forma check` fails if the overlay decorates a node the model no longer has.
+
+```json
+{ "nodes": { "engine": { "status2": "in-progress", "completion": 60, "statusWord": "v2 in progress",
+  "current": "Live on ACA: RAG + citations. Hardening this week.",
+  "target": "Multi-surface substrate with client-ready output.",
+  "verify": { "source": "ADR-040 on main" }, "issues": ["#534"] } } }
+```
+
+**Curated state, verified against reality.** `forma verify` asks your `gh` CLI for the state of every issue the model references (`--gh-repo owner/repo`, or `meta.ghRepo` in the topology), marks the nodes whose issues are closed as done, and prefixes their `current` with dated evidence. It touches state, never structure, and re-running it never stacks the evidence. It is opt-in and separate on purpose: `gen` and `check` never open a socket. In the served viewer, **RE-VERIFY** re-reads the model without losing your level, layout or mode.
 
-**Box text comes from your docs.** `gen` fills each box with the module's docstring (Python `"""…"""`, JS/TS leading block), else the directory `README.md`, else a mapped arc42 section — so the explorer shows meaning, not a list of symbols. On a flat directory of many `foo_*` files it also synthesizes a **component** layer (`--no-cluster` to disable).
+**One source of truth.** `forma doc --attach docs/architecture/arc42.md` injects the generated diagrams/tables between `<!-- forma:begin -->` / `<!-- forma:end -->` markers in your existing doc; your prose lives outside them, and `forma check` fails if that block drifts. Attached files are recorded in `source.attachedDocs`, so the gate governs **every** doc you attach — not just the model's `docPath`; deleting the markers (or the file) from a registered doc fails the check rather than quietly un-governing it. That registry lives in `c4-model.json`, so **commit the model** — a lost model takes the registry with it. Where a repo lacks docs, `forma gen --enrich` can fill the remaining box holes with an LLM — opt-in, cached, never on the deterministic gate:
 
-**One source of truth.** `forma doc --attach docs/architecture/arc42.md` injects the generated diagrams/tables between `<!-- forma:begin -->` / `<!-- forma:end -->` markers in your existing doc; your prose lives outside them, and `forma check` fails if that block drifts. Where a repo lacks docs, `forma gen --enrich` can fill the remaining box holes with an LLM (opt-in, cached, never on the deterministic gate; `--enricher anthropic|openai|ollama`).
+| `--enricher` | Use it when | Network |
+|---|---|---|
+| `agent` | **An agent is driving forma.** Writes `enrich-plan.json` with the holes; the agent writes the sentences (reading the sources if it wants) and `gen --enrich-apply <file>` applies them with the same cache and provenance. | none |
+| `anthropic` (default) | Headless / CI, with `ANTHROPIC_API_KEY`. | REST |
+| `openai` | Same, with `OPENAI_API_KEY`. | REST |
+| `ollama` | Sensitive repos: a local model, nothing leaves the machine. | localhost |
 
 ## How it fits together
 
@@ -59,9 +81,14 @@ The viewer is a live C4 map, not a static picture:
 
 - **Click any box** to read its explanation — what it does, current state, target, verification source — at *every* level, from context down to a leaf.
 - **Double-click a box** (or its `[+] DRILL`) to descend into it; **BACK**, the breadcrumb, or `ESC` climb back out.
-- **Drag boxes** to lay out the view your way; **RESET LAYOUT** restores the auto-arrangement.
-- **Hover an arrow** to reveal its relationship label.
-- **PRINT / EXPORT** to SVG or PNG for docs and slides.
+- **Drag boxes** to lay out the view your way; **RESET LAYOUT** restores the arrangement (your curated hints if the topology has them, the automatic one otherwise). To keep a layout, drag it, pick **Export layout JSON**, and paste the result under `"layout"` in the topology — `gen` carries it into `meta.layout` and the viewer pins those boxes, auto-arranging everything else clear of them.
+- **Arrow labels** are painted on the diagram while the level stays readable (≤14 arrows) and turn off above that; **LABELS** forces them on or off, and hovering an arrow always reveals its label.
+- **PRINT / EXPORT** to SVG or PNG for docs and slides — exported arrows carry their labels.
+- The breadcrumb names the C4 level you are on (`C4-L1 · CONTEXT` → `C4-L3 · COMPONENTS`) and,
+  when the level carries curated state, tallies it: a dot per status with its count plus mean
+  completion, so a level reads as a programme board and not just a diagram.
+- **Every level shrink-wraps its own content** — a context with four boxes renders zoomed and
+  dense instead of adrift in a fixed canvas.
 
 ## Skins
 

package/bin/forma.mjs

@@ -12,7 +12,7 @@ const LIB = join(HERE, '..', 'lib')
 const cmd = process.argv[2]
 const rest = process.argv.slice(3)
 
-const MAP = { init: 'init.mjs', gen: 'gen.mjs', check: 'check.mjs', doc: 'doc.mjs', serve: 'serve.mjs' }
+const MAP = { init: 'init.mjs', gen: 'gen.mjs', check: 'check.mjs', doc: 'doc.mjs', serve: 'serve.mjs', verify: 'verify.mjs' }
 
 if (cmd === '-v' || cmd === '--version') {
   const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'))
@@ -28,6 +28,7 @@ Usage: forma <command> [--repo <path>]
   check   deterministic drift check — fails if the model no longer matches the code
   doc     project the arc42 scaffold (ARCHITECTURE.scaffold.md) from the model
   serve   open the live explorer at http://localhost:4173
+  verify  refresh status from live GitHub issues via your gh CLI (the only networked command)
 
 The file contract is lib/schema/c4-model.schema.json. Enrichment (curate the topology, write the
 arc42 prose) is model-agnostic — any agent edits the same JSON/Markdown.`)

package/lib/check.mjs

@@ -75,17 +75,39 @@ for (const p of topo.plannedLeaves || []) if (p.sourceMustContain) {
 
 // 6) attach-mode doc-block freshness — if docPath carries forma markers, the region between them
 // must equal a freshly rendered block. Opt-in: no markers → nothing runs. No LLM, no network.
-const docRel = model.source && model.source.docPath
-if (docRel && existsSync(rp(docRel))) {
+// Governs docPath AND every doc registered by `forma doc --attach` (source.attachedDocs): a block
+// injected into a file no gate looks at is the false-green this whole command exists to kill.
+const src = model.source || {}
+const registered = new Set(src.attachedDocs || []) // registry membership PROVES a block was injected
+const governed = [...new Set([src.docPath, ...registered].filter(Boolean))]
+const deregister = 'remove it from source.attachedDocs if the block is gone for good'
+for (const docRel of governed) {
+  if (!existsSync(rp(docRel))) {
+    // docPath may simply never have been attached; a REGISTERED doc that vanished is drift.
+    if (registered.has(docRel)) fail(`DOC BLOCK: ${docRel} is registered in source.attachedDocs but the file is gone — ${deregister}.`)
+    continue
+  }
   const text = readFileSync(rp(docRel), 'utf-8')
   const inner = extractBetween(text)
   if (inner != null) {
     if (norm(inner) !== norm(renderBlock(model, { repo: REPO }))) fail(`DOC BLOCK DRIFT: ${docRel} forma block is stale — run \`forma doc --attach\`.`)
   } else if (text.includes('<!-- forma:begin') || text.includes('<!-- forma:end')) {
     fail(`DOC BLOCK: malformed forma markers in ${docRel} (begin/end mismatch).`)
+  } else if (registered.has(docRel)) {
+    // Both markers deleted: the generated block stopped being governed while its (now frozen)
+    // text keeps shipping to readers. Exactly the false green attachedDocs exists to prevent.
+    fail(`DOC BLOCK: ${docRel} is registered in source.attachedDocs but has no forma markers — re-run \`forma doc --attach\`, or ${deregister}.`)
   }
 }
 
+// 7) the status overlay decorates nodes by id: an id that no longer resolves is drift (the node was
+// renamed or deleted and the curated state was left behind). Form only — never the prose itself.
+if (src.statusPath && existsSync(rp(src.statusPath))) {
+  let ov = null
+  try { ov = JSON.parse(readFileSync(rp(src.statusPath), 'utf-8')) } catch (e) { fail(`status overlay: ${src.statusPath} is not valid JSON: ${(e && e.message) || e}`) }
+  if (ov) for (const id of Object.keys(ov.nodes || {})) if (!byId.has(id)) fail(`status overlay: "${id}" is not a node in the model — ${src.statusPath} is stale.`)
+}
+
 // SOFT: LLM-enriched prose whose inputs changed is only a reminder, never a gate failure (structure
 // is the gate; enrichment freshness is advisory). check never calls the LLM — it recomputes the hash.
 for (const n of model.nodes || []) {

package/lib/doc.mjs

@@ -83,7 +83,18 @@ if (attachIdx > -1) {
   catch { console.error('[forma doc] --attach: malformed forma markers in ' + relative(REPO, target) + ' — fix by hand'); process.exit(1) }
   mkdirSync(join(target, '..'), { recursive: true })
   writeFileSync(target, out)
-  console.log(`[forma doc] spliced generated block into ${relative(REPO, target)} — ${containers.length} container(s); prose outside the markers untouched.`)
+  const rel = relative(REPO, target)
+  console.log(`[forma doc] spliced generated block into ${rel} — ${containers.length} container(s); prose outside the markers untouched.`)
+  // Register the target so `forma check` governs THIS file too, not just source.docPath — an
+  // injected block nobody gates is exactly the false-green forma exists to kill. `gen` carries
+  // the registry forward across regens.
+  const known = m.source.attachedDocs || []
+  if (rel !== m.source.docPath && !known.includes(rel)) {
+    m.source.attachedDocs = [...known, rel].sort()
+    writeFileSync(MODEL, JSON.stringify(m, null, 2) + '\n')
+    console.log(`[forma doc] registered ${rel} in ${relative(REPO, MODEL)} — \`forma check\` now governs its block.`)
+    console.log('[forma doc] commit the model: the registry lives in it, and a lost model un-governs the doc.')
+  }
   process.exit(0)
 }
 writeFileSync(OUT, md)

package/lib/gen.mjs

@@ -8,23 +8,29 @@ import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { containerOf, componentsFor } from './cluster.mjs'
 import { makeDescribeCtx, resolveDescription } from './describe.mjs'
-import { loadCache, mergeCache, enrich } from './enrich.mjs'
+import { loadCache, mergeCache, enrich, agentPlan, applyFills } from './enrich.mjs'
 
 const HERE = dirname(fileURLToPath(import.meta.url))
 const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
 const REPO = arg('--repo', process.cwd())
 const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
 const OUT = arg('--out', join(REPO, 'docs/architecture/c4-model.json'))
-const SCHEMA_VERSION = '1.2.0'
+const SCHEMA_VERSION = '1.3.0'
 const CLUSTER = !process.argv.includes('--no-cluster') // §2: auto-cluster flat containers; --no-cluster to disable
 const ENRICH = process.argv.includes('--enrich')       // §7: opt-in LLM prose for description holes
 const ENRICHER = arg('--enricher', 'anthropic')
 const ENRICH_MODEL = arg('--enrich-model', null)
-const CLUSTER_MIN = 8, GROUP_MIN = 3
+const STATUS = arg('--status', join(REPO, 'docs/architecture/c4-status.json')) // curated programme state, optional
+const STATUS_SET = process.argv.includes('--status')
+const APPLY = arg('--enrich-apply', null)          // prose written by the agent driving forma
 
 const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
 const rp = (p) => join(REPO, p)
 const fail = (m) => { console.error('[gen-c4] FAIL: ' + m); process.exit(1) }
+// §2 thresholds, overridable. Guarded: a non-integer would silently disable clustering
+// (`length >= NaN` is false for every group), so a bad value fails loud instead.
+const posInt = (flag, dflt) => { const v = Number(arg(flag, dflt)); if (!Number.isInteger(v) || v < 1) fail(`${flag}: expected a positive integer, got "${arg(flag, dflt)}"`); return v }
+const CLUSTER_MIN = posInt('--cluster-min', 8), GROUP_MIN = posInt('--group-min', 3)
 
 function walk(spec) {
   const dir = rp(spec.dir)
@@ -114,7 +120,9 @@ for (const n of nodes) {
   if (!n.category) n.category = n.kind === 'leaf' ? (par && par.category) || 'leaf' : n.kind
   if (!n.status2) n.status2 = n.status === 'planned' ? 'planned' : 'done'
   if (n.completion == null) n.completion = n.status === 'planned' ? 0 : 100
-  if (!n.current) { const pth = (n.evidence || []).find((e) => e.type === 'path'); n.current = pth ? `Exists: ${pth.ref}` : (n.tech || '') }
+  // `current` is left EMPTY unless curated (topology or status overlay): the viewer falls back to
+  // `func`, which since §1a carries the module's real documentation. The old "Exists: <path>"
+  // filler restated the evidence path in the one field meant for programme facts.
   if (n.target == null) n.target = ''
 }
 
@@ -123,12 +131,74 @@ for (const n of nodes) {
 const dctx = makeDescribeCtx({ repo: REPO, byId, descriptions: topo.descriptions || {}, docPath: topo.docPath, containerOf })
 for (const n of nodes) { const r = resolveDescription(n, dctx); n.func = r.func; n.descSource = r.descSource }
 
+// §1a-bis) a synthesized component has no doc of its own: before settling for "Groups related
+// files under X", compose its box from its children's docs (first sentence of up to 3, ordered by
+// name — deterministic). descSource stays 'fallback': this is a heuristic, and --enrich may still
+// improve it. Separate pass so it does not depend on components being added after their leaves.
+const firstSentence = (s) => (String(s).match(/^[^.!?]*[.!?]/) || [String(s)])[0].trim()
+for (const n of nodes) {
+  if (n.kind !== 'component' || n.descSource !== 'fallback') continue
+  const kids = nodes.filter((k) => k.parent === n.id && ['curated', 'docstring', 'readme'].includes(k.descSource))
+    .sort((a, b) => (String(a.name) < String(b.name) ? -1 : String(a.name) > String(b.name) ? 1 : 0)).slice(0, 3)
+  const txt = kids.map((k) => firstSentence(k.func)).filter(Boolean).join(' ')
+  if (txt) n.func = txt.length > 200 ? txt.slice(0, 199) + '…' : txt
+}
+
+// §WP-A1) programme-status overlay: the one channel for curated STATE (what is true now, where it
+// must land, what proves it). Code can't know it, so a human/agent writes it in c4-status.json and
+// gen validates only its FORM — ids resolve, fields are known, enums/ranges hold. Never `func`:
+// what a module DOES comes from its docs (§1a), what it's WORTH is programme state.
+const STATUS_FIELDS = new Set(['status2', 'completion', 'statusWord', 'current', 'target', 'verify', 'issues'])
+const STATUS2 = new Set(['done', 'in-progress', 'next', 'planned', 'problem'])
+let statusPath = null
+if (existsSync(STATUS) || STATUS_SET) {
+  if (!existsSync(STATUS)) fail(`--status: file missing: ${STATUS}`)
+  let ov
+  try { ov = JSON.parse(readFileSync(STATUS, 'utf-8')) } catch (e) { fail(`--status: ${STATUS} is not valid JSON: ${(e && e.message) || e}`) }
+  let decorated = 0
+  for (const [id, patch] of Object.entries(ov.nodes || {})) {
+    const target = byId.get(id)
+    if (!target) fail(`status overlay: unknown node id "${id}" — it is not in the model (stale overlay?)`)
+    for (const [k, v] of Object.entries(patch)) {
+      if (k.startsWith('$')) continue // $comment and friends
+      if (!STATUS_FIELDS.has(k)) fail(`status overlay: "${id}" has field "${k}"; allowed: ${[...STATUS_FIELDS].join(', ')}${k === 'func' ? ' (func comes from the docs, not the overlay)' : ''}`)
+      if (k === 'status2' && !STATUS2.has(v)) fail(`status overlay: "${id}" status2 "${v}" — expected one of ${[...STATUS2].join('|')}`)
+      if (k === 'completion' && !(Number.isInteger(v) && v >= 0 && v <= 100)) fail(`status overlay: "${id}" completion must be an integer 0-100, got ${JSON.stringify(v)}`)
+      if (k === 'issues') {
+        if (!Array.isArray(v)) fail(`status overlay: "${id}" issues must be an array`)
+        for (const is of v) if (!/^#?\d+$/.test(String(is))) fail(`status overlay: "${id}" issue ${JSON.stringify(is)} — expected "#123"`)
+      }
+      target[k] = v
+    }
+    decorated++
+  }
+  statusPath = relative(REPO, STATUS)
+  console.log(`[gen-c4] status overlay: ${decorated} node(s) decorated from ${statusPath}`)
+}
+
 // §7) enrichment (prose only, never structure/gate). Cache-merge ALWAYS: preserve prior LLM prose
 // whose inputs are unchanged, so a plain regen doesn't discard it. --enrich additionally fills the
 // remaining holes over the network (best-effort — a failure keeps the deterministic fallback).
 const ectx = { repo: REPO, byId, containerOf }
-mergeCache(nodes, ectx, loadCache(OUT))
-if (ENRICH) {
+mergeCache(nodes, loadCache(OUT))
+// --enrich-apply: prose written by the agent that drives forma (see --enricher agent below).
+// Independent of --enrich, and applied first — an explicit fill outranks anything generated.
+if (APPLY) {
+  if (!existsSync(APPLY)) fail(`--enrich-apply: file missing: ${APPLY}`)
+  let fills
+  try { fills = JSON.parse(readFileSync(APPLY, 'utf-8')).fills } catch (e) { fail(`--enrich-apply: ${APPLY} is not valid JSON: ${(e && e.message) || e}`) }
+  if (!Array.isArray(fills)) fail(`--enrich-apply: ${APPLY} must contain {"fills":[{"id","func"}]}`)
+  try { console.log(`[gen-c4] --enrich-apply: ${applyFills(nodes, ectx, fills)} fill(s) applied`) }
+  catch (e) { fail(String((e && e.message) || e)) }
+}
+if (ENRICH && ENRICHER === 'agent') {
+  // No network: emit the work for the agent already in the session, keep the deterministic model.
+  const plan = agentPlan(nodes, ectx)
+  const planPath = join(dirname(OUT), 'enrich-plan.json')
+  writeFileSync(planPath, JSON.stringify({ entries: plan }, null, 2) + '\n')
+  console.log(`[gen-c4] --enricher agent: ${plan.length} hole(s) → ${relative(REPO, planPath)} — write the prose yourself, then:`)
+  console.log(`[gen-c4]   forma gen --enrich-apply ${relative(REPO, join(dirname(OUT), 'enrich-fill.json'))}`)
+} else if (ENRICH) {
   try { const r = await enrich(nodes, ectx, { provider: ENRICHER, model: ENRICH_MODEL }); console.log(`[gen-c4] --enrich (${ENRICHER}): filled ${r.filled}/${r.holes} description hole(s)`) }
   catch (e) { console.error('[gen-c4] --enrich skipped: ' + String((e && e.message) || e)) }
 }
@@ -173,11 +243,26 @@ const gitOpts = { cwd: REPO, stdio: ['ignore', 'pipe', 'ignore'] }
 try { commit = execSync('git rev-parse HEAD', gitOpts).toString().trim() } catch {}
 try { branch = execSync('git rev-parse --abbrev-ref HEAD', gitOpts).toString().trim() } catch {}
 
+// §1b) carry the attach registry forward from the prior model — `forma doc --attach` writes it
+// there, and without this a plain regen would drop it and un-govern the attached docs.
+// The registry lives ONLY in the generated model, so that model has to be committed (or at least
+// kept) for the gate to keep governing. If a prior model is there but unreadable, say so rather
+// than silently ungoverning every attached doc.
+let attachedDocs = []
+if (existsSync(OUT)) {
+  try { attachedDocs = JSON.parse(readFileSync(OUT, 'utf-8')).source.attachedDocs || [] }
+  catch (e) { console.error(`[gen-c4] WARNING: ${OUT} is unreadable (${(e && e.message) || e}) — any source.attachedDocs registry in it is lost; re-run \`forma doc --attach\` for each attached doc.`) }
+}
+
+// generatedAt is the ONE per-run volatile field (a plain `gen` x2 must diff on nothing else).
+// meta.verifiedAt is reserved for `forma verify` (network, opt-in) — gen never writes it.
 const model = {
   schemaVersion: SCHEMA_VERSION,
   generatedAt: new Date().toISOString(),
-  source: { repo: topo.meta.repo, commit, branch, docPath: topo.docPath, generator: 'gen-c4-model@' + SCHEMA_VERSION },
-  meta: { ...topo.meta, verifiedAt: new Date().toISOString(), verifyMethod: 'code+topology (gh re-verify optional)' },
+  source: { repo: topo.meta.repo, commit, branch, docPath: topo.docPath, generator: 'gen-c4-model@' + SCHEMA_VERSION, ...(attachedDocs.length ? { attachedDocs } : {}), ...(statusPath ? { statusPath } : {}) },
+  // topo.layout (optional curated coordinates, keyed by parent id) rides along verbatim: the
+  // viewer pins those nodes and auto-arranges the rest. `meta` is the model's free-form area.
+  meta: { ...topo.meta, ...(topo.layout ? { layout: topo.layout } : {}), verifyMethod: 'code+topology (gh re-verify optional)' },
   levels: topo.levels,
   nodes,
   edges: topo.edges.map((e) => ({ status: 'current', estatus: e.estatus || 'active', ...e })),

package/lib/init.mjs

@@ -22,13 +22,16 @@ const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g
 
 if (existsSync(OUT) && !FORCE) { console.error(`[forma init] ${relative(REPO, OUT)} already exists — use --force to reseed.`); process.exit(1) }
 
-// 1) detect dominant language by extension count (skipping ignored dirs)
+// 1) detect dominant language by extension count. Skips the SAME dirs the container pass skips
+// (build junk AND data/fixture/doc dirs): counting files that can never become a container is how
+// a repo full of Python fixtures gets detected as a Python repo and then finds no source dir.
 const counts = {}
 ;(function walk(dir, depth) {
   if (depth > 12) return
   let ents; try { ents = readdirSync(dir) } catch { return }
   for (const e of ents) {
     if (IGNORE.has(e) || e.startsWith('.')) continue
+    if (SKIP_DIRS.has(e.toLowerCase()) && !KEEP.has(e.toLowerCase())) continue
     const p = join(dir, e)
     let st; try { st = statSync(p) } catch { continue }
     if (st.isDirectory()) walk(p, depth + 1)
@@ -86,7 +89,7 @@ const skipped = []
 // loose files directly in root → an entry container
 if (hasSrc(root)) { nodes.push({ id: 'app', level: 'container', kind: 'container', parent: sysId, name: 'app', tech: lang, description: 'Entry point / loose top-level sources.' }); leafSources.push({ parent: 'app', dir: relative(REPO, root) || '.', match: matchRe }) }
 
-if (leafSources.length === 0) { console.error('[forma init] found a source root but no directory with source files directly in it. Add leafSources manually.'); process.exit(1) }
+if (leafSources.length === 0) { console.error(`[forma init] detected ${lang} (*.${ext[0]}) as the dominant language, but no directory under ${relative(REPO, root) || '.'}/ holds *.${ext[0]} files directly. Pass --include <dir,...> if the sources live in a skipped dir, or add leafSources manually.`); process.exit(1) }
 
 const topo = {
   meta: { repo: basename(REPO), stack: lang, seededBy: 'forma init' },

package/lib/schema/c4-model.schema.json

@@ -45,6 +45,17 @@
           "type": "string",
           "description": "The arc42 architecture doc this model derives from."
         },
+        "statusPath": {
+          "type": "string",
+          "description": "Repo-relative curated programme-status overlay applied by `forma gen` (c4-status.json). The gate fails if it decorates a node id the model no longer has."
+        },
+        "attachedDocs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Repo-relative docs carrying an injected forma block (written by `forma doc --attach`). The drift gate governs every one of them, not just docPath."
+        },
         "generator": {
           "type": "string"
         }

package/lib/verify.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// forma verify — refresh programme status from LIVE GitHub issues, through the user's `gh` CLI.
+// This is the ONLY command that touches the network, and it is opt-in: `gen` and `check` stay
+// deterministic and offline forever (that is the product). It never touches structure — no nodes,
+// no edges, no func — only the state fields of nodes that reference an issue.
+// Usage: node verify.mjs [--repo <path>] [--model <path>] [--gh-repo <owner/repo>] [--gh-cmd <cmd>]
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+
+const arg = (f, d) => { const i = process.argv.indexOf(f); return i > -1 ? process.argv[i + 1] : d }
+const REPO = arg('--repo', process.cwd())
+const MODEL = arg('--model', join(REPO, 'docs/architecture/c4-model.json'))
+const GH_CMD = arg('--gh-cmd', 'gh') // split on whitespace; the tests point it at a stub
+const LIMIT = arg('--limit', '250')
+const fail = (m) => { console.error('[forma verify] ' + m); process.exit(1) }
+
+if (!existsSync(MODEL)) fail(`model missing: ${MODEL} — run \`forma gen\` first.`)
+const model = JSON.parse(readFileSync(MODEL, 'utf-8'))
+const GH_REPO = arg('--gh-repo', (model.meta && model.meta.ghRepo) || null)
+if (!GH_REPO) fail('no target repo: pass --gh-repo <owner/repo>, or set meta.ghRepo in the topology.')
+
+// Which nodes claim which issue — from issues[] and from verify.issue.
+const num = (v) => { const m = /^#?(\d+)$/.exec(String(v)); return m ? Number(m[1]) : null }
+const refs = new Map()
+for (const n of model.nodes || []) {
+  const claimed = [...(n.issues || []), ...(n.verify && n.verify.issue != null ? [n.verify.issue] : [])]
+  for (const raw of claimed) {
+    const i = num(raw); if (!i) continue
+    if (!refs.has(i)) refs.set(i, [])
+    refs.get(i).push(n)
+  }
+}
+if (!refs.size) { console.log('[forma verify] no issue references in the model — nothing to verify (add issues[] via the status overlay).'); process.exit(0) }
+
+// ONE call for every issue: state for the whole repo, then match locally.
+const parts = String(GH_CMD).split(/\s+/).filter(Boolean)
+let raw
+try {
+  raw = execFileSync(parts[0], [...parts.slice(1), 'issue', 'list', '--repo', GH_REPO, '--state', 'all', '--limit', String(LIMIT), '--json', 'number,state'],
+    { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] })
+} catch (e) {
+  const why = (e && e.code === 'ENOENT') ? `\`${parts[0]}\` not found — install the GitHub CLI or pass --gh-cmd` : String((e && (e.stderr || e.message)) || e).trim()
+  console.error(`[forma verify] ${why}`)
+  fail('model left untouched.')
+}
+let issues
+try { issues = JSON.parse(raw) } catch { fail(`unexpected output from \`${parts[0]}\` (wanted JSON): ${String(raw).slice(0, 160)}`) }
+if (!Array.isArray(issues)) fail('unexpected output: expected a JSON array of {number,state}.')
+
+const ts = new Date().toISOString()
+const seen = new Set()
+let closed = 0, decorated = 0
+for (const it of issues) {
+  const n = Number(it.number); seen.add(n)
+  if (String(it.state || '').toUpperCase() !== 'CLOSED') continue
+  const nodes = refs.get(n); if (!nodes) continue
+  closed++
+  for (const node of nodes) {
+    node.status2 = 'done'; node.completion = 100
+    // The badge shows statusWord when there is one, so a curated "NEXT"/"50%" would survive the
+    // node turning green — a box claiming both at once. Marking done owns the badge too.
+    if (node.statusWord) node.statusWord = '100%'
+    const mark = `(#${n} CLOSED` // re-running must not stack prefixes
+    if (!String(node.current || '').includes(mark)) {
+      node.current = `Closed with evidence ${mark}, gh ${ts}). ${String(node.current || '').trim()}`.trim()
+      decorated++
+    }
+  }
+}
+const unknown = [...refs.keys()].filter((n) => !seen.has(n))
+
+model.meta = model.meta || {}
+model.meta.verifiedAt = ts // the ONE field only verify writes — gen must stay single-volatile (R2)
+model.meta.verifyMethod = 'gh live'
+writeFileSync(MODEL, JSON.stringify(model, null, 2) + '\n')
+console.log(`[forma verify] ${GH_REPO}: ${refs.size} referenced issue(s), ${closed} closed → ${decorated} node(s) marked done`)
+if (unknown.length) console.log(`[forma verify] not returned by gh (closed long ago, wrong repo, or beyond --limit ${LIMIT}): ${unknown.map((n) => '#' + n).join(', ')}`)
+console.log(`[forma verify] fact base stamped ${ts} — structure untouched, \`forma check\` unaffected.`)

package/lib/viewer/c4-hologram.html

@@ -29,6 +29,9 @@ button.on{background:rgba(62,231,255,.18);color:var(--cyan);border-color:var(--c
 #back[disabled]{opacity:.28;cursor:default;border-color:var(--border);color:var(--ter)}
 select#skin option{background:#08202e;color:var(--nm)}
 #crumb{font-size:11px;color:var(--sec);margin:8px 0}
+#crumb .agg{float:right;color:var(--ter2);letter-spacing:.05em}
+#crumb .agg i{display:inline-block;width:7px;height:7px;border-radius:50%;margin:0 3px 0 8px;vertical-align:baseline}
+#crumb .agg b{color:var(--nm)}
 #crumb b{color:var(--cyan)}
 #crumb a{color:#8fd8ec;cursor:pointer}
 #crumb a:hover{text-decoration:underline}
@@ -64,6 +67,8 @@ svg{width:100%;height:100%;display:block}
 .edge.plan{stroke:var(--edgeplan);stroke-dasharray:3 6;opacity:.6;marker-end:url(#arp)}
 .edge.hot{stroke:var(--cyan);stroke-width:2.6;opacity:1}
 .edgehit{stroke:transparent;stroke-width:14;fill:none;cursor:help}
+.elbl{font-size:8.2px;fill:var(--elbl);letter-spacing:.04em;pointer-events:none;
+ paint-order:stroke;stroke:var(--stagebg);stroke-width:3px;stroke-linejoin:round}
 @keyframes dash{to{stroke-dashoffset:-24}}
 .nd.pulse rect{animation:pul 2.4s ease-in-out infinite}
 @keyframes pul{0%,100%{filter:drop-shadow(0 0 8px rgba(62,231,255,.5))}50%{filter:drop-shadow(0 0 18px rgba(62,231,255,.95))}}
@@ -132,12 +137,14 @@ html[data-skin="blueprint"] button.on{text-shadow:none}
    <button id="bnow" class="on" type="button"></button>
    <button id="btgt" type="button"></button>
    <button id="brf" type="button"></button>
+   <button id="blbl" type="button"></button>
    <button id="brl" type="button"></button>
    <span class="menuwrap">
     <button id="pexp" type="button" aria-haspopup="true" aria-expanded="false"></button>
     <span id="pmenu" role="menu">
      <button id="pexpSvg" type="button" role="menuitem"></button>
      <button id="pexpPng" type="button" role="menuitem"></button>
+     <button id="pexpLayout" type="button" role="menuitem"></button>
      <button id="pexpPrint" type="button" role="menuitem"></button>
     </span>
    </span>
@@ -165,17 +172,18 @@ var STRINGS={
  en:{
   subhelp:"click = explain (any level) · double-click or [+] = drill in · drag to move · hover an arrow = label · ESC/BACK",
   back:"← BACK", now:"CURRENT STATE", tgt:"TARGET STATE", reverify:"RE-VERIFY",
+  labels:"LABELS", labelsTitle:"arrow labels (auto-off above 14 arrows)",
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"re-arrange",
-  printExport:"PRINT / EXPORT", exportSvg:"Export SVG", exportPng:"Export PNG", print:"Print",
-  legDone:"DONE", legProg:"IN PROGRESS", legNext:"NEXT", legPlan:"PLAN ONLY", legProb:"PROBLEM",
+  printExport:"PRINT / EXPORT", exportSvg:"Export SVG", exportPng:"Export PNG", exportLayout:"Export layout JSON", print:"Print",
+  legDone:"DONE (proven)", legProg:"IN PROGRESS", legNext:"NEXT", legPlan:"PLAN ONLY", legProb:"PROBLEM",
   legHint:"— animated arrow = active flow · dashed = to build",
   crumbRoot:"Context", crumbLevel:"C4", lvlContext:"CONTEXT",
   lvlNames:{context:"Context",container:"Container",component:"Components",leaf:"Leaves"},
   detClose:"[x] close", detFunc:"What it does", detNow:"Current state (facts)",
   detTgt:"Target state (project)", detSrc:"Verification source", detIssue:"Issue",
   detTarget:"TARGET",
-  rosterSearch:"filter…", rosterCount:"members", rosterEmpty:"no match",
-  stampBase:"Fact base:", stampMethod:"method:", stampVerify:"code+topology",
+  rosterSearch:"filter…", rosterCount:"members", rosterEmpty:"no match", aggProgress:"progress",
+  stampBase:"Fact base:", stampMethod:"method:", stampVerify:"code+topology", staticSrc:"(static source)",
   errEmpty:"Model unreachable or empty.",
   errNotFound:"Model not found (./c4-model.json). Open via `forma serve` or inject window.__C4_MODEL__.",
   errUnavail:"Model unavailable."
@@ -183,17 +191,18 @@ var STRINGS={
  it:{
   subhelp:"click = spiega (ogni livello) · doppio-click o [+] = entra · trascina per spostare · hover su una freccia = etichetta · ESC/BACK",
   back:"← BACK", now:"STATO ATTUALE", tgt:"STATO FINITO", reverify:"RE-VERIFICA",
+  labels:"ETICHETTE", labelsTitle:"etichette sugli archi (spente sopra i 14 archi)",
   resetLayout:"RESET LAYOUT", resetLayoutTitle:"ridisponi",
-  printExport:"STAMPA / ESPORTA", exportSvg:"Esporta SVG", exportPng:"Esporta PNG", print:"Stampa",
-  legDone:"FATTO", legProg:"IN CORSO", legNext:"PROSSIMO", legPlan:"SOLO PROGETTO", legProb:"PROBLEMA",
+  printExport:"STAMPA / ESPORTA", exportSvg:"Esporta SVG", exportPng:"Esporta PNG", exportLayout:"Esporta layout JSON", print:"Stampa",
+  legDone:"FATTO (provato)", legProg:"IN CORSO", legNext:"PROSSIMO", legPlan:"SOLO PROGETTO", legProb:"PROBLEMA",
   legHint:"— freccia animata = flusso attivo · tratteggio = da costruire",
   crumbRoot:"Contesto", crumbLevel:"C4", lvlContext:"CONTESTO",
   lvlNames:{context:"Contesto",container:"Container",component:"Componenti",leaf:"Foglie"},
   detClose:"[x] chiudi", detFunc:"Cosa fa", detNow:"Stato attuale (fatti)",
   detTgt:"Stato finito (progetto)", detSrc:"Fonte verifica", detIssue:"Issue",
   detTarget:"TARGET",
-  rosterSearch:"filtra…", rosterCount:"elementi", rosterEmpty:"nessun risultato",
-  stampBase:"Base fatti:", stampMethod:"metodo:", stampVerify:"code+topology",
+  rosterSearch:"filtra…", rosterCount:"elementi", rosterEmpty:"nessun risultato", aggProgress:"avanzamento",
+  stampBase:"Base fatti:", stampMethod:"metodo:", stampVerify:"code+topology", staticSrc:"(fonte statica)",
   errEmpty:"Modello non raggiungibile o vuoto.",
   errNotFound:"Modello non trovato (./c4-model.json). Apri via `forma serve` o inietta window.__C4_MODEL__.",
   errUnavail:"Modello non disponibile."
@@ -207,13 +216,19 @@ function pickLang(model){
  return STRINGS[cand]?cand:"en";
 }
 var CATALOG_THRESHOLD=24; // group of same-category siblings above this collapses to one catalogue node
+var LABEL_AUTO_MAX=14;    // above this many arrows in the current level, fixed labels would knot the view
+var LABELS=null;          // null = auto (by arrow count); true/false = user override for this session
 var SKINS=[["holo","◆ holo"],["blueprint","▭ blueprint"]], SKIN_IDS=["holo","blueprint"];
 var STMAP={done:"done","in-progress":"prog",next:"next",planned:"plan",problem:"prob"};
-var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={};
+var M=null, stack=[null], mode="now", POS={}, drag=null, justDragged=false, CATNODES={}, FETCHED=false
+var VBOX={}; // last fitted viewBox per level — frozen while dragging so the canvas does not rescale
 function $(i){return document.getElementById(i)}
 function esc(s){return String(s==null?"":s).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/"/g,"&quot;")}
 function setSkin(s){var k=SKIN_IDS.indexOf(s)>-1?s:"holo";document.documentElement.dataset.skin=k;var el=$("skin");if(el)el.value=k;}
-function keyOf(){return stack.join(">")||"root";}
+// Layout key = the id of the level's parent ("root" at the top). Stable and documentable: it is
+// exactly the key used by meta.layout hints and by the exported layout JSON.
+function keyOf(){return stack[stack.length-1]||"root";}
+function hintsFor(k){return (M&&M.meta&&M.meta.layout&&M.meta.layout[k])||null;}
 function childrenOf(pid){var o=[];for(var i=0;i<M.nodes.length;i++){var n=M.nodes[i];if((pid==null&&!n.parent)||n.parent===pid)o.push(n);}return o;}
 // FEATURE #4: collapse large homogeneous catalogs.
 // Given real children, returns render items where any group of >CATALOG_THRESHOLD
@@ -260,8 +275,25 @@ function nameOf(id){var n=node(id);return n?n.name:id;}
 function srcOf(n){if(n.verify){if(typeof n.verify==="string")return n.verify;if(n.verify.source)return n.verify.source;if(n.verify.ref)return n.verify.ref;if(n.verify.issue)return "#"+n.verify.issue;}
  var ev=(n.evidence||[]).filter(function(e){return e.type==="doc"||e.type==="path";})[0];return ev?ev.ref:((M.meta&&M.meta.verifyMethod)||"");}
 
-function seedLayout(kids){
- var NW=228,NH=106,pos={},i,hub=null;
+var NW=228,NH=118; // NH fits 3 description lines without hitting the [+] DRILL
+// Curated coordinates from meta.layout win; everything else keeps the automatic arrangement,
+// placed BELOW the pinned block so a partial hint set can never overlap generated nodes.
+function seedLayout(kids,hints){
+ var pinned=[],free=[],i;
+ for(i=0;i<kids.length;i++)(hints&&hints[kids[i].id]?pinned:free).push(kids[i]);
+ if(!pinned.length)return autoLayout(kids);
+ var pos={},maxX=0,maxY=0,h;
+ for(i=0;i<pinned.length;i++){var q=hints[pinned[i].id];
+  h={x:+q.x||0,y:+q.y||0,w:+q.w||NW,h:+q.h||NH};pos[pinned[i].id]=h;
+  maxX=Math.max(maxX,h.x+h.w);maxY=Math.max(maxY,h.y+h.h);}
+ var W=Math.max(1020,maxX+64),H=Math.max(560,maxY+58);
+ if(free.length){var sub=autoLayout(free),oy=maxY+58;
+  for(i=0;i<free.length;i++){var p=sub.pos[free[i].id];pos[free[i].id]={x:p.x,y:oy+p.y,w:p.w,h:p.h};}
+  W=Math.max(W,sub.W);H=Math.max(H,oy+sub.H);}
+ return {W:W,H:H,pos:pos};
+}
+function autoLayout(kids){
+ var pos={},i,hub=null;
  for(i=0;i<kids.length;i++)if(kids[i].kind==="system"){hub=kids[i];break;}
  if(hub&&kids.length<=10){
   var W=1080,H=660,cx=W/2,cy=H/2;
@@ -280,9 +312,9 @@ function seedLayout(kids){
   pos[kids[i].id]={x:offx+c*(NW+gx),y:py+r*(NH+gy),w:NW,h:NH};}
  return {W:W,H:H,pos:pos};
 }
-function layoutFor(kids){var k=keyOf();if(!POS[k])POS[k]=seedLayout(kids);
+function layoutFor(kids){var k=keyOf();if(!POS[k])POS[k]=seedLayout(kids,hintsFor(k));
  // make sure every current kid has a slot (model may have changed)
- var lay=POS[k];for(var i=0;i<kids.length;i++)if(!lay.pos[kids[i].id]){var s=seedLayout(kids);POS[k]=s;return s;}return lay;}
+ var lay=POS[k];for(var i=0;i<kids.length;i++)if(!lay.pos[kids[i].id]){var s=seedLayout(kids,hintsFor(k));POS[k]=s;return s;}return lay;}
 
 function draw(animate){
  if(!M)return;
@@ -297,14 +329,45 @@ function draw(animate){
  function mapId(id){return memberMap[id]||id;}
  var edges=(M.edges||[]).map(function(e){return {from:mapId(e.from),to:mapId(e.to),label:e.label,estatus:e.estatus};})
   .filter(function(e){return idset[e.from]&&idset[e.to]&&e.from!==e.to;});
- var s='<svg viewBox="0 0 '+lay.W+' '+lay.H+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t":"")+'">'
+ // fixed arrow labels: on by default while the level stays readable, else hover-only (the tooltip
+ // is always there). A level with 40 arrows would be unreadable with every label painted at once.
+ var showLbl=(LABELS===null)?(edges.length<=LABEL_AUTO_MAX):LABELS;
+ var blbl=$("blbl");if(blbl)blbl.className=showLbl?"on":"";
+ // geometry pre-pass: edge paths first, so the viewBox can shrink-wrap nodes AND label anchors
+ var geo=[],i;
+ for(i=0;i<edges.length;i++){
+  var a=pos[edges[i].from],b=pos[edges[i].to];if(!a||!b)continue;
+  geo.push({e:edges[i],i:i,g:edgePath(a,b)});
+ }
+ // Fit-to-content viewBox: a sparse level renders zoomed and dense instead of lost in a fixed
+ // 1020px canvas — the hand-made status boards read well precisely because they waste no space.
+ // Minimums stop a single box from becoming comically large; extra room is split evenly so the
+ // content stays centred inside the enforced window.
+ var bx1=Infinity,by1=Infinity,bx2=-Infinity,by2=-Infinity,j,pp;
+ for(j=0;j<kids.length;j++){pp=pos[kids[j].id];if(!pp)continue;
+  if(pp.x<bx1)bx1=pp.x;if(pp.y<by1)by1=pp.y;if(pp.x+pp.w>bx2)bx2=pp.x+pp.w;if(pp.y+pp.h>by2)by2=pp.y+pp.h;}
+ for(j=0;j<geo.length;j++){var gm=geo[j].g;
+  if(gm.mx-14<bx1)bx1=gm.mx-14;if(gm.my-18<by1)by1=gm.my-18;
+  if(gm.mx+14>bx2)bx2=gm.mx+14;if(gm.my+6>by2)by2=gm.my+6;}
+ if(bx2<bx1){bx1=0;by1=0;bx2=lay.W;by2=lay.H;}
+ var VPAD=56,MINW=880,MINH=460;
+ var cw=bx2-bx1+2*VPAD,ch=by2-by1+2*VPAD;
+ var vw=Math.max(MINW,cw),vh=Math.max(MINH,ch);
+ var vx=bx1-VPAD-(vw-cw)/2,vy=by1-VPAD-(vh-ch)/2;
+ // …but hold it still while a box is being dragged: draw() runs on every mousemove, so a live
+ // refit would rescale the whole canvas under the pointer. The drop refits (see mouseup).
+ var vbk=keyOf();
+ if(drag&&VBOX[vbk]){vx=VBOX[vbk][0];vy=VBOX[vbk][1];vw=VBOX[vbk][2];vh=VBOX[vbk][3];}
+ else VBOX[vbk]=[vx,vy,vw,vh];
+ var s='<svg viewBox="'+vx.toFixed(1)+' '+vy.toFixed(1)+' '+vw.toFixed(1)+' '+vh.toFixed(1)+'" preserveAspectRatio="xMidYMid meet" class="'+(mode==="target"?"mode-t":"")+'">'
   +'<defs><marker id="ar" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edge")+'"/></marker>'
   +'<marker id="arp" markerWidth="9" markerHeight="7" refX="9" refY="3.5" orient="auto"><polygon points="0 0,9 3.5,0 7" fill="'+cssv("--edgeplan")+'"/></marker></defs>';
- for(var i=0;i<edges.length;i++){
-  var a=pos[edges[i].from],b=pos[edges[i].to];if(!a||!b)continue;
-  var d=edgePath(a,b),cl=(edges[i].estatus==="to-build"?"plan":"flow");
-  s+='<path class="edge '+cl+'" data-e="'+i+'" d="'+d+'"/>';
-  s+='<path class="edgehit" data-e="'+i+'" data-label="'+esc(edges[i].label||"")+'" d="'+d+'"/>';
+ for(j=0;j<geo.length;j++){
+  var e=geo[j].g,ed=geo[j].e,cl=(ed.estatus==="to-build"?"plan":"flow");
+  s+='<path class="edge '+cl+'" data-e="'+geo[j].i+'" d="'+e.d+'"/>';
+  s+='<path class="edgehit" data-e="'+geo[j].i+'" data-label="'+esc(ed.label||"")+'" d="'+e.d+'"/>';
+  if(showLbl&&ed.label){var lb=String(ed.label);if(lb.length>28)lb=lb.slice(0,27)+"…";
+   s+='<text class="elbl" x="'+e.mx+'" y="'+(e.my-4)+'" text-anchor="middle">'+esc(lb)+'</text>';}
  }
  for(var j=0;j<kids.length;j++){
   var n=kids[j],p=pos[n.id];
@@ -313,18 +376,21 @@ function draw(animate){
   var isCat=!!n.__catalog,dr=!isCat&&hasKids(n.id),cls="nd s-"+st+(dr?" drill":"")+(isCat?" cat":"")+(pulse?" pulse":"");
   var desc=isCat?(n.count+" "+STR.rosterCount):(mode==="target"?(n.target||n.func||""):(n.current||n.func||n.tech||""));
   var badge=isCat?String(n.count):(mode==="target"?STR.detTarget:(n.statusWord||(n.completion!=null?n.completion+"%":(n.tech||""))));
-  var tmax=Math.floor((p.w-70)/6.7),tt=n.name;if(String(tt).length>tmax)tt=String(tt).slice(0,tmax-1)+"…";
+  // the title runs until the badge, so reserve the badge's actual width (9px text ≈ 5.4px/char)
+  // instead of a flat 70px — a fixed reserve clipped names that had all the room they needed
+  var tmax=Math.floor((p.w-34-String(badge).length*5.4)/6.7),tt=n.name;
+  if(String(tt).length>tmax)tt=String(tt).slice(0,Math.max(1,tmax-1))+"…";
   s+='<g class="'+cls+'" data-id="'+esc(n.id)+'">'
    +'<rect x="'+p.x+'" y="'+p.y+'" width="'+p.w+'" height="'+p.h+'" rx="10"/>'
    +'<text class="kk" x="'+(p.x+13)+'" y="'+(p.y+16)+'">'+esc(n.category||n.kind||"")+'</text>'
    +'<text class="tt" x="'+(p.x+13)+'" y="'+(p.y+33)+'">'+esc(tt)+'</text>'
    +'<text class="pp" x="'+(p.x+p.w-13)+'" y="'+(p.y+16)+'" text-anchor="end">'+esc(badge)+'</text>';
-  var words=String(desc).split(" "),line="",ln=0,cpl=Math.floor((p.w-26)/5.4),MAXL=2;
-  for(var k=0;k<words.length&&ln<MAXL;k++){
-   if((line+words[k]).length>cpl){s+='<text class="dd" x="'+(p.x+13)+'" y="'+(p.y+51+ln*12.5)+'">'+esc(line.trim())+'</text>';line=words[k]+" ";ln++;}
-   else line+=words[k]+" ";}
-  if(ln<MAXL&&line)s+='<text class="dd" x="'+(p.x+13)+'" y="'+(p.y+51+ln*12.5)+'">'+esc(line.length>cpl?line.slice(0,cpl-1)+"…":line.trim())+'</text>';
-  else if(ln===MAXL&&line.trim())s+='<text class="dd" x="'+(p.x+13)+'" y="'+(p.y+51+ln*12.5)+'">…</text>';
+  // Description lines: how many fit comes from the geometry (text starts at y+51, 12.5px apart,
+  // and must clear the footer control at h-25), so a curated layout hint with short boxes cannot
+  // print through [+] DRILL. wrapDesc is pure and clamps every line to the box width.
+  var floorY=p.h-((dr||isCat)?25:6),MAXL=Math.min(4,Math.floor((floorY-51)/12.5)+1);
+  var dlines=wrapDesc(desc,Math.floor((p.w-26)/5.4),MAXL);
+  for(var q=0;q<dlines.length;q++)s+='<text class="dd" x="'+(p.x+13)+'" y="'+(p.y+51+q*12.5)+'">'+esc(dlines[q])+'</text>';
   if(dr)s+='<rect class="drillhit" data-drill="1" x="'+(p.x+p.w-96)+'" y="'+(p.y+p.h-25)+'" width="88" height="20" rx="5"/>'
    +'<text class="plus" x="'+(p.x+p.w-13)+'" y="'+(p.y+p.h-9)+'" text-anchor="end">[+] DRILL</text>';
   else if(isCat)s+='<text class="plus" x="'+(p.x+p.w-13)+'" y="'+(p.y+p.h-9)+'" text-anchor="end">[≡] '+esc(String(n.count))+'</text>';
@@ -337,18 +403,58 @@ function draw(animate){
  st2.classList.toggle("anim",animate!==false);
  // breadcrumb
  var chain=[],c=pid;while(c){var nn=node(c);chain.unshift(nn);c=nn?nn.parent:null;}
- var lvl=pid?levelName(kids[0]&&kids[0].level):STR.lvlContext;
- var cb=STR.crumbLevel+" · "+lvl.toUpperCase()+"  &nbsp;&nbsp; <a data-d='-1'>"+esc(STR.crumbRoot)+"</a>";
+ var lvlKey=pid?(kids[0]&&kids[0].level):"context";
+ var lvl=pid?levelName(lvlKey):STR.lvlContext;
+ // C4 notation: number the level by its position in the model's own `levels` list (L1 = context).
+ var lvlIdx=((M.levels||[]).indexOf(lvlKey));
+ var cb=(lvlIdx>-1?STR.crumbLevel+"-L"+(lvlIdx+1):STR.crumbLevel)+" · "+lvl.toUpperCase()+"  &nbsp;&nbsp; <a data-d='-1'>"+esc(STR.crumbRoot)+"</a>";
  for(var w=0;w<chain.length;w++)cb+=" &rsaquo; "+(w===chain.length-1?"<b>"+esc(chain[w].name)+"</b>":"<a data-d='"+w+"'>"+esc(chain[w].name)+"</a>");
+ // Per-level programme tally — the status-board essence in one glance: the status mix of THIS
+ // view plus mean completion. Counts use the real children (a collapsed catalogue still counts
+ // its members), so the tally never changes when the catalogue threshold does.
+ var cnt={},tot=0,sum=0,nc=0,st3;
+ for(j=0;j<realKids.length;j++){
+  st3=STMAP[realKids[j].status2]||(realKids[j].status==="planned"?"plan":"done");
+  cnt[st3]=(cnt[st3]||0)+1;tot++;
+  if(realKids[j].completion!=null){sum+=(+realKids[j].completion||0);nc++;}
+ }
+ if(tot){
+  var DOT={done:"#2fe08a",prog:"#ffc74d",next:"#3ee7ff",plan:"#2d5a72",prob:"#ff5d5d"},ord=["done","prog","next","plan","prob"],agg="";
+  for(j=0;j<ord.length;j++)if(cnt[ord[j]])agg+='<i style="background:'+DOT[ord[j]]+'"></i>'+cnt[ord[j]];
+  if(nc)agg+=' &nbsp;'+esc(STR.aggProgress)+' <b>'+Math.round(sum/nc)+'%</b>';
+  cb='<span class="agg">'+agg+'</span>'+cb;
+ }
  $("crumb").innerHTML=cb;
  $("back").disabled=stack.length<2;
  $("detail").style.display="none";
 }
+// Greedy word wrap into at most `max` lines of `cpl` characters. Every returned line is clamped to
+// cpl — an unbreakable token (a long class name, a URL) would otherwise paint outside the box, and
+// there is no clip-path on the node. The last line carries the ellipsis when text was dropped,
+// rather than spending a whole line on it (on a short curated box that was half the visible text).
+function wrapDesc(desc,cpl,max){
+ if(max<1||cpl<2)return [];
+ var words=String(desc==null?"":desc).split(" "),all=[],line="",i;
+ for(i=0;i<words.length;i++){if(line&&(line+words[i]).length>cpl){all.push(line.trim());line="";}line+=words[i]+" ";}
+ if(line.trim())all.push(line.trim());
+ var out=all.slice(0,max),dropped=all.length>out.length;
+ if(dropped&&out.length)out[out.length-1]=out[out.length-1]+"…";
+ for(i=0;i<out.length;i++)if(out[i].length>cpl)out[i]=out[i].slice(0,cpl-1)+"…";
+ return out;
+}
+// Returns the path plus the point ON the curve at t=0.5 — the label anchor. (The quadratic's
+// control point sits at twice the bow, so anchoring a label there would float it off the arrow.)
+// Endpoints are trimmed at the true RECTANGLE border (not a radial guess): with wide boxes the
+// radial trim landed inside the box on shallow angles, dragging the label anchor under the node.
 function edgePath(a,b){
  var ax=a.x+a.w/2,ay=a.y+a.h/2,bx=b.x+b.w/2,by=b.y+b.h/2,dx=bx-ax,dy=by-ay,L=Math.sqrt(dx*dx+dy*dy)||1;
- var x1=ax+(a.w/2+10)*dx/L,y1=ay+(a.h/2+10)*dy/L,x2=bx-(b.w/2+12)*dx/L,y2=by-(b.h/2+12)*dy/L;
- var mx=(x1+x2)/2+(y2-y1)*.12,my=(y1+y2)/2-(x2-x1)*.12;
- return "M"+x1+","+y1+" Q"+mx+","+my+" "+x2+","+y2;
+ var ux=dx/L,uy=dy/L;
+ var ta=Math.min(ux?(a.w/2)/Math.abs(ux):Infinity,uy?(a.h/2)/Math.abs(uy):Infinity)+8;
+ var tb=Math.min(ux?(b.w/2)/Math.abs(ux):Infinity,uy?(b.h/2)/Math.abs(uy):Infinity)+11;
+ if(ta+tb>L-4){ta=(a.w/2+10);tb=(b.w/2+12);} // boxes touch/overlap: fall back to the radial trim
+ var x1=ax+ta*ux,y1=ay+ta*uy,x2=bx-tb*ux,y2=by-tb*uy;
+ var cx=(x1+x2)/2+(y2-y1)*.12,cy=(y1+y2)/2-(x2-x1)*.12;
+ return {d:"M"+x1+","+y1+" Q"+cx+","+cy+" "+x2+","+y2, mx:(x1+2*cx+x2)/4, my:(y1+2*cy+y2)/4};
 }
 function levelName(l){return (STR.lvlNames&&STR.lvlNames[l])||l||"—";}
 function cssv(v){try{return getComputedStyle(document.documentElement).getPropertyValue(v).trim()||"#2b6e8a";}catch(e){return "#2b6e8a";}}
@@ -416,7 +522,9 @@ function wire(){
   pos[drag.id].y=clamp(p.y-drag.oy,4,lay.H-pos[drag.id].h-4);
   drag.moved=true;draw(false);
  });
- document.addEventListener("mouseup",function(){if(drag){if(drag.moved)justDragged=true;drag=null;}});
+ document.addEventListener("mouseup",function(){if(!drag)return;var m=drag.moved;drag=null;
+  // refit after the drop, deferred so the click that follows mouseup still lands on the live DOM
+  if(m){justDragged=true;setTimeout(function(){draw(false);},0);}});
  // edge label on hover (invisible fat hit-path)
  stage.addEventListener("mouseover",function(ev){
   if(ev.target.classList&&ev.target.classList.contains("edgehit")){
@@ -456,7 +564,15 @@ function wire(){
  document.addEventListener("keydown",function(e){if(e.key==="Escape"&&stack.length>1){stack.pop();draw(true);}});
  $("bnow").addEventListener("click",function(){mode="now";$("bnow").className="on";$("btgt").className="";draw(false);});
  $("btgt").addEventListener("click",function(){mode="target";$("btgt").className="on";$("bnow").className="";draw(false);});
- $("brf").addEventListener("click",function(){var m=(M&&M.meta)||{};$("stamp").textContent=STR.stampBase+" "+(m.verifiedAt||(M&&M.source&&M.source.commit)||"—")+" · "+STR.stampMethod+" "+(m.verifyMethod||STR.stampVerify);});
+ $("brf").addEventListener("click",function(){
+  // Served model ⇒ actually re-read it (a `forma verify` run in the terminal shows up here without
+  // losing the level, the layout or the mode). Injected/offline ⇒ re-stamp, and say why.
+  if(!FETCHED){stamp(STR.staticSrc);return;}
+  fetch("./c4-model.json?ts="+(new Date()).getTime()).then(function(r){return r.json();})
+   .then(function(m){if(m&&m.nodes&&m.nodes.length){M=m;stamp("");draw(false);}else stamp(STR.staticSrc);})
+   .catch(function(){stamp(STR.staticSrc);});
+ });
+ $("blbl").addEventListener("click",function(){LABELS=!($("blbl").className==="on");draw(false);});
  $("brl").addEventListener("click",function(){delete POS[keyOf()];draw(true);});
  $("skin").innerHTML=SKINS.map(function(s){return '<option value="'+s[0]+'">'+s[1]+'</option>';}).join("");
  $("skin").addEventListener("change",function(e){setSkin(e.target.value);});
@@ -467,7 +583,9 @@ function applyStrings(){
  function set(id,txt){var e=$(id);if(e)e.textContent=txt;}
  set("subhelp",STR.subhelp);set("back",STR.back);set("bnow",STR.now);set("btgt",STR.tgt);
  set("brf",STR.reverify);set("brl",STR.resetLayout);var brl=$("brl");if(brl)brl.title=STR.resetLayoutTitle;
- set("pexp",STR.printExport);set("pexpSvg",STR.exportSvg);set("pexpPng",STR.exportPng);set("pexpPrint",STR.print);
+ set("blbl",STR.labels);var bl=$("blbl");if(bl)bl.title=STR.labelsTitle;
+ set("pexp",STR.printExport);set("pexpSvg",STR.exportSvg);set("pexpPng",STR.exportPng);
+ set("pexpLayout",STR.exportLayout);set("pexpPrint",STR.print);
  set("lg-done",STR.legDone);set("lg-prog",STR.legProg);set("lg-next",STR.legNext);
  set("lg-plan",STR.legPlan);set("lg-prob",STR.legProb);set("lg-hint",STR.legHint);
 }
@@ -486,7 +604,7 @@ function collectSvgCss(){
   if(!rules)continue;
   for(j=0;j<rules.length;j++){var r=rules[j],t=r.cssText||"";
    // keep rules that target svg-internal classes/elements + the color vars on :root/html
-   if(/\.(nd|edge|edgehit|s-done|s-prog|s-next|s-plan|s-prob|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
+   if(/\.(nd|edge|edgehit|elbl|s-done|s-prog|s-next|s-plan|s-prob|mode-t|tt|kk|dd|pp|plus|cat)\b/.test(t)
       ||/(^|[\s,])svg\b/.test(t)||/:root|html\[data-skin/.test(t)){
     // drop animations for a static export (keepdefs stable)
     out.push(t);
@@ -512,14 +630,14 @@ function serializeSvg(){
  clone.setAttribute("xmlns","http://www.w3.org/2000/svg");
  clone.setAttribute("xmlns:xlink","http://www.w3.org/1999/xlink");
  var vb=(svg.getAttribute("viewBox")||"0 0 1080 660").split(/\s+/);
- var w=+vb[2]||1080,h=+vb[3]||660;
+ var vbx=+vb[0]||0,vby=+vb[1]||0,w=+vb[2]||1080,h=+vb[3]||660;
  clone.setAttribute("width",w);clone.setAttribute("height",h);
  // Inline the resolved variables on the root so var(--x) resolves standalone,
  // independent of the skin-selector chain that won't exist in the exported file.
  var vars=resolvedVars();if(vars)clone.setAttribute("style",vars);
  // solid dark/light background so the standalone file isn't transparent
  var bg=cssv("--stagebg")||"#050d14";
- var rect='<rect x="0" y="0" width="'+w+'" height="'+h+'" fill="'+bg+'"/>';
+ var rect='<rect x="'+vbx+'" y="'+vby+'" width="'+w+'" height="'+h+'" fill="'+bg+'"/>';
  var style="<style>"+collectSvgCss()+"</style>";
  var inner=clone.innerHTML;
  var attrs='';for(var a=0;a<clone.attributes.length;a++){var at=clone.attributes[a];attrs+=' '+at.name+'="'+String(at.value).replace(/"/g,"&quot;")+'"';}
@@ -531,6 +649,17 @@ function triggerDownload(blob,filename){
  a.href=url;a.download=filename;document.body.appendChild(a);a.click();
  document.body.removeChild(a);setTimeout(function(){URL.revokeObjectURL(url);},4000);
 }
+// Every level you have arranged, in the exact shape meta.layout expects — drag the boxes, export,
+// paste into the topology's "layout" and `gen` bakes it in. No storage: the repo is the memory.
+function exportLayout(){
+ var out={},k,id,p;
+ for(k in POS){if(!POS.hasOwnProperty(k))continue;
+  var lvl={},any=false;
+  for(id in POS[k].pos){if(!POS[k].pos.hasOwnProperty(id))continue;
+   p=POS[k].pos[id];lvl[id]={x:Math.round(p.x),y:Math.round(p.y),w:Math.round(p.w),h:Math.round(p.h)};any=true;}
+  if(any)out[k]=lvl;}
+ triggerDownload(new Blob([JSON.stringify({layout:out},null,2)+"\n"],{type:"application/json"}),exportBaseName()+"-layout.json");
+}
 function exportSvg(){
  var s=serializeSvg();if(!s)return;
  triggerDownload(new Blob([s.xml],{type:"image/svg+xml;charset=utf-8"}),exportBaseName()+".svg");
@@ -564,23 +693,34 @@ function wireExport(){
  document.addEventListener("keydown",function(e){if(e.key==="Escape")close();});
  var sv=$("pexpSvg");if(sv)sv.addEventListener("click",function(){close();exportSvg();});
  var pn=$("pexpPng");if(pn)pn.addEventListener("click",function(){close();exportPng();});
+ var lay=$("pexpLayout");if(lay)lay.addEventListener("click",function(){close();exportLayout();});
  var pr=$("pexpPrint");if(pr)pr.addEventListener("click",function(){close();window.print();});
 }
 function moveTip(ev){var st=$("stage").getBoundingClientRect(),t=$("etip");
  var x=ev.clientX-st.left+12,y=ev.clientY-st.top+12;
  t.style.left=Math.min(x,st.width-t.offsetWidth-6)+"px";t.style.top=Math.min(y,st.height-t.offsetHeight-6)+"px";}
 
+// Fact-base line. `suffix` marks a RE-VERIFY that could not re-read the model (injected/offline).
+function stamp(suffix){
+ var m=(M&&M.meta)||{};
+ $("stamp").textContent=STR.stampBase+" "+(m.verifiedAt||(M&&M.generatedAt)||(M&&M.source&&M.source.commit)||"—")
+  +" · "+STR.stampMethod+" "+(m.verifyMethod||STR.stampVerify)+(suffix?" "+suffix:"");
+}
 function boot(model){
  M=model;
  LANG=pickLang(M);STR=STRINGS[LANG];
  try{document.documentElement.setAttribute("lang",LANG);}catch(e){}
  applyStrings();
  if(!M||!M.nodes||!M.nodes.length){$("err").style.display="block";$("err").textContent=STR.errEmpty;return;}
- if(M.source&&M.source.repo)$("title").textContent="Forma · "+M.source.repo;
- var m=M.meta||{};$("stamp").textContent=STR.stampBase+" "+(m.verifiedAt||(M.source&&M.source.commit)||"—")+" · "+(m.verifyMethod||STR.stampVerify);
- setSkin((new URLSearchParams(location.search).get("skin"))||window.__C4_SKIN__||(m.skin)||"holo");
+ var ttl=(M.meta&&M.meta.title)||((M.source&&M.source.repo)?"Forma · "+M.source.repo:null);
+ if(ttl){$("title").textContent=ttl;try{document.title=ttl;}catch(e){}}
+ stamp("");
+ setSkin((new URLSearchParams(location.search).get("skin"))||window.__C4_SKIN__||(M.meta&&M.meta.skin)||"holo");
  stack=[null];mode="now";POS={};
  draw(true);
+ // Minimal hook for embedders (the Cowork artifact re-verifies through its own MCP bridge and
+ // needs to push the result back in without forking the viewer).
+ window.__C4_API__={model:function(){return M;},redraw:function(){draw(false);},stamp:function(t){$("stamp").textContent=t;}};
 }
 function start(){
  // Pick language from URL/global up-front so header + errors render even if the model never loads.
@@ -589,6 +729,7 @@ function start(){
  applyStrings();
  wire();
  if(window.__C4_MODEL__){boot(window.__C4_MODEL__);return;}
+ FETCHED=true; // the model has a live URL ⇒ RE-VERIFY can re-read it instead of only re-stamping
  try{fetch("./c4-model.json").then(function(r){return r.json();}).then(boot).catch(function(){
   $("err").style.display="block";$("err").textContent=STR.errNotFound;});}
  catch(e){$("err").style.display="block";$("err").textContent=STR.errUnavail;}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-arch",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Forma — present your architecture instead of slides. An interactive, stack-agnostic C4 explorer (context → container → component → leaf) generated from your code and kept true to it by a deterministic drift check.",
   "keywords": [
     "architecture",