bmad-module-skill-forge 4.0.0 → 6.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": "4.0.0",
+      "version": "6.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: "4.0.0"
+skf_version: "6.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/agents.md

@@ -77,4 +77,4 @@ Ferris can run several workflows in one command. Type their codes in order, such
 `campaign` is not a chaining alias. It is a separate workflow (`@Ferris CA` or `@Ferris campaign`) that runs its own pipeline for many skills, builds them in the order their dependencies need, and can resume where it stopped. `CA` cannot be chained with other codes. See the [Campaign](/docs/campaign.md) page.
 
 **Memory:**
-Ferris keeps a memory folder, called the sidecar, at `_bmad/_memory/forger-sidecar/`, so he remembers your setup between sessions. It holds `forge-tier.yaml` (the tools Setup Forge found and your capability tier), `preferences.yaml` (your settings) and the result of your last pipeline run (`pipeline-result-latest.json`). A pipeline keeps its progress in a journal in its own run folder under `_bmad-output/.skf-run/`. If one stopped partway, Ferris reads that journal the next time you open him and offers to resume it, or to repair it first after a failed test, and you can tell him to drop the offer. A start with `--headless` (or `-H`) that names no code, alias or chain stops with "Nothing to run". In `preferences.yaml`, set `headless_mode: true` to make headless the default, or `compact_greeting: true` to get a short greeting without the full menu table (ask for the menu when you want it). [Getting Started → Configuration](/docs/getting-started.md#configuration) lists more preferences.
+Ferris keeps a memory folder, called the sidecar, at `_bmad/_memory/forger-sidecar/`, so he remembers your setup between sessions. It holds `forge-tier.yaml` (the tools Setup Forge found and your capability tier), `preferences.yaml` (your settings) and the result of the last pipeline run that reached its end (`pipeline-result-latest.json`; a chain cut off before it ends writes none, so the file can be an earlier chain's). A pipeline keeps its progress in a journal in its own run folder under `_bmad-output/.skf-run/`. If one stopped partway, Ferris reads that journal the next time you open him and offers to resume it, or to repair it first after a failed test, and you can tell him to drop the offer. A start with `--headless` (or `-H`) that names no code, alias or chain stops with "Nothing to run". In `preferences.yaml`, set `headless_mode: true` to make headless the default, or `compact_greeting: true` to get a short greeting without the full menu table (ask for the menu when you want it). [Getting Started → Configuration](/docs/getting-started.md#configuration) lists more preferences.

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,9 +55,9 @@ 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.
+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, and the step waits in the foreground until every one has returned, since a headless `claude -p` run stops when the agent's turn ends. 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.
 7. **Reference and asset injection**: Steps read `references/*.md` and `assets/*.md` files as needed (rules, patterns, schemas, heuristics). This is deliberate: only the data the current step needs enters the context window.
 8. **Script execution**: Steps run deterministic Python scripts (`scripts/*.py`, `shared/scripts/*.py`), usually with `uv run`, for work that must be reproducible: scoring, structural diffing, manifest operations, frontmatter validation. The assistant prepares the inputs, the script computes, and the assistant uses the output. The same inputs always give the same result.
@@ -143,14 +143,14 @@ forge-data/{skill-name}/
     ├── test-findings-{run_id}.json            # Test Skill's gap ledger, which its hard gate reads
     ├── drift-report-{timestamp}.md            # Written by Audit Skill
     ├── .skf-audit/{timestamp}/                # The JSON each audit scored its drift from
-    └── {workflow}-result-latest.json          # Machine-readable result of the last run
+    └── {workflow}-result-latest.json          # Machine-readable result of the last run whose emitter wrote this copy
 ```
 
 The `provenance-map.json` includes per-export `entries` with a `source_library` field naming the library each export belongs to. For stack skills, it also includes an `integrations` array (cross-library patterns) and, in compose mode only, a `constituents` array. That array records a fingerprint (hash) of each source skill's `metadata.json` at compose time, so Audit Skill can tell when a source skill has changed since. The `file_entries` array tracks copied scripts and assets file by file (SHA-256 hashes, source paths).
 
 ### Pipeline Result Contracts
 
-Pipeline-facing workflows write a machine-readable result JSON file alongside their human-readable output. This makes CI checks and chained runs reliable: a later workflow or script can check what the earlier step produced without parsing Markdown. Each run writes two files. The first is a timestamped record, `{workflow}-result-{YYYYMMDD-HHmmss}.json`, which keeps the full history across retries and aborts. The second is a copy named `{workflow}-result-latest.json`, which other tools read without sorting through timestamps. `{workflow}` names the workflow, not the skill being built. Most workflows leave off the `skf-` prefix (`create-skill`, `update-skill`), but Test Skill keeps it. Its record is `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC, with `-2` appended when a run already took that second's name), no longer named after the run ID. The files sit next to what the run produced. For Create, Update, Test and Audit Skill, that is the skill's version folder in `forge-data/`. When Ferris runs a chain of workflows, he keeps its state in a journal, `pipeline-journal.json`, in the chain's run folder under `_bmad-output/.skf-run/`, and when the chain ends he writes its result from that journal: `pipeline-result-<YYYYMMDD-HHmmss>.json` and its `pipeline-result-latest.json` copy in his sidecar folder. The schema follows a consistent format: `skill`, `status` (success/failed/partial), `timestamp`, `outputs` (array of produced artifacts with type and path), and a skill-specific `summary` object.
+Pipeline-facing workflows write a machine-readable result JSON file alongside their human-readable output. This makes CI checks and chained runs reliable: a later workflow or script can check what the earlier step produced without parsing Markdown. Each run writes two files. The first is a timestamped record, `{workflow}-result-{YYYYMMDD-HHmmss}.json`, which keeps the full history across retries and aborts. The second is a copy named `{workflow}-result-latest.json`, the record of the last run whose emitter wrote this copy, which other tools read without sorting through timestamps. A caller that started a run reads that run's own result line instead: a run cut off before its emitter call printed none and wrote no record, so the copy then belongs to an earlier run. `{workflow}` names the workflow, not the skill being built. Most workflows leave off the `skf-` prefix (`create-skill`, `update-skill`), but Test Skill keeps it. Its record is `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC, with `-2` appended when a run already took that second's name), no longer named after the run ID. The files sit next to what the run produced. For Create, Update, Test and Audit Skill, that is the skill's version folder in `forge-data/`. When Ferris runs a chain of workflows, he keeps its state in a journal, `pipeline-journal.json`, in the chain's run folder under `_bmad-output/.skf-run/`, and when the chain ends he writes its result from that journal: `pipeline-result-<YYYYMMDD-HHmmss>.json` and its `pipeline-result-latest.json` copy in his sidecar folder. A chain cut off before it ends writes none, so the copy can be an earlier chain's. The schema follows a consistent format: `skill`, `status` (success/failed/partial), `timestamp`, `outputs` (array of produced artifacts with type and path), and a skill-specific `summary` object.
 
 `skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
 

package/docs/campaign.md

@@ -186,7 +186,7 @@ A finished campaign leaves:
 - **Verification report and refined architecture**: from Verification and Refinement, when an architecture document was found.
 - **Campaign report** (`campaign-report.md`): the quality gate; a table of every skill with its tier, status, score, pin and workarounds; an Export Gate section with each completed skill's verdict, whether Export exported it or why its export failed, and the skills the gate kept from export; the lowest, highest and average scores; time per skill; and a section on failed or skipped skills.
 - **Decision log** (`_campaign-decision-log.md`): every decision made during the campaign.
-- **Headless result line** (`SKF_CAMPAIGN_RESULT_JSON`): printed in headless mode for scripts to read, as the run's last line. Besides the counts and the score of each skill, it carries `export_verdicts` (each completed skill's verdict at Export), `skills_excluded` (the completed skills the gate kept from export), `skills_exported` (the skills Export exported) and `export_failures` (each skill whose export failed, with its `halt_reason` and `exit_code`). The last two are null when the Export stage did not run. A failed export does not fail the campaign, which still ends with `status` `success`, so a CI job that needs every skill exported checks `export_failures`.
+- **Headless result line** (`SKF_CAMPAIGN_RESULT_JSON`): printed in headless mode for scripts to read, as the run's last line. Besides the counts and the score of each skill, it carries `export_verdicts` (each completed skill's verdict at Export), `skills_excluded` (the completed skills the gate kept from export), `skills_exported` (the skills Export exported) and `export_failures` (each skill whose export failed, with its `halt_reason` and `exit_code`). The last two are null when the Export stage did not run. An `export_failures` entry's `exit_code` is null when the export printed no line (its `halt_reason` is then `no-result`) or one Campaign could not read (`result-unreadable`). A failed export does not fail the campaign, which still ends with `status` `success`, so a CI job that needs every skill exported checks `export_failures`.
 
 The Export stage (stage 9) asks before it writes anything. It lists each completed skill with its verdict, names the skills it leaves out because they fall below the soft fallback or have no score, and waits for `[E]xport all` or `[C]ancel`. `[E]xport all` exports only the `pass` and `fallback` skills, each under the skill folder its build wrote: a Tier B skill under the name Quick Skill gave it, the library's name, even when you named the target differently. In headless mode it exports them without asking.
 

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

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

@@ -53,7 +53,7 @@ When ccc is available (Forge+, or Deep with ccc), create-skill indexes the skill
 
 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`.
+**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`. In a headless run, a first index of a large project can also outlast the longest timeout the agent's shell gives a command, and Setup then reports the stopped call as a failed index (an interactive run builds such an index in the background and waits for it): run `ccc index` in a terminal in the project, then re-run `@Ferris SF`.
 
 ### `@Ferris deepwiki` shows a deprecation notice
 
@@ -69,6 +69,12 @@ Test Skill checks a skill against the source commit it was made from. When the s
 
 **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").
 
+### Test Skill stops with `another-run-active`
+
+Surfaced by `@Ferris TS` (exit `1`) at one of two points. At the start (under `--headless`, `error.phase` is `init:run-lock`), another test of the same skill version holds its run lock, `.test-skill.lock` in `<forge_data_folder>/<name>/<version>/`, and the lock has not gone stale (60 minutes after it was taken or renewed). Just before it writes its results (`report:run-lock`), the run's own lock went stale and another run took it over, so it stops and writes no result. A run that was cut off, by a closed session or by a `claude -p` run whose agent ended its turn early (no `SKF_TEST_RESULT_JSON` line, and `claude -p` still exits `0`), leaves its lock behind, with its in-progress report `.skf-test-report-<name>-<run_id>.md` in the version folder and its run folder `_bmad-output/.skf-run/skf-test-skill-<run_id>/`.
+
+**Fix:** wait until the other test ends, then re-run. If no test of that skill is running, delete the lock file the message names, or wait until the time it gives: a test that finds a stale lock takes it over. After `report:run-lock`, re-run once the run that took the lock over has ended. A run cut off before its result step wrote no result, so `skf-test-skill-result-latest.json` still holds an earlier run's verdict, and one cut off later wrote it: re-run the test rather than read that file. Its in-progress report and run folder are safe to delete once no test of that skill is running.
+
 ### forge-auto halted at the Test stage
 
 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.
@@ -113,7 +119,7 @@ Rename rewrites the skill's `name` fields, the name where the snippet template w
 
 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.
+**Fix:** wait until the other rename ends, then run the rename again. If no rename of that skill is running (a closed session or a cut-off `claude -p` run leaves its lock behind), delete the lock file the message names, or wait until the time it gives.
 
 ### Rename Skill stops with `name-collision` and lists old folders
 
@@ -147,7 +153,7 @@ Surfaced by `@Ferris US` (under `--headless`, `error.phase` is `merge:new-versio
 
 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.
+**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, or a `claude -p` run cut off when its agent ended its turn, 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.