bmad-module-skill-forge 3.0.0 → 5.0.0

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -52,15 +52,15 @@ results = cognee.search("What does Cognee do?", mode="graph")
 import cognee
 
 # Agent follows the skill instruction:
-# `search(query_text: str, query_type: SearchType = GRAPH_COMPLETION) -> List[SearchResult]`
-# [AST:cognee/api/v1/search/search.py:L27]
+# `search(query_text: str, query_type: SearchType = SearchType.HYBRID_COMPLETION, ...) -> list[SearchResult]`
+# [AST:cognee/api/v1/search/search.py:L41]
 results = await cognee.search(
     query_text="What does Cognee do?",
     query_type=cognee.SearchType.GRAPH_COMPLETION
 )
 ```
 
-The skill told the agent the real function name, the real parameters, and that the call is async, all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills), SKF's reference output. That skill predates provenance labels that follow the tool: its provenance map records `search` as read by eye, which SKF 3.0.0 cites as `[SRC:...]`, keeping `[AST:...]` for a definition an ast-grep rule matched. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
+The skill told the agent the real function name, the real parameters, and that the call is async, all traced to the exact source line. This example is from the real [`oms-cognee`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.6.2/oms-cognee/SKILL.md) skill in [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills), SKF's reference output. Its provenance map records `search` as an ast-grep match at that line, which is what `[AST:...]` means; an export SKF reads by eye instead is cited `[SRC:...]`. The [**Verifying a Skill**](#verifying-a-skill) section below shows how to walk the citation chain yourself.
 
 ## Install
 

package/docs/_data/pinned.yaml

@@ -32,7 +32,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "3.0.0"
+skf_version: "5.0.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills
@@ -46,12 +46,13 @@ oh_my_skills_path: "../oh-my-skills"
 skills:
   oms-cognee:
     library: cognee
-    version: "1.0.0"
+    version: "1.6.2"
     source_repo: "https://github.com/topoteretes/cognee"
-    source_commit: "3c048aa4147776f14d4546704f986242554a9ef3"
-    source_ref: "v1.0.0"
-    upstream_commit_date: "2026-04-11"
-    test_score: 99.00
+    source_commit: "ba3631f2ed363a6ea50d649c34c56885af6b36fe"
+    source_ref: "v1.6.2"
+    upstream_commit_date: "2026-09-29"
+    # strict SKF 4.0.0 re-test of the version that ships (20261103T134151Z-12e5ccdf)
+    test_score: 99.0
     test_mode: "naive"
     confidence_tier: "Deep"
     source_authority: "community"
@@ -59,12 +60,13 @@ skills:
 
   oms-cocoindex:
     library: cocoindex
-    version: "0.3.37"
+    version: "1.0.0"
     source_repo: "https://github.com/cocoindex-io/cocoindex"
-    source_commit: "87c5dbf087bfccca83791861db0d33519ef09677"
-    source_ref: "v0.3.37"
-    upstream_commit_date: "2026-03-31"
-    test_score: 99.0
+    source_commit: "5fe4f37a526e51516655832ec9814e7ca24ade9a"
+    source_ref: "v1.0.0"
+    upstream_commit_date: "2026-04-22"
+    # strict SKF 4.0.0 re-test of the version that ships (20261103T131524Z-5907fba9)
+    test_score: 100.0
     test_mode: "naive"
     confidence_tier: "Deep"
     source_authority: "community"
@@ -77,7 +79,9 @@ skills:
     source_commit: "e486d3826bcd40c52db1c766966d1c8ec16df6cb"
     source_ref: "v10.3.5"
     upstream_commit_date: "2026-04-07"
-    test_score: 99.49
+    # null: the strict SKF 4.0.0 re-test of the version that ships
+    # (20261103T131516Z-6e2b972a) is blocked by the hard gate, so it records no score.
+    test_score: null
     test_mode: "naive"
     confidence_tier: "Deep"
     source_authority: "community"
@@ -90,7 +94,9 @@ skills:
     source_commit: "a5ffb45be05335d2c547436664cfbfb8c22d04df"
     source_ref: "HEAD"
     upstream_commit_date: "2026-03-22"
-    test_score: 99.45
+    # null: the strict SKF 4.0.0 report (20261103T100001Z-981f84e6) is
+    # blocked by the hard gate, so it records no score.
+    test_score: null
     test_mode: "naive"
     confidence_tier: "Deep"
     source_authority: "community"

package/docs/architecture.md

@@ -22,7 +22,7 @@ A workflow directory holds some or all of these files, and each has a specific j
 | File                      | What it does                                                                                                        | When it loads                                     |
 |---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
 | `SKILL.md`                | Human-readable entry point: goals, role definition, initialization sequence, invocation contract, and the route to the first step | Entry point per workflow                          |
-| `customize.toml`          | Settings a team or a person can override without editing SKF, such as facts to keep in mind for the whole run or a command to run when the workflow ends. Overrides go in `_bmad/custom/<workflow>.toml` (shared) or `_bmad/custom/<workflow>.user.toml` (personal), for example `_bmad/custom/skf-create-skill.toml`. The workflow reads them by running BMAD Method's customization script, which the BMAD Method installer adds, through `uv`. When that script cannot run, as with SKF installed alone, the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and applies the bundled settings | Read once, when the workflow starts |
+| `customize.toml`          | Settings a team or a person can override without editing SKF, such as facts to keep in mind for the whole run or a command to run when the workflow ends. Overrides go in `_bmad/custom/<workflow>.toml` (shared) or `_bmad/custom/<workflow>.user.toml` (personal), for example `_bmad/custom/skf-create-skill.toml`. The workflow reads them by running SKF's customization helper through `uv`, which runs BMAD Method's customization script, added by the BMAD Method installer. When that script cannot run, as with SKF installed alone, the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and applies the bundled settings | Read once, when the workflow starts |
 | `references/*.md` (step files)    | The workflow's stages, one file per step. Each names the next one in its `nextStepFile` front matter, and the last one hands off to the shared health check | One at a time (just-in-time)                      |
 | `references/*.md` (reference data) | Workflow-specific reference data: rules, patterns, protocols                                                       | Read by steps on demand                           |
 | `assets/*.md`             | Workflow-specific output formats: schemas, templates, heuristics                                                   | Read by steps on demand                           |
@@ -55,7 +55,7 @@ flowchart LR
 
 1. **Trigger**: You type `@Ferris CS` (or a close match like `create-skill`). The menu in `skf-forger/SKILL.md` maps the code to the workflow's skill, here `skf-create-skill`.
 2. **Agent loads**: `skf-forger/SKILL.md` puts the persona (identity, principles, critical actions) into the context window. Ferris also loads its sidecar files (`forge-tier.yaml`, `preferences.yaml`), which keep your tier and preferences between sessions.
-3. **Workflow loads**: The workflow's `SKILL.md` loads your SKF settings from `_bmad/skf/config.yaml` and checks whether the run is headless (runs without asking questions). It then runs BMAD Method's customization script through `uv` to apply any team or personal overrides to the workflow's `customize.toml`, as Ferris does for his own settings when he starts. When that script cannot run (with SKF installed alone it is missing), the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and keeps the bundled settings. Then it opens the first step file.
+3. **Workflow loads**: The workflow's `SKILL.md` loads your SKF settings from `_bmad/skf/config.yaml` and checks whether the run is headless (runs without asking questions). It then runs SKF's customization helper through `uv`, which runs BMAD Method's customization script to apply any team or personal overrides to the workflow's `customize.toml`, as Ferris does for his own settings when he starts. When that script cannot run (with SKF installed alone it is missing), the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and keeps the bundled settings. Then it opens the first step file.
 4. **Step-by-step execution**: Only the current step file is in context (just-in-time loading). Each step names the next one. The assistant reads the step, carries it out, saves its output, then loads the next step. Future steps are never loaded early.
 5. **Sub-agent delegation**: Some steps would otherwise read many large files, such as several `SKILL.md` documents or every file that imports a library. These steps hand the reading to sub-agents, which are helper AI sessions started with the Agent tool. Each sub-agent reads its share and returns a short JSON summary. The parent never loads the full text, so the next step starts with an uncluttered context window. AN (per-unit analysis), TS (coverage and coherence checks), VS (integration verification), RA (gap analysis) and SS (per-library extraction) work this way. VS and RA run at most 8 sub-agents at a time. SS runs 3 to 5 at a time in Claude Code.
 6. **Knowledge injection**: Steps consult `skf-knowledge-index.csv` and load only the fragments from `knowledge/` that match by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) load only when a step asks for them, never in advance.

package/docs/concepts.md

@@ -15,7 +15,7 @@ An agent skill is an instruction file that tells an AI agent how to use your cod
 
 Skills follow the [agentskills.io](https://agentskills.io) open standard, so they work across Claude, Cursor, Copilot, and other AI tools.
 
-**Example:** A skill for [cognee](https://github.com/topoteretes/cognee) tells your agent: "The function is `cognee.search()`, its first parameters are `query_text`, `query_type`, `user`, `datasets`, and `dataset_ids`, and it's defined at `cognee/api/v1/search/search.py:L27` (v1.0.0, commit `3c048aa4`)." With ast-grep installed, SKF reads such a signature from the structure of the actual source code (its abstract syntax tree, or AST) and labels it T1; a signature it reads by eye instead is labeled T1-low (see [Confidence Tiers](#confidence-tiers-t1t1-lowt2t3)).
+**Example:** A skill for [cognee](https://github.com/topoteretes/cognee) tells your agent: "The function is `cognee.search()`, its first parameters are `query_text`, `query_type`, `user`, `datasets`, and `dataset_ids`, and it's defined at `cognee/api/v1/search/search.py:L41` (v1.6.2, commit `ba3631f2`)." With ast-grep installed, SKF reads such a signature from the structure of the actual source code (its abstract syntax tree, or AST) and labels it T1; a signature it reads by eye instead is labeled T1-low (see [Confidence Tiers](#confidence-tiers-t1t1-lowt2t3)).
 
 ---
 
@@ -24,8 +24,8 @@ Skills follow the [agentskills.io](https://agentskills.io) open standard, so the
 Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse such as issues, pull requests, and changelogs, it's the indexed document the instruction came from. **If SKF can't point to a source, it doesn't include the instruction.**
 
 **Examples** (the citation forms, with paths from the oms-cognee skill in [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
-- `[AST:cognee/api/v1/search/search.py:L27]`: an ast-grep rule matched the definition in the source code (T1)
-- `[SRC:cognee/api/v1/add/add.py:L166]`: read from source code by eye, without an ast-grep match (T1-low)
+- `[AST:cognee/api/v1/search/search.py:L41]`: an ast-grep rule matched the definition in the source code (T1)
+- `[SRC:cognee/api/v1/__init__.py:L8]`: read from source code by eye, without an ast-grep match (T1-low)
 - `[QMD:oms-cognee-temporal:releases.md]`: found in indexed release notes and other developer discourse (T2)
 - `[EXT:https://docs.cognee.ai/getting-started/quickstart]`: taken from external documentation (T3)
 
@@ -79,7 +79,7 @@ Audit Skill also checks the documentation pages a skill tracked when it was buil
 
 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 giving it during `@Ferris BS` (Brief Skill) or by adding `@version` to a Quick Skill command (`@Ferris QS cognee@1.0.0`). This is especially useful for docs-only skills, where there is no source code to detect a version from. When you target a version on a remote repository, SKF finds the matching git tag and clones from it. That way the extracted API signatures come from that version's code, not from whatever is on the default branch with a label added. If no tag matches, Quick Skill stops and lists the tags it found, while Create Skill warns you and falls back to the default branch.
+By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version, either by giving it during `@Ferris BS` (Brief Skill) or by adding `@version` to a Quick Skill command (`@Ferris QS cognee@1.6.2`). This is especially useful for docs-only skills, where there is no source code to detect a version from. When you target a version on a remote repository, SKF finds the matching git tag and clones from it. That way the extracted API signatures come from that version's code, not from whatever is on the default branch with a label added. If no tag matches, Quick Skill stops and lists the tags it found, while Create Skill warns you and falls back to the default branch.
 
 When the source updates, re-run `@Ferris US` (Update Skill) to regenerate the skill. SKF writes the result as a new version and leaves the old one in place. Anything you wrote between `<!-- [MANUAL:name] -->` and `<!-- [/MANUAL:name] -->` markers is carried over; edits made anywhere else are not protected and can be overwritten. Update Skill follows the ref the skill was built from, so a skill built from a branch picks up that branch's new commits. To move a skill built from a release tag to a newer release, run `@Ferris US <name> --target-ref <tag>`.
 

package/docs/examples.md

@@ -5,25 +5,26 @@ description: Real-world scenarios and operational tips for Skill Forge. For comm
 
 ## What the Output Looks Like
 
-When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Below is a trimmed example from the real [`oms-cognee` SKILL.md](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) generated for [cognee](https://github.com/topoteretes/cognee) (full portfolio at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
+When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Below is a trimmed example from the real [`oms-cognee` SKILL.md](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.6.2/oms-cognee/SKILL.md) generated for [cognee](https://github.com/topoteretes/cognee) (full portfolio at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
 
 **Frontmatter (tells AI agents when to load this skill):**
 
 ```yaml
 name: oms-cognee
 description: >
-  Builds apps on top of cognee v1.0.0, the knowledge-graph memory engine for AI agents.
-  Use when ingesting text/files/URLs into persistent memory, building knowledge graphs,
-  searching graph-backed memory with multiple SearchType modes, enriching graphs with
-  memify/improve, scoping memory with datasets and node_sets, configuring LLM/embedding/
-  graph/vector backends, running custom task pipelines, tracing operations, decorating
-  agent entrypoints with `agent_memory`, connecting to Cognee Cloud with `serve`, or
-  visualizing the graph. Covers cognee/__init__.py exports: the V1 API (add, cognify,
-  search, memify, datasets, prune, update, run_custom_pipeline, config, SearchType,
-  visualize_graph, pipelines, Drop, run_startup_migrations, tracing) and the V2
-  memory-oriented API (remember, RememberResult, recall, improve, forget, serve,
-  disconnect, visualize, agent_memory). Do NOT use for: cognee internals, the HTTP
-  REST API (use cognee-mcp or the FastAPI server), non-cognee memory/RAG libraries.
+  Builds apps on cognee v1.6.2, the knowledge-graph memory engine for AI agents.
+  Use when ingesting text/files/URLs into memory, building knowledge graphs, searching
+  memory with SearchType modes, enriching graphs with memify/improve, scoping memory
+  with datasets and node_sets, configuring LLM/embedding/graph/vector backends,
+  running custom pipelines, decorating agents with `agent_memory`, connecting
+  to Cognee Cloud with `serve`/`push`, exporting, validating or reporting on graphs,
+  or visualizing graphs and memory provenance. Covers cognee/__init__.py exports: the
+  V1 API (add, cognify, search, memify, datasets, agents, prune, update,
+  run_custom_pipeline, config, SearchType, report, validate, visualize_graph,
+  pipelines, Drop, run_migrations, tracing, tools) and the V2 memory API (remember,
+  recall, improve, forget, serve, disconnect, visualize, push, export, agent_memory,
+  MemoryEntry). Do NOT use for: cognee internals, the HTTP REST API (use
+  cognee-mcp or the FastAPI server), non-cognee memory/RAG libraries.
 ```
 
 **Body (what your AI agent reads):**
@@ -33,15 +34,15 @@ description: >
 
 | Function | Purpose | Key Params | Source |
 |----------|---------|------------|--------|
-| add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L22] |
-| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L44] |
-| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L27] |
-| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L25] |
-| remember() | V2 one-shot memory ingest | data, dataset_name | [AST:cognee/api/v1/remember/remember.py:L339] |
-| DataPoint | Base class for custom graph nodes | inherit and add fields | [EXT:docs.cognee.ai/guides/custom-data-models] |
+| add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L39] |
+| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L110] |
+| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L41] |
+| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L27] |
+| remember() | V2 one-shot memory ingest | data, dataset_name | [AST:cognee/api/v1/remember/remember.py:L867] |
+| DataPoint | Base class for custom graph nodes | inherit and add fields | [SRC:cognee/low_level.py:L2] |
 ```
 
-Every line number above is copied from the real SKILL.md and points at the line where that function is defined in the cognee source, so none of it is illustrative. SKF also ships its extraction record for this skill in oh-my-skills: [`forge-data/oms-cognee/1.0.0/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/provenance-map.json). The tags are copied as published too, and they predate labels that follow the tool: that record lists these functions as read by eye (`source-read`), so SKF 3.0.0 would tag them `[SRC:...]` (T1-low) and keep `[AST:...]` for a definition an ast-grep rule matched. [Verifying a Skill](/docs/verifying-a-skill.md#2-open-the-skills-provenance-mapjson) walks through the `search` entry.
+Every line number above is copied from the real SKILL.md and points at the line where that function is defined in the cognee source, so none of it is illustrative. SKF also ships its extraction record for this skill in oh-my-skills: [`forge-data/oms-cognee/1.6.2/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.6.2/provenance-map.json). The tags follow the tool that read each definition: that record lists the five functions as ast-grep matches (`T1`), so the skill cites them `[AST:...]`, while `DataPoint` is an alias that `cognee/low_level.py` re-binds, read by eye and cited `[SRC:...]` (`T1-low`). [Verifying a Skill](/docs/verifying-a-skill.md#2-open-the-skills-provenance-mapjson) walks through the `search` entry.
 
 Provenance tags trace each instruction to its source:
 - `[AST:file:Lnn]` (T1): an ast-grep rule matched the definition in the code (highest confidence)
@@ -55,16 +56,22 @@ See [Skill Model → Output Architecture](/docs/skill-model.md#output-architectu
 
 ```
 skills/oms-cognee/
-├── active -> 1.0.0
+├── active -> 1.6.2
 ├── 0.5.8/
 │   └── oms-cognee/
 │       ├── SKILL.md              # Archived: v0.5.8, pinned to b51dcce1
 │       ├── context-snippet.md
 │       ├── metadata.json
 │       └── references/
-└── 1.0.0/
+├── 1.0.0/
+│   └── oms-cognee/
+│       ├── SKILL.md              # Archived: v1.0.0, pinned to 3c048aa4
+│       ├── context-snippet.md
+│       ├── metadata.json
+│       └── references/
+└── 1.6.2/
     └── oms-cognee/
-        ├── SKILL.md              # Active: pinned to cognee v1.0.0 (3c048aa4)
+        ├── SKILL.md              # Active: pinned to cognee v1.6.2 (ba3631f2)
         ├── context-snippet.md    # Compressed index for platform context files
         ├── metadata.json         # Machine-readable provenance
         └── references/           # Progressive disclosure detail
@@ -74,7 +81,7 @@ skills/oms-cognee/
             └── pipelines-and-datapoints.md
 ```
 
-This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree. The older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets. oms-cognee has neither; see [Skill Model → Per-Skill Output](/docs/skill-model.md#per-skill-output) for the full schema.
+This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 and then v1.6.2 upstream. Each time SKF recompiled the skill from the new commit and wrote it next to the existing trees. The older versions stay pinned to their original commits (`b51dcce1`, `3c048aa4`) and are still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets. oms-cognee has neither; see [Skill Model → Per-Skill Output](/docs/skill-model.md#per-skill-output) for the full schema.
 
 ---
 
@@ -93,7 +100,7 @@ Ferris reads the repository, lists its public exports, and validates against the
 Need a specific version? Append `@version`:
 
 ```
-@Ferris QS cognee@1.0.0
+@Ferris QS cognee@1.6.2
 ```
 
 ### Brownfield Platform: Pipeline or per-workflow
@@ -325,7 +332,7 @@ Generated skills automatically follow authoring best practices: third-person des
 
 ### Scripts & Assets
 
-If your source repo includes executable scripts (such as `scripts/`, `bin/` or `tools/`) or static assets (such as `assets/`, `templates/` or `schemas/`), SKF detects and packages them automatically with provenance tracking. Scripts and assets you add yourself under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are preserved during updates, just like `<!-- [MANUAL] -->` markers in SKILL.md.
+If your source repo includes executable scripts (such as `scripts/`, `bin/`, `tools/` or `cli/`; when one of these folders is a Python package, holding `__init__.py`, only its `__main__.py` and the modules with a shebang or an `if __name__ == "__main__":` block count as scripts) or static assets (such as `assets/`, `templates/` or `schemas/`), SKF detects and packages them automatically with provenance tracking. Only the files the brief's `scope.include` takes and its `scope.exclude` leaves are packaged, and Audit Skill reports a new one the same way. Scripts and assets you add yourself under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are preserved during updates, just like `<!-- [MANUAL] -->` markers in SKILL.md.
 
 ### Let the Health Check Run
 

package/docs/getting-started.md

@@ -8,7 +8,7 @@ description: Install Skill Forge and generate your first verified skill in under
 One command. One verified skill. Here's what an instruction in a cognee skill looks like:
 
 ```python
-await cognee.search(  # [AST:cognee/api/v1/search/search.py:L27]
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L41]
     query_text="What does Cognee do?"
 )
 ```
@@ -93,7 +93,7 @@ After a successful `install` or `update`, and in `status`, the installer checks
     ccc       -        optional, Forge+ tier  https://github.com/cocoindex-io/cocoindex-code
 ```
 
-Each tool reads `ok`, `upgrade to >= <minimum>` with the command that upgrades it, `missing` or `optional` with where to get it, or `installed, version unknown` when SKF cannot read its version. The minimums are the ones in the [Prerequisites](#prerequisites-full-reference) table. The check waits at most about 3 seconds for the tools to answer and never changes the command's exit code. It runs no tool from your project folder and never runs `npx`, so `tessl` and `skill-check`, which SKF runs through `npx`, read as optional when they are not installed.
+Each tool reads `ok`, `upgrade to >= <minimum>` with the command that upgrades it, `missing` or `optional` with where to get it, or `installed, version unknown` when SKF cannot read its version. The minimums are the ones in the [Prerequisites](#prerequisites-full-reference) table. The check waits at most about 3 seconds for the tools to answer and never changes the command's exit code. It runs no tool from your project folder and never runs `npx`, so `tessl` and `skill-check`, which SKF runs through `npx`, read as optional when they are not installed. It never runs `tessl` or `skill-check`: on a tessl that has never run, any tessl command accepts tessl's Terms. It reads tessl's version from the name of the binary tessl installs, the one tessl's npm and Homebrew packages also run, and the version of `skill-check`, which has no `--version` option, from its installed package. An `@tessl/cli` before 0.63.0 is tessl itself, so its package gives the version. tessl reads `installed, version unknown` when it was installed with winget, pnpm or Volta, when an npm or Homebrew tessl's binary is not installed at `~/.local/bin/tessl` (`%LOCALAPPDATA%\tessl\bin\tessl.exe` on Windows), or when two files in tessl's `versions` folder have the size of the Windows copy, `tessl\bin\tessl.exe`. So does a `skill-check` installed with pnpm or Volta, or with yarn or bun on Windows.
 
 A tier tool below its minimum does not count toward your tier. With an ast-grep older than 0.45.3, `@Ferris SF` leaves you at Quick, whatever else you have installed. Setup's FORGE STATUS report then shows an upgrade line for the tool, and a headless setup adds a `tool_below_minimum` warning to its `SKF_SETUP_RESULT_JSON` envelope. Upgrade the tool and run `@Ferris SF` again. A tool with no minimum, or one whose version SKF cannot read, never lowers your tier.
 
@@ -129,7 +129,7 @@ Ferris reads the repository, extracts the public API, and generates a skill in u
 
 **Targeting a specific version:** Append `@version` to pin the skill to a library version:
 ```
-@Ferris QS cognee@1.0.0
+@Ferris QS cognee@1.6.2
 ```
 
 **Full quality path (pipeline mode):**

package/docs/how-it-works.md

@@ -23,7 +23,7 @@ In under a minute, plus one preview for you to approve, you get a `SKILL.md` you
 
 ### 2. The workflow resolves your target
 
-Ferris turns your input into a GitHub repository. A GitHub URL is used as given. A package name is looked up on every registry of npm, PyPI and crates.io (a language hint asks only that language's registry), with a web search as the last resort. When more than one registry answers, an interactive run lists every candidate and asks which project you mean, and a headless run keeps the first registry's pick (npm, then PyPI, then crates.io) and records an `also_found_in` warning in its result envelope. He then detects the main language from the repository's files, starting with its manifest (`pyproject.toml`, `package.json`, etc.). By default Quick Skill reads the repository's default branch. To pin a release, add it to the command (`@Ferris QS cognee@1.0.0`): Ferris checks that the matching git tag exists, stops if it doesn't, and reads everything from that tag.
+Ferris turns your input into a GitHub repository. A GitHub URL is used as given. A package name is looked up on every registry of npm, PyPI and crates.io (a language hint asks only that language's registry), with a web search as the last resort. When more than one registry answers, an interactive run lists every candidate and asks which project you mean, and a headless run keeps the first registry's pick (npm, then PyPI, then crates.io) and records an `also_found_in` warning in its result envelope. He then detects the main language from the repository's files, starting with its manifest (`pyproject.toml`, `package.json`, etc.). By default Quick Skill reads the repository's default branch. To pin a release, add it to the command (`@Ferris QS cognee@1.6.2`): Ferris checks that the matching git tag exists, stops if it doesn't, and reads everything from that tag.
 
 Quick Skill has a step that checks for an official skill before it reads any code, but it skips that check until agentskills.io offers a registry API to ask, so Ferris goes straight on to extraction.
 
@@ -50,7 +50,7 @@ That's the whole pipeline. One trigger in, one reviewed skill out, built from co
 Quick Skill is the fastest path, not the most thorough one. When you want every instruction tied to a file and a line, use the brief-driven [`create-skill`](/docs/workflows.md#create-skill-cs) path instead: describe the skill's scope with `@Ferris BS`, which writes a `skill-brief.yaml`, then compile it with `@Ferris CS`. That path records the exact commit it read, and with ast-grep installed each export an ast-grep rule matches carries a receipt like this one:
 
 ```python
-await cognee.search(  # [AST:cognee/api/v1/search/search.py:L27]
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L41]
     query_text="What does Cognee do?"
 )
 ```

package/docs/index.md

@@ -26,7 +26,7 @@ Skill Forge reads a library's source code and docs and writes a skill: an instru
 
 <div class="receipt-sample">
   <span class="receipt-sample__label">An ast-grep receipt looks like</span>
-  <code class="receipt-sample__chip">[AST:cognee/api/v1/search/search.py:L27]</code>
+  <code class="receipt-sample__chip">[AST:cognee/api/v1/search/search.py:L41]</code>
   <span class="receipt-sample__check" aria-label="verified">✓</span>
 </div>
 

package/docs/skill-model.md

@@ -187,25 +187,26 @@ Skills follow the [agentskills.io specification](https://agentskills.io/specific
 ---
 name: oms-cognee
 description: >
-  Builds apps on top of cognee v1.0.0, the knowledge-graph memory engine for AI agents.
-  Use when ingesting text/files/URLs into persistent memory, building knowledge graphs,
-  searching graph-backed memory with multiple SearchType modes, enriching graphs with
-  memify/improve, scoping memory with datasets and node_sets, configuring LLM/embedding/
-  graph/vector backends, running custom task pipelines, tracing operations, decorating
-  agent entrypoints with `agent_memory`, connecting to Cognee Cloud with `serve`, or
-  visualizing the graph. Covers cognee/__init__.py exports: the V1 API (add, cognify,
-  search, memify, datasets, prune, update, run_custom_pipeline, config, SearchType,
-  visualize_graph, pipelines, Drop, run_startup_migrations, tracing) and the V2
-  memory-oriented API (remember, RememberResult, recall, improve, forget, serve,
-  disconnect, visualize, agent_memory). Do NOT use for: cognee internals, the HTTP
-  REST API (use cognee-mcp or the FastAPI server), non-cognee memory/RAG libraries.
+  Builds apps on cognee v1.6.2, the knowledge-graph memory engine for AI agents.
+  Use when ingesting text/files/URLs into memory, building knowledge graphs, searching
+  memory with SearchType modes, enriching graphs with memify/improve, scoping memory
+  with datasets and node_sets, configuring LLM/embedding/graph/vector backends,
+  running custom pipelines, decorating agents with `agent_memory`, connecting
+  to Cognee Cloud with `serve`/`push`, exporting, validating or reporting on graphs,
+  or visualizing graphs and memory provenance. Covers cognee/__init__.py exports: the
+  V1 API (add, cognify, search, memify, datasets, agents, prune, update,
+  run_custom_pipeline, config, SearchType, report, validate, visualize_graph,
+  pipelines, Drop, run_migrations, tracing, tools) and the V2 memory API (remember,
+  recall, improve, forget, serve, disconnect, visualize, push, export, agent_memory,
+  MemoryEntry). Do NOT use for: cognee internals, the HTTP REST API (use
+  cognee-mcp or the FastAPI server), non-cognee memory/RAG libraries.
 ---
 ```
 
 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:L27]
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L41]
     query_text="What does Cognee do?"
 )
 ```
@@ -214,44 +215,46 @@ await cognee.search(  # [AST:cognee/api/v1/search/search.py:L27]
 
 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 copied from the file, not made up for illustration.
+This is a trimmed excerpt from the real [`oms-cognee/1.6.2/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.6.2/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
 {
   "name": "oms-cognee",
-  "version": "1.0.0",
+  "version": "1.6.2",
   "skill_type": "single",
   "source_authority": "community",
   "source_repo": "https://github.com/topoteretes/cognee",
-  "source_commit": "3c048aa4",
-  "source_ref": "v1.0.0",
+  "source_commit": "ba3631f2ed363a6ea50d649c34c56885af6b36fe",
+  "source_ref": "v1.6.2",
   "confidence_tier": "Deep",
   "spec_version": "1.3",
-  "generation_date": "2026-04-13T00:00:00Z",
+  "generation_date": "2026-11-02T19:41:43Z",
   "language": "python",
-  "ast_node_count": 34,
+  "ast_node_count": 42,
   "confidence_distribution": {
-    "t1": 34,
-    "t1_low": 0,
-    "t2": 11,
-    "t3": 15
+    "t1": 37,
+    "t1_low": 49,
+    "t2": 0,
+    "t3": 0
   },
   "stats": {
-    "exports_documented": 34,
-    "exports_public_api": 34,
-    "exports_internal": 0,
-    "exports_total": 34,
-    "public_api_coverage": 1.0,
-    "total_coverage": 1.0
+    "exports_documented": 86,
+    "exports_public_api": 102,
+    "exports_internal": 355,
+    "exports_total": 457,
+    "public_api_coverage": 0.8431,
+    "total_coverage": 0.1882,
+    "scripts_count": 0,
+    "assets_count": 0
   }
 }
 ```
 
-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).
+Fields omitted from this excerpt for brevity: `source_root`, `description`, `exports[]`, `tool_versions`, `dependencies`, `compatibility` and `generated_by`. Update Skill 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 146-line file lives at [`oh-my-skills/skills/oms-cognee/1.6.2/oms-cognee/metadata.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.6.2/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`.
+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 each claim by the tier of its signature (`signature_source`: T1, T1-low, T2 or T3), which can be lower than the entry's `confidence` label. In a stack it counts each library once, by the library's tier, so its bins sum to `library_count`.
 
-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.
+Its counts follow the tool that read each export's signature: 37 exports whose signature an ast-grep rule matched count as `t1`, and 49 count as `t1_low`. Of those 49, 44 were read by eye (`source-read`), such as aliases, module namespaces and the names gap-driven repairs added. The other 5 were located by an ast-grep rule, but their signatures were read by eye, such as the methods of the `config` class. `ast_node_count` (42) counts every export an ast-grep rule matched. The skill's 1.0.0 metadata, written by an SKF version that labeled exports by the forge tier, counted all 34 of its exports as `t1`. `exports_documented` (86) is below `exports_public_api` (102): the brief leaves some top-level names out of scope, and the skill's test report lists them and logs the remaining difference as a Medium `metadata-drift` gap.
 
 `scripts` and `assets` arrays are optional: SKF leaves them out entirely, rather than writing empty arrays, when the source has no scripts or assets.
 
@@ -301,18 +304,17 @@ 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 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-25 -->
+<!-- SKF:BEGIN updated:2026-11-02 -->
 [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: skills/oms-cognee/
-|IMPORTANT: oms-cognee v1.0.0 — read SKILL.md before writing cognee code. Do NOT rely on training data.
+|[oms-cognee v1.6.2]|root: skills/oms-cognee/
+|IMPORTANT: oms-cognee v1.6.2 — read SKILL.md before writing oms-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
-|api-v2: remember()→RememberResult, recall(), improve(), forget(), serve()/disconnect(), visualize(), @agent_memory
-|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.
+|api: add(), cognify(), search(), memify(), remember(), recall(), improve(), forget(), serve(), run_migrations()
+|key-types:SKILL.md#key-types — SearchType (20 modes, HYBRID_COMPLETION default), RememberResult, DataPoint, Drop
+|gotchas: cognee.run_startup_migrations is GONE in v1.6.2 (AttributeError) — use cognee.run_migrations(); search() now defaults to HYBRID_COMPLETION (pin query_type when the result shape matters); low_level is not a top-level name but `from cognee.low_level import DataPoint, setup` still works; a bare cognee.serve() runs the Auth0 device flow only when a device client ID is configured, else raises CogneeConfigurationError; agent_memory's save_traces is now save_session_traces; cognee.delete is DEPRECATED since v0.3.9 (use cognee.forget or cognee.datasets.delete_data); cognee.start_ui is sync and needs pid_callback; add/cognify/search/memify/remember/recall/improve/forget/serve/push/export/report/validate are async — always await.
 |
 |(three more skills are left out here for brevity: oms-cocoindex, oms-storybook-react-vite and oms-uitripled; see the full file)
 <!-- SKF:END -->

package/docs/troubleshooting.md

@@ -49,6 +49,12 @@ Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) (the `c
 
 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.
 
+### Setup says the CCC index failed
+
+Surfaced by `@Ferris SF` when ccc is available and `ccc index` exits with an error: the forge status shows `indexing failed, semantic discovery unavailable this session` with ccc's own message. Setup still finishes at your tier; only semantic discovery is off until the index builds. One cause is an index that an older ccc wrote and the installed ccc cannot read, with a message such as `Failed to deserialize pickle payload`.
+
+**Fix:** from the project root, run `ccc reset`, then `ccc daemon restart`, then re-run `@Ferris SF`. `ccc reset` deletes only the index databases and keeps `.cocoindex_code/settings.yml` with SKF's exclusions. Restart the daemon before indexing again: it still holds the databases `ccc reset` deleted, so an index built right after the reset can fail with `environment already open in this program`.
+
 ### `@Ferris deepwiki` shows a deprecation notice
 
 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>`.
@@ -145,6 +151,8 @@ Surfaced by `@Ferris US` when another update of the same skill holds its run loc
 
 **`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.
 
+**`busy`:** the same status with this reason means another run's flip of the skill's `active` link (Create Skill, Quick Skill or Drop Skill) held the link's lock for 5 seconds while the update was pointing the link at its version (`error.phase` is `write:active-symlink`). The update did not change the link, and the halt undid what the update wrote. Re-run the update once that run ends.
+
 ### 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: