CodeWithJuber · CodeWithJuber · Jul 8, 2026 · Jul 8, 2026
@@ -1,21 +1,50 @@
 # Accessibility
 
-forgekit is a terminal tool plus docs and optional generated UI. Accessibility here means
-the CLI output, the docs, and anything it generates are usable by everyone.
-
-## What we do
-- **CLI output never relies on color alone** — status is shown by symbol *and* word
-  (`✓ ok`, `! warn`, `✗ fail`, `PASS`, `BLOCKED`), so it reads on monochrome terminals
-  and to screen readers.
-- **Docs** use semantic Markdown: headings in order, real lists/tables, descriptive link
-  text, and alt text on badges.
-- **Generated UI** (the `taste` design directions and any landing page) targets **WCAG 2.1
-  AA**: sufficient contrast, visible keyboard focus, and `prefers-reduced-motion` support.
-  The `corporate` taste is the AA-first default.
+forgekit is one brain for every AI coding agent — mostly a terminal tool, plus a few web
+surfaces. This page says, honestly, what we check and what we don't. Where a claim is
+machine-enforced we say so; where it isn't, we don't dress it up as conformance.
+
+## The surfaces
+
+forgekit has three places a person actually looks at output:
+
+- **CLI output** — every `forge` command. Plain text.
+- **`forge dash`** — a localhost-only, read-only web dashboard over the ledger, metrics, and
+  blast radius (default port 4242; never exposed off `localhost`).
+- **The public pages** — the landing page and the generated status page shipped to GitHub
+  Pages.
+
+## What we actually check
+
+- **CLI output never relies on color alone.** Status is carried by symbol *and* word
+  (`✓ ok`, `! warn`, `✗ fail`, `PASS`, `BLOCKED`), so it reads on a monochrome terminal and
+  through a screen reader. Color is decoration, not information.
+- **The public pages are gated in CI by `forge uicheck`.** Three checks run before a page
+  ships: `uicheck contrast` (WCAG contrast ratios on the text/background token pairs),
+  `uicheck fingerprint`/`design` (the design system stays on one 8-color / 4px scale), and
+  `uicheck visual` (a Playwright rendered gate — the page is loaded in a real browser and the
+  render is checked). A page that regresses contrast does not merge.
+- **The pages are reduced-motion-safe by construction.** The only motion is a scroll-reveal
+  effect, and it is *progressive enhancement*: it's JavaScript-gated, so with JS off — or for a
+  crawler, or a reader that ignores it — the full content is present and static. Nothing is
+  hidden behind an animation.
+- **Docs use semantic Markdown:** headings in order, real lists and tables, descriptive link
+  text, and alt text on images and badges.
+
+## What we don't claim
+
+We do **not** claim a formal WCAG 2.1/2.2 AA conformance level across every surface — we
+haven't run a full audit, and we'd rather under-promise. What's above is what the gates
+actually enforce. Contrast is measured; keyboard and screen-reader traversal of the dashboard
+is not yet part of the automated gate. Treat any gap as a bug, not a design choice.
 
 ## Reporting an accessibility issue
