bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/export-skill → skf-export-skill}/steps-c/step-03-generate-snippet.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-03-generate-snippet'
-description: 'Generate context-snippet.md in Vercel-aligned indexed format'
-
 nextStepFile: './step-04-update-context.md'
-snippetFormatData: '../data/snippet-format.md'
+snippetFormatData: 'assets/snippet-format.md'
 ---
 
 # Step 3: Generate Snippet
@@ -12,41 +9,11 @@ snippetFormatData: '../data/snippet-format.md'
 
 To generate or update context-snippet.md for the skill in the Vercel-aligned indexed format, targeting ~80-120 tokens per skill with T1-now content only.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a delivery and packaging specialist in Ferris Delivery mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Compress precisely — every token in a snippet must earn its place
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on generating the context-snippet.md content
-- 🚫 FORBIDDEN to include T2 annotations or temporal context — T1-now only
-- 💬 This is a deterministic generation step — auto-proceed when complete
-- 📋 If `passive_context: false` was detected in step-01, SKIP this step entirely and auto-proceed to step-04
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Write context-snippet.md to skill directory (or hold in context if dry-run)
-- 📖 Load {snippetFormatData} for format template
-- 🚫 Strict adherence to Vercel-aligned format — no deviations
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Skill metadata (name, exports, skill_type, components, integrations) from step-01
-- Focus: Snippet generation in exact Vercel-aligned format
-- Limits: T1-now content only, ~80-120 tokens target
-- Dependencies: Step-01 metadata, step-02 package validation
+- Focus only on generating the context-snippet.md content — T1-now only, no T2 annotations
+- If `passive_context: false` was detected in step-01, skip this step entirely
+- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 2–5 per skill. Each skill has its own prior-gotchas carry-forward state (§2.5) — do not share state across skills. §2.7 resolves `{skill_root}` once for the run (it depends on `target_context_files`, not the skill). See step-01 §1c.
 
 ## MANDATORY SEQUENCE
 
@@ -70,7 +37,7 @@ Load {snippetFormatData} and read the format template for the skill type.
 
 Before generating new snippet content, check for a prior snippet:
 
-1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see [knowledge/version-paths.md](../../../knowledge/version-paths.md))
+1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see `knowledge/version-paths.md`)
 2. If it exists, extract the `|gotchas:` line (if any). Trim leading whitespace and the `|gotchas:` prefix, then capture the remaining content as `prior_gotchas_content`.
 3. **Detect the carry-forward marker:** If `prior_gotchas_content` starts with the token `[CARRIED]` (whitespace-insensitive), set `prior_gotchas_already_carried = true` and strip the marker before storing the remainder. Otherwise set `prior_gotchas_already_carried = false`.
 4. **Distinguish empty from absent:** If the `|gotchas:` line exists but has no non-whitespace content after the prefix, treat it as **absent** — set `prior_gotchas = null`. Only a non-empty value counts as a prior gotchas line worth carrying forward.
@@ -78,17 +45,13 @@ Before generating new snippet content, check for a prior snippet:
 
 These values will be used as a fallback in section 3 if new gotchas cannot be derived. The `[CARRIED]` marker provides a **hard one-cycle expiry**: gotchas that were already carried once will be dropped on the next carry-forward attempt rather than preserved indefinitely.
 
-### 2.7. Resolve Platform Root Path
+### 2.7. Resolve Skill Root Path
 
-Using the first platform in `target_platforms` (resolved in step-01), resolve the root path prefix:
+**If `snippet_skill_root_override` is set in config.yaml:** Use its value directly as `{skill_root}` and skip the IDE-mapping lookup below. This is the authoring-repo escape hatch — repos where skills live under a single shared directory (e.g. `skills/`) that does not match any per-IDE skill root. Log: "Using snippet_skill_root_override: `{override}` — bypassing IDE mapping for snippet root path."
 
-| Platform | `{platform_root}` |
-|----------|-------------------|
-| `claude` | `.claude/skills/` |
-| `cursor` | `.cursor/skills/` |
-| `copilot` | `.agents/skills/` |
+**Otherwise (default):** Using the first entry in `target_context_files` (resolved in step-01), take its `skill_root` value. This is the IDE's actual skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
-Store `{platform_root}` for use in snippet generation. The context-snippet.md written to disk uses this platform's root path.
+Store `{skill_root}` for use in snippet generation. The context-snippet.md written to disk uses this resolved skill root path.
 
 ### 3. Generate Snippet Content
 
@@ -106,7 +69,7 @@ Store `{platform_root}` for use in snippet generation. The context-snippet.md wr
 
 Generate:
 ```
-[{skill-name} v{version}]|root: {platform_root}{skill-name}/
+[{skill-name} v{version}]|root: {skill_root}{skill-name}/
 |IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {export-1}(), {export-2}(), {export-3}, {export-4}(), {export-5}
@@ -122,7 +85,7 @@ Generate:
 
 Generate:
 ```
-[{project}-stack v{version}]|root: {platform_root}{project}-stack/
+[{project}-stack v{version}]|root: {skill_root}{project}-stack/
 |IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -135,9 +98,9 @@ Generate:
 
 Estimate token count of generated snippet (approximate: words * 1.3).
 
-- Target: ~80-120 tokens per skill
-- Warning threshold: >150 tokens
-- If exceeding warning threshold, trim description, exports list, or refs to fit
+- Target: ~80-120 tokens per skill (aspirational for Quick/Forge tiers)
+- Warning threshold: >300 tokens (hard ceiling — Deep tier may legitimately exceed 120 when gotchas carry load-bearing breaking-change notices)
+- If exceeding warning threshold, trim description, exports list, or refs to fit — **do NOT drop gotchas to fit the target**; gotchas exist precisely to deliver the "do not rely on training data" signal and are the last thing to cut
 
 ### 5. Write or Preview Snippet
 
@@ -180,28 +143,3 @@ Display: "**Proceeding to context update...**"
 
 ONLY WHEN snippet generation is complete (or skipped due to passive_context opt-out) will you load and read fully `{nextStepFile}` to execute context update.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Snippet format loaded from {snippetFormatData}
-- Content generated matching exact Vercel-aligned format
-- Section anchors verified against SKILL.md headings (split-body anchors rewritten or omitted)
-- Token count estimated and within target
-- File written (or previewed in dry-run)
-- Passive context opt-out correctly handled (skip when disabled)
-- Prior gotchas checked and carried forward when new derivation yields nothing (with warning)
-- Auto-proceed to step-04
-
-### ❌ SYSTEM FAILURE:
-
-- Silently dropping prior gotchas without checking for carry-forward
-- Deviating from Vercel-aligned indexed format
-- Including T2 annotations or temporal context
-- Not checking passive_context setting
-- Not estimating token count
-- Halting for user input (auto-proceed step)
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/export-skill → skf-export-skill}/steps-c/step-04-update-context.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-04-update-context'
-description: 'Update managed section in CLAUDE.md/AGENTS.md with four-case logic per ADR-J'
-
 nextStepFile: './step-05-token-report.md'
-managedSectionData: '../data/managed-section-format.md'
+managedSectionData: 'assets/managed-section-format.md'
 ---
 
 # Step 4: Update Context
@@ -12,44 +9,13 @@ managedSectionData: '../data/managed-section-format.md'
 
 To update the managed `<!-- SKF:BEGIN/END -->` section in the platform-appropriate context file (CLAUDE.md/AGENTS.md/.cursorrules) using the four-case logic defined by ADR-J (Create, Append, Regenerate, Malformed Markers halt), rebuilding the complete skill index from all exported skills.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER modify content outside `<!-- SKF:BEGIN/END -->` markers
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a delivery and packaging specialist in Ferris Delivery mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Surgical precision required — existing file content MUST be preserved
-- ✅ User confirms changes before any writes to shared context files
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on the managed section update in the target context file
-- 🚫 FORBIDDEN to modify ANY content outside `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` markers
-- 🚫 FORBIDDEN to write without user confirmation — this modifies shared project files
-- 💬 Show a clear diff preview before writing
-- 📋 If `passive_context: false` was detected in step-01, SKIP this step entirely and auto-proceed
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Load {managedSectionData} for format template and three-case logic
-- 📖 Rebuild the COMPLETE skill index — not just the current skill
-- 🚫 ZERO data loss — verify preserved content before and after write
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Skill metadata from step-01, context-snippet.md from step-03, platform flag
-- Focus: Three-case detection and managed section update
-- Limits: Only modify content between markers — preserve everything else
-- Dependencies: Step-03 must have generated the snippet (or step skipped if passive_context off)
+- Focus only on the managed section update in the target context file
+- Do not modify any content outside `<!-- SKF:BEGIN -->` and `<!-- SKF:END -->` markers
+- Do not write without user confirmation — this modifies shared project files
+- If `passive_context: false` was detected in step-01, skip this step entirely
+- **Multi-skill mode:** this step executes ONCE for the whole batch, not once per skill. §4b already builds the exported skill set from the manifest (plus current export targets), so a multi-skill run naturally appears as a single rebuild. The only batch adjustment is in §9b: update the manifest entry for every skill in `skill_batch` (not just one), and include all of them when computing `ides_written`. See step-01 §1c.
 
 ## MANDATORY SEQUENCE
 
@@ -67,61 +33,55 @@ Auto-proceed immediately to {nextStepFile}.
 
 ### 2. Load Managed Section Format
 
-Load {managedSectionData} and read the complete format template and three-case logic.
+Load {managedSectionData} and read the complete format template and four-case logic.
 
 ### 3. Determine Target File(s)
 
-Using the `target_platforms` list resolved in step-01, determine all target files:
-
-| Platform | Target File |
-|----------|-------------|
-| `claude` | CLAUDE.md |
-| `cursor` | .cursorrules |
-| `copilot` | AGENTS.md |
+Using the `target_context_files` list resolved in step-01, determine all target files. Each entry has `{context_file, skill_root}` — the context file to write and the IDE's skill directory for root path resolution.
 
-For each platform in `target_platforms`, resolve target file path: `{project-root}/{target-file}`
+For each entry in `target_context_files`, resolve target file path: `{context_file}`
 
-**If multiple platforms:** Sections 4-9a execute as a loop — one full pass per target platform. Each iteration uses the same skill index but rewrites root paths per platform (section 4d) and writes to the platform-specific target file. Section 9b executes once after all iterations complete.
+**If multiple context files:** Sections 4-9a execute as a loop — one full pass per target context file. Each iteration uses the same skill index but rewrites root paths per context file's `skill_root` (section 4d) and writes to the target context file. Section 9b executes once after all iterations complete.
 
-**Processing order:** Process platforms in the order listed in `target_platforms`.
+**Processing order:** Process context files in the order listed in `target_context_files`.
 
 #### 3b. Detect Orphaned Platform Files (Stale Managed Sections)
 
-A platform file becomes orphaned when its IDE is removed from `config.yaml` after a prior export. The file still contains an SKF managed section pointing to stale skill versions, but no future export will rewrite it.
+A context file becomes orphaned when its IDE is removed from `config.yaml` after a prior export. The file still contains an SKF managed section pointing to stale skill versions, but no future export will rewrite it.
 
-Build `orphaned_platform_files` — the set of platform context files that exist on disk with an `<!-- SKF:BEGIN -->` marker but whose platform is NOT in the current `target_platforms` list:
+Build `orphaned_context_files` — the set of context files that exist on disk with an `<!-- SKF:BEGIN -->` marker but whose context file is NOT in the current `target_context_files` list:
 
-1. For each platform in the full set `{claude, cursor, copilot}`:
-   - If the platform is in `target_platforms`, skip (it will be rewritten in the main loop)
-   - Otherwise, check whether its target file exists (`CLAUDE.md`, `.cursorrules`, or `AGENTS.md`)
+1. For each known context file in `{CLAUDE.md, .cursorrules, AGENTS.md}`:
+   - If the context file is in `target_context_files`, skip (it will be rewritten in the main loop)
+   - Otherwise, check whether the file exists at `{context_file}`
    - If the file exists, read it and check for the `<!-- SKF:BEGIN -->` marker
-   - If the marker is present, add the file path to `orphaned_platform_files` along with the platform name
+   - If the marker is present, add the file path to `orphaned_context_files` along with the context file name
 
-2. If `orphaned_platform_files` is non-empty, emit a warning:
+2. If `orphaned_context_files` is non-empty, emit a warning:
 
-   "**Orphaned platform files detected.** The following files contain SKF managed sections but their platforms are no longer in `config.yaml` `ides`:
-   {list: platform → file path}
+   "**Orphaned context files detected.** The following files contain SKF managed sections but no configured IDEs target them:
+   {list: context file → file path}
 
    The managed sections in these files are stale. Options:
    - **(a) clear** — remove the SKF managed section from each orphaned file (surgical marker replacement, leaves user content intact)
-   - **(b) keep** — leave them untouched (they will remain stale until you re-add the IDE or delete the file)
+   - **(b) keep** — leave them untouched (they will remain stale until you re-add an IDE that targets this file or delete the file)
    - **(c) rewrite** — also rewrite the orphaned files with the current skill index (use this if the IDE was removed by mistake)"
 
 3. Wait for user choice. In non-interactive mode (dry-run or unattended), default to **(b) keep** and print the warning only.
 
 4. If the user chose **(a) clear**: for each orphaned file, replace everything between `<!-- SKF:BEGIN` and `<!-- SKF:END -->` (inclusive) with an empty string, preserving surrounding content byte-exactly. Record the cleared files in `orphans_cleared`.
 
-5. If the user chose **(c) rewrite**: add each orphaned platform to a separate `rewrite_platforms` list (kept distinct from `target_platforms` so the user's intent to only export to configured IDEs is preserved in the manifest's `platforms` field). Sections 4–9a will loop over `target_platforms + rewrite_platforms` for this run only. Record the rewritten files in `orphans_rewritten`.
+5. If the user chose **(c) rewrite**: add each orphaned context file to a separate `rewrite_context_files` list (kept distinct from `target_context_files` so the user's intent to only export to configured IDEs is preserved in the manifest). Use `.agents/skills/` as the default skill root for rewritten orphans. Sections 4–9a will loop over `target_context_files + rewrite_context_files` for this run only. Record the rewritten files in `orphans_rewritten`.
 
 6. If the user chose **(b) keep**: record nothing and proceed.
 
-This cleanup only runs during interactive export. Drop-skill and rename-skill operate on the manifest's declared platforms and are not responsible for orphan detection.
+This cleanup only runs during interactive export. Drop-skill and rename-skill operate on the manifest's declared context files and are not responsible for orphan detection.
 
 ### 4. Rebuild Complete Skill Index
 
 #### 4a. Read Export Manifest (v2 — version-aware)
 
-Read `{skills_output_folder}/.export-manifest.json` — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full v2 schema:
+Read `{skills_output_folder}/.export-manifest.json` — see `knowledge/version-paths.md` for the full v2 schema:
 
 **If the file exists:** Parse JSON. Check for `schema_version` field:
 
@@ -134,17 +94,17 @@ Read `{skills_output_folder}/.export-manifest.json` — see [knowledge/version-p
       "active_version": "0.6.0",
       "versions": {
         "0.1.0": {
-          "platforms": ["claude"],
+          "ides": ["claude-code"],
           "last_exported": "2026-01-15",
           "status": "deprecated"
         },
         "0.5.0": {
-          "platforms": ["claude"],
+          "ides": ["claude-code"],
           "last_exported": "2026-03-15",
           "status": "archived"
         },
         "0.6.0": {
-          "platforms": ["claude", "copilot"],
+          "ides": ["claude-code", "github-copilot"],
           "last_exported": "2026-04-04",
           "status": "active"
         }
@@ -160,10 +120,12 @@ Read `{skills_output_folder}/.export-manifest.json` — see [knowledge/version-p
 - `"deprecated"` — dropped via drop-skill workflow; excluded from all exports (files may or may not exist on disk)
 - `"draft"` — created but never exported
 
+**Legacy `platforms` → `ides` rename:** Pre-rename v2 manifests used a `platforms` array at the version level. If a version entry contains `platforms` instead of (or in addition to) `ides`, treat `platforms` as `ides` and rewrite it to `ides` on the next manifest write. This is a silent in-place upgrade — no user prompt, no v3 bump.
+
 **v1 manifest** (no `schema_version` field — migrate in-place to v2):
-1. For each entry in `exports`, read its `platforms` and `last_exported`
+1. For each entry in `exports`, read its `last_exported` (v1 had no per-version IDE list)
 2. Resolve the skill's current version from `{resolved_skill_package}/metadata.json`
-3. Wrap in v2 structure: set `active_version` to the resolved version, create a single entry in `versions` with `status: "active"`, the original `platforms`, and `last_exported`
+3. Wrap in v2 structure: set `active_version` to the resolved version, create a single entry in `versions` with `status: "active"`, `ides: []` (unknown — will be filled on next successful export), and `last_exported`
 4. Set `schema_version: "2"` at root
 5. Hold the migrated structure in context (it will be written in section 9b)
 
@@ -194,30 +156,23 @@ Instead of globbing `{skills_output_folder}/*/context-snippet.md`, resolve snipp
 
 **If no snippets pass the filter:** Generate managed section with zero skills — header only, no skill entries.
 
-#### 4d. Rewrite Root Paths for Target Platform
-
-The context-snippet.md files on disk contain root paths for the platform they were originally exported to. When assembling the managed section for the current target platform, rewrite root paths if they differ:
+#### 4d. Rewrite Root Paths for Target Context File
 
-**Platform root path mapping:**
+The context-snippet.md files on disk contain root paths for the IDE they were originally exported to. When assembling the managed section for the current target context file, rewrite root paths if they differ from the target's `skill_root`.
 
-| Platform | Root Path Prefix |
-|----------|-----------------|
-| `claude` | `.claude/skills/` |
-| `cursor` | `.cursor/skills/` |
-| `copilot` | `.agents/skills/` |
-| _(legacy)_ | `skills/` |
-
-The legacy `skills/` prefix may appear in snippets exported before platform-aware root paths were introduced, or in draft snippets generated by create-skill/quick-skill.
+**Generic root path rewrite algorithm** (no hardcoded prefix list):
 
 For each snippet being included in the managed section:
 
-1. Read the `root:` value from the snippet's first line
-2. Detect the current root prefix by matching against the known prefixes above (check platform-specific prefixes first, then fall back to legacy `skills/`)
-3. If the detected prefix does not match the current target platform's prefix, rewrite it
-4. Example: if snippet has `root: .claude/skills/my-lib/` but target is `cursor`, rewrite to `root: .cursor/skills/my-lib/`
-5. Example: if snippet has legacy `root: skills/my-lib/` and target is `copilot`, rewrite to `root: .agents/skills/my-lib/`
+1. Read the `root:` value from the snippet's first line — it has the form `root: {prefix}{skill-name}/`
+2. Extract the current prefix by stripping the trailing `{skill-name}/` from the root value
+3. **Override guard:** If `snippet_skill_root_override` is set in config.yaml AND the extracted prefix equals the override value, skip the rewrite for this snippet — leave the root path untouched. This is the authoring-repo escape hatch: when the override is set, any snippet that already matches the override prefix is treated as ground truth and must not be rewritten to a per-IDE path that does not exist on disk.
+4. Otherwise, compare the extracted prefix against the current target's `skill_root`
+5. If they differ, replace the prefix with the target's `skill_root`, preserving the skill name
+6. Example: if snippet has `root: .claude/skills/my-lib/` but target skill_root is `.windsurf/skills/`, rewrite to `root: .windsurf/skills/my-lib/`
+7. Example: if snippet has legacy `root: skills/my-lib/` and target skill_root is `.github/skills/`, rewrite to `root: .github/skills/my-lib/` — **unless** `snippet_skill_root_override: skills/` is set, in which case the `skills/` prefix is preserved
 
-This ensures each platform's managed section points to the correct platform-specific skill directory, including during migration from pre-platform-aware exports.
+This algorithm handles any IDE's skill root path — including future IDEs — without enumerating known prefixes. The legacy `skills/` prefix (no leading dot) may appear in draft snippets generated by create-skill/quick-skill before export.
 
 **Sort skills alphabetically by name.**
 
@@ -245,7 +200,7 @@ Assemble the complete managed section:
 
 ### 6. Detect Case and Prepare Changes
 
-**Check target file at `{project-root}/{target-file}`:**
+**Check target file at `{target-file}`:**
 
 **Case 1: Create (file does not exist)**
 - Action: Create new file with managed section only
@@ -269,7 +224,7 @@ Assemble the complete managed section:
 
 "**Context update prepared.{if multi-platform: ' (platform {i}/{total}: {platform})'}**
 
-**Target:** `{project-root}/{target-file}`
+**Target:** `{target-file}`
 **Case:** {1: Create / 2: Append / 3: Regenerate}
 **Skills in index:** {n} skills, {m} stack
 
@@ -298,9 +253,9 @@ Auto-proceed to {nextStepFile}.
 
 Display: "**Select:** [C] Continue — write changes to {target-file}"
 
-**Multi-platform behavior:** When processing multiple platforms, present all platforms' previews together before asking for a single confirmation. After confirmation, write all target files sequentially, verifying each one.
+**Multi-target behavior:** When processing multiple context files, present all previews together before asking for a single confirmation. After confirmation, write all target files sequentially, verifying each one.
 
-"**Targets:** {list all platform → target-file pairs}
+"**Targets:** {list all context-file → target-file pairs}
 **Ready to write changes to all targets?**"
 
 Display: "**Select:** [C] Continue — write changes to all targets"
@@ -313,6 +268,7 @@ Display: "**Select:** [C] Continue — write changes to all targets"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve context file update"
 - ONLY proceed to next step when user selects 'C'
 - In dry-run mode, auto-proceed without writing
 
@@ -331,33 +287,35 @@ After user confirms with 'C':
 
 ### 9b. Update Export Manifest (Non-Dry-Run Only)
 
-**This section executes ONCE after all platform iterations complete** (outside the per-platform loop defined in section 3). Only platforms whose writes succeeded in section 9 are recorded.
+**This section executes ONCE after all context-file iterations complete** (outside the per-context-file loop defined in section 3). Only IDEs whose target context files were successfully written and verified in section 9 are recorded.
+
+**`ides` field definition:** `ides` is the list of IDE identifiers from `config.yaml.ides` (e.g. `claude-code`, `cursor`, `github-copilot`) whose context files were successfully written and verified in section 9. It is NOT the context file name (`CLAUDE.md`) and NOT the skill root path (`.claude/skills/`). Each IDE → context file → skill root mapping is defined in `skf-export-skill/assets/managed-section-format.md`.
 
 1. Read `{skills_output_folder}/.export-manifest.json` (or start with `{"schema_version": "2", "exports": {}}` if it does not exist)
-2. Ensure `schema_version` is `"2"` (if v1 was migrated in section 4a, the migrated structure is already in context)
-3. Add or update the current skill's entry in v2 format:
+2. Ensure `schema_version` is `"2"` (if v1 was migrated in section 4a, the migrated structure is already in context). If any version entry still has a legacy `platforms` key, rename it to `ides` in place (see §4a).
+3. Compute `ides_written` — the set of IDE identifiers from `config.yaml.ides` whose mapped context file was successfully written in section 9 (deduplicated, sorted). When `--context-file` was passed explicitly, `ides_written` contains only the IDEs that map to that single context file.
+4. For each skill in `skill_batch` (multi-skill mode) — or the single current skill (single-skill mode) — add or update its entry in v2 format:
    ```json
    "{skill-name}": {
      "active_version": "{version}",
      "versions": {
        "{version}": {
-         "platforms": ["{successfully-written platforms}"],
+         "ides": ["{ides_written}"],
          "last_exported": "{current-date}",
          "status": "active"
        }
      }
    }
    ```
-   - `{version}` is the version from `{resolved_skill_package}/metadata.json`
-   - Set `platforms` to only the platforms that were successfully written and verified in section 9
+   - `{version}` is the version from each skill's `{resolved_skill_package}/metadata.json`
    - If the skill already has a manifest entry:
      - Set `active_version` to the current version
-     - If the version already exists in `versions`, update its `platforms` (merge, deduplicate), `last_exported`, and set `status: "active"`
+     - If the version already exists in `versions`, union its existing `ides` with `ides_written` (deduplicate, keep sorted), refresh `last_exported`, and set `status: "active"`
      - If this is a new version, add it to `versions` with `status: "active"` and set any previously-active version's status to `"archived"`
      - Preserve all other version entries in `versions` (do not delete archived versions)
-4. Write the updated manifest to `{skills_output_folder}/.export-manifest.json`
+5. Write the updated manifest once to `{skills_output_folder}/.export-manifest.json` after all skills in the batch have been applied
 
-**Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name} on platform(s) {platform-list}.**"
+**Dry-run mode:** Do NOT update the manifest. Display: "**[DRY RUN] Export manifest would be updated for {skill-name-list} — ides: {ides_written}.**" (list every skill in `skill_batch`)
 
 **Error handling:** If manifest write fails, warn but do not fail the workflow — the managed section was already written successfully.
 
@@ -365,35 +323,3 @@ After user confirms with 'C':
 
 ONLY WHEN the user confirms changes by selecting 'C' (or auto-proceed in dry-run) and the write is verified will you load and read fully `{nextStepFile}` to execute the token report.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Managed section format loaded from {managedSectionData}
-- Target file(s) correctly determined from platform flag or config.yaml ides list
-- Multi-platform loop executed for all target_platforms
-- Root paths rewritten per platform in managed section
-- Complete skill index rebuilt from exported skills only (filtered via .export-manifest.json per ADR-K)
-- Export manifest updated after successful write (non-dry-run only)
-- Correct case detected (create/append/regenerate)
-- Clear diff preview shown to user
-- User confirmation received before writing
-- Write verified — markers present, external content preserved
-- Passive context opt-out correctly handled (skip when disabled)
-- Dry-run correctly handled (preview only, no writes)
-
-### ❌ SYSTEM FAILURE:
-
-- Modifying content outside `<!-- SKF:BEGIN/END -->` markers
-- Not rebuilding the COMPLETE skill index (only adding current skill)
-- Including un-exported skills in managed section (bypasses ADR-K publishing gate)
-- Updating export manifest during dry-run
-- Writing without user confirmation
-- Not verifying write after completion
-- Not detecting the correct case (create/append/regenerate)
-- Losing existing file content during write
-- Not skipping when passive_context is disabled
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. ZERO data loss in target files is NON-NEGOTIABLE.

package/src/{workflows/export-skill → skf-export-skill}/steps-c/step-05-token-report.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-05-token-report'
-description: 'Calculate and report token counts for all export artifacts'
-
 nextStepFile: './step-06-summary.md'
 ---
 
@@ -11,40 +8,11 @@ nextStepFile: './step-06-summary.md'
 
 To calculate approximate token counts for all exported artifacts and present a clear report showing the token cost of each component, helping users understand the context budget impact of their skills.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are a delivery and packaging specialist in Ferris Delivery mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Report clearly — token counts inform developers' context budget decisions
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on token counting and reporting
-- 🚫 FORBIDDEN to modify any files — read-only measurement
-- 💬 This is a deterministic reporting step — auto-proceed when complete
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Hold token counts in context for the summary step
-- 📖 Use consistent estimation method across all files
-- 🚫 No file writes — measurement only
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: All artifacts from steps 01-04 (SKILL.md, metadata.json, context-snippet.md, managed section content)
-- Focus: Token estimation and reporting
-- Limits: Estimates only — exact counts vary by tokenizer
-- Dependencies: Steps 01-04 must have completed (or been skipped where appropriate)
+- Focus only on token counting and reporting — read-only measurement
+- Auto-proceed when complete
+- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), compute token counts per skill, then present one aggregate table with one row per skill (context-snippet.md, SKILL.md, metadata.json, references/, package total). Measure the managed section once for the run — it is shared across the batch. See step-01 §1c.
 
 ## MANDATORY SEQUENCE
 
@@ -102,25 +70,3 @@ Display: "**Proceeding to export summary...**"
 
 ONLY WHEN the token report is displayed will you load and read fully `{nextStepFile}` to execute the export summary.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All artifacts measured with consistent heuristic
-- Clear table format with words and estimated tokens
-- Context budget impact explained (always-on vs on-trigger vs full)
-- Benchmark comparison for managed section target
-- Passive context opt-out correctly handled (skip snippet/section measurements)
-- Auto-proceed to step-06
-
-### ❌ SYSTEM FAILURE:
-
-- Not measuring all artifacts
-- Inconsistent estimation method
-- Not explaining context budget impact
-- Modifying any files (read-only step)
-- Not auto-proceeding after report
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.