npm - @kisev/skills-opencode - Versions diffs - 2.0.2 → 2.0.3 - Mend

@kisev/skills-opencode 2.0.2 → 2.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -2,100 +2,89 @@
 [Русский](README.ru.md)
-`@kisev/skills-opencode` is the optional npm integration. It does not include
-portable skills or mutate configuration on import.
-Managed files use exact SHA-256 ownership checks.
-It provides the capability router, OpenCode runtime, agent-profile management,
-and an opt-in installer for agents, commands, and plugins. It requires Node.js
-22+ and OpenCode 1.18.29+; import, plugin loading, and npm lifecycle do not
-write configuration.
+`@kisev/skills-opencode@2.0.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).
-## Install Skills
+## Requirements and Ownership
-Install portable skills first:
+The package requires Node.js 22+ and OpenCode `>=1.18.29 <1.19.0`.
-```shell
-npx --yes skills add kisev/skills --agent opencode --skill '*' --copy --yes
-```
-Use `--skill <name>` for one skill. `npx skills` accepts a reproducible tag URL,
-for example `https://github.com/kisev/skills/tree/v2.0.0`; the package never
-installs or updates skills and reports the exact `npx skills add` command when a
-skill is missing.
+| 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`                     |
-## Install Integration
+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.
-```shell
-npm install @kisev/skills-opencode@2.0.0
-```
+## Persistent Package Install
-Interactive selection is available only in a TTY. Non-TTY installs require
-explicit `--commands`, `--agents`, and `--plugins` flags; selectable plugins
-default to an empty set. The wizard shows skill commands, package commands,
-fixed agents, and `rules-injector`, `rtk`, `zed-bell`.
+### Project Scope
-Preview before any write:
+Install in the repository's npm project and run the CLI from that project root:
 ```shell
-npm exec -- skills-opencode install --scope global --dry-run
+cd /path/to/project
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope project --dry-run
 ```
-Apply the shown digest only:
+The package remains in project `node_modules`; confirmed assets go under
+`.opencode`.
+### Global Scope
+Use `~/.config/opencode` as the persistent npm project:
 ```shell
-npm exec -- skills-opencode install --scope global --confirm <digest>
+mkdir -p "$HOME/.config/opencode"
+cd "$HOME/.config/opencode"
+test -f package.json || npm init --yes
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope global --dry-run
 ```
-Use `--json` for automation.
-The machine-readable plan includes `requires_restart`; a preview uses `--dry-run`
-and an apply uses `--confirm <digest>` with identical arguments.
+Keep the dependency in that npm project's `package.json` and lock file.
+Confirmed assets go under `~/.config/opencode`.
-`global` manages `.config/opencode/agents`, `.config/opencode/commands`, and
-`.config/opencode/plugins`. Project scope manages `.opencode/agents`,
-`.opencode/commands`, and `.opencode/plugins`. Profile configuration is kept in
-`.config/opencode/.skills-opencode/agent-profiles.json` globally or under
-`.opencode/.skills-opencode` for a project.
-Project assets are limited to the current working directory. Scope is required;
-the installer never changes `opencode.json`, overwrites unknown or modified
-files, or records ownership manifests before confirmed apply. The short preview
-reports changed paths, conflicts, restart status, digest, and its confirm command.
+## Select Assets
-## Read-only Doctor
+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.
-`doctor` reports facts without writing:
+Outside a TTY, pass all three selection groups. This example selects three
+commands, all fixed agents, and no wrapper:
 ```shell
-npm exec -- skills-opencode doctor --scope project
-npm exec -- skills-opencode doctor --scope global --json
+npm exec -- skills-opencode install --scope project \
+  --commands doctor,reconcile,agent-profiles \
+  --agents manager,architect,mapper,worker,review,critic \
+  --plugins none --dry-run
 ```
-It never creates lifecycle state, consumes receipts, recovers journals, starts
-plugins, or starts LSP servers. Its versioned JSON report contains stable check
-IDs, catalog and installed-manifest versions, ownership/drift/collision classes,
-inventory findings, runtime summaries, redacted configuration projections, and
-LSP facts. It never serializes secrets, raw configuration, environment values,
-receipts, or credentials. Exit status `0` is clean, `1` reports findings, and
-`2` means invalid input or an incomplete probe failure.
-## Reconcile Retired Assets
-`reconcile` previews retirement and preserves conflicts:
+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 reconcile --scope project --dry-run
-npm exec -- skills-opencode reconcile --scope project --confirm <digest>
-npm exec -- skills-opencode reconcile --scope global --dry-run --json
+npm exec -- skills-opencode capabilities --json
 ```
-It considers only public portable skills, package commands, plugins, agents, and
-installation metadata for the selected scope. Retired exact-owned files move to
-a private content-addressed XDG archive with an index, never disappear.
-Modified-managed, user-owned, unknown, symlink, unsafe-path, worktree, and
-ambiguous-source entries remain byte-for-byte conflicts. The journaled target and
-archive transaction provides rollback, recovery, and repeatable no-op operation.
-Doctor reports archive entries and conflicts read-only.
+The selectable wrappers are `rules-injector`, `rtk`, and `zed-bell`.
+## Activate the Core Plugin
-Add the plugin manually:
+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:
 ```json
 {
@@ -104,104 +93,129 @@ Add the plugin manually:
 }
 ```
-## Manage Agents
+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
-The direct CLI manages models without LLM calls:
+Every mutation begins with `--dry-run`. The preview reports operations,
+conflicts, restart requirements, receipt expiry, a SHA-256 digest, and the exact
+confirmation command.
 ```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 agent reconcile --scope global --dry-run
+npm exec -- skills-opencode install --scope project --dry-run
 ```
-Fixed roles preserve their names and canonical prompts and permissions; only
-model and variant change. The interactive configuration wizard selects an agent,
-provider, its models, and published variants, showing the current target and
-offering keep, change, clear variant, back, and cancel. It does not invoke an
-LLM, OpenCode Question, or catalog refresh. If the catalog is unavailable it
-does not write and prints the exact model instruction.
+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. Only after this flow is complete,
+update the package and apply its installer plan before running reconcile.
+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.
+## Doctor
-When the catalog is unavailable, use exact `--model <provider/model>` and an
-optional `--variant`; `provider/model` identifies the selected model. The
-optional `agent_profiles` tool and slash commands adapt the same direct-CLI
-plan/apply contract.
+`doctor` reads integration facts without creating receipts, recovering journals,
+starting plugins, or starting LSP servers:
 ```shell
-npm exec -- skills-opencode critic add security --scope global \
-  --model anthropic/claude-sonnet-4-6 --dry-run
-npm exec -- skills-opencode critic remove security --scope global --dry-run
+npm exec -- skills-opencode doctor --scope project
+npm exec -- skills-opencode doctor --scope project --json
 ```
-Additional critics use `critic-<safe-suffix>`; fixed roles and the standard
-critic cannot be renamed or removed. Every mutation uses a one-time private
-receipt valid for 10 minutes, a lifecycle lock, inventory recheck, journaled
-all-or-rollback transaction, and final validation. Interrupted mutations recover
-before requiring a fresh plan. Global profile configuration and its semantic
-deployment manifest are kept together; project scope keeps corresponding files
-under its `.opencode` directory. Package updates do not reset selected models,
-variants, or additional critics.
+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
-## Upgrade and Uninstall
+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 exec -- skills-opencode uninstall --scope global --dry-run
-npm exec -- skills-opencode uninstall --scope global --confirm <digest>
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope project --dry-run
 ```
-The full JSON install preview is:
+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 install --scope global --dry-run --json
+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
 ```
-On upgrade, the installer updates only managed files whose SHA-256 still matches.
-The one-time `1.0.0` migration transfers the six fixed-agent ownership records
-only when package/version, manifest records, and every file hash match exactly.
-Uninstall removes only unchanged manifest-owned files; modified files remain
-conflicts and profile configuration is retained for a later installation.
+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 the pinned `npx --yes skills@1.5.23` flow for those skills.
-## Runtime Options
+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.
-Plugins are independent and selectable ones are opt-in.
+## 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 --json
+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
 ```
-The package exports the core OpenCode plugin and independent factories for
-`rules-injector`, `rtk`, and `zed-bell`. Retired plugin APIs and internal lifecycle
-implementations are not public. Rules injection fails soft within a bounded
-budget; RTK fails open.
+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.
-## Stage 18 Routing
+## Uninstall
-`doit` owns the complete evidence -> plan -> confirmation -> execution -> checks
--> report lifecycle; `manager` only adapts it to OpenCode. The route tool has four
-destinations: exploration to `mapper`, architecture to `architect`, implementation
-to `worker`, and review to `review` or one selected `critic`. Documentation and
-quick work remain in `doit`.
+Keep the package resolvable until its assets are removed:
-The route inventory comes only from resolved host configuration. Callers cannot
-inject agents, capabilities, tools, models, or availability. Versioned receipts,
-cards, and mapper/worker/review/critic reports are checked at real Task dispatch
-and result hooks. Cards bind paths, checks, explicit VCS operations, and separate
-execution, publication, and history-rewrite confirmations.
-## Boundaries
-Portable skills and package assets install independently.
+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 install --scope project --dry-run
-npm exec -- skills-opencode install --scope project --confirm <digest>
+npm exec -- skills-opencode uninstall --scope project --dry-run
+npm exec -- skills-opencode uninstall --scope project --confirm <digest>
+npm uninstall @kisev/skills-opencode
 ```
-Commands are thin adapters that pass untrusted arguments to the native Skill
-tool; validation, confirmation, batch/review rules, and result format remain the
-skill or runner responsibility. `capabilities`, `route`, and `doctor` are package
-tools and commands for catalog, routing, and health. `agent_profiles` and the
-four agent slash commands are optional UX adapters, not a separate skill.
+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
-The package is MIT-licensed; the repository root README has full instructions.
+- 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).

package/README.ru.md CHANGED Viewed

@@ -2,97 +2,158 @@
 [English](README.md) | [Русский](README.ru.md)
-`@kisev/skills-opencode` - npm package с capability router, OpenCode runtime,
-управлением agent profiles и opt-in installer для agents, commands и plugins. Он
-не включает portable skills и не меняет конфигурацию при import, plugin load или
-npm lifecycle. Package требует Node.js 22+ и OpenCode 1.18.29+.
+`@kisev/skills-opencode@2.0.3` - optional OpenCode-specific слой. У portable
+skills отдельный lifecycle: их нужно установить независимо через
+[корневую инструкцию](../../README.ru.md).
-## Установка skills
+## Требования и ownership
-Сначала установите нужные portable skills через `npx skills` из публичного
-репозитория:
+Package требует Node.js 22+ и OpenCode `>=1.18.29 <1.19.0`.
+| 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 и generated wrappers должны оставаться доступными после завершения
+installer. Import, plugin loading и npm lifecycle scripts не устанавливают
+assets или portable skills и не меняют OpenCode configuration.
+## Постоянная установка package
+### Project scope
+Установите package в npm project репозитория и запускайте CLI из его корня:
 ```shell
-npx --yes skills add kisev/skills --agent opencode --skill '*' --copy --yes
+cd /path/to/project
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope project --dry-run
 ```
-Для одного skill укажите `--skill <name>`. Для воспроизводимой установки можно
-передать URL GitHub tag, например
-`https://github.com/kisev/skills/tree/v2.0.0`. Package никогда не устанавливает
-и не обновляет skills. Если команда не нашла skill, она сообщает точную команду
-`npx skills add` для его установки.
+Package остаётся в project `node_modules`, confirmed assets размещаются в
+`.opencode`.
-## Установка integration
+### Global scope
-Установите npm package там, где OpenCode сможет разрешить plugin:
+Используйте `~/.config/opencode` как постоянный npm project:
 ```shell
-npm install @kisev/skills-opencode@2.0.0
+mkdir -p "$HOME/.config/opencode"
+cd "$HOME/.config/opencode"
+test -f package.json || npm init --yes
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope global --dry-run
 ```
