bmad-module-skill-forge 2.1.0 → 3.0.0

package/docs/skill-model.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: What a Skill Forge skill contains, from progressive capability tiers and the confidence model to 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](/docs/how-it-works.md). For the audit recipe that ties this all together, see [Verifying a Skill](/docs/verifying-a-skill.md).
@@ -13,10 +13,10 @@ SKF uses an additive tier model. You never lose capability by adding a tool.
 
 | Tier | Required Tools | What You Get |
 |------|---------------|-------------|
-| **Quick** | None (`gh_bridge`, `skill-check`, `tessl` used when available) | Source reading + spec validation + content quality review. Best-effort skills in under a minute. **Note:** Quick Skill (QS) is tier-unaware by design — it always runs at community tier regardless of installed tools. |
-| **Forge** | + `ast_bridge` (ast-grep) | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
-| **Forge+** | + `ccc_bridge` (cocoindex-code) | Semantic discovery. CCC pre-ranks files by meaning before AST extraction. Better coverage on large codebases. |
-| **Deep** | `ast_bridge` + `gh_bridge` (gh) + `qmd_bridge` (QMD). CCC optional — enhances when installed. | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
+| **Quick** | None (`gh_bridge` and `skill-check` used when available; `tessl` when you opt in to Tessl Review) | Source reading + spec validation. Best-effort skills in under a minute. **Note:** Quick Skill (QS) ignores your tier on purpose. It always reads source without ast-grep and records `confidence_tier: Quick` and `source_authority: community`, whatever tools you have installed. It never runs Tessl Review. |
+| **Forge** | + `ast_bridge` (ast-grep) | Structural truth. Each export an ast-grep rule matches is AST-verified and labeled T1; one it cannot match is read by eye and labeled T1-low. Co-import detection. |
+| **Forge+** | + `ccc_bridge` (cocoindex-code) | Semantic discovery. CCC ranks files by meaning, so a step that reads files one at a time reads the most relevant first; the ast-grep recipe runner reads every file in scope either way. Helps most on large codebases. |
+| **Deep** | `ast_bridge` + `gh_bridge` (gh) + `qmd_bridge` (QMD). CCC is optional and adds semantic discovery when installed. | Knowledge search. Temporal provenance (issue, PR and changelog history). Audit Skill adds QMD semantic comparison to its drift checks. Full intelligence. |
 
 Setup detects your installed tools and sets your tier automatically:
 
@@ -30,7 +30,7 @@ Setup detects your installed tools and sets your tier automatically:
 ═══════════════════════════════════════
 
   Tier:  Deep
-  Deep tier active. Full capability unlocked — AST-backed code analysis,
+  Deep tier active. Full capability unlocked: AST-backed code analysis,
   GitHub repository exploration, and QMD knowledge search with
   cross-repository synthesis. Maximum provenance and intelligence.
 
@@ -45,30 +45,29 @@ Setup detects your installed tools and sets your tier automatically:
   23 orphaned collection(s) kept
 
   CCC Index:
-  indexed this run — semantic discovery ready (1 file)
+  indexed this run, semantic discovery ready (1 file)
 
   Files written this run:
-  - forge-tier.yaml — {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
-  - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml (6 SKF exclusion patterns merged)
-  - .cocoindex_code/ ccc index — 1 file indexed
+  - forge-tier.yaml: {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
+  - {project-root}/forge-data/ (directory ensured)
+  - .cocoindex_code/settings.yml: {project-root}/.cocoindex_code/settings.yml (6 SKF exclusion patterns merged)
+  - .gitignore: {project-root}/.gitignore (`/.cocoindex_code/` added by `ccc init`)
+  - .cocoindex_code/ ccc index: 1 file indexed
 
 ═══════════════════════════════════════
   Forge ready. Deep tier active.
 ═══════════════════════════════════════
 
-  Next: try [BS] Brief Skill to scope your first compilation target,
-  or [QS] Quick Skill for a fast template-driven path.
-  Already have a skill? [AS] Audit Skill drift-checks an existing skill
-  against current sources.
-
 Health Check: Clean run. No workflow issues to report.
 
 Workflow complete.
 ```
 
-Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with no additional tools. Optional GitHub CLI improves source access. Install tools later; your tier upgrades automatically.
+Setup then suggests where to go next: `@Ferris forge-auto <repo-or-doc-url>` briefs, compiles, tests and exports a skill in one command; `/skf-brief-skill` lets you scope a skill by hand; `/skf-quick-skill` is a fast template-driven path; and `/skf-audit-skill` checks a skill you already have against its current source.
+
+Don't have ast-grep, cocoindex-code, or QMD yet? That's fine. Quick tier works with no extra tools, and the GitHub CLI (`gh`), if you have it, helps it read remote source. When you install a tool later, run `@Ferris SF` again: setup detects it and raises your tier.
 
-### Tier Override — Comparing Output Across Tiers
+### Tier Override: Comparing Output Across Tiers
 
 You can force a specific tier by setting `tier_override` in your preferences file (`_bmad/_memory/forger-sidecar/preferences.yaml`):
 
@@ -77,22 +76,22 @@ You can force a specific tier by setting `tier_override` in your preferences fil
 tier_override: Forge
 ```
 
-This is useful for comparing skill quality across tiers for the same target:
+This is useful for comparing skill quality across tiers for the same target. Each recompile writes into the same version folder and replaces the previous run's files, so commit or copy the skill folder before you switch tiers:
 
 ```
 # 1. Set tier_override: Quick in preferences.yaml
 @Ferris CS                # compile at Quick tier
 
 # 2. Change to tier_override: Forge
-@Ferris CS                # recompile at Forge tier — compare output
+@Ferris CS                # recompile at Forge tier, then compare output
 
 # 3. Change to tier_override: Forge+
-@Ferris CS                # recompile with semantic discovery — compare coverage
+@Ferris CS                # recompile with semantic discovery, then compare coverage
 
 # 4. Reset to tier_override: ~ (auto-detect)
 ```
 
-Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (AN, BS, CS, SS, US, AS, TS).
+Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep` (capital letters matter). Set it to `~` (null) to return to auto-detection. Setup (SF) and every tier-aware workflow respect it: Analyze Source (AN), Brief Skill (BS), Create Skill (CS), Stack Skill (SS), Update Skill (US), Audit Skill (AS) and Test Skill (TS). Quick Skill (QS) ignores it. SKF ignores a value it does not recognize and uses the detected tier. You can force a tier your tools do not support, but setup warns you, and steps that need a missing tool then stop or fall back to a lower tier with a warning.
 
 ---
 
@@ -102,39 +101,43 @@ Every claim in a generated skill carries a confidence tier that traces to its so
 
 | Tier | Source | Tool | What It Means |
 |------|--------|------|---------------|
-| **T1** | AST extraction | `ast_bridge` | Current code, structurally verified. Immutable for that version. |
-| **T1-low** | Source reading | `ast_bridge` (fallback) | Source-read without AST verification. Produced by Quick tier and by Forge/Forge+/Deep when ast-grep cannot parse a specific file. Location correct, signature may be inferred. |
+| **T1** | AST extraction | `ast_bridge` | An ast-grep rule matched the export in the current code: structurally verified, and immutable for that version. Cited `[AST:file:Lnn]`. |
+| **T1-low** | Source reading | Source reading (no ast-grep) | Read from source without AST verification. Produced by Quick tier, and by Forge, Forge+ and Deep for any export read by eye: when ast-grep cannot parse a file, when a remote source cannot be cloned, or when an export is read directly while ast-grep works. Location correct, signature may be inferred. Cited `[SRC:file:Lnn]`. |
 | **T2** | QMD evidence | `qmd_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
-| **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
+| **T3** | External documentation | `doc_fetcher` | External and untrusted, so SKF keeps it apart: a T3 claim keeps its `[EXT:...]` label and never overrides a T1, T1-low or T2 claim. |
+
+**Labels follow the tool that read each export, not the forge tier.** A Deep-tier skill can hold T1-low entries next to its T1 ones, and its provenance map records each entry's `extraction_method` (`ast-grep` or `source-read`) beside its `confidence`. Before SKF 3.0.0 the label followed the forge tier, so a skill built at Forge or above could claim T1 for an export nothing parsed. Expect lower T1 counts, in the skill's citations and in its `metadata.json` `confidence_distribution`, when you build or update a skill now, with nothing less extracted. Audit Skill lists a label that changed this way in its own table, "Provenance label differences (not drift)", and never counts it as drift.
 
 ### Temporal Provenance
 
 Confidence tiers map to temporal scopes:
 
-- **T1-now (instructions):** What ast-grep sees in the checked-out code. This is what your agent executes.
-- **T2-past (annotations):** Closed issues, merged PRs, changelogs — why the API looks the way it does.
-- **T2-future (annotations):** Open PRs, deprecation warnings, RFCs — what's coming.
+- **T1-now (instructions):** What the checked-out code holds, read by ast-grep (T1) or by eye (T1-low). This is what your agent executes.
+- **T2-past (annotations):** Closed issues, merged PRs and changelogs that explain why the API looks the way it does.
+- **T2-future (annotations):** Open PRs, deprecation warnings and RFCs that show what's coming.
 
 Progressive disclosure controls how much context surfaces at each level:
 
 | Output | Content |
 |--------|---------|
-| `context-snippet.md` | T1-now + T2-future gotchas (breaking changes, deprecation warnings) — compressed, always-on |
-| `SKILL.md` | T1-now + lightweight T2 annotations |
+| `context-snippet.md` | T1-now + T2-future gotchas (breaking changes, deprecation warnings), compressed and always on |
+| `SKILL.md` | T1-now, plus T2-future migration and deprecation warnings (Deep tier only) |
 | `references/` | Full temporal context with all tiers |
 
-### Tier Constrains Authority
+### Tier and Authority
+
+Your forge tier sets how strong a skill's accuracy guarantee can be:
 
-Your forge tier limits what authority claims a skill can make:
+| Forge Tier | AST? | CCC? | QMD? | Accuracy Guarantee |
+|-----------|------|------|------|-------------------|
+| Quick | No | No | No | Best-effort |
+| Forge | Yes | No | No | Structural (each export ast-grep matches is AST-verified) |
+| Forge+ | Yes | Yes | No | Structural + semantic discovery |
+| Deep | Yes | Optional (adds semantic discovery) | Yes | Full (structural + contextual + temporal) |
 
-| Forge Tier | AST? | CCC? | QMD? | Max Authority | Accuracy Guarantee |
-|-----------|------|------|------|---------------|-------------------|
-| Quick | No | No | No | `community` | Best-effort |
-| Forge | Yes | No | No | `official` | Structural (AST-verified) |
-| Forge+ | Yes | Yes | No | `official` | Structural + semantic discovery |
-| Deep | Yes | opt. (enhances when installed) | Yes | `official` | Full (structural + contextual + temporal) |
+At every tier the structural guarantee covers the exports an ast-grep rule matched: an export it could not match is labeled T1-low and cited `[SRC:...]`, even in a Deep-tier skill.
 
-**Tier governs technical verification; authority is an ecosystem claim.** Reaching Deep tier unlocks the *capability* to claim `official` authority — it does not grant it. Only library maintainers can publish `source_authority: official` skills via the [agentskills.io](https://agentskills.io) open-format ecosystem. A Deep-tier skill compiled by a third party is `community` by default. See [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills), where all four Deep-tier skills ship as `community` by design — audited, not blessed.
+**Tier and authority are separate.** Tier says how deeply SKF could check the code. Authority (`source_authority`) says who stands behind the skill, and it comes from your brief, not from your tools. Brief Skill asks whether you maintain the library: a maintainer gets `official`, a private or company codebase gets `internal`, and everyone else gets `community`, the default. In a headless run where you do not set it, SKF picks `official` only when your GitHub login matches the repo owner. Quick Skill and docs-only skills are always `community`. Only library maintainers should publish `official` skills to the [agentskills.io](https://agentskills.io) open-format ecosystem, so a Deep-tier skill compiled by a third party stays `community`. See [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills), where all four Deep-tier skills ship as `community` by design: audited, not blessed.
 
 ---
 
@@ -170,9 +173,11 @@ skills/{name}/
         └── ...
 ```
 
-Multiple versions coexist under the same skill name. The `active` symlink points to the current version. Updating a skill for a new library release creates a new version directory — users pinned to older versions keep their skill intact. The inner `{name}/` directory is a standalone [agentskills.io](https://agentskills.io) package, directly installable via `npx skills add`.
+Multiple versions coexist under the same skill name. The `active` symlink points to the current version. Updating a skill for a new library release creates a new version directory, so users pinned to older versions keep their skill intact. The inner `{name}/` directory is a standalone [agentskills.io](https://agentskills.io) package, directly installable via `npx skills add`.
 
-The `scripts/` and `assets/` directories are optional — only created when the source repository contains executable scripts or static assets matching detection heuristics. Each file traces to its source via `[SRC:file:L1]` provenance citations with SHA-256 content hashes for drift detection. User-authored files go in `scripts/[MANUAL]/` or `assets/[MANUAL]/` subdirectories and are preserved during updates.
+The `scripts/` and `assets/` directories are optional. SKF creates them only when the source repository contains executable scripts or static assets that match its detection rules. Each file traces to its source via `[SRC:file:L1]` provenance citations with SHA-256 content hashes for drift detection. User-authored files go in `scripts/[MANUAL]/` or `assets/[MANUAL]/` subdirectories and are preserved during updates.
+
+SKF also keeps workspace files for each version outside the skill package, in `forge-data/{name}/{version}/` by default: `provenance-map.json` (where each documented symbol came from), `evidence-report.md`, `extraction-rules.yaml` and test reports. The brief, `skill-brief.yaml`, sits one level up in `forge-data/{name}/`. These files are not part of the installable package; see [Verifying a Skill](/docs/verifying-a-skill.md) for how to use them.
 
 ### SKILL.md Format
 
@@ -197,19 +202,19 @@ description: >
 ---
 ```
 
-Every instruction in the body traces to source:
+Every instruction in the body traces to source, with a citation that names the tool that read it (`[AST:]` for an ast-grep match, `[SRC:]` for a read by eye):
 
 ```python
-await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L27]
     query_text="What does Cognee do?"
 )
 ```
 
-### metadata.json — The Birth Certificate
+### metadata.json: The Birth Certificate
 
 Machine-readable provenance for every skill:
 
-This is a trimmed excerpt from the real [`oms-cognee/1.0.0/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/metadata.json) shipped with the oh-my-skills canonical output. Every value below is verbatim from the file — not illustrative.
+This is a trimmed excerpt from the real [`oms-cognee/1.0.0/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/metadata.json) shipped with the oh-my-skills canonical output. Every value below is copied from the file, not made up for illustration.
 
 ```json
 {
@@ -218,7 +223,7 @@ This is a trimmed excerpt from the real [`oms-cognee/1.0.0/metadata.json`](https
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "https://github.com/topoteretes/cognee",
-  "source_commit": "3c048aa4147776f14d4546704f986242554a9ef3",
+  "source_commit": "3c048aa4",
   "source_ref": "v1.0.0",
   "confidence_tier": "Deep",
   "spec_version": "1.3",
@@ -242,13 +247,17 @@ This is a trimmed excerpt from the real [`oms-cognee/1.0.0/metadata.json`](https
 }
 ```
 
-Fields omitted from this excerpt for brevity: `description`, `exports[]`, `tool_versions`, `dependencies`, `compatibility`, `last_update`, `generated_by`. The full 93-line file lives at [`oh-my-skills/skills/oms-cognee/1.0.0/oms-cognee/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/metadata.json).
+Fields omitted from this excerpt for brevity: `source_root`, `description`, `exports[]`, `tool_versions`, `dependencies`, `compatibility`, `generated_by`, and a `last_update` that an earlier SKF version wrote. Update Skill now records `last_update` and `update_type` at the top level of `provenance-map.json` in `forge-data/{name}/{version}/`, and an update removes both from `metadata.json`, which marks an update only in `generation_date`. The full 93-line file lives at [`oh-my-skills/skills/oms-cognee/1.0.0/oms-cognee/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/metadata.json).
+
+Two fields are easy to mix up. `confidence_tier` holds the forge tier a single skill like this one was compiled at (Quick, Forge, Forge+ or Deep). A stack skill records there the dominant confidence tier of its libraries (T1, T1-low, T2 or T3) and keeps its forge tier in `forge_tier`; Export Skill still accepts a forge tier from a stack made by an earlier SKF version, with a warning that running Stack Skill again records the dominant tier. `confidence_distribution` counts the claims at each confidence tier (T1, T1-low, T2, T3). In a stack it counts each library once, by the library's tier, so its bins sum to `library_count`.
 
-`scripts` and `assets` arrays are optional — omitted entirely (not empty) when the source has no scripts or assets.
+The excerpt's `t1` count of 34 comes from an SKF version that labeled exports by the forge tier. This skill's provenance map records its exports as read by eye (`source-read`), which SKF 3.0.0 counts as `t1_low`: only an export an ast-grep rule matched counts as `t1` now, and `ast_node_count` counts only those exports.
+
+`scripts` and `assets` arrays are optional: SKF leaves them out entirely, rather than writing empty arrays, when the source has no scripts or assets.
 
 ### Stack Skill Output
 
-Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
+Stack skills map how your dependencies interact: shared types, co-import patterns and integration points.
 
 ```
 skills/{project}-stack/
@@ -266,36 +275,38 @@ skills/{project}-stack/
                 └── pwa-auth.md   # Cross-library pattern
 ```
 
-The primary source is your project repo. Component references trace to library repos. `skill_type: "stack"` in metadata.
+In code-mode, the source is your project repo: SKF reads your dependency manifests and finds where libraries are imported together, and component references trace to library repos. In compose-mode, when there is no code yet, SKF builds the stack skill from skills you already compiled plus your architecture document, and labels any integration it infers. Either way, `metadata.json` records `skill_type: "stack"`.
 
 ---
 
 ## Dual-Output Strategy
 
-Every skill SKF compiles ships as **two** files on purpose — and the reason is empirical, not aesthetic.
+Every skill SKF compiles ships as **two** files on purpose, and the reason is empirical, not aesthetic.
 
-> **[Vercel research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):** passive context (`AGENTS.md` / `CLAUDE.md`) achieves a **100% pass rate** in agent evals. Active skills loaded alone achieve **79%**. The 21-point gap is what the dual-output strategy closes.
+> **[Vercel research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals):** a compressed docs index in passive context (`AGENTS.md`) reached a **100% pass rate** in Vercel's agent evals. Skills peaked at **79%**, and only when the agent was told explicitly to use them; left to decide on its own, the agent gained nothing from the skill over having no docs at all (53%). The dual-output strategy is built to close that 21-point gap.
 
 Every skill generates both:
 
-1. **`SKILL.md`** — Active skill, loaded on trigger with the full instruction set. This is the instruction manual your agent opens when it knows it needs library guidance.
-2. **`context-snippet.md`** — Passive context, compressed to 80–120 tokens per skill. Injected into platform context files (`CLAUDE.md` / `AGENTS.md` / `.cursorrules`) only when `export-skill` is run. This is the ambient index that tells your agent the skill exists in the first place and should be opened for relevant work.
+1. **`SKILL.md`**: the active skill, loaded on trigger with the full instruction set. This is the instruction manual your agent opens when it knows it needs library guidance.
+2. **`context-snippet.md`**: passive context, compressed to about 80 to 120 tokens per skill (a Deep-tier skill whose gotchas carry breaking changes can run longer). Only `export-skill` injects it into platform context files (`CLAUDE.md` / `AGENTS.md` / `.cursorrules`). This is the ambient index that tells your agent the skill exists in the first place and should be opened for relevant work.
+
+If you do not want SKF to touch those files, set `passive_context: false` in your preferences file (`_bmad/_memory/forger-sidecar/preferences.yaml`). Export then skips the snippet and the managed section.
 
-Without the snippet, the agent never knows to open `SKILL.md`. Without `SKILL.md`, the snippet has nothing to point at. **Both halves are load-bearing.** That's the 21-point delta.
+Without the snippet, the agent has to decide on its own that a skill is relevant, and it often skips `SKILL.md`. Without `SKILL.md`, the snippet has nothing to point at. **Both halves are load-bearing.**
 
 ### Managed Context Section
 
 Export injects a managed section between markers:
 
-The block below is the real managed section currently in [`oh-my-skills/CLAUDE.md`](https://github.com/armelhbobdad/oh-my-skills/blob/main/CLAUDE.md), showing one of its four compiled skills. Every line is verbatim from the file:
+The block below is the real managed section currently in [`oh-my-skills/CLAUDE.md`](https://github.com/armelhbobdad/oh-my-skills/blob/main/CLAUDE.md), showing one of its four compiled skills. Every line is copied from the file except the last one before `<!-- SKF:END -->`, which stands in for the three skills left out:
 
 ```markdown
-<!-- SKF:BEGIN updated:2026-04-13 -->
+<!-- SKF:BEGIN updated:2026-04-25 -->
 [SKF Skills]|4 skills|0 stack
 |IMPORTANT: Prefer documented APIs over training data.
 |When using a listed library, read its SKILL.md before writing code.
 |
-|[oms-cognee v1.0.0]|root: .claude/skills/oms-cognee/
+|[oms-cognee v1.0.0]|root: skills/oms-cognee/
 |IMPORTANT: oms-cognee v1.0.0 — read SKILL.md before writing cognee code. Do NOT rely on training data.
 |quick-start:SKILL.md#quick-start
 |api-v1: add(), cognify(), search(), memify(), update(), run_custom_pipeline(), visualize_graph(), datasets, prune, config, SearchType, pipelines, Drop, run_startup_migrations(), session, tracing
@@ -303,11 +314,11 @@ The block below is the real managed section currently in [`oh-my-skills/CLAUDE.m
 |key-types:SKILL.md#key-types — SearchType: GRAPH_COMPLETION (default), RAG_COMPLETION, CHUNKS, CHUNKS_LEXICAL, SUMMARIES, TEMPORAL, CODING_RULES, CYPHER, FEELING_LUCKY, GRAPH_COMPLETION_DECOMPOSITION (+5 more); Task, Drop, RememberResult, DataPoint, 5 Cognee* exceptions
 |gotchas: cognee.low_level REMOVED from public API in v1.0.0 (import from cognee.infrastructure.engine directly); cognee.run_migrations REPLACED by cognee.run_startup_migrations (relational + vector); cognee.delete is DEPRECATED since v0.3.9 (use cognee.datasets.delete_data or cognee.forget); cognee.pipelines restructured in v1.0.0 (package with Drop + lazy re-exports); cognee.agent_memory requires async function; cognee.serve() without url triggers Auth0 Device Code Flow; cognee.start_ui is sync and needs pid_callback arg; all add/cognify/search/memify/remember/recall/improve/forget/serve are async — always await.
 |
-|(three more skills — oms-cocoindex, oms-storybook-react-vite, oms-uitripled — omitted here for brevity; see the full file)
+|(three more skills are left out here for brevity: oms-cocoindex, oms-storybook-react-vite and oms-uitripled; see the full file)
 <!-- SKF:END -->
 ```
 
-~80-120 tokens per skill (version-pinned, retrieval instruction, section anchors, inline gotchas). Root paths are per-IDE — each of the 23 supported IDEs has its own skill directory (e.g., `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.windsurf/skills/`). See [`skf-export-skill/assets/managed-section-format.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the complete IDE → Context File Mapping. Aligned with [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that indexed format with explicit retrieval instructions dramatically improves agent performance. Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations. An `.export-manifest.json` tracks which skills have been explicitly exported, preventing draft skills from leaking into the managed section.
+A snippet aims for about 80 to 120 tokens per skill: the version, an instruction to read `SKILL.md`, section anchors and inline gotchas. A Deep-tier skill whose gotchas carry breaking changes can run longer, like the cognee entry above. Root paths are per-IDE: each of the 23 supported IDEs has its own skill directory (for example `.claude/skills/`, `.cursor/skills/`, `.github/skills/`, `.windsurf/skills/`). A repo that keeps all its skills in one shared folder can set `snippet_skill_root_override` in its SKF `config.yaml` instead, which is why the oh-my-skills root paths start with `skills/`. See [`skf-export-skill/assets/managed-section-format.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the complete mapping from IDE to context file. The format follows [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that an index with explicit retrieval instructions greatly improves agent performance. You decide where the section sits in the file; Ferris decides what goes between the markers. Create Skill and Update Skill also write `context-snippet.md`, but only as a draft inside the skill folder, and they never touch the managed section. Only `export-skill` adds a skill there, and an `.export-manifest.json` file records which skills you have exported, so drafts never leak into the managed section.
 
 ---
 

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 ---
 title: Troubleshooting
-description: Common errors in Skill Forge — forge setup, ecosystem checks, tier confidence — and how to resolve them.
+description: Common Skill Forge errors and how to fix them, from setup and tiers to skill ownership, updates, renames, Tessl Review and campaigns.
 ---
 
 If something isn't working, start here. For general setup help see [Getting Started → Need help?](/docs/getting-started.md#need-help).
@@ -11,57 +11,174 @@ If something isn't working, start here. For general setup help see [Getting Star
 
 ### "Setup cannot proceed: `uv` is not installed"
 
-Surfaced by `/skf-setup` On Activation when `uv --version` is missing on `$PATH`. SKF helpers depend on `uv` to auto-resolve their Python dependencies via PEP 723 inline metadata; bare `python3` ignores that metadata and would fail later with `ModuleNotFoundError: No module named 'yaml'`. The probe halts the workflow up-front with one cohesive diagnostic instead of letting five steps each fail individually.
+Setup checks for `uv` when it starts, before it detects your tools or writes anything. SKF's helper scripts use `uv` to install the Python packages they need; plain `python3` skips that and later fails with `ModuleNotFoundError: No module named 'yaml'`. So setup stops at once with one clear message instead of failing partway through. Under `--headless` or `--quiet`, the same message arrives as the `error.reason` of an `SKF_SETUP_RESULT_JSON` line whose `status` is `"blocked"`. The helper that builds that line needs only the Python standard library, so setup uses the first of `python3`, `python` or `py -3` that runs on the machine. With none of them, the run's one line is the message alone. Pipelines should treat a run with no `SKF_SETUP_RESULT_JSON` line as a failure.
 
 **Fix:** install `uv` from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. `uv` is documented as a runtime prerequisite in [Getting Started → Prerequisites](/docs/getting-started.md#prerequisites-full-reference).
 
-### "Setup cannot proceed: `_bmad/skf/config.yaml` was not found"
+### "Setup cannot proceed: the SKF config file was not found"
 
-Surfaced by `/skf-setup` On Activation when the SKF install config is missing — typically because you invoked `/skf-setup` from a directory that is not an SKF-initialised project. The check runs before any file mutation so nothing is written.
+Surfaced by `/skf-setup` when the SKF install config, `_bmad/skf/config.yaml`, is missing, usually because you ran `/skf-setup` from a folder where SKF is not installed. The check runs before setup writes anything. Under `--headless` or `--quiet`, the same message arrives as the `error.reason` of an `SKF_SETUP_RESULT_JSON` line whose `status` is `"blocked"`, but only when SKF's scripts are installed in the project and `uv` or a Python interpreter can run them. Usually they are not (the folder is not an SKF project, or the install lost its scripts), so nothing can build that line and the run's one line is the message alone. Pipelines should treat a run with no `SKF_SETUP_RESULT_JSON` line as a failure.
 
-**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see [Getting Started → Install](/docs/getting-started.md#install)), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate "config.yaml is not valid YAML" diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
+Ferris makes the same check before he greets you and stops with "Cannot initialize. SKF is not installed in this project". Neither setup nor Ferris can fix this: setup reads the file and never writes it, and only the installer does, so both messages name the installer command below.
+
+**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module; see [Getting Started → Install](/docs/getting-started.md#install)), then re-run `/skf-setup`, or start Ferris again and give him SF. If you are in the right project but the file was deleted, restore it from version control or re-run the SKF installer. The installer also puts back SKF's scripts and knowledge files: Ferris stops with "Cannot initialize. SKF's scripts are missing from this project" when the config is there but the scripts are not, and KI says so when the knowledge index is missing. If the file exists but is malformed, setup stops with the same message Ferris shows instead: Ferris names the file and the parser error ("YAML parse error in ..."), so open `_bmad/skf/config.yaml` and repair the YAML. If its `sidecar_path` is missing or still holds a placeholder, both stop with the value to set.
 
 ### Forge reports ast-grep is unavailable
 
-If setup reports that ast-grep was not detected, install it to unlock the Forge tier: <https://ast-grep.github.io>. Re-run `@Ferris SF` afterward — your tier upgrades automatically.
+If setup reports that ast-grep was not detected, install it to unlock the Forge tier: <https://ast-grep.github.io>. Re-run `@Ferris SF` afterward and your tier upgrades automatically. If `tier_override` is set in `_bmad/_memory/forger-sidecar/preferences.yaml`, setup keeps that tier instead; set it to `~` to use the detected one.
 
 ### "No skill brief found"
 
-Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation. `CS` always requires a brief — either a `skill-brief.yaml` produced by `BS` (or `AN`), or pass the skill name so it resolves one from your forge-data folder. For brief-less generation use `QS`.
+Create Skill (`CS`) always needs a skill brief. Given a skill name, it loads `<forge_data_folder>/<skill-name>/skill-brief.yaml`; given a path, it loads that brief file. Run with no brief path, skill name or `--batch`, it loads the only brief in `forge_data_folder` and names it in its banner, and with several briefs there it asks which one to compile. A headless run that finds several stops with exit code 2 (`brief-missing`) and names them: pass the brief's path or skill name, or `--batch` to compile them all. "No skill brief found" means the brief you named does not exist or, with nothing named, that `forge_data_folder` holds no brief.
+
+**Fix:** run `@Ferris BS` to write a brief (or `@Ferris AN` to get recommended briefs for a large repo), then run `@Ferris CS <skill-name>`. To make a skill without a brief, use `@Ferris QS` instead.
 
-### "Ecosystem check: official skill exists"
+### "Ecosystem match found"
 
-An official skill already exists for this package. Consider installing it with `npx skills add` instead of generating your own — the official skill is typically better tested and kept up-to-date by the library maintainer.
+No run stops here today. Quick Skill has a step that checks for an official skill that already covers your source, but agentskills.io offers no registry API to ask, so the step skips the check and Quick Skill goes straight on to extraction. Create Skill has no such check since 3.0.0. Once a registry API lists an official skill for your source, Quick Skill will show it with three choices: **[P] Proceed** compiles your own skill anyway, for a different scope or custom content; **[I] Install** stops so you can install the official skill instead; **[A] Abort** cancels. A headless run will pick **[P]**. When you already know of an official skill that fits your needs, installing it with `npx skills add <skill-name>` is usually the better choice, because the library's maintainers test it and keep it current.
 
 ### Quick-tier skills have lower confidence scores
 
-Quick tier reads source without AST analysis, so signatures are read directly from files rather than structurally verified. Install ast-grep to upgrade to the Forge tier for AST-verified signatures (T1 confidence) — see [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
+Quick tier reads source without AST analysis, so signatures are read directly from files rather than structurally verified, and its claims carry the T1-low confidence label. Install ast-grep to upgrade to the Forge tier, where each export an ast-grep rule matches is AST-verified and labeled T1. The label follows the tool that read the export, not the tier: an export ast-grep cannot match, because it cannot parse the file or no rule fits the export, is still read by eye and labeled T1-low, at Forge, Forge+ and Deep too. See [Confidence Tiers](/docs/concepts.md#confidence-tiers-t1t1-lowt2t3).
 
 ### Want semantic discovery for large codebases?
 
-Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlock the Forge+ tier. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
+Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) (the `ccc` command) alongside ast-grep to unlock the Forge+ tier, then re-run `@Ferris SF`. CCC indexes your codebase and ranks its files by meaning, so a step that reads files one at a time reads the most relevant ones first, which helps most on projects with 500+ files. The ast-grep recipe runner reads every file in scope either way.
+
+### `git status` lists a `.cocoindex_code` folder inside a source folder
+
+When ccc is available (Forge+, or Deep with ccc), create-skill indexes the skill's source with it. A local source folder inside your project or inside another git checkout (a subfolder such as `./packages/lib`, a linked worktree or a submodule) becomes a ccc project of its own, and ccc does not gitignore an index there. create-skill keeps it out of git by writing a `.gitignore` holding `*` inside that `.cocoindex_code/` folder, and says so in one line; it never edits your own `.gitignore`. For a folder an earlier SKF release left untracked, run create-skill for that source again, or create `<source>/.cocoindex_code/.gitignore` holding the single line `*`. If you already committed the index, `git rm -r --cached <source>/.cocoindex_code` stops tracking it.
 
 ### `@Ferris deepwiki` shows a deprecation notice
 
-The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](/docs/forge-auto.md) — renamed to avoid confusion with the DeepWiki MCP, since the pipeline compiles a verified skill from source and does **not** call that MCP. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
+The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](/docs/forge-auto.md). It was renamed to avoid confusion with the DeepWiki MCP server, since the pipeline compiles a verified skill from source and does **not** call that server. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
 
 ### `@Ferris onboard` returns an error
 
 The `onboard` alias was removed. Its replacement is [`forge-auto`](/docs/forge-auto.md), which does everything `onboard` did plus auto-scope, auto-brief, and a stricter 90% quality gate. Run `@Ferris forge-auto <repo-or-doc-url>` instead.
 
+### Test Skill stops with `workspace-drift`
+
+Test Skill checks a skill against the source commit it was made from. When the source folder's git checkout is at a different commit from the one the skill records (`source_commit` in its `metadata.json`), the results would show false gaps, so Test Skill stops before it writes a report.
+
+**Fix:** check out the pinned commit the message shows with `git -C <source> checkout <pinned commit>`, then re-run `@Ferris TS <name>`. The checkout line in the message names the skill's `source_ref` when it has one. When `source_ref` is a branch, that line does not move a checkout that is already on a newer commit of the branch. To test against the source as it is now, re-run with `--allow-workspace-drift`: the findings then describe the current checkout, and a pass under that flag does not clear the skill for export until you re-test at the pinned commit. Right after an update, follow the update's report instead (see "Update Skill stops with `blocked` before detecting changes").
+
 ### forge-auto halted at the Test stage
 
-forge-auto runs Test Skill with a stricter **90% quality threshold** (vs the default 80%), so a skill that scores below 90% halts at TS with a gap report rather than exporting a weak skill. Run `@Ferris US` to address the gaps it lists, then `@Ferris TS EX` to re-test and export. If 90% is stricter than you need, run the individual workflows or `forge` instead, which use the default threshold.
+forge-auto aims for 90%, stricter than the default 80%. A score of at least 80% but under 90% still passes, with an `evidence-report-fallback.md` that records the shortfall, unless a cap fired. TS stops the pipeline on any verdict but PASS: every FAIL (a score below 80%, a Critical or High gap at the hard gate, or a cap that turned a pass into a fail whatever the score), INCONCLUSIVE, and pass-with-drift. Run `@Ferris US <name> --from-test-report` to repair the gaps the report lists, then `@Ferris TS[<name>] EX` to test and export again (the brackets give Test Skill the skill's name). A plain `@Ferris US <name>` finds a failed or pass-with-drift test report that is newer than the skill and that no repair has applied, and offers to repair its gaps; a headless run checks the source for changes instead and adds an `unconsumed-test-report` warning. For INCONCLUSIVE, add evidence as [Pass/fail](/docs/verifying-a-skill.md#passfail) describes; for pass-with-drift, test again at the pinned commit. If 90% is stricter than you need, run the individual workflows or `forge` instead, which use the default threshold.
+
+### "Inventory scan unreliable"
+
+Surfaced by Verify Stack and Refine Architecture (exit `7`, `inventory-unreliable`) when there is more than one warning for every four skills SKF generated. Each of these counts as a warning: a `metadata.json` or version folder SKF cannot read, a skill SKF generated with no `SKILL.md` or no exports found in `metadata.json`, `references/` or `SKILL.md`, or a `composes` cycle. Skills SKF did not generate, such as a module's own skills in a shared `skills_output_folder`, are listed once as "Skipped (not SKF output)" and never count. A `metadata.json` SKF cannot read counts whoever made the skill, because SKF then cannot tell whether it generated that skill.
+
+**Fix:** the message names each warning. Re-save an unreadable `metadata.json` as a plain UTF-8 JSON object, without comments or a byte-order mark, or restore it from version control; when another tool owns that skill and needs the file as it is, move the skill out of `skills_output_folder`. Regenerate a skill whose exports are missing with the workflow that made it (`@Ferris CS <name>`, `@Ferris QS` for a Quick Skill, or `@Ferris SS` for a stack skill). For a `composes` cycle, the named skills list each other, directly or through other skills, in the `composes` field of their `metadata.json`: remove the loop from one of those lists. Then re-run.
+
+### "`<name>` is not SKF output"
+
+SKF only writes into, migrates, renames or purges a skill whose `metadata.json` carries SKF's marker. A folder in `skills_output_folder` without that marker, such as a BMad module's own skills or skills another tool installed, makes the workflow stop before it changes anything when:
+
+- create-skill, quick-skill or create-stack-skill would write a new version into it;
+- update-skill, export-skill, audit-skill or test-skill would move a flat skill in it into the versioned layout;
+- drop-skill would delete it, or rename-skill would rename it.
+
+Drop and rename also refuse a skill folder that mixes SKF output with other files. Rename and the three writers refuse an SKF skill that is still in the old flat layout (`flat-layout`). Drop and rename check the skill's folder in `forge_data_folder` too. They refuse one that mixes SKF's brief and reports with other files, and rename also refuses one that is a link, is not a folder, or cannot be listed. A folder there that SKF did not generate, such as another tool's folder of the same name, stays where it is, and both list it as "Left in place (not SKF output)". Verify Stack, Refine Architecture and compose-mode Stack Skill never stop on such skills. They list them once as "Skipped (not SKF output)" and leave them out of every inventory check, unless SKF cannot read a skill's `metadata.json` (see "Inventory scan unreliable").
+
+**Fix:** a `skills_output_folder` shared with skills from elsewhere is supported, and SKF leaves the skills it did not generate alone, so manage `<name>` yourself (to remove it, delete its folder). For create-skill, set a different `name` in the brief to create the skill beside that folder; for create-stack-skill, pass another `stack_name` (or choose a different `project_name`); Quick Skill names a skill after its target, so use Brief Skill and Create Skill to pick another name. If the entries SKF names are in `forge_data_folder/<name>/`, move your own files out of that folder (for a link, replace it with the folder it points to; for a path that is not a folder or cannot be listed, move it out of the way or fix its permissions), then re-run. Relocate only when the folder holds a module's own source rather than skills: then set `skills_output_folder` in `_bmad/skf/config.yaml` to a folder of its own, move your SKF skills there, and re-run `/skf-setup`. If SKF did generate the skill and its `metadata.json` was edited or lost, restore that file; if the message says SKF cannot read it (for example `Unexpected UTF-8 BOM`), re-save it as plain UTF-8. For `flat-layout`, run `@Ferris TS <name>` once to move the skill into the versioned layout, then re-run the workflow that stopped. If the entries SKF names include a version folder with no `metadata.json`, an interrupted update-skill, create-skill, quick-skill or create-stack-skill run may have left it: delete that folder, then re-run the workflow. An entry named `<version>/<entry>` is a file or folder placed inside an SKF version folder: move it out of `<name>/<version>/`, then re-run.
+
+**`<name>` still uses the flat layout:** update-skill `--detect-only` and `--dry-run` never move a skill, but they need the versioned layout, so they stop on an SKF skill that is still flat. Run `@Ferris US <name>` once without the flag (or AS, TS or EX) to move it into the versioned layout, then re-run with the flag.
+
+**Skills an earlier SKF already moved:** an SKF release without this check could move a module's flat skill into `<name>/<version>/<name>/` and add an `active` link. Recover it from version control: `git status` shows what moved, `git restore <skills-folder>/<name>` brings back the original files, and you then delete the `<version>/` folder and `active` link that SKF added. The same recovery applies when an SKF release without this check wrote a new version into such a folder: delete the `<version>/` folder and `active` link it added, and restore any file it replaced with `git restore`. Until you recover them, `/skf-setup` keeps those skills in the ccc search index as long as none of their version folders carries the SKF marker. It warns when the skills folder holds no SKF output at all.
+
+**`skills_output_folder` or `forge_data_folder` set to `_bmad-output`:** create-skill stages a skill in `_bmad-output/.skf-stage/<name>/` before it writes the version. An earlier SKF release staged it in `_bmad-output/<name>/`, which with this setting is also the skill's folder or its forge folder, and left `SKILL.md`, `metadata.json`, `context-snippet.md`, `references/`, `evidence-report.md` and `provenance-map.json` at the root of that folder. That leftover can make create-skill stop with `flat-layout`, and make drop and rename refuse the skill folder or its forge folder as one that holds entries SKF did not generate. Delete those leftovers yourself and keep everything else in the folder, such as the `<version>/` folders, the `active` link and `skill-brief.yaml`; when the folder holds nothing but the leftovers, delete it whole. Then re-run.
+
+### Rename Skill stops with `verify-failed`
+
+Surfaced by `@Ferris RS` (exit `5`) when the old name is still in the renamed skill's files. Before it deletes anything, rename checks each version's `SKILL.md` frontmatter, `metadata.json`, `context-snippet.md` and `provenance-map.json` for the old name as a whole name: a longer name that contains it, such as `<old>-kit`, does not count. In the two JSON files it skips the values of `source_repo`, `source_root`, `source_commit`, `source_ref`, `source_package` and `source_library`: they name the source the skill was made from, not the skill, and rename leaves them as they are. On a match it removes the new folders and stops, so the skill keeps its old name and every file as it was. The message names each file and line.
+
+Rename rewrites the skill's `name` fields, the name where the snippet template writes it (the header, the `|IMPORTANT:` line and the `root:` path) and paths into the skill's own folders, such as a test report path an update run recorded. It leaves every other mention, because there the old name may mean something other than the skill. The source values above and the paths of files in the source stay as they are even when they look like a path into the skills folder, as in a repository that keeps its packages under `skills/<name>/`.
+
+**Fix:** match the line the message names:
+
+- **The skill is named after its library or repository**, as Quick Skill names a skill, and a value that rename does not skip names the library or the repository: the `description` in the `SKILL.md` frontmatter or in `metadata.json`, an export that has the library's name, the path of a file in the source such as `skills/<name>/scripts/fill.py`, or, for a skill named like its repository, the README URL create-skill records in `metadata.json` `doc_sources`. A rename does not rename the library. Such a skill cannot be renamed. Create it again under the new name with Brief Skill and Create Skill.
+- **A note an earlier run wrote in its own words**, such as an `update_source` value in `metadata.json` that names the skill: edit or remove it in the old skill's file, then re-run the rename.
+- **A `context-snippet.md` line other than the header, `|IMPORTANT:` and `root:`** names the skill, for example its `|gotchas:` text: edit that line in the old skill's snippet, then re-run. When the old name is a label or fixed word of the snippet template itself (`api`, `root`, `data`), the skill cannot be renamed; create it again under the new name.
+
+### Rename Skill stops with `halted-for-concurrent-run`
+
+Surfaced by `@Ferris RS` (exit `5`) when another rename of the same skill holds its run lock, `.skf-rename-<name>.lock` in `forge_data_folder`, and the lock has not gone stale (60 minutes after it was taken or renewed). A rename that waited at a question past that time stops the same way before it copies anything, because another rename may have run in the meantime. `--dry-run` takes no lock.
+
+**Fix:** wait until the other rename ends, then run the rename again. If no rename of that skill is running, delete the lock file the message names, or wait until the time it gives.
+
+### Rename Skill stops with `name-collision` and lists old folders
+
+Surfaced by `@Ferris RS` (exit `5`) when an earlier rename of the skill to the same new name stopped after it moved the export manifest entry to the new name, but before it deleted the old folders. The new name is now the renamed skill. The message lists the old folders still on disk, and the run changes nothing.
+
+**Fix:** if you do not want to keep the old skill, run the checked delete the message gives (`skf-skill-inventory.py guarded-delete` with those folders), then run `@Ferris EX` to rebuild the context files that may still name the old skill. A `name-collision` without that list means the new name is already in use: pick another one.
+
+### Update Skill stops with `blocked` before detecting changes
+
+Surfaced by `@Ferris US` for a skill built at Forge tier or above from a remote repository, or when `--target-ref` is passed for any other skill (under `--headless`, `error.phase` is `init:source-tree`). Update Skill reads the commit that the skill's `source_ref` points to now, or the tag, branch or commit passed with `--target-ref`, so every step compares the skill with one known commit. It stops before comparing anything when it cannot get that commit, and `error.reason` says why:
+
+- `ref-not-found`: the ref no longer exists upstream. `invalid-ref`: the ref is not a valid tag or branch name.
+- `upstream-unreachable`: the repository cannot be reached, and either `--target-ref` was passed (it always needs the network) or the skill's pinned commit is not on this machine.
+- `fetch-failed` or `checkout-failed`: git could not fetch or check out the commit, for example after a dropped connection or on a full disk.
+- `timed-out`: reading the commit did not finish within the time limit Update Skill gives it; a first fetch of a large repository is slow.
+- `tree-folder-failed`: no folder for the checkout could be created, neither in SKF's own cache folder nor in the system temp folder.
+- `git-unavailable`: `git` is not installed. `helper-failed`: `skf-source-tree.py` is missing, or it was stopped before it printed a result.
+- `target-ref-needs-remote-source`: `--target-ref` was passed for a skill built from a local folder, from documentation only, or at Quick tier.
+
+**Fix:** for `upstream-unreachable`, `fetch-failed` or `timed-out`, check your network and your access to the repository, then re-run. For `checkout-failed` or `tree-folder-failed`, free disk space and check that you can write to those folders. Install `git` for `git-unavailable`, and re-install SKF for `helper-failed`. When the tag or branch was deleted or renamed upstream, pass the one to use with `--target-ref <tag|branch|HEAD>`; the skill then records it as its `source_ref`. When only the network is down, `--target-ref` was not passed and the pinned commit is on this machine, Update Skill does not stop: it compares that commit, and its report and `warnings[]` say that upstream changes were not checked (`source-not-fetched`).
+
+If Test Skill stops with `workspace-drift` right after an update, the update's report says why the source that Test Skill reads was not moved to the commit the update recorded (`workspace-clone-not-updated`). It also gives the `git` commands that move it there once no other skill needs it where it is. Use those commands, not the `git checkout` that Test Skill's own message suggests: for a branch or `HEAD`, that checkout does not reach the new commit.
+
+### Update Skill stops with `halted-for-write-failure` because the version already exists
+
+Surfaced by `@Ferris US` (under `--headless`, `error.phase` is `merge:new-version-folder`). An update that writes puts the new version of the skill in a folder of its own and never overwrites an existing one. The new version is the source's version when the skill was built from a remote repository and that version is higher; otherwise it is the next patch version. It updates the version the skill's `active` link names, so a second update before an export builds on the first. It stops before writing anything when `<skills_output_folder>/<name>/<version>/` or `<forge_data_folder>/<name>/<version>/` already exists. The version it updates is unchanged.
+
+**Fix:** if an earlier update stopped after creating that version, delete both folders (whichever exist) by hand, then re-run. If you keep that version on purpose, move both folders out of the way by hand before updating. Never remove the version the `active` link names. Drop Skill removes a single version only when the export manifest lists it (`@Ferris DS <name> --mode purge`, choosing that version); for a skill that was never exported it can only drop every version, and a soft drop (`--mode deprecate`) keeps the files on disk.
+
+### Update Skill stops with `halted-for-concurrent-run`
+
+Surfaced by `@Ferris US` when another update of the same skill holds its run lock, `.skf-update.lock` in `<forge_data_folder>/<name>/` (under `--headless`, `error.phase` is `init:concurrency-guard`). The message names the update that holds the lock, the lock file, and when the lock goes stale (60 minutes after it was taken or renewed). `--detect-only` and `--dry-run` take no lock.
+
+**Fix:** wait until the other update ends, then re-run. If no update of that skill is running (a session that crashed or was closed leaves its lock behind), delete the lock file the message names, or wait until the time it gives. An update that finds a stale lock takes it over and undoes what the interrupted update left half written.
+
+**`run-lock-lost`:** the same status with this reason means the update waited at a question past the stale time, so another update may have changed the skill (`error.phase` is `merge:run-lock` or `write:run-lock`). It stops before it writes `metadata.json`, and the halt undoes anything the update already wrote: it removes the new version folders, or, for a repair from a test report, restores the files it edited in place from the copy it took first, and the message says which. Re-run the update once no other update of that skill runs; if a version folder the message names is still on disk, delete it first.
+
+### A report says `Tessl Review: off`, `not run`, `no result` or `failed`
+
+Create Skill and Test Skill record one `Tessl Review:` line in the evidence report and the test report. Tessl Review is optional and never stops a run, so the line says why it produced no score:
+
+| Status | What it means and what to do |
+|---|---|
+| `off` | The default. Set `tessl_review_workspace` in `_bmad/_memory/forger-sidecar/preferences.yaml` to the name of one of your Tessl workspaces (`tessl workspace list` shows them) to enable it. The review uploads the skill's `SKILL.md`, `references/`, `scripts/` and `assets/` to Tessl, where it stays in that workspace's history, and each fresh review spends Tessl credits. |
+| `invalid-config` | `tessl_review_workspace` is set to something that is not a workspace name, such as `true`, a value with spaces or one with characters other than letters, digits, `.`, `_` and `-`. Set it to the workspace name, or to `~` to turn the review off. |
+| `not-installed` | Neither `tessl` nor a cached npm copy of it was found. Install the Tessl CLI (see [tessl.io](https://tessl.io)); SKF never installs it. |
+| `signed-out` | Run `tessl login`, or set `TESSL_TOKEN` for an unattended run. |
+| `command-unavailable` | The installed tessl has no working `tessl review run`. Update tessl. |
+| `pending` | The workflow stopped checking before Tessl finished. The review may still complete on Tessl's side: `tessl review view <run id>` shows it (the line names the run id); re-run the workflow later. |
+| `unknown-run` | Tessl has no review with the run id the workflow checked, or the workflow passed something that is not a run id. Re-run the workflow; `tessl review list` shows your reviews. |
+| `timeout` | The workflow did not see Tessl finish while it waited (about ten minutes): Tessl was still working, or the last checks failed or did not answer. The review may still complete on Tessl's side: `tessl review view <run id>` shows it (the line names the run id); re-run the workflow later. |
+| `failed` | The line carries tessl's own message, a skill file SKF could not read, or a tessl call that did not answer in time. When it is about the workspace, check the name against `tessl workspace list`. `did not answer within` means tessl was slow, for example while its npm launcher downloads tessl on a first run: re-run the workflow. `stopped before skf-tessl-review.py reported a result` means your agent's shell tool stopped a helper call; when Tessl had accepted the review, the report names its run id for `tessl review view <run id>`. |
+| `parse-failure` | tessl printed no review SKF can read. Update tessl, or run `tessl review run <skill-folder> --json` yourself to see its output. |
+
+When Tessl Review produces no score, Test Skill's External Validation uses skill-check's score alone.
+
+### "Description sanitization failed"
+
+Create Skill checks the staged skill's frontmatter `description` for `<` and `>` before it writes the skill, because the Claude platform does not accept XML tags there. When it finds them, it replaces them with `{` and `}` and checks again; this message means they were still there after that, so nothing was written to `skills_output_folder`. Under `--headless` the stderr envelope carries `halt_reason: "description-angle-brackets"`.
+
+**Fix:** check that `_bmad-output/.skf-stage/<name>/SKILL.md` can be written (its permissions, and no other program holding it open), then re-run `@Ferris CS`. To keep angle brackets out of the description from the start, write placeholders in the brief as `{name}` or `NAME` rather than `<name>`.
 
-### My campaign stopped partway — how do I resume?
+### My campaign stopped partway: how do I resume?
 
-Campaign is designed for exactly this. State lives in `_campaign-state.yaml` on disk, so context death, a session timeout, or a machine restart loses nothing. Run `@Ferris campaign resume` — Ferris validates the state file, skips completed skills, and picks up from the next incomplete skill in dependency order. If the state file is corrupted, Ferris falls back to the `.bak` copy automatically. To re-process one specific skill, use `@Ferris campaign resume --from=<skill>`.
+Campaign is designed for exactly this. Its state lives on disk in `_campaign-state.yaml` (by default in `forge-data/_campaign/`), so context death, a session timeout, or a machine restart loses nothing. Run `@Ferris campaign resume`. Ferris validates the state file, skips completed skills, and picks up from the next incomplete skill in dependency order. If the state file is corrupted, Ferris restores the `.bak` copy automatically when that copy is valid; when neither file is usable, it stops and shows both errors. To process one specific skill again, use `@Ferris campaign resume --from=<skill>`; for a skill that already finished, choose **[R]e-run** when asked.
 
 ---
 
 ## Still stuck?
 
 1. Run `@Ferris SF` to check your tool availability and current tier
-2. Check `forge-tier.yaml` in your forger sidecar for your configuration
-3. If `/bmad-help` is installed (via full BMAD Method), run it and describe your state — e.g. `/bmad-help my batch creation failed halfway, how do I resume?`
-4. [File an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — SKF's [health check system](/docs/workflows.md#terminal-step-health-check) is the primary feedback channel, and manual issues feed the same pipeline
+2. Check `_bmad/_memory/forger-sidecar/forge-tier.yaml` for the tools setup detected and your current tier
+3. If `/bmad-help` is installed (via full BMAD Method), run it and describe your state, for example `/bmad-help my batch creation failed halfway, how do I resume?`
+4. [File an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). SKF's [health check system](/docs/workflows.md#terminal-step-health-check) is the main way SKF collects feedback, and issues you file by hand reach the same place.