chore(release): 0.4.0 — public npm, docs rewrite, repo automation

[CodeWithJuber]

What & why

An open-source polish pass across the three things that made forgekit read as an early repo, not a finished project — docs, packaging/release, and repo hygiene — done under a ponytail discipline (reuse existing patterns, fewest new files, no runtime-behavior changes).

1. Packaging & release — the real fix for "nothing publishes / tags & releases don't work"

The audit found release.yml had run zero times (the v0.1.0–v0.3.0 tags predated it), so there were no GitHub Releases and no published package, and it used the fragile --notes-from-tag.

• Publish to public npm with provenance instead of GitHub Packages, so npm install -g @codewithjuber/forgekit needs no token. (forgekit unscoped is taken on npm, so the scoped name stays; .npmrc/publishConfig updated.)
• Rewrote release.yml: triggers on v*, npm publish --provenance --access public with NPM_TOKEN + id-token, and gh release create --generate-notes.
• Bumped to 0.4.0 (package.json, lockfile, both plugin manifests) and added docs/RELEASING.md + a CONTRIBUTING pointer.

2. Repo hygiene as committed automation

• .github/workflows/repo-settings.yml — sets the About description, homepage, topics, and enables Discussions.
• .github/labels.yml + .github/workflows/labels.yml — syncs the labels the issue templates, Dependabot, and the stale bot reference.

3. Docs rewrite + de-duplication

• README rewritten: descriptive SEO H1, problem → solution → how, npm-first install, restored npm badge, canonical tool list; the honest-limits and frozen-model blocks are now short summaries + links.
• Single-sourced the blocks that were copied 3–6× (install, honest-limits, --json, extend) into canonical homes; ONBOARDING and the substrate README trimmed to links.
• Reconciled the supported-tool list from src/emit/*.js across every doc (was 8 vs 9 vs 10).
• Trimmed ARCHITECTURE's RFC scaffolding + stale/dropped stats; added Continue + a Roo/VS Code note.
• Correctness fixes: CHANGELOG double-Added merged into a 0.4.0 section; master/main; SECURITY emoji-only table; ROADMAP spec-lock shipped; CITATION version/date-released/keywords; deliverable-package's ~13 dangling artifacts; impact_oracle pickle-cache + F1 (→0.79); router_gate "production-ready" overclaim.

⚠️ Two one-time maintainer steps (not doable from CI)

1. NPM_TOKEN repo secret (npm Automation token) — required before the first publish. Steps in docs/RELEASING.md. Until it exists, only the publish step fails; nothing else breaks.
2. ADMIN_TOKEN (fine-grained PAT, Administration: write) for repo-settings.yml — the default GITHUB_TOKEN can't edit repo settings. The exact gh fallback is inlined in the workflow if you'd rather run it locally once. (The labels workflow needs no PAT.)

After merge I can trigger labels.yml / repo-settings.yml for you, or you can click Run workflow.

Checklist

• npm test passes — 151/151 (no source changed)
• npm run check + npm run typecheck pass
• npm publish --dry-run targets registry.npmjs.org with public access + provenance
• All 5 workflow YAMLs parse; forge init/doctor green at 0.4.0
• Conventional commit; CHANGELOG.md has a 0.4.0 section
• No new runtime dependency

Risk & rollback

• Risk: low — docs, workflows, and packaging metadata only; no runtime code touched. The release workflow can't publish until NPM_TOKEN exists, so nothing publishes by surprise.
• Rollback: revert the commit; the publishing target reverts and the new workflows/docs disappear.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Eh3SNx15EeVbTmU4nH36XC

---

Generated by Claude Code