-Interactive selection доступен только в TTY. В non-TTY install нужно явно передать
-`--commands`, `--agents` и `--plugins`; selectable plugins по умолчанию пусты.
-Wizard показывает skill commands, package commands, fixed agents и
-`rules-injector`, `rtk`, `zed-bell`. Сначала покажите план installer. CLI выводит короткую сводку:
-счётчики по группам, только изменяемые paths, conflicts, restart flag, digest и
-готовую confirm-команду. Эта команда не меняет deployment:
+Сохраните 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 global --dry-run
+npm exec -- skills-opencode install --scope project \
+  --commands doctor,reconcile,agent-profiles \
+  --agents manager,architect,mapper,worker,review,critic \
+  --plugins none --dry-run
 ```
-Проверьте сводку и примените только показанный digest:
+Если вне TTY передан любой selection flag, обязательны `--commands`, `--agents`
+и `--plugins`. Точные текущие имена показывает команда:
 ```shell
-npm exec -- skills-opencode install --scope global --confirm <digest>
+npm exec -- skills-opencode capabilities --json
 ```
-`global` устанавливает assets в `~/.config/opencode/agents`,
-`~/.config/opencode/commands` и `~/.config/opencode/plugins`. Для текущего
-repository используйте `project`:
+Selectable wrappers: `rules-injector`, `rtk`, `zed-bell`.
+## Активация core plugin
+Installer записывает, нужна ли selection core integration, но никогда не создаёт
+и не меняет `opencode.json`. Добавьте package в user-owned массив `plugin` для
+того же scope, сохранив существующие entries:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@kisev/skills-opencode"]
+}
+```
+Для 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, SHA-256 digest и точную
+confirmation command.
 ```shell
 npm exec -- skills-opencode install --scope project --dry-run
-npm exec -- skills-opencode install --scope project --confirm <digest>
 ```
-Project assets находятся в `.opencode/agents`, `.opencode/commands` и
-`.opencode/plugins` текущего working directory. Scope обязателен. Installer не изменяет `opencode.json`, не
-перезаписывает неизвестные или изменённые files и сохраняет ownership manifests
-только после confirmed apply.
+Обязательный OpenCode flow: persistent npm install, `install --dry-run`, exact
+confirmation command из preview, добавление package в user-owned `plugin` и
+перезапуск OpenCode. Для global-команд используйте persistent npm project в
+`~/.config/opencode`. Только после этого обновите package, примените installer
+plan и запускайте reconcile.
-Для automation добавьте `--json`. Этот режим сохраняет полный стабильный
-machine-readable plan, включая `operations` и `requires_restart`:
+Выполните команду из preview со всеми selection flags. Receipts приватны,
+действуют 10 минут, применяются один раз и связаны с action, scope, root и
+текущим inventory. Apply отклоняет stale state и unsafe conflicts.
+## Doctor
+`doctor` читает integration facts без создания receipts, recovery journals,
+запуска plugins или LSP servers:
 ```shell
-npm exec -- skills-opencode install --scope global --dry-run --json
-npm exec -- skills-opencode agent list --scope global --json
+npm exec -- skills-opencode doctor --scope project
+npm exec -- skills-opencode doctor --scope project --json
 ```
-## Read-only doctor
+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.
-`doctor` is a read-only installer health report. It never creates lifecycle
-state, consumes receipts, recovers journals, starts plugins or starts LSP
-servers. `project` and `global` are isolated scopes; unavailable OpenCode host
-facts are reported as incomplete rather than inferred.
+## Обновление
+В npm project, которому принадлежит dependency, установите точную нужную version,
+покажите и подтвердите `install` с тем же scope и нужной selection, затем
+перезапустите OpenCode:
 ```shell
-npm exec -- skills-opencode doctor --scope project
-npm exec -- skills-opencode doctor --scope global --json
+npm install --save-exact @kisev/skills-opencode@2.0.3
+npm exec -- skills-opencode install --scope project --dry-run
 ```
