bmad-module-skill-forge 0.8.3 → 0.9.0

package/README.md

@@ -31,7 +31,9 @@ This isn't an edge case. It's the default experience.
 
 1. **Analyzes your sources** — extracts real function signatures, types, and patterns from code repositories, documentation websites, and developer discourse
 2. **Compiles verified instruction files** — every instruction links to the exact file and line it came from
-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
+3. **Version-aware** — skills are stored per-version, so updating to v2.0 doesn't break your v1.x skill. Compatible with [skill.sh](https://skill.sh) and [npx skills](https://www.npmjs.com/package/skills)
+4. **Manageable lifecycle** — rename skills and drop deprecated versions without manual file surgery. Transactional safety for destructive operations.
+5. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
 
 ## Before vs After
 
@@ -74,9 +76,11 @@ You'll be prompted for project name, output folders, and IDE configuration. See
 
 1. **Set up your environment:** `@Ferris SF` — detects your tools and sets your capability tier
 2. **Generate your first skill:** `@Ferris QS <package-name>` — creates a verified skill in under a minute
-3. **Full quality path:** `@Ferris BS` then `@Ferris CS` — brief first, then compile for maximum accuracy
+3. **Full quality path:** `@Ferris BS` → clear session → `@Ferris CS` — brief first, then compile for maximum accuracy
 
-See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 12 available workflows.
+> **Tip:** Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference.
+
+See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 14 available workflows.
 
 ## Who Is This For?
 
@@ -84,13 +88,14 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 - **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)
 
 ## Learn More
 
 - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Plain-English definitions of all key terms
 - **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Architecture, capability tiers, output format, and design decisions
-- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 12 workflows with commands and connection diagrams
+- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 14 workflows with commands and connection diagrams
 - **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios, tips, and troubleshooting
 

package/docs/bmad-synergy.md

