oh-my-opencode-slim 0.9.15 → 1.0.1

package/dist/interview/service.d.ts

@@ -3,6 +3,7 @@ import type { InterviewConfig } from '../config';
 import type { InterviewAnswer, InterviewFileItem, InterviewListItem, InterviewRecord, InterviewState } from './types';
 export declare function createInterviewService(ctx: PluginInput, config?: InterviewConfig, deps?: {
     openBrowser?: (url: string) => void;
+    env?: NodeJS.ProcessEnv;
 }): {
     setBaseUrlResolver: (resolver: () => Promise<string>) => void;
     setStatePushCallback: (callback: (interviewId: string, state: InterviewState) => void) => void;

package/dist/multiplexer/index.d.ts

@@ -2,6 +2,7 @@
  * Multiplexer module exports
  */
 export { clearMultiplexerCache, getMultiplexer, startAvailabilityCheck, } from './factory';
+export { MultiplexerSessionManager, TmuxSessionManager, } from './session-manager';
 export { TmuxMultiplexer } from './tmux';
 export type { Multiplexer, PaneResult } from './types';
 export { isServerRunning } from './types';

package/dist/multiplexer/session-manager.d.ts

@@ -0,0 +1,46 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { MultiplexerConfig } from '../config/schema';
+interface SessionEvent {
+    type: string;
+    properties?: {
+        info?: {
+            id?: string;
+            parentID?: string;
+            title?: string;
+            directory?: string;
+        };
+        sessionID?: string;
+        status?: {
+            type: string;
+        };
+    };
+}
+/**
+ * Tracks child sessions and spawns/closes multiplexer panes for them.
+ *
+ * Uses session.status events for completion detection instead of polling,
+ * with polling kept as a fallback for reliability.
+ */
+export declare class MultiplexerSessionManager {
+    private client;
+    private serverUrl;
+    private directory;
+    private multiplexer;
+    private sessions;
+    private pollInterval?;
+    private enabled;
+    constructor(ctx: PluginInput, config: MultiplexerConfig);
+    onSessionCreated(event: SessionEvent): Promise<void>;
+    onSessionStatus(event: SessionEvent): Promise<void>;
+    onSessionDeleted(event: SessionEvent): Promise<void>;
+    private startPolling;
+    private stopPolling;
+    private pollSessions;
+    private closeSession;
+    cleanup(): Promise<void>;
+}
+/**
+ * @deprecated Use MultiplexerSessionManager instead
+ */
+export declare const TmuxSessionManager: typeof MultiplexerSessionManager;
+export {};

package/dist/multiplexer/types.d.ts

@@ -2,7 +2,7 @@
  * Multiplexer abstraction layer
  *
  * Provides a unified interface for terminal multiplexers (tmux, zellij, etc.)
- * to spawn and manage panes for background task visualization.
+ * to spawn and manage panes for child agent sessions.
  */
 import type { MultiplexerConfig, MultiplexerLayout } from '../config/schema';
 export interface PaneResult {

package/dist/tools/ast-grep/index.d.ts

@@ -1,10 +1,10 @@
 import type { ToolDefinition } from '@opencode-ai/plugin';
 import { ast_grep_replace, ast_grep_search } from './tools';
 export declare const builtinTools: Record<string, ToolDefinition>;
-export { ast_grep_search, ast_grep_replace };
 export { ensureCliAvailable, getAstGrepPath, isCliAvailable, startBackgroundInit, } from './cli';
 export type { EnvironmentCheckResult } from './constants';
 export { checkEnvironment, formatEnvironmentCheck } from './constants';
 export { ensureAstGrepBinary, getCacheDir, getCachedBinaryPath, } from './downloader';
 export type { CliLanguage, CliMatch, SgResult } from './types';
 export { CLI_LANGUAGES } from './types';
+export { ast_grep_replace, ast_grep_search };

package/dist/tools/background.d.ts

@@ -8,6 +8,6 @@ import type { MultiplexerConfig } from '../config/schema';
  * @param manager - Background task manager for launching and tracking tasks
  * @param _multiplexerConfig - Optional multiplexer configuration for session management
  * @param _pluginConfig - Optional plugin configuration for agent variants
- * @returns Object containing background_task, background_output, and background_cancel tools
+ * @returns Object containing background_task, background_output, background_cancel, and ask_orchestrator tools
  */
 export declare function createBackgroundTools(_ctx: PluginInput, manager: BackgroundTaskManager, _multiplexerConfig?: MultiplexerConfig, _pluginConfig?: PluginConfig): Record<string, ToolDefinition>;

package/dist/tools/council.d.ts

@@ -4,6 +4,7 @@ import type { CouncilManager } from '../council/council-manager';
  * Creates the council_session tool for multi-LLM orchestration.
  *
  * This tool triggers a full council session: parallel councillors →
- * master synthesis. Available to the council agent.
+ * formatted results returned to the council agent for synthesis.
+ * Available to the council agent.
  */
 export declare function createCouncilTool(_ctx: PluginInput, councilManager: CouncilManager): Record<string, ToolDefinition>;

package/dist/tools/index.d.ts

@@ -1,5 +1,5 @@
 export { ast_grep_replace, ast_grep_search } from './ast-grep';
-export { createBackgroundTools } from './background';
 export { createCouncilTool } from './council';
-export { lsp_diagnostics, lsp_find_references, lsp_goto_definition, lsp_rename, lspManager, setUserLspConfig, } from './lsp';
+export type { PresetManager } from './preset-manager';
+export { createPresetManager } from './preset-manager';
 export { createWebfetchTool } from './smartfetch';

package/dist/tools/lsp/types.d.ts

@@ -32,7 +32,7 @@ export type ServerLookupResult = {
     server: ResolvedServer;
     installHint: string;
 };
-export type { Position, Range, Location, LocationLink, Diagnostic, TextDocumentIdentifier, VersionedTextDocumentIdentifier, TextEdit, TextDocumentEdit, CreateFile, RenameFile, DeleteFile, WorkspaceEdit, SymbolInfo, DocumentSymbol, };
+export type { CreateFile, DeleteFile, Diagnostic, DocumentSymbol, Location, LocationLink, Position, Range, RenameFile, SymbolInfo, TextDocumentEdit, TextDocumentIdentifier, TextEdit, VersionedTextDocumentIdentifier, WorkspaceEdit, };
 export interface DocumentDiagnosticReportFull {
     kind: 'full';
     items: Diagnostic[];

package/dist/tools/preset-manager.d.ts

@@ -0,0 +1,27 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { PluginConfig } from '../config';
+/**
+ * Creates a preset manager for the /preset slash command.
+ *
+ * Uses the OpenCode SDK's client.config.update() to change agent models
+ * and temperatures without restarting. The server invalidates its agent
+ * cache and re-reads config on the next prompt.
+ *
+ * Note: activePreset is tracked in-memory only and resets on plugin reload.
+ * If the user manually edits config or another mechanism changes agents,
+ * this tracker may become stale until the next /preset call.
+ */
+export declare function createPresetManager(ctx: PluginInput, config: PluginConfig): {
+    handleCommandExecuteBefore: (input: {
+        command: string;
+        sessionID: string;
+        arguments: string;
+    }, output: {
+        parts: Array<{
+            type: string;
+            text?: string;
+        }>;
+    }) => Promise<void>;
+    registerCommand: (opencodeConfig: Record<string, unknown>) => void;
+};
+export type PresetManager = ReturnType<typeof createPresetManager>;

package/dist/utils/subagent-depth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tracks subagent spawn depth to prevent excessive nesting.
+ *
+ * Depth 0 = root session (user's main conversation)
+ * Depth 1 = agent spawned by root (e.g., explorer, council)
+ * Depth 2 = agent spawned by depth-1 agent (e.g., councillor spawned by council)
+ * Depth 3 = agent spawned by depth-2 agent (max depth by default)
+ *
+ * When max depth is exceeded, the spawn is blocked.
+ */
+export declare class SubagentDepthTracker {
+    private depthBySession;
+    private readonly _maxDepth;
+    constructor(maxDepth?: number);
+    /** Maximum allowed depth. */
+    get maxDepth(): number;
+    /**
+     * Get the current depth of a session.
+     * Root sessions (not tracked) have depth 0.
+     */
+    getDepth(sessionId: string): number;
+    /**
+     * Register a child session and check if the spawn is allowed.
+     * @returns true if allowed, false if max depth exceeded
+     */
+    registerChild(parentSessionId: string, childSessionId: string): boolean;
+    /**
+     * Clean up session tracking when a session is deleted.
+     */
+    cleanup(sessionId: string): void;
+    /**
+     * Clean up all tracking data.
+     */
+    cleanupAll(): void;
+}

package/dist/utils/tmux-debug-log.d.ts

@@ -0,0 +1,2 @@
+export declare function logTmuxDebug(event: string, data?: unknown): void;
+export declare function getTmuxDebugLogPath(): string;

package/oh-my-opencode-slim.schema.json

@@ -218,6 +218,7 @@
                   "type": "string"
                 },
                 {
+                  "minItems": 1,
                   "type": "array",
                   "items": {
                     "anyOf": [
@@ -263,6 +264,14 @@
                 "type": "string"
               }
             },
+            "prompt": {
+              "type": "string",
+              "minLength": 1
+            },
+            "orchestratorPrompt": {
+              "type": "string",
+              "minLength": 1
+            },
             "options": {
               "type": "object",
               "propertyNames": {
@@ -274,7 +283,8 @@
               "type": "string",
               "minLength": 1
             }
-          }
+          },
+          "additionalProperties": false
         }
       }
     },
@@ -292,6 +302,7 @@
                 "type": "string"
               },
               {
+                "minItems": 1,
                 "type": "array",
                 "items": {
                   "anyOf": [
@@ -337,6 +348,14 @@
               "type": "string"
             }
           },
+          "prompt": {
+            "type": "string",
+            "minLength": 1
+          },
+          "orchestratorPrompt": {
+            "type": "string",
+            "minLength": 1
+          },
           "options": {
             "type": "object",
             "propertyNames": {
@@ -348,11 +367,12 @@
             "type": "string",
             "minLength": 1
           }
-        }
+        },
+        "additionalProperties": false
       }
     },
     "disabled_agents": {
-      "description": "Agent names to disable completely. Disabled agents are not instantiated and cannot be delegated to. Orchestrator and council internal agents (councillor, council-master) cannot be disabled. By default, 'observer' is disabled. Remove it from this list and configure a vision-capable model to enable.",
+      "description": "Agent names to disable completely. Disabled agents are not instantiated and cannot be delegated to. Orchestrator and council internal agents (councillor) cannot be disabled. By default, 'observer' is disabled. Remove it from this list and configure a vision-capable model to enable.",
       "type": "array",
       "items": {
         "type": "string"
@@ -435,17 +455,6 @@
         }
       }
     },
