@codewithjuber/forgekit 0.8.0

package/ONBOARDING.md

@@ -0,0 +1,180 @@
+# Onboarding — five minutes to productive
+
+**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)
+
+The recommended paths need no token and no clone:
+
+```bash
+# Claude Code / Codex — the plugin (guards auto-wire, nothing to merge)
+/plugin marketplace add CodeWithJuber/forgekit
+/plugin install forgekit
+
+# Any tool — the CLI, from public npm
+npm install -g @codewithjuber/forgekit
+
+forge doctor               # everything green?
+```
+
+Full matrix (no-registry `github:` install, symlink dev setup) →
+[README → Install](README.md#install).
+
+## 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 server config for Roo
+Code and VS Code).
+
+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)
+```
+
+## 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/reuse/context/memory/verify in one pass
+forge substrate "<task>" --json
+forge impact <symbol-or-file> # the blast radius on its own
+```
+
+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/).
+
+## 4. Use the extras
+
+```bash
+forge atlas build          # index this repo's symbols → .forge/atlas.json
+forge atlas query useAuth  # where is it defined? (cheaper than grep-and-read)
+forge atlas has useAuth    # does it exist? "not found" = likely hallucinated
+forge recall add "db port" "Postgres is on 5433 here, not 5432"
+forge recall list          # facts the recall-load guard injects next session
+forge catalog              # the Start-Here index of everything
+```
+
+## 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/`. 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
+forge ledger blame <id-prefix>         # who minted a claim, every oracle outcome, per-author trust
+forge reuse query "<what you're about to build>"   # verified code you already have — with its proof
+```
+
+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 (union-merge), so their lessons arrive with their provenance intact. The
+ledger is shared team memory.
+
+---
+
+## Forge principles
+
+Forge is opinionated. These are the ideas every part of it is built on — the "why"
+behind the mechanisms.
+
+### 1. Guard over prose
+
+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.
+
+### 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.
+
+### 3. Precompute, then serve
+
+Answer "where is X / does X exist" from a **prebuilt artifact** (`.forge/atlas.json`),
+not a live scan. Resolve the expensive part once; serve a few-hundred-token slice
+instead of reading five files. The artifact is portable — any tool reads it, no MCP
+required.
+
+### 4. The Lean Path
+
+The smallest change that works, chosen _after_ understanding the problem: need it at
+all? → already here? → stdlib/native/existing dep? → one small change → root not
+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." 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.
+
+### 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.
+
+### 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).
+
+---
+
+## Extend it
+
+- **Add a rule** → a bullet in `source/rules.json`, then `forge sync`.
+- **Add a tool (skill)** → `global/tools/<name>/SKILL.md` with `name` + `description` frontmatter.
+- **Add a guard** → `global/guards/<name>.sh` (source `_guardlib.sh` for fields + the lock), then wire it in `global/settings.template.json` and `hooks/hooks.json`.
+- **Rebrand** → edit `brand.json` (+ `package.json` bin, `.claude-plugin/plugin.json` name).
+
+Every command with worked examples and the full extension guide live in
+[docs/GUIDE.md](docs/GUIDE.md); the architecture, pain-point evidence, and cross-tool
+matrix live in [ARCHITECTURE.md](ARCHITECTURE.md).

package/README.md

@@ -0,0 +1,286 @@
+# Forge — one brain for every AI coding agent
+
+[![CI](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/CodeWithJuber/forgekit/actions/workflows/codeql.yml/badge.svg)](https://github.com/CodeWithJuber/forgekit/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/CodeWithJuber/forgekit/badge)](https://scorecard.dev/viewer/?uri=github.com/CodeWithJuber/forgekit)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![node: >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](./package.json)
+[![runtime deps: 0](https://img.shields.io/badge/runtime%20dependencies-0-brightgreen.svg)](./package.json)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
+    <img alt="forgekit — one brain for every AI coding agent: the cognitive substrate (memory, foresight, guardrails) wraps a stateless model and ships as one config to nine AI coding tools" src="docs/assets/hero-light.svg" width="100%">
+  </picture>
+</p>
+
+Forge is one shared brain for your AI coding agents. It gives a stateless model the
+three things it structurally lacks — memory, foresight, and enforced guardrails — and
+delivers them into every tool you use.
+
+> The cognitive substrate every frozen model is missing — proof-carrying memory, impact
+> foresight, and enforced guardrails — authored once and delivered as native config to
+> Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, and Continue (plus
+> MCP config for Roo and VS Code).
+
+> **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) is
+> tested and in daily use; some flags may change before `1.0`.
+
+## Contents
+
+- [The problem](#the-problem)
+- [How it works — the loop](#how-it-works--the-loop)
+- [What you get](#what-you-get)
+- [60-second quickstart](#60-second-quickstart)
+- [Commands](#commands)
+- [Team memory in three commands](#team-memory-in-three-commands)
+- [How it compares](#how-it-compares)
+- [Honest limits](#honest-limits)
+- [Why a cognitive substrate? The white paper](#why-a-cognitive-substrate-the-white-paper)
+- [Public site](#public-site) · [Documentation](#documentation) · [Community & support](#community--support)
+
+## The problem
+
+A large language model is stateless — one context window, wiped every call.
+
+- It has **no memory** of what your team already learned.
+- It has **no foresight** about what an edit will break.
+- It has **no enforced guardrails** — prose rules get forgotten after a compaction.
+
+And every tool wants its own config file (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`,
+`GEMINI.md`, MCP…). Forge is the **cognitive substrate** — the layer that runs *before*
+the model edits code, supplying memory, foresight, and guardrails — and the compiler that
+delivers it into every tool from one source.
+
+## How it works — the loop
+
+Every task passes a fast, deterministic gate; every outcome flows back into a shared,
+proof-carrying memory.
+
+```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 LR
+    T["task"] --> G["substrate gate<br/>assume · route · reuse<br/>context · impact"]
+    G -->|unclear| Q["ask clarifying<br/>questions first"]
+    Q --> T
+    G -->|clear| A["agent acts"]
+    A --> O["oracles<br/>tests · CI · human"]
+    O --> L["ledger write-back<br/>claims + evidence"]
+    L --> M["team merge<br/>plain git, conflict-free"]
+    M -.->|lessons and verified reuse| G
+    classDef accent fill:#f26430,stroke:#f26430,color:#171310;
+    class G accent;
+```
+
+Only independent oracles (tests, CI, a human accept/revert) move a memory's confidence —
+so a wrong lesson decays out instead of ossifying. Full design:
+[`ARCHITECTURE.md`](ARCHITECTURE.md).
+
+## What you get
+
+The day-to-day value first — the substrate gives a frozen model what it can't hold itself:
+
+- **Memory that persists across sessions and teammates.** Every lesson, fact, and verified
+  reuse is *proof-carrying memory (PCM)* — a claim that carries its own evidence and is only
+  trusted once independent oracles raise its confidence above a floor. Wrong lessons decay
+  out instead of ossifying.
+- **Foresight before you break things.** Ask "what does changing `verifyToken` break?" and
+  get the *blast radius* — the set of files an edit is predicted to impact, read from the
+  code graph, including coupled files you never named.
+- **Guardrails that can't be forgotten.** Deterministic hooks enforce the rules a model must
+  never break (protected paths, cost budget, doom loops) — they survive a context compaction
+  the way `CLAUDE.md` prose does not.
+- **One config for 9 tools.** Author your rules once; Forge emits each tool's native config,
+  plus MCP for Roo and VS Code. Zero runtime dependencies — one Node CLI, plain files in git,
+  no server.
+
+### The measured evidence
+
+Every number is a median from `npm run bench` on this repo, recorded with its environment
+block in [`reports/benchmarks.md`](reports/benchmarks.md) — the project rule is *a number is
+an assumption until measured*.
+
+- **Blast radius in 0.43 ms** (warm code-graph). On 6 hand-labeled cases from this repo's
+  real import graph: recall **0.97** vs **0.33** for looking at the edited file alone.
+- **A full pre-action gate in 118 ms** — assumption check, routing, reuse lookup, context
+  assembly, blast radius, scope, and goal anchor in one deterministic pass, no LLM call. On
+  Claude Code it runs on **every prompt, automatically**.
+- **62.1% cost saved vs always-premium** — from the white paper's live routing prototype on
+  real models (paper §9; that's the paper's measurement, not this repo's — `forge cost
+  --stages` reports only *your* measured stages).
+- **Conflict-free team memory** — merging two 500-claim ledger replicas takes **158 ms**; the
+  merge is a property-tested join-semilattice, so teammate ledgers converge in any order over
+  plain git.
+
+## 60-second quickstart
+
+Install — pick one row (the recommended paths need no token and no clone):
+
+| You use… | Run this |
+| --- | --- |
+| **Claude Code / Codex** *(recommended — full plugin, ambient guards)* | `/plugin marketplace add CodeWithJuber/forgekit` then `/plugin install forgekit` |
+| **Any tool, from the CLI** | `npm install -g @codewithjuber/forgekit` |
+| **No registry** | `npm install -g github:CodeWithJuber/forgekit` |
+| **Contributors / local dev** | `git clone https://github.com/CodeWithJuber/forgekit.git && cd forgekit && npm link` — or `bash install.sh` for the symlink setup |
+
+Then, in your project:
+
+```bash
+forge init      # emit every AI tool's native config from one shared source
+forge doctor    # pass/fail health check: tools, guards, MCP, config drift
+
+# pre-action check before you (or your agent) edit anything:
+forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests"
+#   → assumption verdict · cheapest capable model · predicted blast radius
+#     (including files you didn't name) · scope clusters · verification checklist
+
+# team memory: fold in a teammate's ledger — conflict-free, any order
+git pull && forge ledger merge <path-to-their-ledger>
+```
+
+On Claude Code the substrate then runs on **every prompt automatically** via a
+`UserPromptSubmit` hook — advisory only, silent on clean tasks. Every other tool gets a
+native config rule plus MCP tools (`substrate_check`, `predict_impact`, `assumption_gate`,
+`route_task`, `scope_files`) it can call itself.
+
+## Commands
+
+Advisory by default. Set `FORGE_ENFORCE=1` to turn the substrate into a hard block on the
+strongest signals (vacuous prompt, un-assemblable required context, blast radius over the
+default 25-file threshold).
+
+| Group | Command | Does |
+| --- | --- | --- |
+| **Config layer** | `forge init` | emit every tool's native config from one source |
+| | `forge sync` | recompile canonical source → each tool's native files (idempotent) |
+| | `forge doctor` | pass/fail health check: tools, guards, MCP, drift |
+| | `forge harden` | wire gitleaks pre-commit + sandbox settings |
+| | `forge catalog` | Start-Here index of every tool / crew / guard |
+| | `forge brand` | print the brand token map |
+| **Memory & team** | `forge ledger` | proof-carrying memory — stats / verify / show / blame / query / ratify / retract / merge / import |
+| | `forge recall` | cross-session personal memory — list / add / consolidate |
+| | `forge remember` | durable, repo-committable fact |
+| | `forge brain` | portable project-memory index |
+| | `forge cortex` | self-correcting lessons — `status` / `why` |
+| | `forge reuse` | proof-carrying code cache — query / mint / stats |
+| **Substrate (pre-action)** | `forge substrate` | the full pre-action gate in one pass |
+| | `forge preflight` | assumption / info-gap check |
+| | `forge route` | cheapest capable model tier (`route gateway` emits LiteLLM config) |
+| | `forge impact` | predict blast radius for a symbol or file |
+| | `forge scope` | cluster + surface coupled files |
+| | `forge imagine` | consequence sim + minimal dry-run suite (`--run` executes it sandboxed) |
+| | `forge context` | budgeted context assembly + completeness gate |
+| | `forge atlas` | build / query / has (hallucinated-symbol check) the code graph |
+| | `forge anchor` | goal-drift check (advisory) |
+| | `forge diagnose` | doom-loop: same failure 3× → diagnosis + escalation |
+| | `forge lean` | scope-minimality footprint (advisory) |
+| | `forge cost` | real per-day spend · measured stage factors (`--stages`) |
+| **Verification & safety** | `forge verify` | independent gate — tests + hallucinated-symbol flag + provenance |
+| | `forge scan` | skill-gate: vet a SKILL.md / .mcp.json for injection / RCE / exfil |
+| | `forge spec` | spec-as-contract drift — init / lock / check |
+| **UI / design** | `forge taste` | pick one visual direction → DESIGN.md |
+| | `forge uicheck` | contrast · fingerprint · design · visual (WCAG · slop+conformance · Playwright) |
+| **Observability** | `forge dash` | localhost-only read-only dashboard over ledger, metrics, blast radius (default port 4242) |
+
+**→ Every command with a worked example and real output:
+[`docs/GUIDE.md`](docs/GUIDE.md).**
+
+## Team memory in three commands
+
+Everything the substrate learns — Cortex lessons, `forge remember` facts, verified reuse
+artifacts — lands as content-addressed claims in a git-native ledger (`.forge/ledger/`)
+built to merge without conflicts:
+
+```bash
+forge init                    # once — also emits the .gitattributes union-merge rule the ledger needs
+# …work normally: cortex and `forge remember` shadow claims into the ledger as you go…
+git pull && forge ledger merge <path-to-their-ledger>   # fold in a teammate's ledger — any order
+```
+
+Identical knowledge minted independently converges to **one** claim with every author
+preserved in its provenance; `forge ledger blame <id>` shows who minted it, every oracle
+outcome, and per-author trust. No server, no sync service — it's just files in git.
+
+## How it compares
+
+Structural differences only — each row is checkable against the named source, and the full
+tables (including what each adjacent tool does *better*) are in
+[`reports/benchmarks.md` → Uniqueness](reports/benchmarks.md#uniqueness--structural-contrasts-with-adjacent-tools):
+
+| Property | Forge | Note stores / gateways / RAG |
+| --- | --- | --- |
+| Memory confidence moved **only by independent oracles** (tests, CI, human) | yes — closed `ORACLES` table; unverifiable evidence rejected (`src/ledger.js`) | note stores keep notes as written |
+| Unreviewed knowledge decays toward *uncertainty*, not deletion | yes — time-decayed Beta posterior; dormant claims kept for audit | notes persist unchanged until deleted |
+| Conflict-free team merge over plain git | yes — join-semilattice, property-tested | per-machine SQLite or a hosted store |
+| Routing decision visible and diffable **before** dispatch | yes — deterministic rubric over `src/model_tiers.json` | gateways decide inside the proxy at request time |
+| Cached code served **only with verification evidence**, revalidated against the current code graph | yes — `SERVE_FLOOR`, `revalidate()` in `src/reuse.js` | plain RAG serves on similarity alone |
+| **What they do better** | — | hosted sync, web UIs, embedding search that catches paraphrase; gateways actually *move traffic* (failover, quotas). Forge is a transparency layer, not a replacement |
+
+## Honest limits
+
+Forge states its own ceiling everywhere. In short: **guards reduce, don't eliminate** the
+"ignored my rules" problem; `recall`/`cortex` are file memory, **not** weight-level
+learning; the `atlas`/`impact` graph is regex-approximate (conservative, not a sound call
+graph — the impact numbers above are n = 6 hand-labeled cases on one JavaScript repo); the
+substrate's rubrics are heuristic; the MinHash near-match is weak on very short specs (an
+optional embeddings backend — `FORGE_EMBED` — lifts this; MinHash stays the zero-dependency
+default); and `forge cost --stages` reports **measured stages only** — a stage with no
+events says "no data", never a default. What's *asserted* is safe to gate on (repo
+grounding, graph traversal, routing arithmetic, test commands); everything else is
+*advisory*. **Tests and human corrections always win.** Full list:
+[docs/GUIDE.md → Honest limits](docs/GUIDE.md#honest-limits).
+
+## Why a cognitive substrate? The white paper
+
+A language model at inference is a fixed function `y = f(x)` — frozen weights, a bounded
+window, no state between calls. Memory, foresight, and self-checking can't be prompted into
+that shape; they have to be supplied from outside. The full argument, with every
+load-bearing statistic re-graded against primary sources, is the
+[cognitive-substrate white paper](docs/cognitive-substrate/).
+
+## Public site
+
+Forgekit ships two static pages. [`landing/index.html`](landing/index.html) is a
+hand-authored landing page — the project's front door. [`public/index.html`](public/index.html)
+is a generated status page, intentionally static and auto-updated from real repository data
+(`package.json`, `README.md`, `CHANGELOG.md`, and `reports/benchmarks.md`) by the generator
+in [`scripts/build-pages.mjs`](scripts/build-pages.mjs).
+
+```bash
+npm run pages:build        # offline, deterministic repo-data build
+BUILD_PAGES_LIVE=1 npm run pages:build  # also refresh public GitHub counters
+```
+
+The optional live mode uses the no-auth GitHub repository API with timeouts, retries,
+jitter, and ETag/Last-Modified caching.
+
+Both pages share one design system (the same tokens as `forge dash`) and are gated by
+`forge uicheck design` and the rendered `forge uicheck visual` check.
+
+GitHub Pages is the primary deployment, via [`.github/workflows/static.yml`](.github/workflows/static.yml):
+the landing page is published at the site root and the status page at `/status/`. GitLab
+Pages ([`.gitlab-ci.yml`](.gitlab-ci.yml)) is unchanged and only deploys the status page at
+its root — it does not get the landing page.
+
+## Documentation
+
+| Doc | What's in it |
+| --- | --- |
+| [`ONBOARDING.md`](ONBOARDING.md) | Five minutes to productive + the design principles. |
+| [`docs/GUIDE.md`](docs/GUIDE.md) | Every command, worked examples, all cases, how to extend. |
+| [`reports/benchmarks.md`](reports/benchmarks.md) | Every measured number, methodology, and `npm run bench` to reproduce. |
+| [`docs/cognitive-substrate/`](docs/cognitive-substrate/) | The white paper, evidence map, ecosystem map, and prototype sources. |
+| [`ARCHITECTURE.md`](ARCHITECTURE.md) | The four-layer compiler and the cross-tool emit matrix. |
+| [`docs/RELEASING.md`](docs/RELEASING.md) | How releases are cut (tag → npm + GitHub Release). |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed, per release. |
+
+## Community & support
+
+- **Get help** → [SUPPORT.md](./SUPPORT.md) · [Discussions](https://github.com/CodeWithJuber/forgekit/discussions)
+- **Contribute** → [CONTRIBUTING.md](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md)
+- **Direction** → [ROADMAP.md](./ROADMAP.md) · [GOVERNANCE.md](./GOVERNANCE.md)
+- **Security** → [SECURITY.md](./SECURITY.md) (report privately) · **Accessibility** → [ACCESSIBILITY.md](./ACCESSIBILITY.md)
+
+---
+
+MIT licensed. Built by [CodeWithJuber](https://github.com/CodeWithJuber).

package/bin/claude-init.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# claude-init — scaffold per-repo AI config in the CURRENT directory.
+# Auto-detects stack + commands and writes a shared AGENTS.md (read by
+# Claude/Cursor/Codex/Gemini) + a thin CLAUDE.md that references it.
+# Idempotent: won't overwrite existing files unless --force.
+set -uo pipefail
+
+FORCE=0; [ "${1:-}" = "--force" ] && FORCE=1
+root="$PWD"
+name="$(basename "$root")"
+
+# --- detect package manager + scripts (Node) ---
+pm=""; dev=""; build=""; test=""; lint=""; typecheck=""; fw=""; ts=""
+if [ -f package.json ]; then
+  [ -f pnpm-lock.yaml ] && pm=pnpm; [ -f yarn.lock ] && pm=yarn
+  [ -f package-lock.json ] && pm=npm; [ -f bun.lockb ] && pm=bun
+  [ -z "$pm" ] && pm=npm
+  read -r dev build test lint typecheck fw ts < <(node -e '
+    const p=require("./package.json"); const s=p.scripts||{}; const d={...p.dependencies,...p.devDependencies};
+    const has=k=>s[k]?k:"-";
+    const fw = d.next?"Next.js":d.astro?"Astro":d.nuxt?"Nuxt":d["@remix-run/react"]?"Remix":d.svelte?"Svelte":d.vue?"Vue":d.react?"React":d.express?"Express/Node":"Node";
+    const ts = (d.typescript||require("fs").existsSync("tsconfig.json"))?"TypeScript":"JavaScript";
+    console.log([has("dev"),has("build"),has("test"),has("lint"),has("typecheck")||has("type-check"),fw,ts].join(" "));
+  ' 2>/dev/null || echo "- - - - - Node JavaScript")
+fi
+
+# --- detect python / db / infra ---
+py=""; [ -f pyproject.toml ] && py="uv (pyproject.toml)"; [ -z "$py" ] && [ -f requirements.txt ] && py="pip (requirements.txt)"
+db=""
+[ -f prisma/schema.prisma ] && db="Prisma"
+[ -f drizzle.config.ts ] || [ -f drizzle.config.js ] && db="${db:+$db, }Drizzle"
+grep -riqE 'pgvector|postgres' docker-compose*.yml 2>/dev/null && db="${db:+$db, }Postgres"
+infra=""; ls ./*.tf >/dev/null 2>&1 && infra="Terraform"
+[ -f Dockerfile ] || ls docker-compose*.yml >/dev/null 2>&1 && infra="${infra:+$infra, }Docker"
+
+pmr(){ [ -n "$pm" ] && [ "$1" != "-" ] && echo "\`$pm run $1\`" || echo "<add>"; }
+stack="$( [ -n "$fw" ] && echo -n "$fw · $ts"; [ -n "$py" ] && echo -n " · Python ($py)"; [ -n "$db" ] && echo -n " · $db"; [ -n "$infra" ] && echo -n " · $infra")"
+[ -z "$stack" ] && stack="<fill in: language, framework, DB, infra>"
+
+write_agents(){
+cat > AGENTS.md <<EOF
+# AGENTS.md — $name
+
+Cross-tool rules (Claude Code, Cursor, Codex, Gemini, Aider…). Keep thin.
+
+## Stack
+$stack
+
+## Commands
+- Install: \`${pm:-npm} ${pm:+install}${pm:-} \`
+- Dev: $(pmr "${dev:--}")
+- Test: $(pmr "${test:--}")
+- Lint: $(pmr "${lint:--}")  ·  Typecheck: $(pmr "${typecheck:--}")
+- Build: $(pmr "${build:--}")
+$( [ -n "$py" ] && echo "- Python: \`uv run <cmd>\` · lint \`ruff check\` · test \`pytest\`" )
+$( [ -n "$db" ] && echo "- DB migrate: <add migrate command>" )
+
+## Rules
+- Reuse existing components/utils before writing new; smallest change that works.
+- Verify current best library from live sources before adding a dependency; prefer what's here.
+- Wrap fallible async in try/catch; guard array/object access; explicit errors.
+- UI: check mobile AND desktop; clear loading/empty/error states; follow DESIGN.md if present.
+- Verify before "done": run tests/build/lint and show output; screenshot UI changes.
+- Never commit secrets or .env*; never run destructive DB/FS commands without confirmation.
+
+## References
+- Visual rules: @DESIGN.md (if present)
+EOF
+}
+
+write_claude(){
+cat > CLAUDE.md <<EOF
+# $name — Claude notes
+
+Shared rules live in @AGENTS.md (stack, commands, engineering rules). Keep this
+file thin — only Claude-specific or repo-specific bits Claude keeps getting wrong.
+
+## Notes
+- <add non-obvious gotchas, e.g. "run X before Y", env quirks>
+EOF
+}
+
+made=""
+if [ -f AGENTS.md ] && [ $FORCE -eq 0 ]; then echo "skip AGENTS.md (exists — use --force)"; else write_agents; made="$made AGENTS.md"; fi
+if [ -f CLAUDE.md ] && [ $FORCE -eq 0 ]; then echo "skip CLAUDE.md (exists — use --force)"; else write_claude; made="$made CLAUDE.md"; fi
+
+echo "✓ $name: detected [$stack]"
+[ -n "$made" ] && echo "  wrote:$made" || echo "  nothing written (both existed)"
+echo "  next: skim AGENTS.md, fill any <add>/<fill> spots, then: git add AGENTS.md CLAUDE.md"
+echo "  optional: 'graphify install --project' + '/graphify .' to add a code graph"

package/bin/claude-taste.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# claude-taste — enable ONE UI taste skill for the CURRENT repo (project-scoped).
+# Best practice: one taste direction per project. Global taste skills compete and
+# produce inconsistent UI. This copies a taste into ./.claude/skills/ so it applies
+# only here. List with no args; enable with a name.
+set -uo pipefail
+
+ARCH="$HOME/.claude/skills-archive"
+KEPT="$HOME/.claude/skills"
+
+list() {
+  echo "Taste skills you can enable per-repo (usage: claude-taste <name>):"
+  { for d in "$ARCH"/*/ "$KEPT"/design-taste-frontend/; do
+      [ -f "${d}SKILL.md" ] && basename "$d"; done; } 2>/dev/null | sort -u | sed 's/^/  - /'
+  echo
+  echo "Then set the actual look in DESIGN.md (run: claude-init  or  ask for /design-md)."
+}
+
+[ $# -eq 0 ] && { list; exit 0; }
+
+name="$1"
+src=""
+for cand in "$ARCH/$name" "$KEPT/$name"; do
+  [ -f "$cand/SKILL.md" ] && src="$cand" && break
+done
+[ -z "$src" ] && { echo "No taste skill named '$name'."; echo; list; exit 1; }
+
+dest="./.claude/skills/$name"
+if [ -d "$dest" ]; then echo "'$name' already enabled in $(basename "$PWD")."; exit 0; fi
+mkdir -p "./.claude/skills"
+cp -R "$src" "$dest"
+echo "✓ enabled taste '$name' for $(basename "$PWD")  ->  $dest"
+echo "  next: define the look in DESIGN.md, then: git add .claude/skills/$name DESIGN.md"

package/bin/learn-consolidate.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Consolidate accumulated learned lessons: merge duplicates, prune trivia,
+# keep only durable rules. Run weekly (manually or via cron). Uses Haiku.
+# Fixes the append-only bloat of the session-learning hook.
+set -uo pipefail
+
+DIR="$HOME/.claude/skills/learned"
+command -v claude >/dev/null 2>&1 || { echo "claude CLI not found on PATH"; exit 1; }
+
+# Gather current consolidated file (if any) + all monthly lesson files.
+inputs=$(ls "$DIR"/CONSOLIDATED.md "$DIR"/lessons-*.md 2>/dev/null)
+[ -z "$inputs" ] && { echo "nothing to consolidate in $DIR"; exit 0; }
+all="$(cat "$DIR"/CONSOLIDATED.md "$DIR"/lessons-*.md 2>/dev/null)"
+[ -n "${all//[[:space:]]/}" ] || { echo "no lesson content"; exit 0; }
+
+# Archive originals before rewriting.
+mkdir -p "$DIR/archive"
+ts="$(date +%Y%m%d-%H%M%S)"
+for f in $inputs; do cp "$f" "$DIR/archive/$(basename "$f").$ts.bak"; done
+
+prompt="You are consolidating a developer's accumulated learned lessons from AI
+coding sessions. MERGE duplicates and near-duplicates into one rule. DROP anything
+trivial, one-off, session-specific, or contradicted. KEEP only durable, reusable
+rules (project gotchas, error->fix patterns, workflow rules). Group under
+'## <project>' headers (use '## General' for cross-project). Each rule = one
+markdown bullet. Do NOT invent anything — only compress what is given. NEVER
+include secrets/tokens/PII. Output only the markdown, no preamble.
+
+LESSONS:
+$all"
+
+# Uses your logged-in session (slower startup, but authed). Weekly/cron task.
+out="$(printf '%s' "$prompt" | timeout 180 claude -p --model haiku 2>/dev/null)"
+out="$(printf '%s' "$out" | sed '/^[[:space:]]*$/d')"
+
+# Guard: never overwrite/delete on an error or empty/too-short response.
+if printf '%s' "$out" | grep -qiE 'not logged in|/login|error|usage:'; then
+  echo "! claude returned an error (not logged in / empty) — originals kept, nothing changed"; exit 1
+fi
+if [ "$(printf '%s' "$out" | wc -c)" -lt 20 ]; then
+  echo "! response too short to be valid — originals kept"; exit 1
+fi
+
+if [ -n "$out" ]; then
+  { echo "# Learned — consolidated $(date +%Y-%m-%d)"; echo; printf '%s\n' "$out"; } > "$DIR/CONSOLIDATED.md"
+  rm -f "$DIR"/lessons-*.md
+  echo "✓ consolidated -> $DIR/CONSOLIDATED.md (originals archived in $DIR/archive/)"
+  echo "  lines: $(wc -l < "$DIR/CONSOLIDATED.md")"
+else
+  echo "! Haiku produced no output — originals kept, nothing changed"
+fi

package/brand.json

@@ -0,0 +1,15 @@
+{
+  "brand": "Forge",
+  "cli": "forge",
+  "pkg": "forgekit",
+  "tagline": "One brain for every AI coding agent.",
+  "home": "~/.forge",
+  "layers": {
+    "tools": "skills (model-invoked capabilities)",
+    "crew": "agents (isolated-context sub-agents)",
+    "guards": "hooks (deterministic, enforced)",
+    "atlas": "code-graph (symbol/call index)",
+    "lean": "minimalism discipline",
+    "recall": "cross-session memory"
+  }
+}