forma-arch 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Luca Dominici
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,10 @@
+Forma
+Copyright 2026 Luca Dominici
+
+This product includes software developed as an original work.
+
+Conceptual standards referenced (not vendored, not affiliated):
+- The C4 model (https://c4model.com) — CC BY 4.0. Forma is not affiliated with or endorsed by C4.
+- arc42 (https://arc42.org) — CC BY-SA 4.0. Only referenced; template text is not redistributed.
+
+No third-party source code is copied into this project.

package/README.md

@@ -0,0 +1,59 @@
+# Forma
+
+**Present your architecture instead of slides.** Forma turns any codebase into an interactive,
+stack-agnostic C4 explorer — big-picture → drill-down to the leaf — generated *from the code* and
+kept true to it by a deterministic drift check. No more slide decks that lie the day after you draw
+them.
+
+Forma is the companion to `arbiter`: arbiter governs the process, Forma shows the system and
+guarantees the picture matches reality.
+
+## Why
+
+A hand-drawn architecture diagram is stale the moment code changes. Forma walks your source for the
+real structure, infers relationships from cross-references to exported symbol names (heuristic, additive), and **fails a check** when the model
+and the code disagree. What you present is what actually exists.
+
+## Install
+
+```sh
+npx forma-arch <command>        # or: npm i -D forma-arch
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `forma init` | Seed `docs/architecture/c4-topology.json` from your source dirs (best-effort; then curate) |
+| `forma gen` | Walk `src/` leaves + derive container edges from cross-references to exported symbol names → `c4-model.json` |
+| `forma check` | Deterministic drift check — **fails if the model no longer matches the code** |
+| `forma doc` | Project the arc42 scaffold (`ARCHITECTURE.scaffold.md`) from the model |
+| `forma serve` | Open the live explorer at `http://localhost:4173` |
+
+## How it fits together
+
+```
+        code  ──►  forma gen  ──►  c4-model.json  ──┬──►  c4-viewer.html   (present / explore)
+                                    (single source)  ├──►  ARCHITECTURE.md  (arc42, via forma doc)
+                                                      └──►  forma check     (gate: model == code?)
+```
+
+One source of truth (`c4-model.json`); two renderings (the interactive viewer and the arc42 doc);
+one deterministic check that keeps them honest. The file contract is
+[`lib/schema/c4-model.schema.json`](lib/schema/c4-model.schema.json).
+
+## Model-agnostic by design
+
+The engine is plain Node — no LLM required. Structure is auto-walked, relationships are derived from
+code, the check is deterministic. The only human (or agent) step is curating the topology groupings
+and writing the arc42 prose — and *any* model can do that against the documented JSON/Markdown
+contract. The Claude skill in `adapters/` is a thin wrapper, not the product.
+
+## Skins
+
+The viewer ships with swappable skins (`holo`, `blueprint`) via a dropdown or `?skin=`. Themes are
+CSS variables; the engine is decoupled from the look.
+
+## License
+
+Apache-2.0. Not affiliated with C4 or arc42 — see [`NOTICE`](NOTICE).

package/bin/forma.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// forma — present your architecture instead of slides.
+// Thin CLI dispatcher over the lib/ engine. Every subcommand is a plain Node script, so any
+// agent (or a human with no AI) drives the same contract. The engine is model-agnostic.
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { readFileSync } from 'node:fs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+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' }
+
+if (cmd === '-v' || cmd === '--version') {
+  const pkg = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf-8'))
+  console.log(pkg.version); process.exit(0)
+}
+if (!cmd || cmd === '-h' || cmd === '--help' || !MAP[cmd]) {
+  console.log(`forma — present your architecture instead of slides.
+
+Usage: forma <command> [--repo <path>]
+
+  init    seed docs/architecture/c4-topology.json from your source dirs (best-effort; then curate)
+  gen     walk src/ leaves + derive container edges from real code → c4-model.json
+  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
+
+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.`)
+  const unknown = cmd && cmd !== '-h' && cmd !== '--help' && !MAP[cmd]
+  process.exit(unknown ? 1 : 0)
+}
+
+const r = spawnSync(process.execPath, [join(LIB, MAP[cmd]), ...rest], { stdio: 'inherit' })
+process.exit(r.status == null ? 1 : r.status)

package/lib/check.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// check-c4-model.mjs — NON-VACUOUS anti-drift gate for the C4 model.
+// Fails LOUD (never SKIP). Asserts the committed model against INDEPENDENT ground truth in src/,
+// and flags architecture-doc numbers that disagree with code (the "14 vs 25 tables" trap).
+// Usage: node check-c4-model.mjs [--repo <path>] [--model <path>] [--topology <path>]
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+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 MODEL = arg('--model', join(REPO, 'docs/architecture/c4-model.json'))
+const TOPO = arg('--topology', join(REPO, 'docs/architecture/c4-topology.json'))
+const rp = (p) => join(REPO, p)
+const errs = []
+const fail = (m) => errs.push(m)
+
+if (!existsSync(MODEL)) { console.error('[check-c4] FAIL: model missing (no SKIP): ' + MODEL); process.exit(1) }
+if (!existsSync(TOPO)) { console.error('[check-c4] FAIL: topology missing: ' + TOPO); process.exit(1) }
+const model = JSON.parse(readFileSync(MODEL, 'utf-8'))
+const topo = JSON.parse(readFileSync(TOPO, 'utf-8'))
+
+// 1) schemaVersion present + basic shape
+if (!/^\d+\.\d+\.\d+$/.test(model.schemaVersion || '')) fail('missing/invalid schemaVersion')
+if (!Array.isArray(model.nodes) || model.nodes.length === 0) fail('no nodes')
+
+// 2) re-derive leaf counts from src/ INDEPENDENTLY and compare to the model
+function walk(spec) {
+  const dir = rp(spec.dir); if (!existsSync(dir)) { fail('leafSource dir missing: ' + spec.dir); return [] }
+  const re = new RegExp(spec.match), ex = spec.exclude ? new RegExp(spec.exclude) : null
+  return readdirSync(dir).filter((f) => {
+    if (spec.filesOnly !== false && statSync(join(dir, f)).isDirectory()) return false
+    return re.test(f) && !(ex && ex.test(f))
+  })
+}
+for (const spec of topo.leafSources) {
+  const live = walk(spec).length
+  const inModel = model.nodes.filter((n) => n.parent === spec.parent && n.kind === 'leaf' && n.status === 'current').length
+  if (live === 0) fail(`phantom parent "${spec.parent}": src glob ${spec.dir} matches 0 files`)
+  if (live !== inModel) fail(`DRIFT: ${spec.parent} — src has ${live} files, model has ${inModel}. Regenerate c4-model.json.`)
+}
+
+// 3) OPTIONAL count checks — generic, config-driven (the "14-vs-25 tables" trap, for ANY stack).
+// A repo opts in by adding `countChecks` to its topology, e.g.:
+//   "countChecks": [{ "file": "src/db/schema.ts", "pattern": "sqliteTable\\(", "nodeId": "l_db_1",
+//                     "doc": { "file": "docs/architecture/ARCHITECTURE.md", "pattern": "(\\d+)\\s+tables?" } }]
+// No project-specific constants live here. Absent → nothing runs.
+for (const c of topo.countChecks || []) {
+  const f = rp(c.file)
+  if (!existsSync(f)) { fail(`countCheck: file missing: ${c.file}`); continue }
+  const actual = (readFileSync(f, 'utf-8').match(new RegExp(c.pattern, 'g')) || []).length
+  const node = model.nodes.find((n) => n.id === c.nodeId)
+  if (!node) { fail(`countCheck: model node "${c.nodeId}" not found`); continue }
+  const modelN = parseInt(node.tech, 10)
+  if (actual !== modelN) fail(`DRIFT: ${c.file} has ${actual} match(es) of /${c.pattern}/, model node ${c.nodeId} says ${modelN}`)
+  if (c.doc && existsSync(rp(c.doc.file))) {
+    const claims = [...readFileSync(rp(c.doc.file), 'utf-8').matchAll(new RegExp(c.doc.pattern, 'gi'))].map((m) => parseInt(m[1], 10)).filter((n) => !Number.isNaN(n))
+    for (const cl of claims) if (cl !== actual) fail(`DOC DRIFT: ${c.doc.file} claims "${cl}" but ${c.file} has ${actual}.`)
+  }
+}
+
+// 4) every node evidence path of type "path" must exist (no phantom evidence)
+for (const n of model.nodes) for (const e of n.evidence || []) if (e.type === 'path' && !existsSync(rp(e.ref))) fail(`node ${n.id}: evidence path missing: ${e.ref}`)
+
+// 5) planned premises still hold
+for (const p of topo.plannedLeaves || []) if (p.sourceMustContain) {
+  const f = rp(p.sourceRef)
+  if (!existsSync(f) || !readFileSync(f, 'utf-8').includes(p.sourceMustContain)) fail(`planned "${p.name}" premise broken in ${p.sourceRef}`)
+}
+
+if (errs.length) { console.error('[check-c4] FAIL (' + errs.length + '):\n - ' + errs.join('\n - ')); process.exit(1) }
+console.log('[check-c4] OK — model is adherent to src/ (leaves, table count, evidence, planned premises all verified)')

package/lib/doc.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+// forma doc — project an arc42 scaffold from c4-model.json.
+// The DETERMINISTIC sections (context/building-block diagrams, container table, ADR index, stack)
+// are filled from the model — so they can never drift from it. The JUDGMENT sections (goals,
+// strategy, decisions, risks) are stubbed with TODO(forma) for a human/agent to write.
+// Output: docs/architecture/ARCHITECTURE.scaffold.md (never overwrites a real ARCHITECTURE.md).
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, relative } 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 OUT = arg('--out', join(REPO, 'docs/architecture/ARCHITECTURE.scaffold.md'))
+if (!existsSync(MODEL)) { console.error('[forma doc] model missing: ' + MODEL + ' — run `forma gen` first.'); process.exit(1) }
+const m = JSON.parse(readFileSync(MODEL, 'utf-8'))
+const byId = new Map(m.nodes.map((n) => [n.id, n]))
+const sid = (s) => String(s).replace(/[^A-Za-z0-9_]/g, '_')
+const name = (id) => (byId.get(id) || { name: id }).name
+const C4 = { person: 'Person', system: 'System', external: 'System_Ext', container: 'Container', component: 'Component', store: 'ContainerDb', boundary: 'Container_Boundary', leaf: 'Component' }
+const q = (s) => String(s == null ? '' : s).replace(/"/g, '')
+const el = (n) => `${C4[n.kind] || 'Container'}(${sid(n.id)}, "${q(n.name)}"${n.tech ? `, "${q(n.tech)}"` : ''})`
+const rels = (ids) => m.edges.filter((e) => ids.has(e.from) && ids.has(e.to)).map((e) => `  Rel(${sid(e.from)}, ${sid(e.to)}, "${(e.label || '').replace(/"/g, '')}")`).join('\n')
+
+// context = nodes with no parent
+const ctx = m.nodes.filter((n) => !n.parent)
+const ctxIds = new Set(ctx.map((n) => n.id))
+const contextDiagram = `\`\`\`mermaid\nC4Context\n  title System Context\n${ctx.map((n) => '  ' + el(n)).join('\n')}\n${rels(ctxIds)}\n\`\`\``
+
+// containers = children of the system node
+const sys = ctx.find((n) => n.kind === 'system') || ctx[0]
+const containers = m.nodes.filter((n) => n.parent === (sys && sys.id))
+const contIds = new Set(containers.map((n) => n.id))
+const containerDiagram = containers.length ? `\`\`\`mermaid\nC4Container\n  title Container view — ${sys.name}\n${containers.map((n) => '  ' + el(n)).join('\n')}\n${rels(contIds)}\n\`\`\`` : '_No containers in the model yet._'
+const leafCount = (id) => m.nodes.filter((n) => n.parent === id && n.kind === 'leaf').length
+const containerTable = containers.length
+  ? ['| Container | Tech | Leaves | What it does |', '|---|---|---|---|', ...containers.map((n) => `| ${n.name} | ${n.tech || '—'} | ${leafCount(n.id)} | ${(n.func || n.description || 'TODO(forma): describe').replace(/\n/g, ' ')} |`)].join('\n')
+  : '_No containers yet._'
+
+// ADR index if present
+const adrDir = join(REPO, 'docs/adr')
+let adrs = '_No `docs/adr/` found — record decisions as ADRs._'
+if (existsSync(adrDir)) {
+  const files = readdirSync(adrDir).filter((f) => /\.md$/.test(f) && !/readme|template/i.test(f)).sort()
+  if (files.length) adrs = files.map((f) => { const t = (readFileSync(join(adrDir, f), 'utf-8').match(/^#\s+(.+)/m) || [, f])[1]; return `- [${t}](../adr/${f})`; }).join('\n')
+}
+
+const stack = (m.meta && m.meta.stack) || (sys && sys.tech) || 'TODO'
+const TODO = (s) => `> TODO(forma): ${s}`
+const md = `<!-- forma: arc42 scaffold projected from c4-model.json. Deterministic sections are generated;
+     do not edit them by hand — re-run \`forma doc\`. Fill the TODO(forma) prose, then promote to ARCHITECTURE.md. -->
+
+# Architecture — ${sys ? sys.name : m.source.repo}
+
+> **Format:** [arc42](https://arc42.org/) + [C4](https://c4model.com/). Generated by \`forma doc\` from
+> \`c4-model.json\` (commit \`${(m.source.commit || '').slice(0, 8)}\`). The live explorer is \`c4-viewer.html\`.
+
+## 1. Introduction and Goals
+${TODO('one paragraph: what this system is and who uses it.')}
+${TODO('top 3-5 quality goals as a table (goal → driver).')}
+
+## 2. Architecture Constraints
+Stack: **${stack}**.
+${TODO('list hard constraints (language, deploy target, governance) with sources.')}
+
+## 3. Context and Scope
+${contextDiagram}
+${TODO('in-scope / out-of-scope in one line each.')}
+
+## 4. Solution Strategy
+${TODO('the 3-5 load-bearing decisions and why (one table).')}
+
+## 5. Building Block View
+${containerTable}
+
+${containerDiagram}
+${TODO('for each container, a short drilldown paragraph (the explorer shows the leaves).')}
+
+## 6. Runtime View
+${TODO('1-3 key sequences (a request / a job / a sync) as mermaid sequenceDiagrams.')}
+
+## 7. Deployment View
+${existsSync(join(REPO, 'Dockerfile')) || existsSync(join(REPO, 'docker')) ? 'A Dockerfile/`docker/` was detected — document the deployment topology.' : TODO('how and where this runs (a mermaid flowchart).')}
+
+## 8. Cross-cutting Concepts
+${TODO('validation, security, persistence, error handling, i18n — where each lives.')}
+
+## 9. Architecture Decisions
+${adrs}
+
+## 10. Quality Requirements
+${TODO('measurable targets (coverage, latency, availability) + how each is verified.')}
+
+## 11. Risks and Technical Debt
+${TODO('known risks and debt, with links to any register.')}
+
+## 12. Glossary
+${TODO('domain and project terms.')}
+`
+writeFileSync(OUT, md)
+console.log(`[forma doc] wrote ${relative(REPO, OUT)} — ${containers.length} container(s), context + container diagrams from the model.`)
+console.log('[forma doc] deterministic sections filled; write the TODO(forma) prose, then promote to ARCHITECTURE.md.')