-    "background": {
-      "type": "object",
-      "properties": {
-        "maxConcurrentStarts": {
-          "default": 10,
-          "type": "number",
-          "minimum": 1,
-          "maximum": 50
-        }
-      }
-    },
     "interview": {
       "type": "object",
       "properties": {
@@ -462,6 +471,7 @@
         },
         "autoOpenBrowser": {
           "default": true,
+          "description": "Automatically open the interview UI in your default browser during interactive runs. Disabled automatically in tests and CI.",
           "type": "boolean"
         },
         "port": {
@@ -589,26 +599,6 @@
     "council": {
       "type": "object",
       "properties": {
-        "master": {
-          "type": "object",
-          "properties": {
-            "model": {
-              "type": "string",
-              "pattern": "^[^/\\s]+\\/[^\\s]+$",
-              "description": "Model ID for the council master (e.g. \"anthropic/claude-opus-4-6\")"
-            },
-            "variant": {
-              "type": "string"
-            },
-            "prompt": {
-              "description": "Optional role/guidance injected into the master synthesis prompt",
-              "type": "string"
-            }
-          },
-          "required": [
-            "model"
-          ]
-        },
         "presets": {
           "type": "object",
           "propertyNames": {
@@ -628,12 +618,7 @@
             }
           }
         },
-        "master_timeout": {
-          "default": 300000,
-          "type": "number",
-          "minimum": 0
-        },
-        "councillors_timeout": {
+        "timeout": {
           "default": 180000,
           "type": "number",
           "minimum": 0
@@ -642,14 +627,6 @@
           "default": "default",
           "type": "string"
         },
-        "master_fallback": {
-          "description": "Fallback models for the council master. Tried in order if the primary model fails. Example: [\"anthropic/claude-sonnet-4-6\", \"openai/gpt-5.4\"]",
-          "type": "array",
-          "items": {
-            "type": "string",
-            "pattern": "^[^/\\s]+\\/[^\\s]+$"
-          }
-        },
         "councillor_execution_mode": {
           "default": "parallel",
           "description": "Execution mode for councillors. \"serial\" runs them one at a time (required for single-model systems). \"parallel\" runs them concurrently (default, faster for multi-model systems).",
@@ -661,14 +638,22 @@
         },
         "councillor_retries": {
           "default": 3,
-          "description": "Number of retry attempts for councillors and master that return empty responses (e.g. due to provider rate limiting). Default: 3 retries.",
+          "description": "Number of retry attempts for councillors that return empty responses (e.g. due to provider rate limiting). Default: 3 retries.",
           "type": "integer",
           "minimum": 0,
           "maximum": 5
+        },
+        "master": {
+          "description": "DEPRECATED — ignored. Council agent synthesizes directly."
+        },
+        "master_timeout": {
+          "description": "DEPRECATED — ignored. Use \"timeout\" instead."
+        },
+        "master_fallback": {
+          "description": "DEPRECATED — ignored. No separate master session."
         }
       },
       "required": [
-        "master",
         "presets"
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode-slim",
-  "version": "0.9.15",
+  "version": "1.0.1",
   "description": "Lightweight agent orchestration plugin for OpenCode - a slimmed-down fork of oh-my-opencode",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,8 +36,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build:plugin": "bun build src/index.ts --outdir dist --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external jsdom",
-    "build:cli": "bun build src/cli/index.ts --outdir dist/cli --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external jsdom",
+    "build:plugin": "bun build src/index.ts --outdir dist --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external jsdom --external zod",
+    "build:cli": "bun build src/cli/index.ts --outdir dist/cli --target node --format esm --external @ast-grep/napi --external @opencode-ai/plugin --external @opencode-ai/sdk --external jsdom --external zod",
     "build": "bun run build:plugin && bun run build:cli && tsc --emitDeclarationOnly && bun run generate-schema",
     "prepare": "bun run build",
     "contributors:add": "all-contributors add",
@@ -66,21 +66,20 @@
     "@opencode-ai/sdk": "^1.3.17",
     "jsdom": "^26.1.0",
     "lru-cache": "^11.3.3",
-    "turndown": "^7.2.4",
-    "vscode-jsonrpc": "^8.2.1",
-    "vscode-languageserver-protocol": "^3.17.5",
-    "which": "^6.0.1",
-    "zod": "^4.3.6"
+    "turndown": "^7.2.4"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.11",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^24.6.1",
     "@types/turndown": "^5.0.6",
-    "@types/which": "^3.0.4",
     "all-contributors-cli": "^6.26.1",
     "bun-types": "1.3.12",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
   },
   "trustedDependencies": [
     "@ast-grep/cli"

package/src/skills/{cartography → codemap}/README.md

@@ -1,31 +1,33 @@
-# Cartography Skill
+# Codemap Skill
 
 Repository understanding and hierarchical codemap generation.
 
 ## Overview
 
-Cartography helps orchestrators map and understand codebases by:
+Codemap helps orchestrators map and understand codebases by:
 
 1. Selecting relevant code/config files using LLM judgment
-2. Creating `.slim/cartography.json` for change tracking
-3. Generating empty `codemap.md` templates for explorers to fill in
+2. Creating `.slim/codemap.json` for change tracking
+3. Generating empty `codemap.md` templates for fixers to fill in
+
+Legacy `.slim/cartography.json` state is migrated to `.slim/codemap.json` automatically.
 
 ## Commands
 
 ```bash
 # Initialize mapping
-python3 cartographer.py init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
+node codemap.mjs init --root /repo --include "src/**/*.ts" --exclude "node_modules/**"
 
 # Check what changed
-python3 cartographer.py changes --root /repo
+node codemap.mjs changes --root /repo
 
 # Update hashes
-python3 cartographer.py update --root /repo
+node codemap.mjs update --root /repo
 ```
 
 ## Outputs
 
-### .slim/cartography.json
+### .slim/codemap.json
 
 ```json
 {
@@ -46,7 +48,7 @@ python3 cartographer.py update --root /repo
 
 ### codemap.md (per folder)
 
-Empty templates created in each folder for explorers to fill with:
+Empty templates created in each folder for fixers to fill with:
 - Responsibility
 - Design patterns
 - Data/control flow

package/src/skills/{cartography → codemap}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: cartography
+name: codemap
 description: Generate comprehensive hierarchical codemaps for UNFAMILIAR repositories. Expensive operation - only use when explicitly asked for codebase documentation or initial repository mapping
 ---
 
-# Cartography Skill
+# Codemap Skill
 
 You help users understand and map repositories by creating hierarchical codemaps.
 
@@ -17,11 +17,15 @@ You help users understand and map repositories by creating hierarchical codemaps
 
 ### Step 1: Check for Existing State
 
-**First, check if `.slim/cartography.json` exists in the repo root.**
+**First, check if `.slim/codemap.json` exists in the repo root.**
 
-If it **exists**: Skip to Step 3 (Detect Changes) - no need to re-initialize.
+If it does not exist, check for legacy state at `.slim/cartography.json`.
 
-If it **doesn't exist**: Continue to Step 2 (Initialize).
+If legacy state exists: move `.slim/cartography.json` to `.slim/codemap.json`, then continue with change detection.
+
+If `.slim/codemap.json` exists: Skip to Step 3 (Detect Changes) - no need to re-initialize.
+
+If neither file exists: Continue to Step 2 (Initialize).
 
 ### Step 2: Initialize (Only if no state exists)
 
@@ -33,27 +37,27 @@ If it **doesn't exist**: Continue to Step 2 (Initialize).
      - Docs: `docs/**`, `*.md` (except root `README.md` if needed), `LICENSE`
      - Build/Deps: `node_modules/**`, `dist/**`, `build/**`, `*.min.js`
    - Respect `.gitignore` automatically
-3. **Run cartographer.py init**:
+3. **Run codemap.mjs init**:
 
 ```bash
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs init \
   --root ./ \
   --include "src/**/*.ts" \
   --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"
 ```
 
 This creates:
-- `.slim/cartography.json` - File and folder hashes for change detection
+- `.slim/codemap.json` - File and folder hashes for change detection
 - Empty `codemap.md` files in all relevant subdirectories
 
-4. **Delegate to Explorer agents** - Spawn one explorer per folder to read code and fill in its specific `codemap.md` file.
+4. **Delegate codemap writing to Fixer agents** - Spawn one fixer per folder to read code and create or update its specific `codemap.md` file.
 
 ### Step 3: Detect Changes (If state already exists)
 
-1. **Run cartographer.py changes** to see what changed:
+1. **Run codemap.mjs changes** to see what changed:
 
 ```bash
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs changes \
   --root ./
 ```
 
@@ -63,11 +67,11 @@ python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
    - Modified files
    - Affected folders
 
-3. **Only update affected codemaps** - Spawn one explorer per affected folder to update its `codemap.md`.
+3. **Only update affected codemaps** - Spawn one fixer per affected folder to update its `codemap.md`.
 4. **Run update** to save new state:
 
 ```bash
-python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
+node ~/.config/opencode/skills/codemap/scripts/codemap.mjs update \
   --root ./
 ```
 
@@ -100,12 +104,11 @@ Before working on any task, read `codemap.md` to understand:
 For deep work on a specific folder, also read that folder's `codemap.md`.
 ```
 
-This is idempotent — repeated cartography runs will detect the existing section and skip. No duplication.
-
+This is idempotent — repeated codemap runs will detect the existing section and skip. No duplication.
 
 ## Codemap Content
 
-Explorers are granted write permissions for `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
+Fixers are responsible for writing `codemap.md` files during this workflow. Use precise technical terminology to document the implementation:
 
 - **Responsibility** - Define the specific role of this directory using standard software engineering terms (e.g., "Service Layer", "Data Access Object", "Middleware").
 - **Design Patterns** - Identify and name specific patterns used (e.g., "Observer", "Singleton", "Factory", "Strategy"). Detail the abstractions and interfaces.
@@ -144,7 +147,7 @@ Example **Root Codemap (Atlas)**:
 # Repository Atlas: oh-my-opencode-slim
 
 ## Project Responsibility
-A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.
+A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and multiplexer-assisted child sessions.
 
 ## System Entry Points
 - `src/index.ts`: Plugin initialization and OpenCode integration.
@@ -155,6 +158,6 @@ A high-performance, low-latency agent orchestration plugin for OpenCode, focusin
 | Directory | Responsibility Summary | Detailed Map |
 |-----------|------------------------|--------------|
 | `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
-| `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
+| `src/features/` | Core logic for tmux integration and session state. | [View Map](src/features/codemap.md) |
 | `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |
 ```

package/src/skills/codemap/codemap.md

@@ -0,0 +1,36 @@
+# src/skills/codemap/
+
+## Responsibility
+
+- Provide a command-style skill package that standardizes repository mapping workflows for unfamiliar codebases.
+- Define the task contract used by Orchestrator/fixer agents via `SKILL.md` and operational guidance via `README.md`.
+- Generate and evolve change-aware codemap state artifacts (`.slim/codemap.json`) and scaffold placeholders (`codemap.md`).
+
+## Design
+
+- Contract layer: `SKILL.md` (machine prompt contract) + `README.md` (human-facing operation notes).
+- Execution layer: `scripts/codemap.mjs` exports deterministic helper functions:
+  - `parseArgs(argv)`
+  - `cmdInit`, `cmdChanges`, `cmdUpdate`
+  - `selectFiles`, `computeFileHash`, `computeFolderHash`, `createEmptyCodemap`
+  - `loadState`, `saveState`, `migrateLegacyState`
+- Persistence model: JSON state at `.slim/codemap.json` with `metadata`, `file_hashes`, and `folder_hashes`.
+- Testing layer: `scripts/codemap.test.ts` validates pattern matching, hash determinism, and migration behavior.
+- The script intentionally avoids network and mutates only filesystem-local state and codemap templates.
+
+## Flow
+
+- Entry point `main(argv)` parses command and arguments (`init|changes|update`, `--root`, `--include`, `--exclude`, `--exception`) and dispatches via strict branches.
+- `cmdInit()` computes include/exclude candidate sets using `selectFiles()` and writes:
+  1) `.slim/codemap.json` via `saveState()`
+  2) one `codemap.md` per discovered folder via `createEmptyCodemap()`.
+- `cmdChanges()` reloads state (`loadState()` + `migrateLegacyState()`), recomputes current hashes, emits added/removed/modified diffs and affected folder list, and exits non-zero if state is absent.
+- `cmdUpdate()` recomputes full state from existing metadata and persists it, used after targeted fixers finish updates.
+- `codemap` skill invocation path in SKILL workflow is explicit: Step 1 checks `.slim/codemap.json` or `.slim/cartography.json`, then Step 2/3 selects init or incremental path.
+
+## Integration
+
+- Installed under OpenCode through `src/cli/custom-skills.ts` as `name: 'codemap'`, `sourcePath: 'src/skills/codemap'`.
+- `src/cli/install.ts` copies this directory into the user skill directory; OpenCode executes `scripts/codemap.mjs` from that context.
+- `src/hooks/filter-available-skills/index.ts` applies agent-level skill gating via names from `getSkillPermissionsForAgent()`.
+- `scripts/verify-release-artifact.ts` includes codemap skill metadata and runtime checks as required packaged files.