-The JSON report is versioned and contains stable check IDs, package/catalog and
-installed-manifest versions, ownership/drift/collision classifications, stage-8
-inventory findings, lifecycle/runtime state summaries, redacted config
-projections and LSP facts. Secrets, raw config, environment values, receipts
-and credentials are never serialized. Exit code `0` is clean, `1` reports
-findings, and `2` means invalid input or an incomplete probe failure.
+Используйте полную 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 retired assets
+## Reconcile
-`reconcile` проверяет только public portable skills, package commands, plugins,
-agents и installation metadata выбранного scope. XDG runtime state не читается и
-не изменяется. Preview сохраняет private receipt с TTL и печатает digest:
+`reconcile` классифицирует current и historical portable skills, package
+commands, plugins, agents и installation metadata одного scope:
 ```shell
 npm exec -- skills-opencode reconcile --scope project --dry-run
@@ -100,143 +161,63 @@ npm exec -- skills-opencode reconcile --scope project --confirm <digest>
 npm exec -- skills-opencode reconcile --scope global --dry-run --json
 ```
-Retired files с доказанным inventory ownership и exact SHA-256 перемещаются в
-private content-addressed XDG archive с index, а не удаляются. Modified-managed,
-user-owned, unknown, symlink, unsafe-path, worktree и ambiguous-source entries
-остаются conflicts без изменения bytes. Journal target и archive обеспечивает
-rollback, recovery и повторный no-op reconcile. Doctor показывает archive и
-conflicts read-only.
+Перед reconcile сначала обновите package в принадлежащем ему npm project и
+примените exact installer plan. Reconcile не устанавливает, не обновляет и не
+удаляет portable skills; для них используйте только pinned
+`npx --yes skills@1.5.23` flow.
-Добавьте plugin в `opencode.json` вручную:
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["@kisev/skills-opencode"]
-}
-```
-Полностью перезапустите OpenCode после install, upgrade или uninstall: registry
-agents и commands строится до plugin hooks.
+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
-Рекомендуемый интерфейс - прямой terminal CLI: он не вызывает LLM и не расходует
-токены. Fixed roles `manager`, `architect`, `mapper`, `worker`, `review` и
-стандартный `critic` всегда сохраняют имена и canonical prompts/permissions.
-Меняются только `model` и `variant`:
+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 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
 ```
