CodeWithJuber · CodeWithJuber · Jul 6, 2026 · Jul 6, 2026
@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "forgekit",
   "displayName": "Forge",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "One config, every AI coding tool — cognitive substrate, tools, crew, guards, atlas, lean, recall from one source.",
   "author": { "name": "CodeWithJuber" },
   "license": "MIT",

@@ -1,6 +1,6 @@
 {
   "name": "forgekit",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "One config, every AI coding tool — cognitive substrate, MCP tools, guards, atlas, recall, and routing from one source.",
   "author": { "name": "CodeWithJuber", "url": "https://github.com/CodeWithJuber" },
   "homepage": "https://github.com/CodeWithJuber/forgekit#readme",

@@ -0,0 +1,38 @@
+# Canonical issue/PR labels, synced by .github/workflows/labels.yml.
+# Edit here (not in the GitHub UI) so the set stays reproducible.
+- name: bug
+  color: d73a4a
+  description: Something isn't working
+- name: enhancement
+  color: a2eeef
+  description: New feature or request
+- name: documentation
+  color: 0075ca
+  description: Improvements or additions to docs
+- name: question
+  color: d876e3
+  description: Further information is requested
+- name: good first issue
+  color: 7057ff
+  description: Good for newcomers
+- name: help wanted
+  color: 008672
+  description: Extra attention is wanted
+- name: dependencies
+  color: 0366d6
+  description: Dependency updates (Dependabot)
+- name: github-actions
+  color: 000000
+  description: CI / GitHub Actions changes
+- name: security
+  color: b60205
+  description: Security-sensitive report or fix
+- name: accessibility
+  color: 5319e7
+  description: Accessibility (a11y) report or fix
+- name: stale
+  color: cccccc
+  description: Inactive; will be closed if it stays quiet
+- name: pinned
+  color: fbca04
+  description: Exempt from the stale bot
@@ -0,0 +1,24 @@
+# Sync repo labels from .github/labels.yml (the labels the templates, Dependabot,
+# and the stale bot reference). Runs on change + on demand. Uses the default token
+# (label management needs write, not admin).
+name: Labels
+
+on:
+  push:
+    branches: [master]
+    paths: [".github/labels.yml", ".github/workflows/labels.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: crazy-max/ghaction-github-labeler@v5
+        with:
+          yaml-file: .github/labels.yml
+          skip-delete: true # never delete labels this file doesn't list
@@ -1,5 +1,5 @@
-# Tag v* -> test -> publish to GitHub Packages, then cut a GitHub release.
-# GitHub Packages auth uses the built-in GITHUB_TOKEN (packages: write) — no external secret.
+# Push a v* tag -> test -> publish to public npm (with provenance) -> cut a GitHub Release.
+# Requires one repo secret: NPM_TOKEN (an npm "Automation" token). See docs/RELEASING.md.
 name: Release
 
 on:
@@ -10,25 +10,29 @@ permissions:
   contents: read
 
 jobs:
-  publish:
+  release:
     runs-on: ubuntu-latest
     permissions:
-      contents: write # create the GitHub release
-      packages: write # publish to GitHub Packages (npm.pkg.github.com)
+      contents: write # create the GitHub Release
+      id-token: write # npm provenance (supply-chain attestation)
     steps:
       - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # full history so release notes can diff from the last tag
       - uses: actions/setup-node@v6
         with:
           node-version: 22
-          registry-url: "https://npm.pkg.github.com"
+          registry-url: "https://registry.npmjs.org"
           cache: npm
       - run: npm ci
       - run: npm test
-      - run: npm publish
+      - run: npm publish --provenance --access public
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Create GitHub release
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Create GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.ref_name }}
-        run: gh release create "$TAG" --notes-from-tag --verify-tag
+        # --generate-notes builds notes from merged PRs/commits since the previous tag,
+        # so it works with lightweight OR annotated tags (unlike --notes-from-tag).
+        run: gh release create "$TAG" --title "$TAG" --generate-notes --verify-tag
@@ -0,0 +1,41 @@
+# Repo "About" as code: description, homepage, topics, and Discussions.
+# Run manually: Actions -> "Repo settings" -> Run workflow.
+#
+# NOTE: editing repo settings needs an ADMIN-scoped token. The default GITHUB_TOKEN
+# cannot be granted `administration`, so add a fine-grained PAT (Administration: write,
+# Metadata: read) as the repo secret ADMIN_TOKEN. Without it the job will 403 — in that
+# case just run the two `gh` commands below locally once (they need no workflow):
+#
+#   gh repo edit CodeWithJuber/forgekit \
+#     --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \
+#     --homepage "https://github.com/CodeWithJuber/forgekit#readme" \
+#     --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \
+#     --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \
+#     --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor
+#   gh api --method PATCH /repos/CodeWithJuber/forgekit -F has_discussions=true
+name: Repo settings
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  settings:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Apply About, topics, and Discussions
+        env:
+          GH_TOKEN: ${{ secrets.ADMIN_TOKEN || github.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -e
+          gh repo edit "$REPO" \
+            --description "One config for every AI coding agent — cross-tool config + a cognitive substrate (memory, blast-radius, guardrails) for Claude Code, Codex, Cursor, Gemini, Aider, and more." \
+            --homepage "https://github.com/CodeWithJuber/forgekit#readme" \
+            --add-topic claude-code --add-topic ai-coding --add-topic ai-agents --add-topic mcp \
+            --add-topic agents-md --add-topic cross-tool --add-topic cognitive-substrate \
+            --add-topic developer-tools --add-topic cli --add-topic codex --add-topic cursor
+          gh api --method PATCH "/repos/$REPO" -F has_discussions=true
+          echo "Applied About, topics, and Discussions for $REPO."
@@ -1,6 +1,4 @@
-# Public deps (Biome, typescript) resolve from npmjs; only the @codewithjuber scope
-# publishes/installs from GitHub Packages. Without the explicit default, setup-node's
-# registry-url would point the default at GitHub Packages and break `npm ci`.
+# Everything resolves from the public npm registry (devDeps and the published package).
+# Without the explicit default, setup-node's registry-url could repoint npm and break `npm ci`.
 registry=https://registry.npmjs.org/
-@codewithjuber:registry=https://npm.pkg.github.com
 min-release-age=7
@@ -1,10 +1,10 @@
-# Forge — architecture & production plan
+# Forge — architecture
 
 > Cross-tool configuration layer for agentic AI coding assistants. One source of
 > truth, emitted natively into every tool; a small set of *enforced* guards; a
 > lean discipline; a code-graph (`atlas`); cross-session memory (`recall`); and a
-> token-budget cost governor. Install once (Claude plugin **or** installer **or**
-> `forgekit` npm CLI). Near-zero learning curve.
+> token-budget cost governor. Install as a Claude Code plugin, from public npm
+> (`@codewithjuber/forgekit`), or from source. Near-zero learning curve.
 
 Grounded in a verified multi-source research pass (Reddit/HN/dev.to, GitHub issue
 trackers, official vendor docs). Evidence + config-format verdicts in the appendix.
@@ -116,6 +116,10 @@ only as the AST/chunking fallback for files with no language server.
 | **Copilot** | root `AGENTS.md` (since 2025-08-28) + `.github/copilot-instructions.md` | Rely on root `AGENTS.md`; optional generated `.github` pointer |
 | **Windsurf/Devin** | `AGENTS.md` auto-discovered; caps 6k/12k chars; mid-rebrand to Devin | Root `AGENTS.md` under caps; detect `.windsurf` vs `.devin` at init |
 | **Zed** | first match of a precedence list incl. `AGENTS.md` | Emit `AGENTS.md` + doctor flags any earlier-precedence legacy file shadowing it |
+| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | Emit a rules file plus the Forge MCP server config |
+
+Roo Code and VS Code receive the Forge MCP server via `forge init` (`.roo/mcp.json`,
+`.vscode/mcp.json`) rather than a rules file.
 
 ## Repo layout — one tree, three front doors
 ```
@@ -127,7 +131,7 @@ forgekit/
     cli.js                # init | sync | doctor | taste | learn-consolidate | brand
     sync.js               # emitter (source → per-tool targets); hash + DO-NOT-EDIT
     doctor.js             # health checks
-    emit/                 # one module per tool (claude, codex, cursor, gemini, aider, copilot, windsurf, zed)
+    emit/                 # one module per tool (claude, codex, cursor, gemini, aider, copilot, windsurf, zed, continue) + mcp
   source/
     AGENTS.md             # THE canonical source
     rules/                # git.md, testing.md, security.md, style.md → assembled
@@ -142,18 +146,6 @@ plugin.json, install.sh, and the npm bin **all reference `global/` + `source/`**
 no duplication; each channel just runs `forge sync` at the end. A test asserts all
 three resolve to `global/`.
 
-## Build phases (each = a shippable slice, with a runnable exit check)
-
-| Phase | Deliverables | Exit check |
-|-------|-------------|------------|
-| **0. Repo + brand spine** | git init; `brand.json` one-token; rename to `forgekit/`; `forge` bin stub | `forge --version` prints brand+version; grep proves brand defined once |
-| **1. Emitter** | `source/AGENTS.md` from fragments; `sync.js` + all 8 emit modules; hash headers | `forge sync` in a fixture emits every target; idempotent re-run; golden-file tests pass |
-| **2. Install + doctor** | hardened `install.sh`; `plugin.json`+`marketplace.json`; `forge doctor` | fresh-machine sim → doctor all-green; `npm pack` exposes `forge`; plugin loads w/o inflating skill count |
-| **3. Guards** | rebranded protect-paths/format/recall-load; `cost-budget` w/ lock; `lean-guard`; session-learner gate | guard harness: blocks `.env` write; lock prevents re-entry; fires from subdir + worktree; settings validates |
-| **4. lean + recall + crew** | `lean` tool; unified `recall`; rebranded crew | recall: write→new-session load→consolidate dedupes; secret write refused; verifier runs diff-scoped |
-| **5. atlas** | serena/LSP-backed `atlas` build/query/update; portable artifact; hallucinated-symbol flag; lazy MCP | indexes a sample repo; nonexistent symbol → not-found; reuse-first consumes atlas; MCP responds |
-| **6. Onboarding polish** | `forge init` wizard + active-summary; Start-Here catalog; docs | clean-env `forge init` → working in one command; catalog lists every item w/ one-line why; smoke test needs no external doc |
-
 ## Risks & honest boundaries
 - **Enforcement ceiling** — guards enforce only what's expressible as a hook (paths,
   format, diff-size, budget). Semantic rules ("prefer functional") stay prose and
@@ -169,17 +161,6 @@ three resolve to `global/`.
   the minimum graph that powers reuse + hallucination-flag, not a code-intel product.
 - **Three channels triple drift surface** — mitigated by "one tree" + the resolve test.
 
-## Open decisions → recommended resolutions
-| Decision | Recommendation |
-|----------|----------------|
-| atlas: existing indexer vs hand-roll | **serena/LSP** (resolved by tech-selector) |
-| Gemini: 2nd copy vs settings opt-in | **settings `context.fileName` opt-in** |
-| Windsurf `.windsurf` vs `.devin` | **detect at init + confirm** |
-| recall consolidation cadence | **opt-in Stop-hook**, optional `forge learn-consolidate` cron |
-| cost-budget: block vs warn | **warn** (blocking re-creates permission fatigue) |
-| atlas MCP always-on vs lazy | **lazy-start** |
-| convert semantic rules → guards | **incrementally**, only where a deterministic check is clean |
-
 ---
-*Appendix: config-format verdicts confirmed against vendor docs; single/secondhand
-stats (Cursor "1/3 ignore", arXiv 42/96/48) flagged and not hardcoded into user copy.*
+See [ROADMAP.md](ROADMAP.md) for direction and [`docs/adr/`](docs/adr/) for the recorded
+architecture decisions (zero runtime deps, the SKILL.md standard, guard-over-prose).
@@ -6,33 +6,28 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-06
+
 ### Added
 
-- **M4 goal-anchoring (`forge anchor`)** — the one paper capability that was mapped in the docs but never implemented. A deterministic goal-drift check: it re-reads the stated objective against the files actually changed (`git diff HEAD` + untracked, minus forge's own generated config) and flags work that wandered off-goal. Reuses `referencedEntities` + the atlas; folded into `forge substrate` (quiet on a clean tree, speaks mid-session on drift). All 11 paper capabilities now ship a real mechanism.
+- **Forge Cognitive Substrate** — one pre-action command (`forge substrate`) plus an MCP surface (`substrate_check`, `predict_impact`, `assumption_gate`, `route_task`, `scope_files`): assumption gate, transparent model routing, impact/blast-radius, scope decomposition, Cortex lessons, minimality, and a verification checklist.
+- **M4 goal-anchoring (`forge anchor`)** — a deterministic goal-drift check that flags changed files off the stated goal. All 11 white-paper capabilities now ship a real mechanism.
+- **Atlas v2 graph** — dependency nodes/edges + reverse-dependency impact traversal (the symbol-query API is preserved).
+- **`docs/GUIDE.md`** (the complete command guide) and **`docs/RELEASING.md`** (release runbook).
+- **Repo automation** — `repo-settings.yml` (About/topics/Discussions as code) and `labels.yml` (label sync) workflows; a Codex plugin manifest and `cognitive-substrate` skill; the paper bundle under `docs/cognitive-substrate/`.
 
 ### Changed
 
-- **Substrate now auto-runs in Claude Code.** The `UserPromptSubmit` hook injects the full substrate advisory (assumption gate + model routing + blast radius + memory + verify) when it matters, silent otherwise. Load-only — never builds/writes `.forge/` from a hook, fail-safe, never blocks.
-- **Cross-tool auto-use.** Added a `substrate` section to `source/rules.json` so `forge init` emits the "run substrate before risky work" rule into every tool's config (AGENTS.md, .cursor/rules, …).
-- **Docs rewritten** — `docs/cognitive-substrate/README.md` is a professional, example-rich guide (real command output, auto-use setup, extension points); README/SKILL aligned.
-- **README restructured** to a professional standard — clear value prop, an install matrix, quickstart, a "how it works" three-layer table, an auto-use section, a full command list, honest limits, and a docs index.
-- **Install story fixed.** The recommended paths are now the **plugin** (Claude Code / Codex) and a token-free CLI install, `npm install -g github:CodeWithJuber/forgekit` — no `curl | bash`, no clone. `bash install.sh` is documented as the symlink/dev path and the GitHub Packages route as CI-only. Updated across README, ONBOARDING, `docs/cognitive-substrate/README.md`, and the landing page.
-- **New `docs/GUIDE.md`** — the complete guide: every command with a worked example and its real output, the everyday workflow, auto-use inside an agent, recipes, and how to extend each layer (rules, tools, guards, crew, routing signals, emitters, rebrand).
-- **Landing page** — install snippet uses the token-free CLI command; version string corrected to 0.3.1.
+- **Publish to public npm.** `@codewithjuber/forgekit` now publishes to npmjs with provenance, so `npm install -g @codewithjuber/forgekit` needs no token (replacing the GitHub Packages route, which required auth even for public installs). The release workflow was fixed to trigger on a tag, publish, and cut a GitHub Release with generated notes.
+- **Substrate auto-runs in Claude Code** via a `UserPromptSubmit` hook — it surfaces only when something needs attention and never blocks — and `forge init` emits a "run substrate before risky work" rule into every other tool's config.
+- **Docs overhaul** — README rewritten (problem → solution → how, npm-first, SEO-friendly); the install, honest-limits, frozen-model, and substrate blocks are single-sourced instead of copied across files; the supported-tool list is reconciled everywhere.
 
 ### Fixed
 
-- **Security (research prototype): removed pickle-based cache** in `impact_oracle/world_model.py` — it was an insecure-deserialization (RCE) vector on a caller-supplied `cache_dir`. Now JSON node-link only, with `cache_dir` containment inside `root`.
-- **Smaller npm package** — stopped publishing `docs/cognitive-substrate` (a ~2 MB whitepaper + zips); tarball dropped to ~280 KB. Removed the redundant `*_src.zip` binaries (source lives unzipped in `research/`).
+- **Security (research prototype):** removed the pickle-based cache in `impact_oracle/world_model.py` — an insecure-deserialization (RCE) vector on a caller-supplied `cache_dir`. Now JSON node-link only, with `cache_dir` contained inside `root`.
+- **Smaller npm package** — stopped publishing the ~2 MB paper bundle and the redundant `*_src.zip` (source lives unzipped under `research/`).
 - **Perf** — `substrateCheck` no longer recomputes the assumption assessment.
 
-### Added
-
-- **Forge Cognitive Substrate** — one pre-action command (`forge substrate`) and MCP surface (`substrate_check`, `predict_impact`, `assumption_gate`) that combines assumption gating, transparent model routing, impact prediction, scope decomposition, Cortex lessons, minimality warnings, and verification planning.
-- **Atlas v2 graph** — dependency nodes/edges, file hashes, and reverse-dependency impact traversal while preserving the old symbol query API.
-- Codex plugin manifest and `cognitive-substrate` skill so Forge can be installed/used from Codex-style extension surfaces as well as Claude/NPM.
-- Cognitive-substrate paper bundle under `docs/cognitive-substrate/`: full PDF/HTML paper, deliverable overview, evidence map, ecosystem map, and original prototype packages.
-
 ## [0.3.1] - 2026-07-05
 
 ### Changed

@@ -1,10 +1,14 @@
 cff-version: 1.2.0
 message: "If you use forgekit, please cite it using this metadata."
-title: forgekit
+title: "Forge (forgekit)"
+version: 0.4.0
+date-released: "2026-07-06"
 abstract: >-
-  One config, every AI coding tool — a cross-tool configuration layer for agentic
-  coding assistants with an independent verification gate, portable memory, a
-  security-vetting skill-gate, and a cost governor.
+  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.
 type: software
 authors:
   - name: CodeWithJuber
@@ -15,4 +19,10 @@ keywords:
   - claude-code
   - agents-md
   - ai-coding
+  - ai-agents
   - cross-tool
+  - cognitive-substrate
+  - mcp
+  - codex
+  - cursor
+  - cli
@@ -65,6 +65,11 @@ diffs with no tests) will be closed. To get merged:
 We'd rather give a clear "not now" than merge something that adds maintenance burden — see
 [GOVERNANCE.md](./GOVERNANCE.md).
 
+## Releasing (maintainers)
+
+Cutting a release is one command plus a tag — the full runbook (and the one-time
+`NPM_TOKEN` setup) is in [docs/RELEASING.md](./docs/RELEASING.md).
+
 ## Sign your work (DCO)
 
 This project uses the [Developer Certificate of Origin](https://developercertificate.org/).