@@ -0,0 +1,183 @@
+---
+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
+---
+
+# Using SKF with BMAD
+
+This page is for people already using [BMAD](https://docs.bmad-method.org/) who want to know where SKF workflows plug in. It assumes you know what BMM phases are, what TEA does, and what a BMAD module is. If any of that is new, start with the [BMAD docs](https://docs.bmad-method.org/) and then come back.
+
+If you're new to SKF itself, read [Getting Started](../getting-started/) first. The rest of this page assumes you have SKF installed and have run `@Ferris SF`.
+
+---
+
+## Launcher Skills vs Content Skills
+
+A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same platform skills directory (`.claude/skills/` for Claude Code, `.cursor/skills/` for Cursor, `.agents/skills/` for Copilot/Codex and similar). They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
+
+| | BMAD launcher skill | SKF content skill |
+|---|---|---|
+| **Created by** | `npx bmad-method install` (when you pick a module) | `@Ferris CS` / `QS` / `SS` |
+| **File contains** | A thin wrapper that loads a BMAD workflow, agent, or task | The instructions themselves, with citations to real source code |
+| **Updates when** | You reinstall or upgrade BMAD | You re-run SKF compilation against a new upstream version |
+| **Provenance** | Points to a BMAD workflow file inside `_bmad/` | Points to upstream repo commits, files, and line ranges |
+| **Example** | `bmad-create-prd/SKILL.md` loads a PRD workflow | `hono-4.6.0/SKILL.md` contains verified Hono API signatures |
+
+> BMAD skills *launch workflows*. SKF skills *are the workflows' output, frozen with citations*. Both coexist in the same platform skills directory on purpose.
+
+When a BMAD agent runs a workflow, that workflow can consult SKF content skills for verified API knowledge. The two kinds of skills compose — they don't compete.
+
+---
+
+## SKF and BMM: Phase-by-Phase Playbook
+
+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.
+
+```mermaid
+flowchart TD
+    P1[BMM Phase 1: Analysis<br/>product-brief · research] -.->|unfamiliar deps| AN[SKF: Analyze Source]
+    AN --> BS[SKF: Brief Skill]
+    BS -.->|risk register| P1
+
+    P1 --> P2[BMM Phase 2: Planning<br/>create-prd]
+    P2 -.->|uncertain API| QS[SKF: Quick Skill]
+    QS -.->|verified API ref| P2
+
+    P2 --> P3[BMM Phase 3: Solutioning<br/>create-architecture]
+    P3 -.->|declared stack| VS[SKF: Verify Stack]
+    VS --> RA[SKF: Refine Architecture]
+    RA -.->|refined arch| P3b[BMM: check-implementation-readiness]
+    P3 --> P3b
+
+    P3b --> P4[BMM Phase 4: Implementation<br/>create-story · dev-story]
+    P4 -.->|story libs| CS[SKF: Create Skill / Stack Skill]
+    CS -.->|verified skill context| P4
+
+    P4 --> RETRO[BMM: retrospective]
+    RETRO -.->|API confusion found| US[SKF: Update Skill]
+    US -.->|patched skill| P4
+```
+
+### Phase 1 — Analysis
+
+**Trigger:** A brownfield repo or an unfamiliar third-party dependency surfaces during `product-brief` or `research`. The team can't answer "what does this library actually expose?" from training data.
+
+**SKF command:** `@Ferris AN` on the repo, then `@Ferris BS` to scope each priority library.
+
+**What flows back:** Recommended skill boundaries, an analysis report of the discovered units, and one skill-brief per library that's ready to compile later. The scoping data is what PMs typically feed into their own risk register.
+
+**Why now, not later:** Catching surprise libraries during Analysis keeps the PRD honest. Discovering the same unknowns during Implementation forces course corrections that a two-paragraph risk entry could have prevented.
+
+### Phase 2 — Planning
+
+**Trigger:** The PRD draft references an API and you realize nobody on the team is 100% sure how it behaves.
+
+**SKF command:** `@Ferris QS <package>` — no brief needed.
+
+**What flows back:** A verified skill you can cite directly in acceptance criteria. PM and architect read the same source.
+
+**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.
+
+### Phase 3 — Solutioning
+
+This is the highest-value integration. BMM's architect agent works from assumptions about the declared stack; SKF is how those assumptions become evidence-backed before the team commits to an implementation readiness check.
+
+**Trigger:** Architecture draft exists, `check-implementation-readiness` hasn't run yet.
+
+**SKF commands:** `@Ferris QS <library>` per declared dependency, then `@Ferris VS`, then `@Ferris RA` on any gaps or failures.
+
+**What flows back:** A pass/fail feasibility report per component, version-pinned evidence for every claim, and a refined architecture document with verified API signatures filled in at the callout points.
+
+**Why now, not later:** Running VS after Implementation has started means your stories are already built on an unverified foundation. The loop below is designed to iterate cheaply *before* code gets written.
+
+```mermaid
+flowchart TD
+    ARCH[BMM: create-architecture draft] --> GEN["SKF: Create Skill | Quick Skill<br/>(per declared dependency)"]
+    GEN --> VS[SKF: Verify Stack]
+    VS -->|pass| READY[BMM: check-implementation-readiness]
+    VS -->|fail / gaps| RA[SKF: Refine Architecture]
+    RA -.->|refined draft| VS
+    RA --> READY
+```
+
+The "Pre-Code Architecture Verification — Greenfield Confidence" scenario in [Examples](../examples/) walks through a concrete case of this loop.
+
+### Phase 4 — Implementation
+
+Two distinct triggers fire during Implementation, one at the start of each story and one after each retrospective.
+
+**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.
+
+**What flows back:** A verified content skill the `dev-story` workflow can consult during implementation — no training-data guessing about function signatures.
+
+**Trigger B (after `retrospective`):** The retro flagged something like "we kept getting API X wrong this sprint."
+
+**SKF command:** `@Ferris US` on the affected skill.
+
+**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.
+
+---
+
+## SKF with Optional BMAD Modules
+
+BMAD ships several [optional modules](https://docs.bmad-method.org/). Synergy with SKF ranges from very high (TEA) to none at all (CIS). This section is honest about both.
+
+### TEA — Test Architect
+
+TEA produces structured test strategies and release gates. SKF produces the verified skills TEA's workflows need when the test target is a library they don't fully know.
+
+```mermaid
+flowchart TD
+    TD[TEA: Test Design] -.->|test lib unknown| CS[SKF: Create Skill<br/>on Playwright/Vitest/Pact]
+    CS --> AUTO[TEA: Automate / ATDD]
+    AUTO --> GATE[TEA: Release Gate]
+    GATE -.->|drift check| AS[SKF: Audit Skill]
+    AS -->|no drift| GATE
+    AS -.->|drift found| US[SKF: Update Skill]
+    US -.->|refreshed skill| GATE
+```
+
+Two concrete integrations:
+
+- **Before Test Design / ATDD / Automate / Framework Scaffolding** — run `@Ferris CS` on whichever test library the strategy depends on (Playwright, Vitest, Pact, etc.). TEA's test-authoring agents then work against verified API surfaces instead of training-data approximations.
+- **Before Release Gate** — run `@Ferris AS` on the skills the gate cites. If the skill has drifted from the current source, the drift report itself becomes evidence the gate can act on, and `@Ferris US` closes the loop.
+
+### BMB — BMad Builder
+
+BMB authors extend BMAD with new agents, workflows, or entire modules. When a new module depends on third-party libraries, ship a verified companion skill alongside it:
+
+- During `module-builder`, run `@Ferris SS` on the module's declared stack. The resulting stack skill becomes part of the module's distribution — downstream users get both the BMAD module BMB built and the SKF content skill you compiled as its companion in a single install.
+
+### GDS — Game Dev Studio
+
+Narrow synergy. GDS covers GDD authoring, narrative design, and engine-specific guidance for 21+ game types, and most of that is conceptual work with no code to verify. The exception is when the GDD commits to a concrete engine SDK (Bevy, Godot-Rust, Unity DOTS):
+
+- Once the engine binding is pinned, run `@Ferris CS` on it. The implementation team then has verified bindings to work against.
+
+For narrative, character design, world-building, or genre research — no synergy. SKF has nothing to offer the creative side of GDS.
+
+### CIS — Creative Intelligence Suite
+
+No direct synergy. CIS covers ideation, brainstorming, innovation strategy, and storytelling — phases with no code to verify. SKF's whole value proposition is turning code and docs into evidence-backed skills, and CIS operates upstream of any of that. Use CIS for the creative work, then bring SKF in once you're producing concrete technical artifacts.
+
+---
+
+## Delivery and Lifecycle in a BMAD Project
+
+`@Ferris EX` is the **only workflow that introduces new skill context** into `CLAUDE.md`, `AGENTS.md`, and `.cursorrules`. 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 [How It Works](../how-it-works/) 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.
+
+For long-running BMAD projects, `@Ferris RS` (rename) and `@Ferris DS` (drop) keep the skill inventory clean as libraries get swapped, versions get deprecated, or naming conventions evolve across sprints. Both *rebuild* the existing managed sections in `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` so references stay consistent after a rename or drop — they never inject previously-unpublished content, so the EX gate still governs what initially enters those files.
+
+---
+
+## 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
+- [Workflows](../workflows/) — complete SKF workflow reference with commands and connection diagrams
+- [Examples](../examples/) — concrete scenarios including the BMM retrospective loop and greenfield architecture verification

package/docs/concepts.md

@@ -71,19 +71,47 @@ SKF detects drift by comparing the skill's recorded provenance against the curre
 
 ---
 
+## Completeness Score
+
+The completeness score is a weighted measure of how thoroughly a skill documents its target. The Test Skill workflow (`@Ferris TS`) calculates it across five categories: **Export Coverage** (are all source exports documented?), **Signature Accuracy** (do documented signatures match the actual code?), **Type Coverage** (are referenced types complete?), **Coherence** (do cross-references and integration patterns resolve?), and **External Validation** (do skill-check and tessl confirm quality?).
+
+The default pass threshold is **80%**, overridable by specifying a custom threshold when invoking `@Ferris TS`. Skills that pass are ready for export (`@Ferris EX`); skills that fail route to update (`@Ferris US`) with a gap report showing what to fix.
+
+**Example:** A skill scores 92% export coverage, 85% signature accuracy, 100% type coverage, 80% coherence, and 78% external validation. With the default weights (36/22/14/18/10), the weighted total is 88.0% — a pass.
+
+Your forge tier determines which categories are scored. Quick-tier skills skip signature accuracy and type coverage (no AST available), and the weights redistribute proportionally. See [How It Works](../how-it-works/#completeness-scoring) for the full formula and tier adjustments.
+
+---
+
 ## Version Pinning
 
 Every skill records the exact version (or commit) of the source code it was built from. This means you always know which version of the library the instructions apply to.
 
+By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version — either by specifying it during `@Ferris BS` (brief-skill) or by appending `@version` to a quick skill command (`@Ferris QS cognee@0.5.0`). This is especially useful for docs-only skills where no source code is available for auto-detection. When targeting a specific version on a remote repository, SKF resolves the matching git tag and clones from it — so the extracted API signatures actually reflect the target version's code, not just the label applied to whatever happens to be on the default branch.
+
 When the source updates, you can re-run `@Ferris US` (update-skill) to regenerate the skill for the new version while preserving any manual additions you've made.
 
 ---
 
+## Skill Management
+
+Two workflows let you rename and retire skills without manually editing files:
+
+**Rename (`@Ferris RS`)** — Change a skill's name across all its versions. Transactional: copies to the new name, verifies every reference, then deletes the old name only after verification succeeds. If anything fails mid-rename, the old skill stays intact. Use it to graduate quick-skills to formal names, or to add a suffix like `-community`.
+
+**Drop (`@Ferris DS`)** — Retire a specific version (e.g., drop `cognee 0.1.0` because it's deprecated) or an entire skill. Two modes:
+- **Soft drop (default)** marks the version as deprecated in the manifest and keeps files on disk. It stops appearing in CLAUDE.md/AGENTS.md/.cursorrules immediately but is reversible by editing the manifest.
+- **Hard drop (purge)** also deletes the files from disk. Irreversible.
+
+Both operations automatically rebuild platform context files so your AI agents see the updated state on the next session.
+
+---
+
 ## BMAD Module
 
-SKF is a plugin (called a "module") for the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD), a framework for running structured AI workflows. BMad provides the workflow engine — step-by-step execution, shared knowledge bases, and consistent outputs. SKF plugs into that engine and focuses specifically on skill compilation.
+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.
 
-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.
 
 ---
 
@@ -111,8 +139,38 @@ Skills can include executable scripts and static assets alongside the main SKILL
 
 ---
 
+## Session Context
+
+Each SKF workflow should run in a clean conversation session. Workflows load step files, knowledge fragments, and extraction data into the LLM's context as they execute. If you run a second workflow in the same session, leftover context from the first workflow can interfere with the second — causing stale references, mode confusion, or degraded output quality.
+
+**Best practice:** Clear your session context (start a new conversation) before invoking a new workflow. For example, after `@Ferris CS` completes a skill, start a fresh session before running `@Ferris TS` to test it.
+
+This applies to sequential workflows in the same session. Sidecar state (forge tier, preferences) persists across sessions automatically — you don't lose any configuration by clearing context.
+
+---
+
+## Full Control Over Scope
+
+You can compile multiple skills from the same target (repo or docs) with different scopes, intents, and audiences. Each brief defines what to extract and why, producing a distinct skill from the same source.
+
+**Example:** From a single library like [cognee](https://github.com/topoteretes/cognee), you could compile:
+
+- `cognee-core` — public API surface for general usage
+- `cognee-graph-types` — type system and data model for schema work
+- `cognee-migration` — upgrade patterns and breaking changes for version transitions
+
+Each skill serves a different use case. You decide the scope — SKF compiles exactly what you specify.
+
+---
+
 ## Best Practices
 
 SKF integrates skill authoring best practices from the Claude platform and community guidelines. Generated skills use third-person descriptions for reliable agent discovery, consistent terminology throughout, and appropriate degrees of freedom (prescriptive for fragile operations like database migrations, flexible for creative tasks like code reviews). These practices are enforced during compilation and verified during testing.
 
 **Example:** A skill description reads "Processes payments via REST API with token-based auth. NOT for: billing dashboards" — third-person voice, specific keywords, and negative triggers help agents select the right skill.
+
+**Operational best practices:**
+
+- **One workflow per session** — clear context between workflows to prevent stale state from affecting results
+- **Multiple skills per target** — compile different skills from the same repo or docs for different use cases and audiences
+- **Progressive capability** — start with Quick mode, upgrade tiers as you install more tools

package/docs/examples.md

@@ -50,19 +50,22 @@ See [How It Works](../how-it-works/) for the full output structure.
 
 ```
 skills/cognee/
-├── SKILL.md              # What your agent reads
-├── context-snippet.md    # Compressed index for CLAUDE.md
-├── metadata.json         # Machine-readable provenance
-├── references/           # Progressive disclosure detail
-│   ├── api-core.md
-│   └── graph-types.md
-├── scripts/              # Executable utilities (when detected)
-│   └── setup-graphdb.sh
-└── assets/               # Templates and schemas (when detected)
-    └── config-schema.json
+├── active -> 0.5.5
+└── 0.5.5/
+    └── cognee/
+        ├── SKILL.md              # What your agent reads
+        ├── context-snippet.md    # Compressed index for platform context files
+        ├── metadata.json         # Machine-readable provenance
+        ├── references/           # Progressive disclosure detail
+        │   ├── api-core.md
+        │   └── graph-types.md
+        ├── scripts/              # Executable utilities (when detected)
+        │   └── setup-graphdb.sh
+        └── assets/               # Templates and schemas (when detected)
+            └── config-schema.json
 ```
 
-The `scripts/` and `assets/` directories appear only when the source repository contains them. Each file traces back to its source with provenance citations and SHA-256 hashes.
+Skills are stored per-version — updating cognee to v0.6.0 creates a new version directory without overwriting v0.5.5. The `active` symlink always points to the current version. The `scripts/` and `assets/` directories appear only when the source repository contains them. Each file traces back to its source with provenance citations and SHA-256 hashes.
 
 ---
 
@@ -76,7 +79,13 @@ Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python proje
 @Ferris QS https://github.com/topoteretes/cognee
 ```
 
-Ferris reads the repository, extracts the public API via source reading, validates against spec. Skill appears in `skills/cognee/`. Agent stops hallucinating. Forty-seven seconds. Done.
+Ferris reads the repository, extracts the public API via source reading, validates against spec. Skill appears in `skills/cognee/0.5.5/cognee/`. Agent stops hallucinating. Forty-seven seconds. Done.
+
+Need a specific version? Append `@version`:
+
+```
+@Ferris QS cognee@0.5.0
+```
 
 ### Brownfield Platform — 8 Minutes
 
@@ -84,11 +93,13 @@ Alex's team adopts BMAD for 10 microservices (TypeScript, Go, Rust).
 
 ```
 @Ferris SF          # Setup — Deep mode detected
+# — clear session —
 @Ferris AN          # Analyze — 10 services mapped
+# — clear session —
 @Ferris CS --batch  # Create — batch generation
 ```
 
-10 individual skills + 1 platform stack skill. BMM architect navigates cross-service flows with verified knowledge.
+10 individual skills + 1 platform stack skill. [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect navigates cross-service flows with verified knowledge.
 
 ### Release Prep — Trust Builder
 
@@ -96,8 +107,11 @@ Sarah prepares v3.0.0 with breaking changes.
 
 ```
 @Ferris AS    # Audit — finds 3 renames, 1 removal, 1 addition
+# — clear session —
 @Ferris US    # Update — preserves [MANUAL] sections, adds annotations
+# — clear session —
 @Ferris TS    # Test — verify completeness
+# — clear session —
 @Ferris EX    # Export — package for npm release
 ```
 
@@ -134,13 +148,13 @@ VS finds a Risky integration between Drizzle and SpacetimeDB (incompatible query
 
 ### Scenario A: Greenfield + BMM Integration
 
-BMAD user starts a new project. BMM architect suggests skill generation after retrospective.
+BMAD user starts a new project. [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect suggests skill generation after retrospective.
 
 ```
 @Ferris BS    # Brief — scope the skill
 @Ferris CS    # Create — compile from brief
 @Ferris TS    # Test — verify completeness
-@Ferris EX    # Export — inject into CLAUDE.md
+@Ferris EX    # Export — inject into platform context files
 ```
 
 Skills accumulate over sprints. Agent gets smarter every iteration.
@@ -168,8 +182,10 @@ No source code available — only documentation.
 ```
 @Ferris BS
 # When asked for target, provide documentation URLs:
-# https://docs.cognee.ai/
+# https://docs.cognee.ai/v2/api/
 # Ferris sets source_type: "docs-only" and collects doc_urls
+# When asked for target version, specify: 2.0.0
+# Ferris confirms your doc URLs match that version
 @Ferris CS
 # step-03 skips (no source), step-03c fetches docs via doc_fetcher
 # All content is T3 [EXT:url] confidence. source_authority: community
@@ -177,6 +193,35 @@ No source code available — only documentation.
 
 The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whatever web fetching tool is available in its environment (Firecrawl, WebFetch, curl, etc.) to retrieve documentation as markdown and extract API information with T3 citations.
 
+### Scenario E: Rename a Skill
+
+You generated a quick skill for `cognee` and now want a more specific name to distinguish it from the official one.
+
+```
+@Ferris RS
+# Ferris asks: Which skill? → cognee
+# Ferris asks: New name? → cognee-skf-community
+# Ferris copies to new name across all versions, verifies every reference,
+# updates the export manifest, rebuilds CLAUDE.md/AGENTS.md,
+# then deletes the old name.
+```
+
+Transactional safety: if verification fails, the old skill stays intact.
+
+### Scenario F: Drop a Deprecated Version
+
+You have `cognee` with versions 0.1.0, 0.5.0, and 0.6.0 (active). Version 0.1.0 is obsolete.
+
+```
+@Ferris DS
+# Ferris asks: Which skill? → cognee
+# Ferris asks: Which version? → 0.1.0
+# Ferris asks: Deprecate (keep files) or Purge (delete)? → Purge
+# Ferris updates the manifest, rebuilds context files, deletes the 0.1.0 directory.
+```
+
+Version 0.6.0 remains active. Version 0.5.0 is untouched. The managed sections in CLAUDE.md/AGENTS.md no longer reference 0.1.0.
+
 ---
 
 ## Tips & Tricks
@@ -195,7 +240,15 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 ### The Loop
 
-After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
+After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates your platform context files (CLAUDE.md, AGENTS.md, .cursorrules) automatically. Skill generation becomes routine — like running tests.
+
+### One Workflow Per Session
+
+Clear your conversation context (start a new chat) before invoking a new workflow. Each SKF workflow loads step files, knowledge fragments, and extraction data into context. Starting fresh ensures the next workflow operates without interference from prior steps. Sidecar state (forge tier, preferences) persists automatically across sessions — you don't lose configuration.
+
+### Full Control Over Scope
+
+You can compile multiple skills from the same target (repo or docs) with different scopes and intents. Each brief defines what to extract and why, producing a distinct skill from the same source. For example, from a single library you could compile `cognee-core` for the public API, `cognee-graph-types` for the type system, and `cognee-migration` for upgrade patterns — each serving a different use case.
 
 ### Best Practices Built In
 

package/docs/getting-started.md

@@ -51,6 +51,18 @@ npx bmad-module-skill-forge install
 
 The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules.
 
+### Updating an existing SKF installation
+
+To move to a newer (or older) SKF version, run the installer again in your project directory:
+
+```bash
+npx bmad-module-skill-forge@latest install
+```
+
+The installer reads the installed version from your manifest and shows the delta in the prompt — for example `v0.8.3 → v0.8.4 available`. Pick **Update** to replace SKF files while keeping your `config.yaml` intact. The option label adapts to the direction you're moving (upgrade, reinstall the same version, or downgrade) so you always see exactly what you're about to apply. Pick **Fresh install** instead if you want to wipe everything and start clean.
+
+> The `@latest` suffix forces npx to fetch the newest published version instead of reusing a cached copy from a previous run.
+
 ---
 
 ## Prerequisites
@@ -103,14 +115,24 @@ This detects your tools, sets your capability tier, and initializes the forge en
 
 Ferris reads the repository, extracts the public API, and generates a skill in under a minute.
 
-**Full quality path:**
+**Targeting a specific version:** Append `@version` to pin the skill to a library version:
+```
+@Ferris QS cognee@0.5.0
+```
+
+**Full quality path (one workflow per session):**
 ```
 @Ferris BS    # Brief — scope and design the skill
+# — clear session —
 @Ferris CS    # Create — compile from the brief
+# — clear session —
 @Ferris TS    # Test — verify completeness
+# — clear session —
 @Ferris EX    # Export — package for distribution
 ```
 
+> Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference. See [Session Context](../concepts/#session-context).
+
 ### 3. Stack Skill (for full projects)
 
 ```