@kisev/skills-opencode 2.2.3 → 2.3.0

package/README.md

@@ -2,89 +2,39 @@
 
 [Русский](README.ru.md)
 
-`@kisev/skills-opencode@2.2.3` is the optional OpenCode-specific layer. Portable
-skills have a separate lifecycle and must be installed independently through the
-[root portable flow](../../README.md).
+`@kisev/skills-opencode` is the first-class OpenCode-specific component of
+Agent Skills. It complements the portable skills but has its own installation,
+update, and removal lifecycle.
 
-## Requirements and Ownership
+## What It Adds
 
-The package requires Node.js 22+ and OpenCode `>=1.18.29 <1.19.0`.
+- OpenCode slash-command adapters for installed portable skills and package tools.
+- Six fixed agents: `manager`, `architect`, `mapper`, `worker`, `review`, and
+  `critic`.
+- Capability routing, doctor, reconcile, and agent-profile tooling.
+- Optional `rules-injector`, `rtk`, and `zed-bell` plugin wrappers.
 
-| Component          | Project scope                | Global scope                                              |
-| ------------------ | ---------------------------- | --------------------------------------------------------- |
-| npm package        | project `node_modules`       | `node_modules` in the npm project at `~/.config/opencode` |
-| Commands           | `.opencode/commands`         | `~/.config/opencode/commands`                             |
-| Agents             | `.opencode/agents`           | `~/.config/opencode/agents`                               |
-| Optional wrappers  | `.opencode/plugins`          | `~/.config/opencode/plugins`                              |
-| Ownership metadata | `.opencode/.skills-opencode` | `~/.config/opencode/.skills-opencode`                     |
+The package does not contain, install, update, or remove portable skills.
 
-The package and generated wrappers must remain resolvable after the installer
-exits. Import, plugin loading, and npm lifecycle scripts do not install assets,
-install portable skills, or edit OpenCode configuration.
+## Requirements
 
-## Persistent Package Install
+- Node.js 22 or later.
+- OpenCode `>=1.18.29 <1.19.0`.
+- A persistent npm project that owns the dependency.
 
-### Project Scope
+## Project Install
 
-Install in the repository's npm project and run the CLI from that project root:
+Install the package in the repository's npm project and preview the managed
+assets:
 
 ```shell
-cd /path/to/project
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope project --dry-run
+npm install --save-exact @kisev/skills-opencode
+npx --yes @kisev/skills-opencode@latest install --scope project --dry-run
 ```
 
-The package remains in project `node_modules`; confirmed assets go under
-`.opencode`.
-
-### Global Scope
-
-Use `~/.config/opencode` as the persistent npm project:
-
-```shell
-mkdir -p "$HOME/.config/opencode"
-cd "$HOME/.config/opencode"
-test -f package.json || npm init --yes
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope global --dry-run
-```
-
-Keep the dependency in that npm project's `package.json` and lock file.
-Confirmed assets go under `~/.config/opencode`.
-
-## Select Assets
-
-In a TTY, `install` opens four selection groups: Skill command adapters, Package
-command adapters, Fixed agents, and Selectable plugins. The two command groups
-and six fixed agents start selected; optional plugins start unselected. Skill
-command adapters are OpenCode slash commands that load an already-installed
-same-named portable skill. Package command adapters invoke package tools. A
-command adapter selection never selects or installs a skill.
-
-Outside a TTY, pass all three selection groups. This example selects three
-commands, all fixed agents, and no wrapper:
-
-```shell
-npm exec -- skills-opencode install --scope project \
-  --commands doctor,reconcile,agent-profiles \
-  --agents manager,architect,mapper,worker,review,critic \
-  --plugins none --dry-run
-```
-
-If any selection flag is present outside a TTY, `--commands`, `--agents`, and
-`--plugins` are all required. Query exact current names with:
-
-```shell
-npm exec -- skills-opencode capabilities --json
-```
-
-The selectable wrappers are `rules-injector`, `rtk`, and `zed-bell`.
-
-## Activate the Core Plugin
-
-The installer records whether the selection needs core integration, but never
-creates or edits `opencode.json`. Add the package to the user-owned `plugin`
-array for the same scope while preserving existing entries:
+Run the exact confirmation command printed by the preview. If the selected
+assets need core integration, add the package to the user-owned OpenCode
+configuration while preserving existing entries:
 
 ```json
 {
@@ -93,139 +43,16 @@ array for the same scope while preserving existing entries:
 }
 ```
 
