bmad-module-skill-forge 2.2.0 → 4.0.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "2.2.0",
+      "version": "4.0.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -12,16 +12,16 @@
 [![npm](https://img.shields.io/npm/v/bmad-module-skill-forge)](https://www.npmjs.com/package/bmad-module-skill-forge)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![BMAD Module](https://img.shields.io/badge/BMAD-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
-[![Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue?logo=python&logoColor=white)](https://www.python.org)
+[![Python Version](https://img.shields.io/badge/python-%3E%3D3.11-blue?logo=python&logoColor=white)](https://www.python.org)
 [![uv](https://img.shields.io/badge/uv-package%20manager-blueviolet?logo=uv)](https://docs.astral.sh/uv/)
 [![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-skill-forge/)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
 
-_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to its upstream — a specific `file:line` at a pinned commit when source is available, or a documentation URL when it isn't._
+_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to its upstream: a specific `file:line` at a pinned commit when source is available, or a documentation URL when it isn't._
 
-**If SKF fixes your agent's API guesses, give it a ⭐ — it helps others find this tool.**
-**If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad) — it helps me keep forging.**
+**If SKF fixes your agent's API guesses, give it a ⭐. It helps others find this tool.**
+**If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad). It helps me keep forging.**
 
 </div>
 
@@ -29,7 +29,7 @@ _Skill Forge analyzes your code repositories, documentation, and developer disco
 
 ## The Problem
 
-You ask an AI agent to use a library. It invents function names that don't exist. It guesses parameter types. You paste documentation into the context — it still gets details wrong. You write instructions by hand — they go stale the moment the code changes.
+You ask an AI agent to use a library. It invents function names that don't exist. It guesses parameter types. You paste documentation into the context, and it still gets details wrong. You write instructions by hand, and they go stale the moment the code changes.
 
 This isn't an edge case. It's the default experience.
 
@@ -37,7 +37,7 @@ For the full story behind SKF, read [_Hallucination has a line number_](https://
 
 ## Before vs After
 
-**Without SKF** — your agent guesses:
+**Without SKF**, your agent guesses:
 
 ```python
 import cognee
@@ -46,7 +46,7 @@ import cognee
 results = cognee.search("What does Cognee do?", mode="graph")
 ```
 
-**With SKF** — your agent reads the verified skill:
+**With SKF**, your agent reads the verified skill:
 
 ```python
 import cognee
@@ -60,24 +60,24 @@ results = await cognee.search(
 )
 ```
 
-The skill told the agent the real function name, the real parameters, and that the call is async — all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills) — SKF's reference output. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
+The skill told the agent the real function name, the real parameters, and that the call is async, all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills), SKF's reference output. That skill predates provenance labels that follow the tool: its provenance map records `search` as read by eye, which SKF 3.0.0 cites as `[SRC:...]`, keeping `[AST:...]` for a definition an ast-grep rule matched. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
 
 ## Install
 
-Linux, Windows, and macOS supported ([platform details](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/#platform-support)). Requires [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.10, and [uv](https://docs.astral.sh/uv/) (Python package runner).
+Linux, Windows, and macOS supported ([platform details](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/#platform-support)). Requires [Node.js](https://nodejs.org/) >= 22, [Python](https://www.python.org/) >= 3.11, and [uv](https://docs.astral.sh/uv/) (Python package runner).
 
 ```bash
 npx bmad-module-skill-forge install
 ```
 
-You'll be prompted for project name, output folders, and IDE configuration. When the install completes, open your IDE and invoke `@Ferris SF` to confirm Ferris is reachable. Ferris reports your detected tools and capability tier. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
+You'll be asked for a project name, where to save skills and workspace files, which IDEs you use, and whether to install learning material. When the install completes, open your IDE and start Ferris, the SKF agent. Type `/skf-forger` in Claude Code, Cursor and most other IDEs, or `$skf-forger` in Codex. IDEs that load skills on their own, such as GitHub Copilot, start Ferris when you ask for him. The installer prints the exact command for each IDE you picked. Then give Ferris the menu code `SF`; this page writes that step as `@Ferris SF`. Ferris reports the tools it found and your capability tier, which is how much analysis those tools allow. See the [docs](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/) for other install methods.
 
 ## Quick Start
 
-1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ — detects your tools and sets your capability tier
-2. **Zero-ceremony path:** `@Ferris forge-auto <repo-or-doc-url>` _(Forge-Auto)_ — one command turns a repo or doc URL into a verified skill (auto-scope, auto-brief, 90% quality gate, export)
-3. **Fast path:** `@Ferris QS <package-name>` _(Quick Skill)_ — creates a verified skill in under a minute
-4. **Full quality path:** `@Ferris forge <your-library>` chains Brief → Create → Test → Export automatically — or run manually: `@Ferris BS` _(Brief Skill)_ → clear session → `@Ferris CS` _(Create Skill)_ for maximum control
+1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ detects your tools and sets your capability tier
+2. **Zero-ceremony path:** `@Ferris forge-auto <repo-or-doc-url>` _(Forge-Auto)_ turns a repo or doc URL into a verified skill in one command. It scopes, briefs, compiles, tests and exports on its own. The test aims for a 90% score but still passes a skill that scores 80% or more, and records the shortfall in an evidence report.
+3. **Fast path:** `@Ferris QS <package-name-or-github-url>` _(Quick Skill)_ writes a best-effort skill with no brief and no provenance map. `@Ferris forge-quick <package-name>` also tests and exports it.
+4. **Full quality path:** `@Ferris forge <repo-url> <skill-name>` chains Brief → Create → Test → Export automatically. For maximum control, run the same steps one at a time and start a fresh session before each: `@Ferris BS` _(Brief Skill)_, `@Ferris CS` _(Create Skill)_, `@Ferris TS` _(Test Skill)_, `@Ferris EX` _(Export Skill)_.
 
 For producing **many coordinated skills** across sessions, `@Ferris campaign` _(Campaign)_ orchestrates the whole set with dependency tracking and resume.
 
@@ -90,8 +90,8 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 - **You use AI agents to write code** and they keep guessing API calls wrong
 - **You maintain a library** and want to ship official, verified instruction files so AI agents use your API correctly
 - **You manage a codebase with many dependencies** and want a consolidated "stack skill" that teaches your agent how all the pieces fit together
-- **You use a SaaS API or closed-source tool** with no public code — SKF can generate skills from documentation alone
-- **You need different skills for different use cases** from the same target — compile multiple skills with different scopes from one repo or doc set (e.g., a core API skill and a migration guide skill)
+- **You use a SaaS API or closed-source tool** with no public code: SKF can generate skills from documentation alone
+- **You need different skills for different use cases** from the same target: compile multiple skills with different scopes from one repo or doc set (e.g., a core API skill and a migration guide skill)
 
 ## How SKF Compares
 
@@ -100,68 +100,68 @@ A skeptical reader is probably already considering one of these alternatives:
 |                            | **Skill Forge**                           | MCP doc servers   | Hand-edited `.cursorrules` | awesome-\* lists |
 | -------------------------- | ----------------------------------------- | ----------------- | -------------------------- | ---------------- |
 | Reproducible from upstream | AST + pinned commit (or pinned doc URL)   | varies; opaque    | whatever you wrote         | none             |
-| Version-pinned & immutable | yes — per-version directories             | runtime-dependent | rots silently              | no               |
+| Version-pinned & immutable | yes, per-version directories              | runtime-dependent | rots silently              | no               |
 | Audit trail                | `provenance-map.json` + test + evidence   | depends on server | none                       | none             |
 | Runtime cost               | zero (markdown + JSON)                    | a running process | zero                       | zero             |
 | Lifecycle tooling          | rename, drop, update, export transactions | varies            | file surgery               | none             |
-| Falsifiable                | yes — three steps, 60 seconds             | rarely            | no                         | no               |
+| Falsifiable                | yes, three steps, 60 seconds              | rarely            | no                         | no               |
 
 The others aren't bad. They solve different problems. **SKF solves exactly one: the claim your agent is reading about a library was true at a specific commit on a specific day, and you can prove it in under a minute.**
 
 ## How Skill Forge Fixes This
 
-SKF extracts real function signatures, types, and patterns from code, docs, and developer discourse — every instruction links to the exact file and line it came from. On top of that foundation:
+SKF extracts real function signatures, types, and patterns from code, docs, and developer discourse. Every instruction cites where it came from: the exact file and line for code, or the source document for docs and discussions. On top of that foundation:
 
-1. **Version-pinned** — skills are stored per-version, so updating to v2.0 doesn't replace your v1.x skill. Compatible with [skills.sh](https://skills.sh) and [npx skills](https://www.npmjs.com/package/skills)
-2. **Lifecycle tooling** — rename skills and drop deprecated versions without manual file surgery. Destructive operations are transactional.
-3. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
+1. **Version-pinned:** skills are stored per-version, so updating to v2.0 doesn't replace your v1.x skill. Compatible with [skills.sh](https://skills.sh) and [npx skills](https://www.npmjs.com/package/skills)
+2. **Lifecycle tooling:** rename a skill, or deprecate or delete one version or the whole skill, without manual file surgery. Destructive operations are transactional.
+3. **Follows an open standard:** skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
 
-> **Every skill ships two files — `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index that the export step injects into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, passive context achieves a **100% pass rate vs. 79% for active skills loaded alone** (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
+> **Every skill ships two files: `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index that the export step injects into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, a docs index in passive context reached a **100% pass rate**, while skills reached **79%** only when the agent was told to use them, and 53% when it decided on its own (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
 
 ## Verifying a Skill
 
-You can falsify any citation in an SKF-compiled skill in under a minute:
+You can falsify any citation in an SKF-compiled skill in under a minute. Quick Skill output is the exception: it keeps no provenance map, so this audit does not apply to it.
 
-1. **Open the skill's `provenance-map.json`** — find your symbol; read its `source_file` and `source_line`.
-2. **Open the skill's `metadata.json`** — read `source_commit` and `source_repo`.
+1. **Open the skill's `provenance-map.json`** in the forge workspace (`forge-data/<skill>/<version>/` by default, not the skill folder). Find your symbol under `export_name` and read its `source_file` and `source_line`.
+2. **Open the skill's `metadata.json`** (next to its `SKILL.md`) and read `source_commit` and `source_repo`.
 3. **Jump to the upstream repo at that commit**, open that file, find that line. The signature in `SKILL.md` should match the one you're reading.
 
-For docs-only skills, the audit shape is the same — `provenance-map.json` still lists every symbol — but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
+For docs-only skills, the audit shape is the same: `provenance-map.json` still lists every symbol, but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
 
-If it doesn't, that's a bug — open an issue and SKF will republish the skill with a fresh provenance map (a new commit SHA for source skills, a fresh fetch for docs-only). Falsifiability isn't a feature; it's the whole deal.
+If it doesn't, that's a bug. Open an issue and SKF will republish the skill with a fresh provenance map (a new commit SHA for source skills, a fresh fetch for docs-only). Falsifiability isn't a feature; it's the whole deal.
 
-**Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores range from 99.0% to 99.49%. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and ongoing proof that the pipeline does what it says.
+**Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills).** It holds four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores range from 99.0% to 99.49%. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and ongoing proof that the pipeline does what it says.
 
 ## Help SKF Improve
 
-Workflows end with a health check that files bug reports as GitHub issues (auto-deduped by fingerprint — re-reporting is safe); friction notes go to a local queue you can opt in to submit live. **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
+Every workflow ends with a health check. If it finds a problem in SKF's own instructions, it shows you the findings and, only if you approve, files bug reports as GitHub issues. Duplicates are detected, so reporting a known problem again is safe. Friction notes and gaps go to a local queue unless you choose to submit them too. **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
 
 ## Learn More
 
-The docs are organized into three buckets — **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
+The docs are organized into three buckets: **Why** (start here), **Try** (do stuff), and **Reference** (look things up):
 
 **Why**
 
-- **[Why Skill Forge?](https://armelhbobdad.github.io/bmad-module-skill-forge/why-skf/)** — The JTBD pitch, persona router, and the honest anti-pitch
-- **[Verifying a Skill](https://armelhbobdad.github.io/bmad-module-skill-forge/verifying-a-skill/)** — The 60-second audit recipe and scoring formula
+- **[Why Skill Forge?](https://armelhbobdad.github.io/bmad-module-skill-forge/why-skf/)**: What SKF is for, who it suits, and when it is the wrong tool
+- **[Verifying a Skill](https://armelhbobdad.github.io/bmad-module-skill-forge/verifying-a-skill/)**: The 60-second audit recipe and scoring formula
 
 **Try**
 
-- **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Install, first skill, prereqs, and config
-- **[Forge-Auto](https://armelhbobdad.github.io/bmad-module-skill-forge/forge-auto/)** — The zero-ceremony path: one command from a repo or doc URL to a verified skill
-- **[Campaign](https://armelhbobdad.github.io/bmad-module-skill-forge/campaign/)** — Orchestrate many coordinated skills across sessions with dependency tracking and resume
-- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Plain-English walkthrough of one skill being built, end to end
-- **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios with full command transcripts
-- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 15 workflows with commands and connection diagrams
+- **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)**: Install, first skill, prereqs, and config
+- **[Forge-Auto](https://armelhbobdad.github.io/bmad-module-skill-forge/forge-auto/)**: The zero-ceremony path, one command from a repo or doc URL to a verified skill
+- **[Campaign](https://armelhbobdad.github.io/bmad-module-skill-forge/campaign/)**: Orchestrate many coordinated skills across sessions with dependency tracking and resume
+- **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)**: Plain-English walkthrough of one skill being built, end to end
+- **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)**: Real-world scenarios with full command transcripts
+- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)**: All 15 workflows with commands and connection diagrams
 
 **Reference**
 
-- **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Seven load-bearing terms: provenance, confidence tiers, drift, and more
-- **[Architecture](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)** — Runtime flow, 7 tools, workspace artifacts, security, and the design decisions behind them
-- **[Skill Model](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/)** — Capability tiers, confidence tiers, output format, dual-output strategy, ownership model
-- **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the single AI agent that runs every SKF workflow
-- **[BMAD Synergy](https://armelhbobdad.github.io/bmad-module-skill-forge/bmad-synergy/)** — How SKF pairs with BMAD CORE phases and optional modules (TEA, BMB, GDS, CIS)
-- **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-skill-forge/troubleshooting/)** — Common errors (forge setup, ecosystem checks, tier confidence) and how to resolve them
+- **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)**: Seven key terms, including provenance, confidence tiers and drift
+- **[Architecture](https://armelhbobdad.github.io/bmad-module-skill-forge/architecture/)**: Runtime flow, 7 tools, workspace artifacts, security, and the design decisions behind them
+- **[Skill Model](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/)**: Capability tiers, confidence tiers, output format, dual-output strategy, ownership model
+- **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)**: Ferris, the single AI agent that runs every SKF workflow
+- **[BMAD Synergy](https://armelhbobdad.github.io/bmad-module-skill-forge/bmad-synergy/)**: How SKF pairs with the BMAD Method's four phases and its optional modules: Test Architect (TEA), BMAD Builder (BMB), Game Dev Studio (GDS) and Creative Intelligence Suite (CIS)
+- **[Troubleshooting](https://armelhbobdad.github.io/bmad-module-skill-forge/troubleshooting/)**: Common errors (forge setup, skill briefs, tier confidence, run locks, campaigns) and how to resolve them
 
 ## Acknowledgements
 
@@ -173,11 +173,11 @@ SKF builds on these excellent open-source tools:
 | [GitHub CLI](https://cli.github.com/)                            | Source code access and repository intelligence (all tiers)             |
 | [ast-grep](https://github.com/ast-grep/ast-grep)                 | AST-based structural code extraction (Forge/Forge+/Deep tiers)         |
 | [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)         | MCP server for memory-efficient AST queries (recommended)              |
-| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)      |
+| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file pre-ranking (Forge+; optional on Deep)   |
 | [QMD](https://github.com/tobi/qmd)                               | Local hybrid search engine for knowledge indexing (Deep tier)          |
 | [skill-check](https://github.com/thedaviddias/skill-check)       | Skill validation, auto-fix, quality scoring, and security scanning     |
 | [Snyk Agent Scan](https://github.com/snyk/agent-scan)            | Security scanning for prompt injection and data exposure (optional)    |
-| [tessl](https://tessl.io)                                        | Content quality review, actionability scoring, and AI judge evaluation |
+| [tessl](https://tessl.io)                                        | Opt-in Tessl Review: AI-judge scoring of description and content       |
 | [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD)      | Agent-workflow framework that SKF extends as a module                  |
 
 ## Contributing
@@ -190,11 +190,11 @@ Past releases are documented in [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 
-MIT License — see [LICENSE](LICENSE) for details.
+MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 
-**Skill Forge (SKF)** — A standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
+**Skill Forge (SKF)**: a standalone [BMAD](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
 
 [![Contributors](https://contrib.rocks/image?repo=armelhbobdad/bmad-module-skill-forge)](https://github.com/armelhbobdad/bmad-module-skill-forge/graphs/contributors)
 

package/docs/404.md

@@ -1,23 +1,25 @@
 ---
 title: Page Not Found
-description: The URL you tried didn't resolve. Use the search or the links below to continue.
+description: There is no page at this address. Use search or the links below to find what you need.
 template: splash
 ---
 
-## 404 — no source cited
+## 404: no page at this address
 
-No page resolves to that URL. In keeping with the rest of this site, if a claim can't cite a source, we don't fake it — even for our own docs.
+There is no page at this address. This site has one rule for every claim: if it can't cite a source, we don't make it up. That goes for our own pages too, so we won't guess where you meant to go.
 
-Try one of these cited sources instead, or use the **search bar** at the top of the page:
+Try one of these pages instead, or use **Search** at the top of the page:
 
-**Why** — [Why Skill Forge?](/docs/why-skf.md) · [Verifying a Skill](/docs/verifying-a-skill.md)
+**Why:** [Why Skill Forge?](/docs/why-skf.md) · [Verifying a Skill](/docs/verifying-a-skill.md)
 
-**Try** — [Getting Started](/docs/getting-started.md) · [How It Works](/docs/how-it-works.md) · [Examples](/docs/examples.md) · [Workflows](/docs/workflows.md)
+**Try:** [Getting Started](/docs/getting-started.md) · [Forge-Auto](/docs/forge-auto.md) · [Campaign](/docs/campaign.md) · [How It Works](/docs/how-it-works.md) · [Examples](/docs/examples.md) · [Workflows](/docs/workflows.md)
 
-**Reference** — [Concepts](/docs/concepts.md) · [Architecture](/docs/architecture.md) · [Skill Model](/docs/skill-model.md) · [Agents](/docs/agents.md) · [BMAD Synergy](/docs/bmad-synergy.md) · [Troubleshooting](/docs/troubleshooting.md)
+**Reference:** [Concepts](/docs/concepts.md) · [Architecture](/docs/architecture.md) · [Skill Model](/docs/skill-model.md) · [Agents](/docs/agents.md) · [BMAD Synergy](/docs/bmad-synergy.md) · [Troubleshooting](/docs/troubleshooting.md)
+
+Or start over from the [home page](/docs/index.md).
 
 ---
 
 ### Think this page should exist?
 
-A missing page is drift — a citation the docs site made to itself that no longer resolves. [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) with the URL you tried. SKF's docs ship a [drift validator](/docs/verifying-a-skill.md#build-time-drift-detection-for-docs-themselves) that catches exactly this pattern — if one slipped through, it's a bug we want to know about.
+If a link on this site sent you here, that is a bug. Every change to these docs goes through a check that builds the site and confirms each link between our own pages leads to a real page, so a broken link should never ship. If one did, [open a bug report](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) with the URL you tried and the page that linked you here. If you typed the address, or followed a bookmark or a link from another site, the page may have moved or been renamed: search is the quickest way to find it.

package/docs/_data/pinned.yaml

@@ -1,4 +1,4 @@
-# Skill Forge — Pinned Canonical Anchors
+# Skill Forge: Pinned Canonical Anchors
 #
 # This file is the SINGLE SOURCE OF TRUTH for every version number, commit
 # SHA, and library reference that the docs cite about oh-my-skills, the
@@ -8,8 +8,11 @@
 # entry here and then run `npm run docs:validate-drift` from the SKF repo
 # root. The script will:
 #
-#   1. Verify every skill below actually exists at the claimed version and
-#      commit in $OMS/skills/<name>/<version>/<name>/metadata.json
+#   1. Verify every skill below exists at the claimed version in
+#      $OMS/skills/<name>/<version>/<name>/metadata.json, and that its
+#      version, source_commit, confidence_tier and source_authority match.
+#      The other fields (source_repo, source_ref, upstream_commit_date,
+#      test_score, test_mode, language) are not checked.
 #   2. Grep every docs/*.md for stale version strings and flag any that
 #      disagree with the anchors
 #
@@ -17,25 +20,29 @@
 # then fix the docs until the check is clean.
 #
 # Do NOT edit docs/*.md version references without updating this file
-# first — the drift check will catch you. That's the point.
+# first. The drift check catches the mismatch when you run it. That's the point.
 #
 # File ignored by Astro/Starlight content collections because the parent
-# directory starts with `_`. It is purely a build-time / CI-time anchor.
+# directory starts with `_`. Nothing reads it at build time: only
+# tools/validate-docs-drift.js checks it, and release.yaml rewrites
+# skf_version. CI does not run the drift check, and the check needs a local
+# oh-my-skills checkout, so run `npm run docs:validate-drift` yourself.
 
-# SKF package version — matches the `version` field in package.json.
+# SKF package version: matches the `version` field in package.json.
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "2.2.0"
+skf_version: "4.0.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills
 # lives elsewhere on your machine.
 oh_my_skills_path: "../oh-my-skills"
 
-# Every oms-* skill currently shipped in oh-my-skills. The library key
-# (e.g. cognee) is the user-facing library name; the entry key is the
-# skill package name (oms-<library>).
+# Every oms-* skill currently shipped in oh-my-skills. The `library` field
+# (e.g. cognee) is the library name the docs use, and the drift check
+# searches docs/*.md for it. The entry key is the skill package name, usually
+# oms-<library>; oms-storybook-react-vite covers the storybook library.
 skills:
   oms-cognee:
     library: cognee
@@ -90,9 +97,11 @@ skills:
     language: "typescript"
 
 # Libraries that are mentioned in docs as illustrative examples but don't
-# have a corresponding oms-* skill. The drift check IGNORES version
-# mentions for these libraries — they're allowed to drift because they're
-# illustration, not canonical.
+# have a corresponding oms-* skill. Their versions are allowed to drift
+# because they're illustration, not canonical. The drift check only searches
+# for the `library` names under skills, so it already ignores every other
+# library. This list matters only if one of these gains a skill: it then
+# hides that library's drift until you remove it here.
 illustrative_libraries:
   - better-auth
   - hono

package/docs/_internal/STABILITY.md

@@ -1,15 +1,17 @@
 ---
 title: SKF Stability & Public API Contract
-description: What SemVer covers at v1.0.0 — the surfaces downstream consumers may pin against, and the surfaces explicitly excluded.
+description: Which SKF surfaces SemVer covers, so that downstream consumers can pin against them, and which surfaces it excludes.
 ---
 
-> **Status:** STABLE — locked at v1.0.0. Amendments follow the "Changes to This Contract" section below.
+> **Status:** Stable. This contract took effect at v1.0.0 and was last amended at v3.0.0. Amendments follow [§ Changes to This Contract](#changes-to-this-contract), which also records what each one changed.
 
-This document is the public API contract for `bmad-module-skill-forge` at v1.0.0. It enumerates exactly which SKF surfaces [Semantic Versioning 2.0.0](https://semver.org/) covers and which are explicitly `@internal`. The goal is that a downstream consumer pinning `"bmad-module-skill-forge": "^1.0.0"` can identify — unambiguously — whether a given SKF change is breaking, additive, or internal. Breaking changes to covered surfaces require a major-version bump; additive changes to covered surfaces are minor bumps; changes to `@internal` surfaces are free to land in any release.
+This document is the public API contract for `bmad-module-skill-forge`. It enumerates exactly which SKF surfaces [Semantic Versioning 2.0.0](https://semver.org/) covers and which are explicitly `@internal`. The goal is that a downstream consumer pinning `"bmad-module-skill-forge": "^3.0.0"` can identify, unambiguously, whether a given SKF change is breaking, additive, or internal. Breaking changes to covered surfaces require a major-version bump; additive changes to covered surfaces are minor bumps; changes to `@internal` surfaces are free to land in any release, apart from the parts the release check reviews (see [§ @internal: Not Covered by SemVer](#internal--not-covered-by-semver)).
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119), [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)) when, and only when, they appear in all capitals, as shown here.
 
 ## Covered Surfaces
 
-The five buckets below are the entirety of the v1.0.0 public surface. Anything not explicitly listed here is `@internal` (see [§ @internal — Not Covered by SemVer](#internal--not-covered-by-semver)).
+The buckets below are the entirety of the public surface. Anything not explicitly listed here is `@internal` (see [§ @internal: Not Covered by SemVer](#internal--not-covered-by-semver)).
 
 ### CLI Command Surface
 
@@ -17,19 +19,19 @@ The CLI is invoked via `npx bmad-module-skill-forge <subcommand>` (one-shot) or
 
 - **Subcommands**: `install`, `update`, `status`, `uninstall`. Renaming, removing, or changing the semantics of any subcommand is breaking.
 - **Options**: `-V, --version` (top-level; prints the installed package version), `-h, --help` (top-level and per-subcommand; prints help output — commander-provided). Both are covered.
-- **Per-subcommand flags (other than `-h/--help`)**: none are currently part of the v1.0.0 surface. Adding a new flag is additive (minor); removing or renaming a flag once added would be breaking.
+- **Per-subcommand flags (other than `-h/--help`)**: none are currently part of this contract. Adding a new flag is additive (minor); removing or renaming a flag once added would be breaking.
 - **Exit codes**: `0` on success — including user-cancel of `install` (Ctrl-C at a prompt or explicit decline at a confirm step) and "nothing to do" paths on `uninstall`; `1` on unhandled failure. Only `0` and `1` are reserved today; introducing additional exit-code values in the future is additive (minor) and will be called out in `CHANGELOG.md`.
-- **`npm run skf:*` script aliases**: `skf:install`, `skf:update`, `skf:status`, `skf:uninstall` in `package.json` are the post-install convenience entry points. Renaming or removing any `skf:*` script is breaking. (Note: `release:*` scripts are NOT part of this contract — they are internal-to-maintainers and are being retired across Epic 4 and Epic 6.)
+- **`npm run skf:*` script aliases**: `skf:install`, `skf:update`, `skf:status`, `skf:uninstall` in `package.json` are the post-install convenience entry points. Renaming or removing any `skf:*` script is breaking.
 
 ### Programmatic API of `tools/cli/skf-cli.js`
 
-`tools/cli/skf-cli.js` is the CLI logic for `npx bmad-module-skill-forge` (invoked via a thin `bin` wrapper at `tools/skf-npx-wrapper.js` that execs `skf-cli.js`) and for `npm run skf:<subcommand>`. Though `package.json`'s `main` field points at `skf-cli.js`, it has **no programmatic export surface**. The file runs commander setup and calls `program.parse(process.argv)` as top-level side effects; it has no `module.exports` block. A `require('bmad-module-skill-forge')` from Node runs the CLI parser against the caller's `process.argv` — not a supported usage.
+`tools/cli/skf-cli.js` is the CLI logic for `npx bmad-module-skill-forge` (invoked through a thin `bin` wrapper at `tools/skf-npx-wrapper.js` that runs `skf-cli.js`) and for `npm run skf:<subcommand>`. It has **no programmatic export surface**: the file runs commander setup and calls `program.parse(process.argv)` as top-level side effects, and it has no `module.exports` block. `package.json` declares no `main` field, so a `require('bmad-module-skill-forge')` from Node finds no entry point and throws `MODULE_NOT_FOUND`; requiring the package is not a supported usage.
 
-Programmatic embedding of SKF is explicitly `@internal` at v1.0.0. If a programmatic API is ever added, it will be introduced via an explicit `module.exports` block and a minor version bump (additive).
+Programmatic embedding of SKF is explicitly `@internal`. If a programmatic API is ever added, it will be introduced through an explicit entry point in `package.json` and a `module.exports` block, with a minor version bump (additive).
 
 ### Skill Manifest & Frontmatter Contract
 
-**`SKILL.md` frontmatter.** SKF-shipped `SKILL.md` files conform to the [agentskills.io minimal frontmatter spec](https://github.com/agentskills/agentskills). Required fields are `name` (kebab-case) and `description` (one-line natural-language summary that terminates with an explicit trigger phrase — see the `src/skf-*/SKILL.md` files in this repo for live examples). SKF does NOT extend the agentskills.io spec; there are no SKF-specific frontmatter fields. If the agentskills.io spec evolves, SKF tracks upstream rather than forking.
+**`SKILL.md` frontmatter.** SKF-shipped `SKILL.md` files conform to the [agentskills.io minimal frontmatter spec](https://github.com/agentskills/agentskills). Required fields are `name` (kebab-case) and `description`, a natural-language summary of at most 1024 characters that contains a `Use when` or `Use if` trigger clause, anywhere in the text and in any letter case, in which every quoted trigger names its object (`"drop a skill"`, never a bare verb such as `"drop"` or `"set up"`). Rule `SKILL-06` of [`tools/validate-skills.js`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/tools/validate-skills.js) checks the length, the clause and the triggers; the `src/skf-*/SKILL.md` files in this repository are live examples. SKF does not extend the agentskills.io spec; there are no SKF-specific frontmatter fields. If the agentskills.io spec evolves, SKF tracks upstream rather than forking.
 
 **`bmad-skill-manifest.yaml` schema.** The agent-type skill manifest shape SKF uses is validated by a zod schema. A simplified transcription (see the live source on GitHub for exact error-map options and inline comments):
 
@@ -57,67 +59,88 @@ The schema is strict — unknown keys are rejected. Renaming or removing a requi
 
 When a consumer runs `skf install` in a project, SKF creates or modifies the following on-disk paths (some names are configurable at install time; defaults are shown). Renaming any path, changing a path's semantics, or removing a path from this list is breaking.
 
-- `_bmad/skf/` — SKF module files.
-- `_bmad/_config/skf-manifest.yaml` — install manifest. Format per `tools/cli/lib/manifest.js`; covered top-level keys: `version` (equals the SKF package version at install time — downstream tooling may read it to detect the installed SKF version), `installed_at`, `action`, `module`, `skf_folder`, `ides`, `skills_output_folder`, `forge_data_folder`, `directories[]`, `files.{skf,sidecar,ide_skills,learning,output}`. Downstream tooling that introspects an SKF install (e.g. to detect installed IDEs or list installed skills) reads this file; its top-level shape is the v1.0.0 contract.
-- `_bmad/_memory/forger-sidecar/` — Ferris agent runtime state directory. The directory's existence and location are covered. File formats inside are `@internal` (not a downstream-consumable schema); `skf update` round-trips sidecar state between SKF versions — see `skf update` in [§ User-Facing Command Output Formats](#user-facing-command-output-formats) for the state-preservation commitment.
-- `_skf-learn/` — optional learning material; created only when the user opts into learning at install time.
-- `{skills_output_folder}/` — default `skills/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
-- `{forge_data_folder}/` — default `forge-data/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
-- `.gitignore` at project root — SKF appends `_bmad/_memory/` as an ignore entry (or creates the file if absent). Existing content is preserved; if the entry is already present, the file is left untouched. The appended entry name is part of the contract.
-- **Per-IDE skill directories.** SKF installs skills to each configured IDE's conventional skills directory. The IDE → directory mapping is enumerated in `tools/cli/lib/platform-codes.yaml` under `platforms.<ide>.installer.target_dir`; the `platforms.<ide>.installer.target_dir` mapping is part of the v1.0.0 contract (other keys in that file are `@internal`). Renaming `platforms.*` or `installer.target_dir` is breaking; removing a platform's `target_dir` is breaking for consumers of that IDE; adding a new platform entry is additive (minor).
+- `_bmad/skf/`: SKF module files.
+- `_bmad/_config/skf-manifest.yaml`: install manifest. Format per `tools/cli/lib/manifest.js`; covered top-level keys: `version` (equals the SKF package version at install time; downstream tooling MAY read it to detect the installed SKF version), `installed_at`, `action`, `module`, `skf_folder`, `ides`, `skills_output_folder`, `forge_data_folder`, `directories[]`, `files.{skf,sidecar,ide_skills,learning,output}`. Downstream tooling that introspects an SKF install (e.g. to detect installed IDEs or list installed skills) reads this file; its top-level shape is part of this contract.
+- `_bmad/_memory/forger-sidecar/`: Ferris agent runtime state directory. The directory's existence and location are covered. File formats inside are `@internal` (not a downstream-consumable schema); `skf update` round-trips sidecar state between SKF versions (see `skf update` in [§ User-Facing Command Output Formats](#user-facing-command-output-formats) for the state-preservation commitment).
+- `_skf-learn/`: optional learning material; created only when the user opts into learning at install time.
+- `{skills_output_folder}/`: default `skills/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
+- `{forge_data_folder}/`: default `forge-data/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
+- `.gitignore` at project root: SKF appends `_bmad/_memory/` as an ignore entry (or creates the file if absent). Existing content is preserved; if the entry is already present, the file is left untouched. The appended entry name is part of the contract.
+- **Per-IDE skill directories.** SKF installs skills to each configured IDE's conventional skills directory. The IDE → directory mapping is enumerated in `tools/cli/lib/platform-codes.yaml` under `platforms.<ide>.installer.target_dir`; the `platforms.<ide>.installer.target_dir` mapping is part of this contract (other keys in that file are `@internal`). Renaming `platforms.*` or `installer.target_dir` is breaking; removing a platform's `target_dir` is breaking for consumers of that IDE; adding a new platform entry is additive (minor).
 
 ### User-Facing Command Output Formats
 
-The v1.0.0 contract commits to the **information each command outputs** and to **exit-code semantics**, not to exact human-readable wording, ANSI color choices, or console layout. Downstream tooling that needs structured introspection of an install should read `_bmad/_config/skf-manifest.yaml` directly (see [§ Installation Layout](#installation-layout)), which IS committed verbatim.
+This contract commits to the **information each command outputs** and to **exit-code semantics**, not to exact human-readable wording, ANSI color choices, or console layout. Downstream tooling that needs structured introspection of an install SHOULD read `_bmad/_config/skf-manifest.yaml` directly (see [§ Installation Layout](#installation-layout)), which is committed verbatim.
 
 - **`skf status`** SHALL convey: installation-present boolean, installed version string, forge-tier name (or a "not detected" equivalent), configured IDE list, workflow-skill count, sidecar state, and output-folder paths. Exit `0` on success; `1` on unhandled failure.
 - **`skf install`** SHALL exit `0` on successful install and on user-cancel (Ctrl-C at a prompt or explicit decline at a confirm step); `1` on unhandled failure. The success path SHALL emit a success confirmation.
 - **`skf update`** SHALL exit `0` on successful update and on "nothing to do" (no prior install detected); `1` on unhandled failure. `skf update` aims to preserve existing config and sidecar state across SKF versions; breaking migrations, when needed, will be called out in `CHANGELOG.md`.
 - **`skf uninstall`** SHALL exit `0` on successful removal, on "nothing to do" (no prior install detected), and on user-declined confirmation. Exit `1` on unhandled failure.
 
-Explicit non-commitments: ANSI color choices, exact prose wording, precise layout of tables or lists, and i18n prose variations are `@internal` and may change in minor releases.
+Explicit non-commitments: ANSI color choices, exact prose wording, precise layout of tables or lists, and i18n prose variations are `@internal` and MAY change in minor releases.
 
 ### Engine & Platform Compatibility
 
 SKF supports the Node.js major versions declared in `package.json` `engines.node` (currently `>=22.0.0`). Dropping a supported major is breaking; adding support for a new major is additive. Linux, macOS, and Windows are supported runtime platforms; dropping OS support is breaking. Adding support for a new platform is additive.
 
-## @internal — Not Covered by SemVer
+The external tools SKF runs have minimum versions too, in `src/shared/tool-requirements.yaml` (installed as `_bmad/skf/shared/tool-requirements.yaml`), such as ast-grep >= 0.45.3 and git >= 2.15; a tool whose `minimum` is null has none. `skf install`, `skf update` and `skf status` report each tool against its minimum, and `skf-setup` counts no tier tool below its minimum toward the capability tier. Raising a tool's minimum, or giving a tool a minimum it did not have, is breaking. Lowering or removing a minimum is additive. Changing a tool's `tested` versions is neither. The release check compares these minimums with the last stable release, as it does the items of [§ Workflow Contract Surfaces](#workflow-contract-surfaces): a raised or new minimum needs a major release and a breaking change fragment that names the tool.
+
+### Workflow Contract Surfaces
 
-The following surfaces are explicitly excluded from the v1.0.0 contract. Changes to any of these may land in any release — patch, minor, or major — without constituting a "breaking change" from a SemVer perspective. Downstream consumers SHOULD NOT pin against these surfaces.
+These are the parts of SKF's workflows that pipelines, scripts and saved Ferris commands depend on by name. Removing or renaming any item below is breaking (major), and adding one is additive (minor); for a flag, removing it means what the **Workflow flags** entry says:
 
-- **`tools/cli/lib/*` internal helper modules** — implementation detail of the CLI; not a library. Any refactor that preserves the observable CLI surface and install layout above is allowed.
-- **Internal structure of workflow step files under `src/skf-*/references/`** — the workflow authoring format is an SKF-internal authoring surface; step numbering, file names, and prose can change.
-- **`_bmad/_memory/forger-sidecar/*.yaml` file schemas** — Ferris sidecar state. Stable as a runtime contract between SKF versions during one install's lifetime (so `skf update` works), but not a downstream-consumable schema.
-- **Ferris agent persona prose and menu wording** — the in-product agent persona can be rephrased or restructured at any time.
-- **Exact chalk styling / ANSI color choices in command output** — stylistic; see the output-format bucket above for what IS committed.
-- **Internal logic of the `Installer` class in `tools/cli/lib/installer.js`** — private implementation; what's covered is the observable install layout, not how the files get there.
-- **Workflow `{communication_language}` / `{document_output_language}` template substitution** — an authoring convenience for workflow prose; the mechanism is internal.
-- **Knowledge-base contents under `src/knowledge/` and `src/skf-*/references/`** — evolving reference material, not a schema.
-- **Test fixtures and test file layout under `test/`** — test organization is internal (except `test/schema/**`, which defines schemas covered by [§ Skill Manifest & Frontmatter Contract](#skill-manifest--frontmatter-contract)).
-- **Build and docs tooling (`tools/build-docs.js`, `website/`)** — internal build pipeline for the Starlight docs site; not a consumer surface.
-- **`_bmad-output/` planning-artifact layout** — gitignored and never distributed; not shipped in the npm package.
+- **Schema enum values and properties.** Every enum value and every property in the JSON schemas directly under `src/shared/scripts/schemas/` (installed under `_bmad/skf/shared/scripts/schemas/`): the skill brief, workspace detection, and the headless result envelope of every workflow, covered from 3.0.0 with its `status`, `exit_code` and `halt_reason` values and its properties: `skf-analyze-source` (`skf-analyze-result-envelope.v1.json`), `skf-audit-skill` (`skf-audit-result-envelope.v1.json`, whose `halt_reason` values include `helper-missing`, `provenance-invalid`, `source-unreadable` and `no-baseline`, and whose properties include `upstream_moved` and `upstream_ref`), `skf-brief-skill` (`skf-brief-result-envelope.v1.json`), `skf-campaign` (`skf-campaign-result-envelope.v1.json`), `skf-create-skill` (`skf-create-skill-result-envelope.v1.json`), `skf-create-stack-skill` (`skf-stack-result-envelope.v1.json`, whose `halt_reason` values include `helper-missing`, and whose properties include `run_id`, `result_path`, `headless_decisions` and `warnings`), `skf-drop-skill` (`skf-drop-skill-result-envelope.v1.json`), `skf-export-skill` (`skf-export-result-envelope.v1.json`), `skf-quick-skill` (`skf-quick-skill-result-envelope.v1.json`), `skf-refine-architecture` (`skf-refine-architecture-result-envelope.v1.json`), `skf-rename-skill` (`skf-rename-skill-result-envelope.v1.json`), `skf-setup` (`skf-setup-result-envelope.v1.json`), `skf-test-skill` (`skf-test-result-envelope.v1.json`), `skf-update-skill` (`skf-update-result-envelope.v1.json`) and `skf-verify-stack` (`skf-verify-stack-result-envelope.v1.json`). For example, the `status` values of `skf-setup-result-envelope.v1.json`.
+- **Ferris menu codes.** The codes in the Code column of the Capabilities table in `src/skf-forger/SKILL.md`, such as `SF`, `CS` and `CA`. The descriptions beside them stay `@internal`.
+- **Pipeline aliases.** The aliases in the alias table of `src/shared/references/pipeline-contracts.md`, such as `forge-auto` and `maintain`. An alias named on a "Deprecated alias:" line there still works and stays covered, so deprecating one is not breaking; removing it is. The rest of that file stays `@internal`.
+- **Workflow flags.** Every flag, such as `--headless` and `--dry-run`, written in the Flags, Inputs, Headless inputs, Headless flag or Overrides row of a workflow's `SKILL.md` (`src/skf-<name>/SKILL.md`) or of its `references/invocation-contract.md` (where a headless contract moved out of `SKILL.md` keeps its rows), per workflow. A row moved from one of these files to the other moves no flag. A flag counts when it opens a backticked span, such as `--tier=<Quick>`, or is a long flag written without backticks, such as `--batch`. A flag written only elsewhere in those files, or only inside a longer backticked command such as `campaign resume [--from=<skill>]`, is not covered. A flag that enters a flag row is added, even when the workflow's files named it before. A covered flag is removed, and so breaking, when the Markdown of its workflow (`SKILL.md`, `references/`, `templates/` and `assets/`) no longer names it; a mention in a command that runs another program, in an argument the workflow hands to a helper script, or in a note that the flag was renamed or removed does not count. A flag that leaves every flag row while that Markdown still names it is listed for review at release time instead, unless a flag the workflow never named before enters its rows in the same release: that may be a rename, so it counts as a removal.
+
+Each release checks this bucket mechanically: [`tools/covered-surfaces.js`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/tools/covered-surfaces.js) compares these items with the last stable release, and the release workflow refuses a release that removes one unless it is a major release whose notes name the item. The same check also reports the workflow exit codes and the `halt_reason` and `error.phase` values written in the step files, required schema fields, preference keys and install config keys: a new exit code or preference key raises the minimum bump to minor, and the other changes are listed for review at release time. None of these is part of this contract beyond the `exit_code` and `halt_reason` values a result envelope schema lists (**Schema enum values and properties**, above), and promoting one later is an additive change.
+
+## @internal — Not Covered by SemVer
+
+The following surfaces are explicitly excluded from this contract. Changes to any of these MAY land in any release (patch, minor, or major) without constituting a "breaking change" from a SemVer perspective, except the parts that entries below name as reviewed by the release check. Downstream consumers SHOULD NOT pin against these surfaces.
+
+- **`tools/cli/lib/*` internal helper modules**: implementation detail of the CLI; not a library. Any refactor that preserves the observable CLI surface and install layout above is allowed.
+- **Workflow step files and reference material under `src/skf-*/references/`**: the workflow authoring format is an SKF-internal authoring surface; step numbering, file names, prose and reference material can change. The exit-code tables and the `halt_reason` and `error.phase` values these files define are the exception: the release check reviews every change to them at each release, and a new workflow exit code needs at least a minor bump, while an `exit_code` or `halt_reason` value a result envelope schema lists is covered surface (see [§ Workflow Contract Surfaces](#workflow-contract-surfaces)).
+- **`_bmad/_memory/forger-sidecar/*.yaml` file schemas**: Ferris sidecar state. Stable as a runtime contract between SKF versions during one install's lifetime (so `skf update` works), but not a downstream-consumable schema. The preference keys of `preferences.yaml` are the exception: the release check reviews every change to them at each release, and a new preference key needs at least a minor bump (see [§ Workflow Contract Surfaces](#workflow-contract-surfaces)).
+- **Ferris agent persona prose and menu wording**: the in-product agent persona can be rephrased or restructured at any time.
+  The menu codes themselves are covered: see [§ Workflow Contract Surfaces](#workflow-contract-surfaces).
+- **Exact chalk styling / ANSI color choices in command output**: stylistic; see the output-format bucket above for what is committed.
+- **Internal logic of the `Installer` class in `tools/cli/lib/installer.js`**: private implementation; what's covered is the observable install layout, not how the files get there.
+- **Workflow `{communication_language}` / `{document_output_language}` template substitution**: an authoring convenience for workflow prose; the mechanism is internal.
+- **Knowledge-base contents under `src/knowledge/`**: evolving reference material, not a schema.
+- **Test fixtures and test file layout under `test/`**: test organization is internal (except `test/schema/**`, which defines schemas covered by [§ Skill Manifest & Frontmatter Contract](#skill-manifest--frontmatter-contract)).
+- **Build and docs tooling (`tools/build-docs.js`, `website/`)**: internal build pipeline for the Starlight docs site; not a consumer surface.
+- **`_bmad-output/` planning-artifact layout**: gitignored and never distributed; not shipped in the npm package.
 
 ## How to Use This Contract
 
 Pin SKF as a dependency with caret-range major-version pinning to get minor and patch updates automatically:
 
 ```json
-"bmad-module-skill-forge": "^1.0.0"
+"bmad-module-skill-forge": "^3.0.0"
 ```
 
 The caret range covers additive changes and internal refactors on covered surfaces, and any change on `@internal` surfaces. If you find that an SKF release broke a covered surface listed in this document, please open an issue at <https://github.com/armelhbobdad/bmad-module-skill-forge/issues> citing the relevant section — it is either a bug in SKF that needs reverting or a missed major-version bump.
 
-If a surface you depend on is NOT explicitly enumerated in [§ Covered Surfaces](#covered-surfaces), treat it as `@internal` — if in doubt, it is `@internal`. If you believe a surface should be promoted from `@internal` to covered, open an issue with a use-case description; promotion is additive and can land in a minor release.
+If a surface you depend on is not explicitly enumerated in [§ Covered Surfaces](#covered-surfaces), treat it as `@internal`: if in doubt, it is `@internal`. If you believe a surface should be promoted from `@internal` to covered, open an issue with a use-case description; promotion is additive and can land in a minor release.
 
 ## Changes to This Contract
 
 Shrinking the covered surface (removing a commitment) is a breaking change and requires a major-version bump. Expanding the covered surface (promoting an `@internal` surface to covered, or adding a new commitment) is additive and ships in a minor release. This document is versioned alongside the package; historical versions are visible via `git log -- docs/STABILITY.md docs/_internal/STABILITY.md`.
 
+What each version changed in this contract:
+
+- **v1.0.0**: the contract took effect, with the first six buckets of [§ Covered Surfaces](#covered-surfaces).
+- **v3.0.0**: added [§ Workflow Contract Surfaces](#workflow-contract-surfaces), which widens what the contract covers and removes nothing from it, so it is an additive change. It also adopted the BCP 14 keywords, stopped counting the workflow exit codes, `halt_reason` and `error.phase` values and preference keys that the release check reviews among the `@internal` surfaces free to change in any release, restated the `SKILL.md` description rule as rule `SKILL-06` checks it, trigger phrases that name their object included, named the headless result envelope schema of every workflow among the covered schemas, and recorded that `package.json` declares no `main` field, so requiring the package throws `MODULE_NOT_FOUND`. It also added the tool minimums of `tool-requirements.yaml` to [§ Engine & Platform Compatibility](#engine--platform-compatibility), so raising or adding one is breaking.
+
 ## References
 
 - [agentskills.io spec](https://github.com/agentskills/agentskills) — external canonical source for the `SKILL.md` frontmatter grammar.
 - [Semantic Versioning 2.0.0](https://semver.org/) — the SemVer semantics this contract commits to.
+- [BCP 14](https://www.rfc-editor.org/info/bcp14) ([RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174)): the meaning of the requirement words this document writes in capitals.
 - [`CHANGELOG.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/CHANGELOG.md) — release-by-release history; breaking changes are called out there.
-- [`docs/_internal/RELEASING.md`](RELEASING.md) — maintainer reference for the release pipeline (companion document: this file is about what ships, `RELEASING.md` is about how).
+- [`docs/_internal/RELEASING.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/docs/_internal/RELEASING.md) — maintainer reference for the release pipeline (companion document: this file is about what ships, `RELEASING.md` is about how). Linked by URL, not relatively: `RELEASING.md` is maintainer-only and excluded from the published npm tarball, while this file ships as the public API contract, so a relative link would dangle for anyone reading the installed package.
+- [`tools/covered-surfaces.js`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/tools/covered-surfaces.js) and [`changes/README.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/changes/README.md): the release check for [§ Workflow Contract Surfaces](#workflow-contract-surfaces) and the change-fragment format the release notes are written in. Linked by URL: neither ships in the npm package.
 - [`tools/cli/lib/platform-codes.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/tools/cli/lib/platform-codes.yaml) — source of truth for the IDE → skills-directory mapping covered under [§ Installation Layout](#installation-layout).
 - [`test/schema/agent.js`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/test/schema/agent.js) — zod schema definitions for `bmad-skill-manifest.yaml` covered under [§ Skill Manifest & Frontmatter Contract](#skill-manifest--frontmatter-contract).