-`agent configure` предлагает настоящий terminal wizard: стрелками выбираются
-agent из inventory, затем provider, только его models и, если metadata выбранной
-модели публикует variants, variant. Текущие model/variant и target показываются
-перед выбором; доступны `keep`, `change`, `clear variant`, `back` и `cancel`.
-Wizard не вызывает LLM, OpenCode Question или refresh catalog. Если catalog
-недоступен, он завершается без записи и печатает инструкцию для exact
-`--model <provider/model>` с optional `--variant`. Для модели без variants
-дополнительный selector не показывается.
+Fixed roles сохраняют имена, prompts и permissions; меняются только model и
+variant. Additional critics используют `critic-<safe-suffix>`. Каждая mutation
+использует тот же contract preview и one-time confirmation.
-Additional critic имеет имя `critic-<safe-suffix>`. Стандартный `critic` и fixed
-roles нельзя удалить или переименовать:
+## Uninstall
-```shell
-npm exec -- skills-opencode critic add security --scope global \
-  --model anthropic/claude-sonnet-4-6 --dry-run
-npm exec -- skills-opencode critic remove security --scope global --dry-run
-```
+Package должен оставаться доступным до удаления его assets:
-Для любой mutation используйте готовую confirm-команду из preview либо замените
-`--dry-run` на `--confirm <digest>` и повторите те же аргументы. Человекочитаемый
-plan не печатает полный JSON и сворачивает длинные группы paths. Digest связан с
-одноразовым private receipt, действует 10 минут и повторно не применяется. Для
-machine-readable result добавьте `--json`; поле `requires_restart` сообщает о
-необходимости полностью перезапустить OpenCode.
-В global scope profile configuration хранится в
-`~/.config/opencode/.skills-opencode/agent-profiles.json`, а semantic deployment
-manifest - рядом в `agent-profiles.manifest.json`. Для project scope те же файлы
-находятся под `.opencode/.skills-opencode/`. Configuration хранит выбранные
-model/variant и additional critics; package update её не сбрасывает. Manifest
-хранит package version, exact critic pool и hashes canonical configuration и
-rendered files.
-Inventory различает `package-owned`, `managed`, `user-owned`, `drift` и exact-name
-`collision`. User-owned и неизвестные agents не изменяются. Collision блокирует
-apply; drift исправляется только явным `agent reconcile`. Все mutations проходят
-под lifecycle lock, повторно проверяют inventory, используют journaled
-all-or-rollback transaction и выполняют final validation. После прерывания
-следующая mutation безопасно восстанавливает before-images и требует свежий plan.
-## Upgrade и uninstall
-После обновления npm package снова выполните dry-run и подтвердите новый digest.
-Installer обновляет только files с совпадающим managed SHA-256.
-При первом upgrade с `1.0.0` installer передаёт ownership шести fixed agents из
-generic manifest в profile domain только при точном совпадении package/version,
-manifest records и SHA-256 каждого файла. Любое отличие остаётся конфликтом.
-Commands и plugins продолжают принадлежать generic installer. Uninstall удаляет
-неизменённые deployments, но сохраняет profile configuration для последующей
-установки.
+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 global --dry-run
-npm exec -- skills-opencode uninstall --scope global --confirm <digest>
+npm exec -- skills-opencode uninstall --scope project --dry-run
+npm exec -- skills-opencode uninstall --scope project --confirm <digest>
+npm uninstall @kisev/skills-opencode
 ```
-Uninstall удаляет только files из ownership manifest, если их SHA-256 не
-изменился. Изменённые пользователем files остаются как `conflict`.
-## Runtime options
-Package экспортирует core OpenCode plugin и independent plugin factories
-`rules-injector`, `rtk`, `zed-bell`. Retired plugin APIs и internal lifecycle
-implementations public surface не входят:
-Background Attempts создают workspace только через единый managed worktree
-owner. Records используют private current-only state, marker и repository
-fingerprint; release перепроверяет регистрацию, fingerprint и чистый status и
-возвращает `blocked` без удаления при расхождении. Scheduler принимает строгий
-five-field cron, не воспроизводит missed slots и пишет receipts `started`,
-`completed`, `failed` или `overrun`.
-`rules-injector` fail-soft применяет ограниченный budget и пропускает native
-project/global rules. `rtk` fail-open сжимает большой bash output и добавляет
-подсказку для edit error, но не содержит ownership guard.
-## Routing этапа 18
-`doit` владеет полным lifecycle evidence -> plan -> confirmation -> execution ->
-checks -> report; `manager` только адаптирует его к OpenCode. Tool `route` имеет
-четыре назначения: exploration -> `mapper`, architecture -> `architect`,
-implementation -> `worker`, review -> `review` или один `critic`. Documentation и
-quick остаются у `doit`.
-Inventory берётся только из resolved host config. Caller не может подменить agents,
-capabilities, tools, models или availability. Versioned receipts, cards и
-mapper/worker/review/critic reports проверяются на реальных Task dispatch/result
-hooks. Card связывает paths, checks, явные VCS operations и отдельные confirmations
-для execution, publication и history rewrite.
+Для 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 в корне `skills/` универсальны и устанавливаются только через
-`npx skills`. Этот package поставляет только OpenCode-specific assets и runtime
-router. Команды - тонкие adapters: передают `$ARGUMENTS` как недоверенный ввод
-в native Skill tool, а target validation, confirmation, batch/review rules и
-формат результата остаются ответственностью skill или runner.
-`capabilities`, `route` и `doctor` - package tools/commands для catalog, routing и
-health. Tool `doctor` and direct CLI share one read-only facts API; `/doctor` is
-only a thin adapter. Tool `agent_profiles` и четыре slash-команды `agent-list`,
-`agent-model-set`, `critic-add`, `critic-remove` - optional thin UX над теми же
-plan/apply contracts. Отдельного skill `agent-profiles` нет.
-Package распространяется по лицензии MIT. Полные инструкции по portable skills,
-upgrade и security boundaries находятся в корневом README репозитория.
+- 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).

package/dist/catalog.d.ts CHANGED Viewed

@@ -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.0.2";
+    readonly version: "2.0.3";
 };

package/dist/catalog.js CHANGED Viewed

@@ -34,5 +34,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.0.2",
+    version: "2.0.3",
 };

package/dist/cli-output.js CHANGED Viewed

@@ -179,15 +179,24 @@ export function renderReconcile(plan, options) {
     if (plan.retired.length)
         lines.push("", "Retired:", ...plan.retired.slice(0, 20).map((entry) => `  ${terminalSafe(entry.path)}`));
     if (plan.conflicts.length)
-        lines.push("", "Conflicts:", ...plan.conflicts
-            .slice(0, 20)
-            .map((entry) => `  ${terminalSafe(entry.path)} (${terminalSafe(entry.reason)})`));
+        lines.push("", "Conflicts:", ...plan.conflicts.map((entry) => `  ${terminalSafe(entry.path)} (${terminalSafe(entry.reason)})`));
+    if (plan.modified_managed.length)
+        lines.push("", "Modified managed:", ...plan.modified_managed.map((entry) => `  ${terminalSafe(entry.path)} (${terminalSafe(entry.reason)})`));
     if (!options.applied) {
         lines.push("", `Digest: ${plan.digest}`);
         if (plan.receipt_expires_at)
             lines.push(`Confirmation expires: ${plan.receipt_expires_at}`);
-        if (options.confirmationCommand)
+        const blocked = plan.modified_managed.length > 0 || plan.conflicts.length > 0;
+        if (blocked) {
+            lines.push("", "Blocked:");
+            if (plan.modified_managed.length)
+                lines.push(`  Update managed assets first: ${shellCommand(["install", "--scope", plan.scope, "--dry-run"])}`, "  Apply the exact confirmation command from that installer preview, then build a new reconcile preview.");
+            if (plan.conflicts.length)
+                lines.push("  Manually resolve every ownership conflict listed above before reconciling.");
+        }
+        else if (options.confirmationCommand) {
             lines.push("", "Apply:", `  ${options.confirmationCommand}`);
+        }
     }
     return `${lines.join("\n")}\n`;
 }

package/dist/cli.js CHANGED Viewed

@@ -100,6 +100,14 @@ function help() {
 async function interactiveInstallerSelection() {
     if (!process.stdin.isTTY || !process.stderr.isTTY)
         throw new InstallerError("terminal_required", "install requires explicit selection flags outside a terminal");
+    process.stderr.write([
+        "Portable skills are installed separately through npx skills.",
+        "This installer does not install, update, or remove portable skills.",
+        "Skill command adapters are OpenCode slash commands that load an already-installed skill with the same name.",
+        "Package command adapters invoke package tools.",
+        "Selecting a command adapter does not select or install its skill.",
+        "\n",
+    ].join("\n"));
     const group = async (label, names, initial) => {
         const choices = ["Select all", "Select none", ...names];
         const selected = await selectOption(label, choices, process.stdin, process.stderr, initial);
@@ -112,8 +120,8 @@ async function interactiveInstallerSelection() {
         return [names[selected - 2]];
     };
     const commands = [
-        ...(await group("Skill commands", SKILL_COMMANDS, 0)),
-        ...(await group("Package commands", PACKAGE_COMMANDS, 0)),
+        ...(await group("Skill command adapters", SKILL_COMMANDS, 0)),
+        ...(await group("Package command adapters", PACKAGE_COMMANDS, 0)),
     ];
     const agents = await group("Fixed agents", defaultSelection().agents, 0);
     const plugins = await group("Selectable plugins (none selected by default)", SELECTABLE_PLUGINS, 1);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@kisev/skills-opencode",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "OpenCode integration and opt-in installer for portable Agent Skills.",
   "license": "MIT",
   "repository": {