-For project scope, keep the package in project `node_modules` and configuration
-in the project. For global scope, keep the npm project and user configuration
-under `~/.config/opencode`. Restart OpenCode after activation or asset changes.
-
-## Preview and Confirm
-
-Every mutation begins with `--dry-run`. The preview reports operations,
-conflicts, restart requirements, receipt expiry, separate plan and confirmation
-digests, and the exact confirmation command. If reconcile reports modified
-managed files or ownership conflicts, it is blocked: no receipt or Apply command
-is issued. Install or upgrade the current package first, apply its exact
-installer confirmation, then repeat reconcile; resolve ownership conflicts
-manually.
-
-```shell
-npm exec -- skills-opencode install --scope project --dry-run
-```
-
-The mandatory OpenCode flow is: persistent npm install, `install --dry-run`, the
-exact confirmation command printed by that preview, add the package to the
-user-owned `plugin` entry, and restart OpenCode. Use the persistent npm project
-at `~/.config/opencode` for global commands. Install or upgrade the package and
-apply its installer plan before every reconcile.
+Restart OpenCode after activation or asset changes. The installer does not edit
+`opencode.json` and command adapter selections do not install portable skills.
 
-The preview has a deterministic `plan_digest` and a unique
-`confirmation_digest`. A later dry-run in the same scope supersedes any older
-unconsumed preview, including previews from another package or agent operation;
-the older confirmation is rejected.
+## Documentation
 
-Run the command printed by the preview, including all selection flags. Receipts
-are private, valid for 10 minutes, single-use, and bound to the action, scope,
-root, and current inventory. Apply rejects stale state and unsafe conflicts.
+The canonical documentation lives in `docs/`, not in the package source:
 
