bmad-module-skill-forge 2.0.2 → 2.2.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.0.2",
+      "version": "2.2.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -1,3 +1,5 @@
+
+
 <div align="center">
 
 <img src="website/public/img/skf-logo-animated.svg" alt="Skill Forge Logo" width="120" />
@@ -75,7 +77,7 @@ You'll be prompted for project name, output folders, and IDE configuration. When
 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` → clear session → `@Ferris CS` for maximum control
+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
 
 For producing **many coordinated skills** across sessions, `@Ferris campaign` _(Campaign)_ orchestrates the whole set with dependency tracking and resume.
 

package/docs/404.md

@@ -10,14 +10,14 @@ No page resolves to that URL. In keeping with the rest of this site, if a claim
 
 Try one of these cited sources instead, or use the **search bar** at the top of the page:
 
-**Why** — [Why Skill Forge?](/why-skf/) · [Verifying a Skill](/verifying-a-skill/)
+**Why** — [Why Skill Forge?](/docs/why-skf.md) · [Verifying a Skill](/docs/verifying-a-skill.md)
 
-**Try** — [Getting Started](/getting-started/) · [How It Works](/how-it-works/) · [Examples](/examples/) · [Workflows](/workflows/)
+**Try** — [Getting Started](/docs/getting-started.md) · [How It Works](/docs/how-it-works.md) · [Examples](/docs/examples.md) · [Workflows](/docs/workflows.md)
 
-**Reference** — [Concepts](/concepts/) · [Architecture](/architecture/) · [Skill Model](/skill-model/) · [Agents](/agents/) · [BMAD Synergy](/bmad-synergy/) · [Troubleshooting](/troubleshooting/)
+**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)
 
 ---
 
 ### 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](/verifying-a-skill/#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.
+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.

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # 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.0.2"
+skf_version: "2.2.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

package/docs/_internal/RELEASING.md

@@ -23,7 +23,7 @@ For background on GitHub rulesets vs legacy branch protection, see the [GitHub r
 | `code_quality`           | Blocks merge on `severity: errors` from GitHub code-quality checks.                                                        |
 | `required_status_checks` | Merge blocked until all seven `quality.yaml` checks pass (names below).                                                    |
 
-**Required status checks (7):** sourced from `.github/workflows/quality.yaml` job keys. Matrix jobs expand to `jobname (matrix-value)`:
+**Required status checks (8):** sourced from `.github/workflows/quality.yaml` job keys. Matrix jobs expand to `jobname (matrix-value)`:
 
 - `prettier`
 - `eslint`
@@ -32,6 +32,7 @@ For background on GitHub rulesets vs legacy branch protection, see the [GitHub r
 - `validate (windows-latest)`
 - `python (ubuntu-latest)`
 - `python (windows-latest)`
+- `docs-links`
 
 **Coupling with `quality.yaml`:** if that workflow renames a job or changes the `strategy.matrix.os` for `validate` or `python`, the ruleset's `required_status_checks` list must be updated in lock-step — otherwise merges to `main` will either block on a check name that no longer reports, or silently pass without the renamed check. Update both in the same PR.
 
@@ -188,6 +189,40 @@ The future `release.yaml` workflow (Story 3.1) publishes to npm via **OIDC trust
 
 **Fixing a bad registration.** The npm UI exposes both **Edit** and **Delete** on an existing Trusted Publisher entry (observed 2026-04-20). Prefer edit for a single-field typo; prefer delete-and-re-add if multiple fields are wrong or the edit form ever feels ambiguous. **Pre-Story 3.2**: there is no destructive side effect because no publish is attempted yet, and delete-and-re-add keeps the audit trail cleaner. **Post-Story 3.2**: a publish that fires during the delete-and-re-add window will 404 — gate any delete-and-re-add behind a manual publish freeze (pause any active `release.yaml` runs, confirm no tags are in-flight) before touching the entry.
 
+## Cutting a Release
+
+The dispatch mechanics are worked end-to-end in [§ Cutting v1.0.0 under --tag latest](#cutting-v100-under---tag-latest). That section is a launch-specific record, but its dispatch command, two-gate sequence, and verification block are the same for every cut. The two steps below are general, apply to every cut, and have no other home — both are invisible until they bite, because the default state of each is the harmless one.
+
+### Pre-dispatch — reconcile a non-empty `## [Unreleased]`
+
+The `Restore CHANGELOG preamble` step splits `CHANGELOG.md` at the **first** `## [X.Y.Z]` header and treats everything above it as preamble. The generated block for the new version is therefore inserted _below_ any prose sitting under `## [Unreleased]`, and the workflow neither empties that section nor warns about it. Check before dispatching:
+
+```bash
+sed -n '/^## \[Unreleased\]/,/^## \[[0-9]/p' CHANGELOG.md
+```
+
+If the `## [Unreleased]` header is immediately followed by the first released header, there is nothing to do — that was the state at every cut through v2.0.2, which is why the interaction went unexercised for so long. If it carries prose, those entries describe work that is about to ship, and after the cut they read as unreleased directly above the release containing them.
+
+**Do not hand-edit it before dispatch.** The `## [X.Y.Z]` header the prose belongs under does not exist until the workflow generates it. Reconcile after publish in a normal PR: move the prose under the generated version header and leave the `## [Unreleased]` header in place with an empty body — deleting the header itself breaks the section split the preamble-restore step depends on.
+
+Prefer moving the prose over dropping it in favour of the generated list. Under `conventionalcommits`, `test:` and `chore:` subjects produce no generated entry at all, and one `fix:` subject often stands in for several distinct fixes, so the hand-written text is frequently the only record of both. v2.1.0 is the worked example: five bullets stranded, moved under `## [2.1.0]` in a follow-up PR.
+
+### Post-publish — delete the bot temp branch after an admin-bypass merge
+
+`Auto-merge bot PR` runs `gh pr merge --auto --merge --delete-branch`, so on the auto-merge path the temp branch `release/bot/vX.Y.Z-<run_id>` is removed when the queued merge fires. Clearing gate 2 with the PR merge button instead — admin bypass, the observed pattern for most cuts — merges the PR directly, and the queued `--delete-branch` never runs. The branch stays on origin.
+
+```bash
+# Expect zero once a cut is fully closed out.
+git ls-remote --heads origin 'release/bot/*'
+
+# Delete a leftover only after confirming its commit is reachable from main.
+git fetch origin --quiet
+git merge-base --is-ancestor <temp-branch-sha> origin/main \
+  && git push origin --delete release/bot/vX.Y.Z-<run_id>
+```
+
+The tag anchors on the bot PR's merge commit on `main`, not on the temp branch (see the `Create and push tag` step's main-dispatch path), so deleting the branch after the merge orphans nothing. The reachability check is what distinguishes this from the tag-orphan case in [§ Scenario D](#scenario-d--tag-exists-but-npm-publish-failed); if the commit is _not_ reachable, the merge did not land and the branch is still load-bearing.
+
 <!-- Rollback Playbook — added in Story 4.1 -->
 
 ## Rollback Playbook
@@ -581,7 +616,7 @@ For the `release` environment, a deletion+restore similarly uses the two-call pa
   The workflow pauses at **two** gates that the maintainer must clear in the browser. Gate 1 requires explicit approval; gate 2 accepts either approval or admin-bypass-merge:
 
   1. The `release` environment deployment gate (at job start). Approve via "Review deployments" → "Approve and deploy" on the run page.
-  2. The bot PR review-decision gate (after the 7 required status checks pass). EITHER approve the bot PR via the review UI, OR admin-bypass-merge via the PR merge button — both paths are accepted by `release.yaml`'s `Wait for PR approval or admin-bypass merge` step. Admin-bypass-merge is the observed pattern for prior cuts (PRs #209 and #213).
+  2. The bot PR review-decision gate (after the 8 required status checks pass). EITHER approve the bot PR via the review UI, OR admin-bypass-merge via the PR merge button — both paths are accepted by `release.yaml`'s `Wait for PR approval or admin-bypass merge` step. Admin-bypass-merge is the observed pattern for prior cuts (PRs #209 and #213).
 
   Expected wall-clock: ~5–8 minutes end-to-end when both gates are approved promptly.
 
@@ -633,10 +668,12 @@ For the `release` environment, a deletion+restore similarly uses the two-call pa
 
 #### Post-publish verification (NFR9)
 
-Cross-platform install verification for any cut is performed by the [`install-smoke.yaml`](../.github/workflows/install-smoke.yaml) workflow, not by `release.yaml` itself. Dispatch it within 1 hour of publish per NFR9:
+Cross-platform install verification for any cut is performed by the [`install-smoke.yaml`](/.github/workflows/install-smoke.yaml) workflow, not by `release.yaml` itself. Dispatch it within 1 hour of publish per NFR9:
 
 ```bash
 gh workflow run install-smoke.yaml -f version=latest --ref main
 ```
 
-The workflow fans a `workflow_dispatch` input over `ubuntu-latest`, `windows-latest`, and `macos-latest`, running `npx --yes bmad-module-skill-forge@<version> --version` on each runner. A clean three-leg run is the canonical post-publish evidence — its run URL + matrix table belong in the release audit artifact's `## Story <N> Post-Publish Verification` section. Any failing leg routes through the `Rollback Playbook § Scenario B` (deprecate + ship `vX.Y.Z+1`).
+The workflow fans a `workflow_dispatch` input over `ubuntu-latest`, `windows-latest`, and `macos-latest`, running `npx --yes bmad-module-skill-forge@<version> --version` on each runner. A clean three-leg run is the canonical post-publish evidence. Any failing leg routes through the `Rollback Playbook § Scenario B` (deprecate + ship `vX.Y.Z+1`).
+
+**Where the evidence lives.** For a routine release the workflow run **is** the record — the dispatch satisfies NFR9 on its own and no audit artifact is written. Launch cuts additionally transcribe the run URL and matrix table into a per-launch audit artifact under `release-audits/`; `v1.0.0-launch-audit.md § Story 5.4 Post-Publish Verification` is the worked example and remains the only such artifact. Do not append routine releases to it — each audit file is a forensic record scoped to the launch that produced it.

package/docs/agents.md

@@ -86,9 +86,9 @@ PIPELINE ALIASES:
 
 **Pipeline Aliases:**
 
-Ferris chains multiple workflows in one command via named aliases (`forge-auto`, `forge`, `forge-quick`, `maintain`). The full alias table, expansion rules, and target-resolution contract live in [Workflows → Pipeline Mode](../workflows/#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
+Ferris chains multiple workflows in one command via named aliases (`forge-auto`, `forge`, `forge-quick`, `maintain`). The full alias table, expansion rules, and target-resolution contract live in [Workflows → Pipeline Mode](/docs/workflows.md#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
 
-`campaign` is not a chaining alias — it is a standalone orchestrator workflow (`@Ferris campaign`) that runs its own multi-stage pipeline internally, with dependency tracking and resume. See the [Campaign](../campaign/) page.
+`campaign` is not a chaining alias — it is a standalone orchestrator workflow (`@Ferris campaign`) that runs its own multi-stage pipeline internally, with dependency tracking and resume. See the [Campaign](/docs/campaign.md) page.
 
 **Memory:**
 Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions. Set `headless_mode: true` in preferences to make headless the default.

package/docs/architecture.md

@@ -3,7 +3,7 @@ title: Architecture
 description: How Skill Forge runs — the BMAD-backed agent and workflow engine, tool ecosystem, workspace artifacts, security, and the design decisions behind them.
 ---
 
-Skill Forge runs entirely inside the LLM context window through structured instructions. There is no external orchestrator — just an agent persona (Ferris), a set of workflows, and a curated knowledge base. This page covers the machinery. For an end-to-end walkthrough, see [How It Works](../how-it-works/). For what a skill contains, see [Skill Model](../skill-model/).
+Skill Forge runs entirely inside the LLM context window through structured instructions. There is no external orchestrator — just an agent persona (Ferris), a set of workflows, and a curated knowledge base. This page covers the machinery. For an end-to-end walkthrough, see [How It Works](/docs/how-it-works.md). For what a skill contains, see [Skill Model](/docs/skill-model.md).
 
 ---
 

package/docs/bmad-synergy.md

@@ -3,7 +3,7 @@ title: BMAD Synergy
 description: How SKF workflows pair with BMAD CORE phases and optional modules (BMM, TEA, BMB, GDS, CIS) — integration patterns, entry points, and artifact flow
 ---
 
-This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start with the [BMAD docs](https://docs.bmad-method.org/) first. New to SKF? Read [Getting Started](../getting-started/) instead.
+This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start with the [BMAD docs](https://docs.bmad-method.org/) first. New to SKF? Read [Getting Started](/docs/getting-started.md) instead.
 
 ---
 
@@ -29,13 +29,13 @@ When a BMAD agent runs a workflow, that workflow can consult SKF content skills
 
 SKF works standalone — no BMAD installation required. If you found this page from a search and don't use the BMAD Method, this section is for you.
 
-The fastest way to start is [`forge-auto`](../forge-auto/). One command produces a verified skill in 3–5 minutes with zero configuration:
+The fastest way to start is [`forge-auto`](/docs/forge-auto.md). One command produces a verified skill in 3–5 minutes with zero configuration:
 
 ```
 @Ferris forge-auto https://github.com/honojs/hono
 ```
 
-That's it. No brief file, no scope decisions, no multi-step pipeline to learn. forge-auto handles analysis, scoping, compilation, testing (with a 90% quality gate), and export automatically. See the [forge-auto guide](../forge-auto/) for the full syntax and input types.
+That's it. No brief file, no scope decisions, no multi-step pipeline to learn. forge-auto handles analysis, scoping, compilation, testing (with a 90% quality gate), and export automatically. See the [forge-auto guide](/docs/forge-auto.md) for the full syntax and input types.
 
 If you later adopt the BMAD Method, the skills you created via forge-auto integrate seamlessly into BMM phases — they become the verified content skills that BMAD workflows consult during planning and implementation. The [phase-by-phase playbook](#skf-and-bmm-phase-by-phase-playbook) below shows exactly where each SKF workflow fits.
 
@@ -45,7 +45,7 @@ If you later adopt the BMAD Method, the skills you created via forge-auto integr
 
 BMM is BMAD's core [4-phase workflow](https://docs.bmad-method.org/) (Analysis → Planning → Solutioning → Implementation). SKF has five concrete entry points across those phases. The diagram below shows the end-to-end picture; the subsections that follow give the trigger, command, and artifact flow for each phase.
 
-> **Atomic workflows vs pipeline aliases.** The playbook below maps each phase to an *atomic* SKF workflow (`AN`, `BS`, `QS`, `VS`, `CS`…) on purpose — in BMM you often want only part of the chain (a brief to feed a risk register, a quick reference for acceptance criteria). When you instead want the *finished, exported skill* in one command, reach for a pipeline alias: [`forge-auto`](../forge-auto/) collapses `AN → BS → CS → TS → EX` for a single library, and [`campaign`](../campaign/) orchestrates that whole chain across many dependencies. Rule of thumb: **atomic when you want a stage's artifact; alias when you want the verified skill.**
+> **Atomic workflows vs pipeline aliases.** The playbook below maps each phase to an *atomic* SKF workflow (`AN`, `BS`, `QS`, `VS`, `CS`…) on purpose — in BMM you often want only part of the chain (a brief to feed a risk register, a quick reference for acceptance criteria). When you instead want the *finished, exported skill* in one command, reach for a pipeline alias: [`forge-auto`](/docs/forge-auto.md) collapses `AN → BS → CS → TS → EX` for a single library, and [`campaign`](/docs/campaign.md) orchestrates that whole chain across many dependencies. Rule of thumb: **atomic when you want a stage's artifact; alias when you want the verified skill.**
 
 ```mermaid
 flowchart TD
@@ -96,7 +96,7 @@ flowchart TD
 
 **Why now, not later:** Quick Skill is cheap insurance. It takes under a minute and prevents a whole class of "actually that function doesn't exist" moments during story writing.
 
-**Want more than a quick reference?** When the PRD leans heavily on one library and you'd rather have a thorough, doc-enriched skill behind a 90% quality gate than a fast QS pass, run [`@Ferris forge-auto <repo>`](../forge-auto/) instead — one command produces the finished, exported skill (auto-scope, auto-brief, test, export) ready for BMM workflows to consult.
+**Want more than a quick reference?** When the PRD leans heavily on one library and you'd rather have a thorough, doc-enriched skill behind a 90% quality gate than a fast QS pass, run [`@Ferris forge-auto <repo>`](/docs/forge-auto.md) instead — one command produces the finished, exported skill (auto-scope, auto-brief, test, export) ready for BMM workflows to consult.
 
 ### Phase 3 — Solutioning
 
@@ -123,7 +123,7 @@ flowchart TD
     CAMPAIGN -->|"automates the full pipeline<br/>for all dependencies"| READY
 ```
 
-The "Pre-Code Architecture Verification — Greenfield Confidence" scenario in [Examples](../examples/) walks through a concrete case of this loop.
+The "Pre-Code Architecture Verification — Greenfield Confidence" scenario in [Examples](/docs/examples.md) walks through a concrete case of this loop.
 
 #### Campaign Orchestration
 
@@ -141,7 +141,7 @@ Two distinct triggers fire during Implementation, one at the start of each story
 
 **Trigger A (before `create-story`):** The story touches a library whose API isn't already in a content skill.
 
-**SKF command:** `@Ferris CS` for a single library, or `@Ferris SS` when the story spans several dependencies. If there's no brief yet and you want the skill in one shot, [`@Ferris forge-auto <repo>`](../forge-auto/) runs the full analyze → brief → compile → test → export chain from just the repo URL.
+**SKF command:** `@Ferris CS` for a single library, or `@Ferris SS` when the story spans several dependencies. If there's no brief yet and you want the skill in one shot, [`@Ferris forge-auto <repo>`](/docs/forge-auto.md) runs the full analyze → brief → compile → test → export chain from just the repo URL.
 
 **What flows back:** A verified content skill the `dev-story` workflow can consult during implementation — no training-data guessing about function signatures.
 
@@ -151,7 +151,7 @@ Two distinct triggers fire during Implementation, one at the start of each story
 
 **What flows back:** A patched skill with the newly-discovered edge cases captured — `[MANUAL]` sections preserved so human annotations aren't overwritten. Next sprint's stories consume the updated skill automatically.
 
-This retrospective → update loop is the pattern that [Scenario A in Examples](../examples/#scenario-a-greenfield--bmm-integration) sketches for one project; it generalizes to any BMM project that runs more than a few sprints.
+This retrospective → update loop is the pattern that [Scenario A in Examples](/docs/examples.md#scenario-a-greenfield--bmm-integration) sketches for one project; it generalizes to any BMM project that runs more than a few sprints.
 
 ---
 
@@ -203,7 +203,7 @@ Beyond briefing, CIS and SKF don't overlap — CIS covers ideation, storytelling
 
 ## Delivery and Lifecycle in a BMAD Project
 
-`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
+`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](/docs/skill-model.md#dual-output-strategy) for the architectural rationale.
 
 This matters specifically in a BMAD project: you may have multiple BMAD modules, each with its own launcher skills, plus SKF content skills, all trying to contribute context. The write-guard means only verified, tested SKF skills ever reach an agent's passive context — nothing half-baked sneaks in. `@Ferris EX` injects managed sections that coexist cleanly with whatever BMAD's installer wrote in the same files.
 
@@ -214,7 +214,7 @@ For long-running BMAD projects, `@Ferris RS` (rename) and `@Ferris DS` (drop) ke
 ## Where to Go Next
 
 - [BMAD docs](https://docs.bmad-method.org/) — canonical reference for BMM phases, TEA workflows, BMB / GDS / CIS details, and the full module list
-- [Forge-Auto](../forge-auto/) — the one-command alias that collapses analyze → brief → compile → test → export for a single library
-- [Campaign](../campaign/) — orchestrate the full pipeline across many declared dependencies with dependency ordering and resume
-- [Workflows](../workflows/) — complete SKF workflow reference with commands and connection diagrams
-- [Examples](../examples/) — concrete scenarios including the BMM retrospective loop and greenfield architecture verification
+- [Forge-Auto](/docs/forge-auto.md) — the one-command alias that collapses analyze → brief → compile → test → export for a single library
+- [Campaign](/docs/campaign.md) — orchestrate the full pipeline across many declared dependencies with dependency ordering and resume
+- [Workflows](/docs/workflows.md) — complete SKF workflow reference with commands and connection diagrams
+- [Examples](/docs/examples.md) — concrete scenarios including the BMM retrospective loop and greenfield architecture verification

package/docs/campaign.md

@@ -167,6 +167,6 @@ Plan a campaign as multi-session work rather than a single sitting — the resum
 
 ## Related
 
-- [Workflows](../workflows/) — pipeline mode mechanics, headless mode, circuit breakers
-- [forge-auto](../forge-auto/) — zero-ceremony single-skill creation (campaign orchestrates many of these)
-- [BMAD Synergy](../bmad-synergy/) — how campaign fits into BMAD Phase 3 as an orchestration layer
+- [Workflows](/docs/workflows.md) — pipeline mode mechanics, headless mode, circuit breakers
+- [forge-auto](/docs/forge-auto.md) — zero-ceremony single-skill creation (campaign orchestrates many of these)
+- [BMAD Synergy](/docs/bmad-synergy.md) — how campaign fits into BMAD Phase 3 as an orchestration layer

package/docs/concepts.md

@@ -3,7 +3,7 @@ title: Concepts
 description: Seven load-bearing terms for using and understanding Skill Forge — agent skills, provenance, confidence tiers, capability tiers, drift, version pinning, and the BMAD module.
 ---
 
-These are the seven terms you'll meet in every other page of this site. Each one names something SKF does differently from generic docs tooling. For the full mechanism behind them, see [Architecture](../architecture/) and [Skill Model](../skill-model/).
+These are the seven terms you'll meet in every other page of this site. Each one names something SKF does differently from generic docs tooling. For the full mechanism behind them, see [Architecture](/docs/architecture.md) and [Skill Model](/docs/skill-model.md).
 
 ---
 
@@ -55,7 +55,7 @@ Your capability tier depends on which tools you have installed. Each tier builds
 - **Forge+** — Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF uses semantic code search to discover relevant source regions before AST extraction, improving coverage on large codebases.
 - **Deep** — Full pipeline: requires [ast-grep](https://ast-grep.github.io) + [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd) (all three). SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence. CCC (cocoindex-code) enhances Deep tier when installed — ast-grep + gh + qmd + ccc gives maximum capability.
 
-You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [Skill Model → Progressive Capability Model](../skill-model/#progressive-capability-model) for the full technical treatment.
+You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [Skill Model → Progressive Capability Model](/docs/skill-model.md#progressive-capability-model) for the full technical treatment.
 
 ---
 
@@ -83,4 +83,4 @@ When the source updates, you can re-run `@Ferris US` (update-skill) to regenerat
 
 SKF is a plugin (called a "module") for [BMAD Method](https://docs.bmad-method.org/), a framework for running structured AI workflows. You don't need to know BMAD to use SKF — the standalone installer sets everything up.
 
-If you already use BMAD, see [BMAD Synergy](../bmad-synergy/) for how SKF workflows pair with BMM phases and optional modules like TEA, BMB, and GDS.
+If you already use BMAD, see [BMAD Synergy](/docs/bmad-synergy.md) for how SKF workflows pair with BMM phases and optional modules like TEA, BMB, and GDS.

package/docs/examples.md

@@ -49,7 +49,7 @@ Provenance tags trace each instruction to its source:
 - `[EXT:url]` — sourced from external documentation
 - `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
 
-See [Skill Model → Output Architecture](../skill-model/#output-architecture) for the full output structure.
+See [Skill Model → Output Architecture](/docs/skill-model.md#output-architecture) for the full output structure.
 
 **Full skill directory structure** (real layout from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee)):
 
@@ -74,7 +74,7 @@ skills/oms-cognee/
             └── pipelines-and-datapoints.md
 ```
 
-This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree — the older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets — oms-cognee doesn't have either, but see [Skill Model → Per-Skill Output](../skill-model/#per-skill-output) for the full schema.
+This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree — the older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets — oms-cognee doesn't have either, but see [Skill Model → Per-Skill Output](/docs/skill-model.md#per-skill-output) for the full schema.
 
 ---
 
@@ -115,7 +115,7 @@ Or one workflow per session:
 @Ferris CS --batch  # Create — batch generation
 ```
 
-10 individual skills + 1 platform stack skill. The [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect then navigates cross-service flows using verified knowledge.
+10 individual skills + 1 platform stack skill. The [BMM](/docs/bmad-synergy.md#skf-and-bmm-phase-by-phase-playbook) architect then navigates cross-service flows using verified knowledge.
 
 ### Release Prep — Trust Builder
 
@@ -146,7 +146,7 @@ Armel, building a full-stack side project on Next.js + Serwist + SpacetimeDB + b
 @Ferris SS
 ```
 
-Ferris detects 8 significant dependencies, finds 5 co-import integration points. Generates a consolidated stack skill. The agent now knows: "When you modify the auth flow, update the Serwist cache exclusion at `src/sw.ts:L23`." That integration detail isn't available from any other tool in the [comparison table](/#how-skf-compares).
+Ferris detects 8 significant dependencies, finds 5 co-import integration points. Generates a consolidated stack skill. The agent now knows: "When you modify the auth flow, update the Serwist cache exclusion at `src/sw.ts:L23`." That integration detail isn't available from any other tool in the [comparison table](/docs/index.md#how-skf-compares).
 
 ### Pre-Code Architecture Verification — Greenfield Confidence
 
@@ -169,7 +169,7 @@ VS flags the Drizzle↔SpacetimeDB integration as incompatible (query-model mism
 
 ### Scenario A: Greenfield + BMM Integration
 
-BMAD user starts a new project. [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect suggests skill generation after retrospective.
+BMAD user starts a new project. [BMM](/docs/bmad-synergy.md#skf-and-bmm-phase-by-phase-playbook) architect suggests skill generation after retrospective.
 
 ```
 @Ferris BS    # Brief — scope the skill
@@ -188,7 +188,7 @@ Blondin, a platform lead, needs cross-service knowledge for 10 microservices so
 @Ferris campaign    # Orchestrate all 10 skills across sessions, in dependency order
 ```
 
-Campaign reads the dependency graph, sorts the skills topologically, and drives each one through the full pipeline (brief, generate, compile, test) with quality gates enforced. State is written to disk, so Blondin can walk away and `@Ferris campaign resume` after a context death or a session break — picking up exactly where the last session stopped. One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns. See [Campaign Orchestration](../campaign/) for the full stage-by-stage flow.
+Campaign reads the dependency graph, sorts the skills topologically, and drives each one through the full pipeline (brief, generate, compile, test) with quality gates enforced. State is written to disk, so Blondin can walk away and `@Ferris campaign resume` after a context death or a session break — picking up exactly where the last session stopped. One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns. See [Campaign Orchestration](/docs/campaign.md) for the full stage-by-stage flow.
 
 ### Scenario C: External Dependency
 
@@ -268,7 +268,7 @@ You're building skills for a production payments library and need maximum citati
 @Ferris TS    # Completeness score — 80%+ threshold
 ```
 
-**What you get:** Every signature carries `[AST:file:Lnn]` at T1. Deprecation warnings and design rationale carry `[QMD:collection:doc]` at T2. Install tooling once, every downstream skill benefits. See [Capability Tiers](../concepts/#capability-tiers-quickforgeforgedeep).
+**What you get:** Every signature carries `[AST:file:Lnn]` at T1. Deprecation warnings and design rationale carry `[QMD:collection:doc]` at T2. Install tooling once, every downstream skill benefits. See [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
 
 ### Scenario H: OSS Maintainer Publishing Official Skills
 
@@ -327,10 +327,10 @@ If your source repo includes executable scripts (`scripts/`, `bin/`) or static a
 
 ### Let the Health Check Run
 
-Every SKF workflow ends with a shared **health check** step where Ferris reflects on the session and offers to file friction, bugs, or gaps as GitHub issues (with your approval). Clean runs exit in one line — zero overhead. When something breaks, it's SKF's primary feedback channel, so **please let workflows run to completion**. If you had to cancel before the health check fired, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](../workflows/#terminal-step-health-check) for details.
+Every SKF workflow ends with a shared **health check** step where Ferris reflects on the session and offers to file friction, bugs, or gaps as GitHub issues (with your approval). Clean runs exit in one line — zero overhead. When something breaks, it's SKF's primary feedback channel, so **please let workflows run to completion**. If you had to cancel before the health check fired, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](/docs/workflows.md#terminal-step-health-check) for details.
 
 ---
 
 ## Something not working?
 
-See [Troubleshooting](../troubleshooting/) for common errors (ast-grep unavailable, "no brief found", ecosystem check messages) and how to resolve them. For general setup help, see [Getting Started → Need help?](../getting-started/#need-help).
+See [Troubleshooting](/docs/troubleshooting.md) for common errors (ast-grep unavailable, "no brief found", ecosystem check messages) and how to resolve them. For general setup help, see [Getting Started → Need help?](/docs/getting-started.md#need-help).

package/docs/forge-auto.md

@@ -3,7 +3,7 @@ title: Forge-Auto
 description: Zero-ceremony skill creation — one command turns a GitHub repo, doc URL, or pinned version into a verified skill
 ---
 
-Forge-Auto is a [pipeline alias](../workflows/#pipeline-aliases) that chains five workflows into a single command. Give it a repo URL, a documentation URL, or a pinned version, and it produces a verified skill in 3–5 minutes with zero configuration.
+Forge-Auto is a [pipeline alias](/docs/workflows.md#pipeline-aliases) that chains five workflows into a single command. Give it a repo URL, a documentation URL, or a pinned version, and it produces a verified skill in 3–5 minutes with zero configuration.
 
 If you're new to SKF and want to try it without reading anything else, start here.
 
@@ -27,7 +27,7 @@ Three input types, one command pattern:
 
 ## Pipeline Stages
 
-forge-auto expands to `AN[auto] BS[auto] CS TS[min:90] EX`. The two analysis stages (AN, BS) run in [headless mode](../workflows/#headless-mode) via their `[auto]` flags — no confirmation gates, no interactive prompts. The compile, test, and export stages then proceed with their standard behaviors once the analysis context is ready.
+forge-auto expands to `AN[auto] BS[auto] CS TS[min:90] EX`. The two analysis stages (AN, BS) run in [headless mode](/docs/workflows.md#headless-mode) via their `[auto]` flags — no confirmation gates, no interactive prompts. The compile, test, and export stages then proceed with their standard behaviors once the analysis context is ready.
 
 | Stage | Workflow | Mode | What Happens |
 |-------|----------|------|-------------|
@@ -37,7 +37,7 @@ forge-auto expands to `AN[auto] BS[auto] CS TS[min:90] EX`. The two analysis sta
 | 4 | **Test Skill** (TS) | `[min:90]` | Verifies completeness with a **90% quality threshold** (stricter than the default 80%). Fail halts the pipeline. |
 | 5 | **Export Skill** (EX) | standard | Validates the package, generates context snippets, and injects into your IDE's context file. |
 
-Data flows automatically between stages — the brief path from AN feeds BS, the skill name from CS feeds TS, and so on. See [Pipeline Mode](../workflows/#pipeline-mode) for the general mechanics.
+Data flows automatically between stages — the brief path from AN feeds BS, the skill name from CS feeds TS, and so on. See [Pipeline Mode](/docs/workflows.md#pipeline-mode) for the general mechanics.
 
 ---
 
@@ -85,6 +85,6 @@ Before that, the auto pipeline replaced the older `onboard` alias. `onboard` has
 
 ## Related
 
-- [Workflows](../workflows/) — pipeline mode mechanics, headless mode, circuit breakers
-- [Concepts](../concepts/) — provenance, confidence tiers, drift, version pinning
-- [BMAD Synergy](../bmad-synergy/) — how forge-auto fits into BMAD phases, and standalone SKF usage
+- [Workflows](/docs/workflows.md) — pipeline mode mechanics, headless mode, circuit breakers
+- [Concepts](/docs/concepts.md) — provenance, confidence tiers, drift, version pinning
+- [BMAD Synergy](/docs/bmad-synergy.md) — how forge-auto fits into BMAD phases, and standalone SKF usage

package/docs/getting-started.md

@@ -15,7 +15,7 @@ await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
 
 Every instruction carries a receipt — a file, a line, and a commit SHA from the upstream repo. Your AI reads these instead of guessing from training data, and you can open the source at the pinned commit to confirm the function exists. Nothing is made up; everything is falsifiable.
 
-Want to see the full audit on a real shipped skill before you install anything? → [Verifying a Skill](../verifying-a-skill/).
+Want to see the full audit on a real shipped skill before you install anything? → [Verifying a Skill](/docs/verifying-a-skill.md).
 
 ---
 
@@ -51,7 +51,7 @@ Or, if you've already cloned the repo locally, provide the path to the repo root
 /path/to/bmad-module-skill-forge
 ```
 
-This installs BMAD core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMAD development workflow. See [BMAD Synergy](../bmad-synergy/) for how SKF workflows pair with BMM phases and other BMAD modules.
+This installs BMAD core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMAD development workflow. See [BMAD Synergy](/docs/bmad-synergy.md) for how SKF workflows pair with BMM phases and other BMAD modules.
 
 ### Add SKF to an existing BMAD project
 
@@ -61,7 +61,7 @@ If you already have BMAD installed, you can add SKF afterward by running the sta
 npx bmad-module-skill-forge install
 ```
 
-The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. See [BMAD Synergy](../bmad-synergy/) for integration patterns with your existing BMM workflows.
+The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. See [BMAD Synergy](/docs/bmad-synergy.md) for integration patterns with your existing BMM workflows.
 
 ### Updating an existing SKF installation
 
@@ -94,7 +94,7 @@ This detects your tools, sets your capability tier, and initializes the forge en
 @Ferris forge-auto https://github.com/honojs/hono
 ```
 
-One command turns a repo URL (or a doc URL) into a verified skill — auto-scope, auto-brief, a 90% quality gate, and export, with no configuration. If you only read one thing, [start with forge-auto](../forge-auto/).
+One command turns a repo URL (or a doc URL) into a verified skill — auto-scope, auto-brief, a 90% quality gate, and export, with no configuration. If you only read one thing, [start with forge-auto](/docs/forge-auto.md).
 
 **Fastest path (Quick Skill):**
 ```
@@ -136,13 +136,13 @@ Or one workflow per session:
 
 Analyzes your project's dependencies and generates a consolidated stack skill with integration patterns.
 
-> **After every workflow:** Ferris runs a **health check** — a reflection step that captures any friction, bugs, or gaps from the session. Clean runs exit in one line; when something breaks, Ferris offers to file structured findings as GitHub issues (with your approval). **Please let workflows run to completion** so the health check can fire. If it was skipped, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](../workflows/#terminal-step-health-check).
+> **After every workflow:** Ferris runs a **health check** — a reflection step that captures any friction, bugs, or gaps from the session. Clean runs exit in one line; when something breaks, Ferris offers to file structured findings as GitHub issues (with your approval). **Please let workflows run to completion** so the health check can fire. If it was skipped, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](/docs/workflows.md#terminal-step-health-check).
 
 ---
 
 ## Common use cases
 
-> **Looking for end-to-end examples?** See [Examples](../examples/) for thirteen real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
+> **Looking for end-to-end examples?** See [Examples](/docs/examples.md) for thirteen real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
 
 ---
 
@@ -190,11 +190,11 @@ Runtime configuration (tool detection, tier, and collection state) is managed by
 
 ## What's next?
 
-- [Forge-Auto](../forge-auto/) — the zero-ceremony path: one command from repo or doc URL to a verified skill
-- [Campaign](../campaign/) — orchestrate many coordinated skills across sessions with dependency tracking and resume
-- [Agents](../agents/) — learn about Ferris
-- [Workflows](../workflows/) — the full command reference
-- [Examples](../examples/) — real-world scenarios with transcripts
+- [Forge-Auto](/docs/forge-auto.md) — the zero-ceremony path: one command from repo or doc URL to a verified skill
+- [Campaign](/docs/campaign.md) — orchestrate many coordinated skills across sessions with dependency tracking and resume
+- [Agents](/docs/agents.md) — learn about Ferris
+- [Workflows](/docs/workflows.md) — the full command reference
+- [Examples](/docs/examples.md) — real-world scenarios with transcripts
 
 ---
 
@@ -206,4 +206,4 @@ If you run into issues:
    *Provided by the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 2. Run `@Ferris SF` to check your tool availability and tier
 3. Check `forge-tier.yaml` in your forger sidecar for your current configuration
-4. If a workflow gave you friction, ask Ferris to run the health check for that session, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — see [Workflow Health Check](../workflows/#terminal-step-health-check)
+4. If a workflow gave you friction, ask Ferris to run the health check for that session, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — see [Workflow Health Check](/docs/workflows.md#terminal-step-health-check)

package/docs/how-it-works.md

@@ -3,7 +3,7 @@ title: How It Works
 description: A plain-English walkthrough of Skill Forge compiling one skill from a real library, end to end.
 ---
 
-Skill Forge reads your code, extracts what your AI agents actually need, and compiles it into instructions with citations. This page walks through what that looks like end-to-end. For the machinery behind it, see [Architecture](../architecture/). For what ships inside a skill, see [Skill Model](../skill-model/).
+Skill Forge reads your code, extracts what your AI agents actually need, and compiles it into instructions with citations. This page walks through what that looks like end-to-end. For the machinery behind it, see [Architecture](/docs/architecture.md). For what ships inside a skill, see [Skill Model](/docs/skill-model.md).
 
 ---
 
@@ -43,7 +43,7 @@ That tag means: *this came from AST extraction of this exact file at this exact
 
 ### 5. You get a skill package
 
-Ferris writes a `SKILL.md` (the full instruction manual your agent loads on demand) and a `context-snippet.md` (an 80–120 token index) alongside it. The snippet is the always-on reminder — *"This skill exists; read it before writing cognee code."* — but it isn't wired in automatically: when you run `export-skill`, the snippet gets injected into your platform context file (`CLAUDE.md`, `AGENTS.md`, or `.cursorrules`). Both halves are load-bearing — see the [Dual-Output Strategy](../skill-model/#dual-output-strategy) for why.
+Ferris writes a `SKILL.md` (the full instruction manual your agent loads on demand) and a `context-snippet.md` (an 80–120 token index) alongside it. The snippet is the always-on reminder — *"This skill exists; read it before writing cognee code."* — but it isn't wired in automatically: when you run `export-skill`, the snippet gets injected into your platform context file (`CLAUDE.md`, `AGENTS.md`, or `.cursorrules`). Both halves are load-bearing — see the [Dual-Output Strategy](/docs/skill-model.md#dual-output-strategy) for why.
 
 ### 6. The audit trail stays on disk
 
@@ -51,13 +51,13 @@ Alongside the skill, Ferris leaves a `metadata.json` (the pinned source, commit
 
 That's the whole pipeline. One trigger in, one verifiable skill out, every claim traceable back to a file and a commit.
 
-Quick Skill is the fastest path, not the most thorough one. When you want a full audit trail — a `provenance-map.json` of every receipt and an `evidence-report.md` build log, both produced from a `skill-brief.yaml` — run the brief-driven [`create-skill`](../workflows/#create-skill-cs) path instead.
+Quick Skill is the fastest path, not the most thorough one. When you want a full audit trail — a `provenance-map.json` of every receipt and an `evidence-report.md` build log, both produced from a `skill-brief.yaml` — run the brief-driven [`create-skill`](/docs/workflows.md#create-skill-cs) path instead.
 
 ---
 
 ## Next
 
-- **[Architecture](../architecture/)** — how Ferris loads workflows, how sub-agents handle large extractions, how the 7 tools resolve conflicts, where artifacts land on disk
-- **[Skill Model](../skill-model/)** — what a skill contains, confidence tiers (T1 / T2 / T3), capability tiers (Quick / Forge / Forge+ / Deep), and the dual-output strategy
-- **[Verifying a Skill](../verifying-a-skill/)** — the 60-second audit recipe and how completeness scoring works
-- **[BMAD Synergy](../bmad-synergy/)** — how SKF fits alongside BMAD Method, TEA, BMB, and other modules
+- **[Architecture](/docs/architecture.md)** — how Ferris loads workflows, how sub-agents handle large extractions, how the 7 tools resolve conflicts, where artifacts land on disk
+- **[Skill Model](/docs/skill-model.md)** — what a skill contains, confidence tiers (T1 / T2 / T3), capability tiers (Quick / Forge / Forge+ / Deep), and the dual-output strategy
+- **[Verifying a Skill](/docs/verifying-a-skill.md)** — the 60-second audit recipe and how completeness scoring works
+- **[BMAD Synergy](/docs/bmad-synergy.md)** — how SKF fits alongside BMAD Method, TEA, BMB, and other modules

package/docs/index.md

@@ -32,6 +32,12 @@ Skill Forge reads the source and hands your agent the truth — with receipts. E
 
 If SKF can't cite a source, it doesn't include the instruction.
 
+<!-- Raw HTML bypasses rehype-markdown-links, so this href ships verbatim and
+     cannot take the `/docs/*.md` form the Markdown links use: nothing would
+     rewrite it into a route and the site would 404. It stays site-relative,
+     which is correct here because this page is the site root. That makes it
+     the one link in docs/ that does not also resolve on GitHub. -->
+
 <p class="cta-pill"><a href="./verifying-a-skill/">Verify any claim in 60 seconds →</a></p>
 
 ## How SKF compares
@@ -65,4 +71,4 @@ Then generate your first skill:
 @Ferris QS <package>             # Or a fast skill from a package name in under a minute
 ```
 
-[forge-auto](./forge-auto/) is the recommended starting point — one command, no configuration. See [Getting Started](./getting-started/) for platform support, tier selection, and troubleshooting.
+[forge-auto](/docs/forge-auto.md) is the recommended starting point — one command, no configuration. See [Getting Started](/docs/getting-started.md) for platform support, tier selection, and troubleshooting.

package/docs/skill-model.md

@@ -3,7 +3,7 @@ title: Skill Model
 description: What a Skill Forge skill contains — progressive capability tiers, confidence model, output architecture, the dual-output strategy, and the ownership model.
 ---
 
-A Skill Forge skill is more than a single markdown file. This page explains what ships when you compile and export a skill: the capability tier your forge runs at, the confidence level of every claim, the files in the output directory, and why every skill is shipped as both an active instruction manual and a passive context index. For a walkthrough of compilation, see [How It Works](../how-it-works/). For the audit recipe that ties this all together, see [Verifying a Skill](../verifying-a-skill/).
+A Skill Forge skill is more than a single markdown file. This page explains what ships when you compile and export a skill: the capability tier your forge runs at, the confidence level of every claim, the files in the output directory, and why every skill is shipped as both an active instruction manual and a passive context index. For a walkthrough of compilation, see [How It Works](/docs/how-it-works.md). For the audit recipe that ties this all together, see [Verifying a Skill](/docs/verifying-a-skill.md).
 
 ---
 
@@ -140,7 +140,7 @@ Your forge tier limits what authority claims a skill can make:
 
 ## Completeness Scoring
 
-Skills are graded on a 0–100 completeness scale. See [how the score is computed](../verifying-a-skill/#how-the-score-is-computed) in Verifying a Skill for the formula and tier adjustments.
+Skills are graded on a 0–100 completeness scale. See [how the score is computed](/docs/verifying-a-skill.md#how-the-score-is-computed) in Verifying a Skill for the formula and tier adjustments.
 
 ---