-Open an issue with the `accessibility` label, or start a Discussion. We treat accessibility
+
+Open an issue with the `accessibility` label, or start a
+[Discussion](https://github.com/CodeWithJuber/forgekit/discussions). We treat accessibility
 bugs as regular bugs, not nice-to-haves.
 
 ## Known gaps
-A few CLI glyphs assume a UTF-8 terminal; ASCII fallbacks are welcome PRs.
+
+- A few CLI glyphs assume a UTF-8 terminal; ASCII fallbacks are welcome PRs.
+- The `forge dash` dashboard has not been through a full keyboard / screen-reader audit.
@@ -4,11 +4,12 @@ title: "Forge (forgekit)"
 version: 0.6.0
 date-released: "2026-07-07"
 abstract: >-
-  One config for every AI coding agent — a cross-tool configuration layer plus a
-  cognitive substrate that gives a frozen model the memory, blast-radius awareness, and
-  guardrails it structurally lacks: an independent verification gate, self-correcting
-  project memory, portable memory, a security-vetting skill-gate, and a cost governor,
-  emitted natively to Claude Code, Codex, Cursor, Gemini, Aider, and more.
+  One brain for every AI coding agent — the cognitive substrate every frozen model is
+  missing. Forge gives a stateless model the memory, blast-radius foresight, and
+  guardrails it structurally lacks: proof-carrying team memory, an independent
+  verification gate, self-correcting project memory, a security-vetting skill-gate, and a
+  cost governor — authored once and emitted natively to Claude Code, Codex, Cursor,
+  Gemini, Aider, and more.
 type: software
 authors:
   - name: CodeWithJuber

@@ -1,15 +1,16 @@
 # Contributing to forgekit
 
-Thanks for your interest. forgekit stays small and dependency-free — please read
-this before opening a PR.
+forgekit is one brain for every AI coding agent — a cognitive substrate (memory, foresight,
+guardrails) authored once and compiled into every tool's native config. Keeping that brain
+small and dependency-free is the whole point, so please read this before opening a PR.
 
 ## Ground rules
 
 - **Zero runtime dependencies.** forgekit ships with no production `dependencies`.
   PRs adding one are rejected unless there's an exceptional, discussed reason. Dev
   dependencies (test/lint tooling) are fine.
 - **Node.js ESM only.** All code is ES modules (`"type": "module"`). No CommonJS.
-- **Supported Node versions:** 18, 20, 22.
+- **Supported Node versions:** 20 and 22 (the `>=20` engines floor; Node 18 is EOL).
 - **Cross-tool first.** New behavior should work across the tools forgekit targets
   (Claude Code, Codex, Cursor, Gemini, Aider, …), emitted from one source — not
   Claude-only. Say so in the PR if a piece is unavoidably tool-specific.
@@ -29,11 +30,11 @@ npm run check     # Biome lint + format check
 1. Branch: `git checkout -b feat/my-change`.
 2. Write the change **plus tests** — every new public function needs at least one
    test. Shell guards are tested via `spawnSync` (see `test/guards.test.js`).
-3. Run `npm test` and `npm run check:fix` before committing.
+3. Run `npm test`, `npm run typecheck`, and `npm run check:fix` before committing.
 4. Use [Conventional Commits](https://www.conventionalcommits.org/):
    `feat(scope): description`, `fix: …`, `docs: …`.
 5. Add a line to `CHANGELOG.md` under `## [Unreleased]`.
-6. Open a PR. CI (tests on Node 18/20/22, Biome, shellcheck) must pass.
+6. Open a PR. CI (tests on Node 20/22, Biome, typecheck, shellcheck) must pass.
 
 ## Project shape
 

@@ -1,17 +1,26 @@
 # Onboarding — five minutes to productive
 
-> **Forge** is a cross-tool config layer plus a cognitive substrate for AI coding
-> agents (Claude Code, Codex, Cursor, Gemini, Aider…). Author your rules once; it
-> configures every tool and adds memory, blast-radius checks, and guardrails.
+**One brain for every AI coding agent.** A language model is *stateless* — one
+context window, wiped every call — so it has no memory of what your team learned, no
+foresight about what an edit breaks, and no enforced guardrails. forgekit is the
+**cognitive substrate** that supplies exactly those three things, and it delivers them
+as native config to Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed,
+and Continue at once. Author the brain once; every tool reads it.
+
+This page is the fast path: install, configure a repo, do a task, and watch the ledger
+start paying off on day two.
 
 ```mermaid
+%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','primaryTextColor':'#f2ede7','primaryBorderColor':'#372c22','lineColor':'#f26430','secondaryColor':'#272019','tertiaryColor':'#171310','fontFamily':'ui-sans-serif, system-ui, sans-serif'}}}%%
 flowchart TD
     I["forge init"] --> Cfg["every tool configured<br/>from one source"]
     Cfg --> Work["you work as usual"]
     Work --> Gate["substrate checks each task:<br/>ask first? · which model? · what breaks?"]
     Gate --> Edit["agent edits, with guardrails"]
     Edit --> Learn["cortex learns from corrections"]
     Learn -.->|next task is smarter| Work
+    classDef accent fill:#f26430,stroke:#f26430,color:#171310;
+    class Gate accent;
 ```
 
 ## 1. Install (once)
@@ -34,35 +43,43 @@ Full matrix (no-registry `github:` install, symlink dev setup) →
 
 ## 2. Configure a repo (once per repo)
 
+One config for every tool. Author your rules once; `forge init` emits each tool's
+native file.
+
 ```bash
 cd ~/your-project
 forge init                 # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml …
 ```
 
 Now Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and Continue all
-read the **same** rules — each from its own native file (plus MCP config for Roo and VS Code).
+read the **same** rules — each from its own native file (plus MCP server config for Roo
+Code and VS Code).
 
-## 3. Change a rule
-
-Edit `source/rules.json` (or drop a per-repo `.forge/rules.json`), then:
+Change a rule later by editing `source/rules.json` (or dropping a per-repo
+`.forge/rules.json`), then:
 
 ```bash
 forge sync                 # recompiles into every tool; idempotent (only rewrites what changed)
 ```
 
-## 4. Use the cognitive substrate
+## 3. Use the cognitive substrate
+
+The substrate is the layer that runs *before* the model edits code. One command runs
+the whole pre-action gate:
 
 ```bash
-forge substrate "<task>"      # ask/route/impact/scope/memory/verify in one pass
+forge substrate "<task>"      # ask/route/impact/scope/reuse/context/memory/verify in one pass
 forge substrate "<task>" --json
-forge impact <symbol-or-file>
+forge impact <symbol-or-file> # the blast radius on its own
 ```
 
-If `forge substrate` says `ASK FIRST`, ask the returned questions before editing. Read predicted impacted files before making mutating changes.
+If `forge substrate` says `ASK FIRST`, ask the returned questions before editing. Read
+the predicted impacted files — the **blast radius**, the set of files an edit is
+predicted to touch — before any mutating change.
 
 Paper and evidence package: [docs/cognitive-substrate/](docs/cognitive-substrate/).
 
-## 5. Use the extras
+## 4. Use the extras
 
 ```bash
 forge atlas build          # index this repo's symbols → .forge/atlas.json
@@ -73,10 +90,13 @@ forge recall list          # facts the recall-load guard injects next session
 forge catalog              # the Start-Here index of everything
 ```
 
-## 6. Day two: the ledger is learning
+## 5. Day two: the ledger is learning
 
 Everything the substrate learned on day one — cortex lessons, remembered facts,
-verified code — landed as claims in `.forge/ledger/`. Now it starts paying off:
+verified code — landed as claims in `.forge/ledger/`. This is **proof-carrying memory
+(PCM)**: every stored fact carries its own evidence and is only trusted once independent
+oracles (tests, CI, a human accept/revert) raise its confidence above a floor. A wrong
+lesson decays out instead of ossifying. Now it starts paying off:
 
 ```bash
 forge ledger stats                     # what the repo knows, by kind and trust level
@@ -87,7 +107,8 @@ forge reuse query "<what you're about to build>"   # verified code you already h
 A `forge reuse query` hit points at working, test-confirmed code and the
 `forge ledger blame` command that proves it — reuse it instead of regenerating. And
 after `git pull`, `forge ledger merge <path>` folds a teammate's ledger in
-conflict-free, so their lessons arrive with their provenance intact.
+conflict-free (union-merge), so their lessons arrive with their provenance intact. The
+ledger is shared team memory.
 
 ---
 
@@ -100,14 +121,14 @@ behind the mechanisms.
 
 Rules the model can drift from live in prose; rules it must **never** break live in
 **guards** (deterministic shell hooks). A guard can't be forgotten after context
-compaction. Move every enforceable invariant out of `CLAUDE.md` and into a guard;
-keep the prose thin.
+compaction. Move every enforceable invariant out of `CLAUDE.md` and into a guard; keep
+the prose thin.
 
 ### 2. One source, many emitters
 
 Author rules **once** (`source/rules.json`); a deterministic compiler (`forge sync`)
-emits each tool's native format with a content-hash header, so drift is detectable
-and re-running is a no-op. No rule is ever written twice.
+emits each tool's native format with a content-hash header, so drift is detectable and
+re-running is a no-op. No rule is ever written twice.
 
 ### 3. Precompute, then serve
 
@@ -124,28 +145,26 @@ symptom. Deletion over addition. Boring over clever. (See the `lean` tool.)
 
 ### 5. Reuse over rebuild — thin layers over proven primitives
 
-"Our own" never means "reimplement a mature tool." `atlas` leans on LSP-class
-primitives; `lean` is one rule file, not a plugin engine. The smallest surface that
-delivers the capability.
+"Our own" never means "reimplement a mature tool." The smallest surface that delivers
+the capability: `lean` is one rule file, not a plugin engine.
 
 ### 6. Verify, don't assert
 
-Nothing is "done" without a check you can run — a test, a build exit code, a
-screenshot. Show the command and its output. Fix root causes; never suppress an
-error to make a check pass.
+Nothing is "done" without a check you can run — a test, a build exit code, a screenshot.
+Show the command and its output. Fix root causes; never suppress an error to make a
+check pass.
 
 ### 7. Re-entrancy safety
 
-No guard may loop. Every guard is idempotent, holds an atomic lock while it runs,
-and the one guard that calls a model (`session-learner`) is opt-in, gated, and
-single-shot. The class of bug that once burned 1.67B tokens in five hours cannot
-originate here.
+No guard may loop. Every guard is idempotent, holds an atomic lock while it runs, and
+the one guard that calls a model (`session-learner`) is opt-in, gated, and single-shot.
+The class of bug that once burned 1.67B tokens in five hours cannot originate here.
 
 ### 8. Name the ceiling
 
-Every deliberate simplification states its limit and upgrade path, in code and in
-docs. Forge would rather ship an honest subset with a clear boundary than a vague
-claim — see [the honest limits](docs/GUIDE.md#honest-limits).
+Every deliberate simplification states its limit and upgrade path, in code and in docs.
+Forge would rather ship an honest subset with a clear boundary than a vague claim — see
+[the honest limits](docs/GUIDE.md#honest-limits).
 
 ---