-## Doctor
-
-`doctor` reads integration facts without creating receipts, recovering journals,
-starting plugins, or starting LSP servers:
-
-```shell
-npm exec -- skills-opencode doctor --scope project
-npm exec -- skills-opencode doctor --scope project --json
-```
-
-The report includes versions, ownership, drift, collisions, archive counts,
-redacted configuration projections, runtime summaries, and LSP facts. It does
-not serialize raw configuration, environment values, receipts, credentials, or
-secrets. Exit status `0` is clean, `1` reports findings, and `2` reports invalid
-input or an incomplete probe failure.
-
-## Update
-
-From the npm project that owns the dependency, install the exact intended
-version, preview and confirm `install` with the same scope and desired selection,
-then restart OpenCode:
-
-```shell
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope project --dry-run
-```
-
-Use the complete confirmation command printed by the preview. The installer
-updates only files whose recorded ownership and SHA-256 still match. User-owned
-or modified managed files remain conflicts. Package update does not reset agent
-model choices, variants, additional critics, or retained profile configuration.
-
-## Reconcile
-
-`reconcile` classifies current and historical portable skills, package commands,
-plugins, agents, and installation metadata for one scope:
-
-```shell
-npm exec -- skills-opencode reconcile --scope project --dry-run
-npm exec -- skills-opencode reconcile --scope project --confirm <digest>
-npm exec -- skills-opencode reconcile --scope global --dry-run --json
-```
-
-Before reconcile, first update the package in its owning npm project and apply
-the exact installer plan. Reconcile does not install, update, or remove portable
-skills; use only pinned `npx --yes skills@1.5.23` with
-`https://kisev.github.io/skills` for those skills.
-
-Confirmed reconcile archives exact-owned retired assets in a private
-content-addressed XDG archive and removes their deployed copies. Modified,
-user-owned, unknown, symlink, unsafe, or ambiguous entries remain unchanged as
-findings or conflicts. Worktrees and runtime state are preserved. The archive is
-inspectable through `doctor`; no archive restore or purge command is provided.
-
-## Manage Agents
-
-The direct CLI manages fixed-agent models and additional critics without an LLM
-call:
-
-```shell
-npm exec -- skills-opencode agent list --scope global
-npm exec -- skills-opencode agent configure manager --scope global --dry-run
-npm exec -- skills-opencode agent model-set worker --scope global --model openai/gpt-5 --variant high --dry-run
-npm exec -- skills-opencode critic add security --scope global --model anthropic/claude-sonnet-4-6 --dry-run
-npm exec -- skills-opencode agent reconcile --scope global --dry-run
-```
-
-Fixed roles keep their names, prompts, and permissions; only model and variant
-change. Additional critics use `critic-<safe-suffix>`. Every mutation uses the
-same preview and one-time confirmation contract.
-
-## Uninstall
-
-Keep the package resolvable until its assets are removed:
-
-1. Preview and confirm package-owned asset removal.
-2. Remove `@kisev/skills-opencode` from the user-owned `plugin` array.
-3. Uninstall the dependency from the same npm project.
-4. Restart OpenCode.
-
-```shell
-npm exec -- skills-opencode uninstall --scope project --dry-run
-npm exec -- skills-opencode uninstall --scope project --confirm <digest>
-npm uninstall @kisev/skills-opencode
-```
+- [Complete OpenCode integration guide](https://github.com/kisev/skills/blob/main/docs/how-to/opencode-integration.md)
+- [Portable skills guide](https://github.com/kisev/skills/blob/main/docs/how-to/portable-skills.md)
+- [Documentation index](https://github.com/kisev/skills/blob/main/docs/README.md)
 
-For global scope, run the same flow from `~/.config/opencode` with
-`--scope global`. Uninstall archives exact manifest-owned assets and preserves
-modified files as conflicts, along with worktrees, runtime state, and retained
-profile configuration. It does not remove portable skills or edit
-`opencode.json`. No archive restore or purge command is provided.
-
-## Boundaries
-
-- Portable skills and package assets install, update, and uninstall independently.
-- Commands corresponding to skills are thin adapters; the portable skill remains
-  authoritative and must be installed separately.
-- Package tools are `capabilities`, `route`, `doctor`, `agent_profiles`, and
-  `reconcile`; `route` has no slash command.
-- The installer owns only files proved by manifests and exact hashes.
-- The package is MIT-licensed. Current inventory and checks are in
-  [Migration Inventory](../../docs/migration-inventory.md) and
-  [Verification](../../docs/verification.md).
+The complete guide covers global installation, asset selection, confirmation,
+activation, doctor, update, reconcile, agent profiles, ownership, and uninstall.

package/README.ru.md

@@ -1,90 +1,39 @@
 # Интеграция OpenCode
 
-[English](README.md) | [Русский](README.ru.md)
+[English](README.md)
 
-`@kisev/skills-opencode@2.2.3` - optional OpenCode-specific слой. У portable
-skills отдельный lifecycle: их нужно установить независимо через
-[корневую инструкцию](../../README.ru.md).
+`@kisev/skills-opencode` - полноценный OpenCode-specific компонент Agent
+Skills. Он дополняет portable skills, но имеет собственный lifecycle установки,
+обновления и удаления.
 
-## Требования и ownership
+## Что добавляет package
 
-Package требует Node.js 22+ и OpenCode `>=1.18.29 <1.19.0`.
+- OpenCode slash-command adapters для установленных portable skills и package tools.
+- Шесть fixed agents: `manager`, `architect`, `mapper`, `worker`, `review` и
+  `critic`.
+- Capability routing, doctor, reconcile и управление agent profiles.
+- Optional plugin wrappers `rules-injector`, `rtk` и `zed-bell`.
 
-| Component          | Project scope                | Global scope                                      |
-| ------------------ | ---------------------------- | ------------------------------------------------- |
-| npm package        | project `node_modules`       | `node_modules` в npm project `~/.config/opencode` |
-| Commands           | `.opencode/commands`         | `~/.config/opencode/commands`                     |
-| Agents             | `.opencode/agents`           | `~/.config/opencode/agents`                       |
-| Optional wrappers  | `.opencode/plugins`          | `~/.config/opencode/plugins`                      |
-| Ownership metadata | `.opencode/.skills-opencode` | `~/.config/opencode/.skills-opencode`             |
+Package не содержит, не устанавливает, не обновляет и не удаляет portable skills.
 
-Package и generated wrappers должны оставаться доступными после завершения
-installer. Import, plugin loading и npm lifecycle scripts не устанавливают
-assets или portable skills и не меняют OpenCode configuration.
+## Требования
 
-## Постоянная установка package
+- Node.js 22 или новее.
+- OpenCode `>=1.18.29 <1.19.0`.
+- Постоянный npm project, которому принадлежит dependency.
 
-### Project scope
+## Project installation
 
-Установите package в npm project репозитория и запускайте CLI из его корня:
+Установите package в npm project репозитория и покажите preview managed assets:
 
 ```shell
-cd /path/to/project
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope project --dry-run
+npm install --save-exact @kisev/skills-opencode
+npx --yes @kisev/skills-opencode@latest install --scope project --dry-run
 ```
 
-Package остаётся в project `node_modules`, confirmed assets размещаются в
-`.opencode`.
-
-### Global scope
-
-Используйте `~/.config/opencode` как постоянный npm project:
-
-```shell
-mkdir -p "$HOME/.config/opencode"
-cd "$HOME/.config/opencode"
-test -f package.json || npm init --yes
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope global --dry-run
-```
-
-Сохраните dependency в `package.json` и lock file этого npm project. Confirmed
-assets размещаются в `~/.config/opencode`.
-
-## Выбор assets
-
-В TTY команда `install` открывает четыре группы: Skill command adapters, Package
-command adapters, Fixed agents и Selectable plugins. Две command-группы и шесть
-fixed agents изначально выбраны, optional plugins - нет. Skill command adapters
-это OpenCode slash-команды, загружающие уже установленный одноимённый portable
-skill. Package command adapters вызывают package tools. Выбор adapter не выбирает
-и не устанавливает skill.
-
-Вне TTY передайте все три selection group. Этот пример выбирает три commands,
-всех fixed agents и ни одного wrapper:
-
-```shell
-npm exec -- skills-opencode install --scope project \
-  --commands doctor,reconcile,agent-profiles \
-  --agents manager,architect,mapper,worker,review,critic \
-  --plugins none --dry-run
-```
-
-Если вне TTY передан любой selection flag, обязательны `--commands`, `--agents`
-и `--plugins`. Точные текущие имена показывает команда:
-
-```shell
-npm exec -- skills-opencode capabilities --json
-```
-
-Selectable wrappers: `rules-injector`, `rtk`, `zed-bell`.
-
-## Активация core plugin
-
-Installer записывает, нужна ли selection core integration, но никогда не создаёт
-и не меняет `opencode.json`. Добавьте package в user-owned массив `plugin` для
-того же scope, сохранив существующие entries:
+Выполните exact confirmation command из preview. Если выбранным assets нужна core
+integration, добавьте package в user-owned configuration OpenCode, сохранив
+существующие entries:
 
 ```json
 {
@@ -93,139 +42,16 @@ Installer записывает, нужна ли selection core integration, но
 }
 ```
 
-Для project scope храните package в project `node_modules`, а configuration - в
-project. Для global scope храните npm project и user configuration в
-`~/.config/opencode`. После activation или изменения assets перезапустите
-OpenCode.
-
-## Preview и confirm
-
-Каждая mutation начинается с `--dry-run`. Preview показывает operations,
-conflicts, необходимость restart, срок действия receipt, отдельные plan и
-confirmation digests и точную confirmation command. Если reconcile показывает
-modified managed files или ownership conflicts, он блокируется: receipt и Apply
-command не создаются. Сначала установите или обновите текущий package,
-примените его exact installer confirmation, затем повторите reconcile; ownership
-conflicts нужно разрешить вручную.
-
-```shell
-npm exec -- skills-opencode install --scope project --dry-run
-```
-
-Обязательный OpenCode flow: persistent npm install, `install --dry-run`, exact
-confirmation command из preview, добавление package в user-owned `plugin` и
-перезапуск OpenCode. Для global-команд используйте persistent npm project в
-`~/.config/opencode`. Перед каждым reconcile установите или обновите package и
-примените его installer plan.
+После activation или изменения assets перезапустите OpenCode. Installer не
+меняет `opencode.json`, а выбор command adapters не устанавливает portable skills.
 
-Preview имеет deterministic `plan_digest` и unique `confirmation_digest`. Новый
-dry-run в том же scope supersede-ит любой старый unconsumed preview, включая
-preview другой package или agent operation; старая confirmation отклоняется.
+## Документация
 
-Выполните команду из preview со всеми selection flags. Receipts приватны,
-действуют 10 минут, применяются один раз и связаны с action, scope, root и
-текущим inventory. Apply отклоняет stale state и unsafe conflicts.
+Каноническая документация находится в `docs/`, а не в исходниках package:
 
-## Doctor
-
-`doctor` читает integration facts без создания receipts, recovery journals,
-запуска plugins или LSP servers:
-
-```shell
-npm exec -- skills-opencode doctor --scope project
-npm exec -- skills-opencode doctor --scope project --json
-```
-
-Report содержит versions, ownership, drift, collisions, archive counts, redacted
-configuration projections, runtime summaries и LSP facts. Raw configuration,
-environment values, receipts, credentials и secrets не сериализуются. Exit
-status `0` означает чистое состояние, `1` - findings, `2` - invalid input или
-incomplete probe failure.
-
-## Обновление
-
-В npm project, которому принадлежит dependency, установите точную нужную version,
-покажите и подтвердите `install` с тем же scope и нужной selection, затем
-перезапустите OpenCode:
-
-```shell
-npm install --save-exact @kisev/skills-opencode@2.2.3
-npm exec -- skills-opencode install --scope project --dry-run
-```
-
-Используйте полную confirmation command из preview. Installer обновляет только
-files с совпадающими recorded ownership и SHA-256. User-owned или modified
-managed files остаются conflicts. Package update не сбрасывает выбранные agent
-models, variants, additional critics или retained profile configuration.
-
-## Reconcile
-
-`reconcile` классифицирует current и historical portable skills, package
-commands, plugins, agents и installation metadata одного scope:
-
-```shell
-npm exec -- skills-opencode reconcile --scope project --dry-run
-npm exec -- skills-opencode reconcile --scope project --confirm <digest>
-npm exec -- skills-opencode reconcile --scope global --dry-run --json
-```
-
-Перед reconcile сначала обновите package в принадлежащем ему npm project и
-примените exact installer plan. Reconcile не устанавливает, не обновляет и не
-удаляет portable skills; для них используйте только pinned
-`npx --yes skills@1.5.23` с `https://kisev.github.io/skills`.
-
-Confirmed reconcile архивирует exact-owned retired assets в private
-content-addressed XDG archive и удаляет их deployed copies. Modified, user-owned,
-unknown, symlink, unsafe и ambiguous entries остаются без изменений как findings
-или conflicts. Worktrees и runtime state сохраняются. Archive доступен для
-просмотра через `doctor`; команд restore или purge нет.
-
-## Управление agents
-
-Direct CLI управляет models fixed agents и additional critics без LLM call:
-
-```shell
-npm exec -- skills-opencode agent list --scope global
-npm exec -- skills-opencode agent configure manager --scope global --dry-run
-npm exec -- skills-opencode agent model-set worker --scope global --model openai/gpt-5 --variant high --dry-run
-npm exec -- skills-opencode critic add security --scope global --model anthropic/claude-sonnet-4-6 --dry-run
-npm exec -- skills-opencode agent reconcile --scope global --dry-run
-```
-
-Fixed roles сохраняют имена, prompts и permissions; меняются только model и
-variant. Additional critics используют `critic-<safe-suffix>`. Каждая mutation
-использует тот же contract preview и one-time confirmation.
-
-## Uninstall
-
-Package должен оставаться доступным до удаления его assets:
-
-1. Покажите preview и подтвердите удаление package-owned assets.
-2. Удалите `@kisev/skills-opencode` из user-owned массива `plugin`.
-3. Удалите dependency из того же npm project.
-4. Перезапустите OpenCode.
-
-```shell
-npm exec -- skills-opencode uninstall --scope project --dry-run
-npm exec -- skills-opencode uninstall --scope project --confirm <digest>
-npm uninstall @kisev/skills-opencode
-```
+- [Полная инструкция по интеграции OpenCode](https://github.com/kisev/skills/blob/main/docs/ru/how-to/opencode-integration.md)
+- [Инструкция по portable skills](https://github.com/kisev/skills/blob/main/docs/ru/how-to/portable-skills.md)
+- [Индекс документации](https://github.com/kisev/skills/blob/main/docs/ru/README.md)
 
-Для global scope выполните тот же flow из `~/.config/opencode` с
-`--scope global`. Uninstall архивирует exact manifest-owned assets и сохраняет
-modified files как conflicts вместе с worktrees, runtime state и retained
-profile configuration. Он не удаляет portable skills и не меняет
-`opencode.json`. Команд restore или purge для archive нет.
-
-## Границы
-
-- Portable skills и package assets устанавливаются, обновляются и удаляются
-  независимо.
-- Commands, соответствующие skills, являются thin adapters; portable skill
-  остаётся authoritative и устанавливается отдельно.
-- Package tools: `capabilities`, `route`, `doctor`, `agent_profiles`, `reconcile`;
-  у `route` нет slash command.
-- Installer владеет только files с доказанными manifests и exact hashes.
-- Package распространяется по лицензии MIT. Текущий inventory и checks описаны в
-  [инвентаре миграции](../../docs/ru/migration-inventory.md) и
-  [документе проверки](../../docs/ru/verification.md).
+Полная инструкция описывает global installation, выбор assets, confirmation,
+activation, doctor, update, reconcile, agent profiles, ownership и uninstall.

package/dist/agent-profiles.js

@@ -1,11 +1,11 @@
 import { execFile } from "node:child_process";
-import { readFileSync } from "node:fs";
 import { lstat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { promisify } from "node:util";
 import { fileURLToPath } from "node:url";
 import { applyTransaction, consumeReceipt, deploymentRoot, destination, digest, LifecycleError, lifecycleRoot, listDirectRegular, readRegular, recoverTransaction, saveReceipt, sha256, stable, withLifecycleLock, } from "./lifecycle.js";
+import { readPackageVersion } from "./package-metadata.js";
 export const FIXED_AGENT_ROLES = [
     "manager",
     "architect",
@@ -36,10 +36,10 @@ const V1_AGENT_SHA256 = {
     worker: "eee1163111b59856cc95c8be4ef4bc85a12e23c05bf576ece9f8e6a933b5466d",
 };
 function packageVersion() {
-    const value = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
-    if (typeof value.version !== "string")
+    const version = readPackageVersion();
+    if (!version)
         throw new AgentProfileError("invalid_package", "Package version is unavailable");
-    return value.version;
+    return version;
 }
 function emptyConfig() {
     return {

package/dist/catalog.d.ts

@@ -4,5 +4,5 @@ export declare const CATALOG: {
     readonly agents: readonly ["manager", "architect", "mapper", "worker", "review", "critic"];
     readonly package_commands: readonly ["capabilities", "doctor", "reconcile", "agent-profiles"];
     readonly tools: readonly ["capabilities", "route", "doctor", "agent_profiles", "reconcile"];
-    readonly version: "2.2.3";
+    readonly version: string;
 };

package/dist/catalog.js

@@ -1,3 +1,4 @@
+import { requirePackageVersion } from "./package-metadata.js";
 export const CATALOG = {
     skills: [
         "agents-md",
@@ -34,5 +35,5 @@ export const CATALOG = {
     agents: ["manager", "architect", "mapper", "worker", "review", "critic"],
     package_commands: ["capabilities", "doctor", "reconcile", "agent-profiles"],
     tools: ["capabilities", "route", "doctor", "agent_profiles", "reconcile"],
-    version: "2.2.3",
+    version: requirePackageVersion(),
 };

package/dist/cli-output.js

@@ -1,3 +1,4 @@
+import { CATALOG } from "./catalog.js";
 const GROUPS = ["Agents", "Commands", "Plugins", "State"];
 const OPERATIONS = [
     "create",
@@ -164,7 +165,7 @@ export function renderInventory(inventory) {
     ].join("\n")}\n`;
 }
 export function shellCommand(arguments_) {
-    return ["npm", "exec", "--", "skills-opencode", ...arguments_]
+    return ["npx", "--yes", `@kisev/skills-opencode@${CATALOG.version}`, ...arguments_]
         .map((value) => /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`)
         .join(" ");
 }
@@ -215,10 +216,10 @@ export function renderDoctor(report) {
     const actionable = report.checks.filter((item) => item.status === "fail" || item.status === "warn");
     const next = new Set(actionable.flatMap((item) => item.remediation ?? []));
     if (report.conflicts.length) {
-        next.add(`npm exec -- skills-opencode reconcile --scope ${report.scope} --dry-run`);
+        next.add(shellCommand(["reconcile", "--scope", report.scope, "--dry-run"]));
     }
     if (actionable.some((item) => item.id.startsWith("assets."))) {
-        next.add(`npm exec -- skills-opencode install --scope ${report.scope} --dry-run`);
+        next.add(shellCommand(["install", "--scope", report.scope, "--dry-run"]));
     }
     const lines = [
         `Doctor TLDR: ${report.status} (${report.scope})`,