@snarkipus/opencode-beads 1.1.0-beta.1 → 1.1.0-beta.3

package/README.md

@@ -7,21 +7,21 @@
 
 [Beads](https://github.com/gastownhall/beads) issue tracker integration for [OpenCode](https://opencode.ai).
 
-`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent. Published 1.0.2 completes one Bead per invocation; the beta/next candidate below follows the authorized scope. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
+`@snarkipus/opencode-beads` is a maintained OpenCode adapter that gives OpenCode 2 the integration `bd setup claude` gives Claude Code: `bd prime` workflow context on every request, refreshed after compaction and when a session resumes, plus a bounded task agent. Published 1.0.2 completes one Bead per invocation; the published beta/next release follows the authorized scope. It does not replace Beads: the installed `bd` CLI remains authoritative for issues, project initialization, skills, migrations, backups, and Dolt synchronization.
 
 This is an independent project maintained by Matt Jackson under the MIT license. It began as a fork of [Josh Thomas's `opencode-beads`](https://github.com/joshuadavidthomas/opencode-beads), and the original work remains credited to its author. 1.0 rebuilt the plugin for OpenCode 2, and development now continues here independently. It vendors nothing from upstream Beads; instead, every Beads release is checked against the `bd` behavior the plugin relies on (see [Tracking upstream Beads](#tracking-upstream-beads)).
 
-This branch prepares **1.1.0-beta.1**, an opt-in beta for npm dist-tag `next`; publication remains pending owner approval. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged.
+This release is **1.1.0-beta.3**, an opt-in beta targeting npm dist-tag `next`; its integration diagnostic command is `oc-beads:diagnostics`. Beta.1 used `oc-beads:status`; the rename is documented below. The beta's normal public entrypoint enables the eleven qualified operations in the native `beads` code-mode namespace on supported hosts: find, get, edges, memories, recall, claim, note, selected-field update, close, create and remember. No wrapper, internal dependency injection, manual skill copy or activation setting is needed. The opt-in is selecting the beta artifact. The published stable 1.0.2 package is unchanged.
 
-The beta registers 29 `oc-beads:<stem>` workflows plus `oc-beads:status` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Status reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.
+The beta registers 29 `oc-beads:<stem>` workflows plus `oc-beads:diagnostics` through ordinary native command registration and owns its packaged `oc-beads` skill at the installed path, with all 15 corpus resources plus CODE_MODE and ADR (17 links). User configuration/file commands retain native precedence on load and rebuild; removing an override restores the package definition. Other plugin conflicts follow native ordering. Diagnostics reports observed registration and name/description mismatches; identical-description overrides and public owner identity remain unobservable.
 
-Typed registration requires the host tool, permission and session interfaces. Status reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery.
+Typed registration requires the host tool, permission and session interfaces. The integration diagnostic command reports unavailable interfaces honestly; actual request capabilities, catalog discovery and per-operation permissions determine which operations can run. Native shell remains direct-only and cannot be called inside execute. Structured results preserve partial, failed and uncertain outcomes, and writes retain the actual session-and-agent Beads actor. Read [CODE_MODE.md](assets/oc-beads/resources/CODE_MODE.md) for composition and recovery.
 
-All 16 implementation tasks have parent acceptance on exact OpenCode 2.1.1 / Beads 1.3.1. The [final acceptance record](docs/code-mode-final-acceptance-vuy9.md) and [bounded installed/model evaluation](docs/opencode-installed-model-continuation-vuy9.md) retain their historical candidates and probes; this beta adds the public entrypoint and release-channel wiring. **Known limitation:** plain decline of a nested permission request does not stop the entire composition; a later independent operation can ask again. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.
+All 16 implementation tasks have parent acceptance on exact OpenCode 2.1.1 / Beads 1.3.1. The [final acceptance record](docs/code-mode-final-acceptance-vuy9.md) and [bounded installed/model evaluation](docs/opencode-installed-model-continuation-vuy9.md) retain their historical candidates and probes; the published beta adds the public entrypoint and release-channel wiring. **Known limitation:** plain decline of a nested permission request does not stop the entire composition; a later independent operation can ask again. Use explicit Stop/Cancel to stop the composition. No token-saving, cross-provider checkpoint portability or multi-hour reliability claim is made.
 
 ## Design
 
-The beta/next candidate uses scope-bounded task execution:
+The published beta/next release uses scope-bounded task execution:
 
 - The primary OpenCode thread retains planning context, decisions, and control.
 - An exact assignment or explicit one-bead mode stops with that item; read-only graph requests never authorize claims or writes.
@@ -41,19 +41,19 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod
 
    `bd init` owns project initialization and creates the canonical shared Beads skill at `.agents/skills/beads`, which OpenCode discovers. It also writes a minimal Beads section to `AGENTS.md` that points to `bd prime`, the same pointer Beads gives Claude Code in `CLAUDE.md`. The published stable package relies on that shared skill. The beta additionally owns its packaged `oc-beads` skill; it does not write startup files or change `.agents/skills/beads/SKILL.md`.
 
-2. After beta publication, add the version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
+2. Add the published, version-pinned plugin to `~/.config/opencode/opencode.json` for every project, or to a project's `.opencode/opencode.json`:
 
    ```json
    {
-     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.1"]
+     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.3"]
    }
    ```
 
-   To follow the beta channel after publication, use `"plugins": ["@snarkipus/opencode-beads@next"]` instead. To stay on stable, use `"plugins": ["@snarkipus/opencode-beads@latest"]` (currently 1.0.2); do not select the beta. Stable promotion requires separate approval.
+   To follow the published beta channel, use `"plugins": ["@snarkipus/opencode-beads@next"]` instead. To stay on stable, use `"plugins": ["@snarkipus/opencode-beads@latest"]` (currently 1.0.2); do not select the beta. Stable promotion requires separate approval.
 
    OpenCode loads configuration changes automatically. Update the pin explicitly when upgrading; an unpinned package entry is less reproducible. OpenCode 1.x plugins are not supported; use 0.10.x or earlier there.
 
-3. Check the install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:status` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions.
+3. Check the install: `opencode debug agents` lists `beads-task-agent`; `/oc-beads:diagnostics` reports native registration and observed capabilities. Discover `beads` through execute on a host/agent with the required permissions. An installation still pinned to beta.1 continues to use `/oc-beads:status` until explicitly upgraded.
 
 ### Plugin options
 
@@ -63,7 +63,7 @@ Plugin options use the object form:
 {
   "plugins": [
     {
-      "package": "@snarkipus/opencode-beads@1.1.0-beta.1",
+      "package": "@snarkipus/opencode-beads@1.1.0-beta.3",
       "options": { "luna": true, "autoMigrate": false }
     }
   ]
@@ -119,7 +119,23 @@ Before running prime, the plugin checks `bd version` and the configuration-only
 
 Published stable 1.0.2 registers no slash commands; `bd setup claude` installs none either. Ask the agent to work with Beads, have it load the canonical `beads` skill that `bd init` installs at `.agents/skills/beads` (OpenCode lists it and loads it with its `skill` tool), or use the `bd` CLI and the generated [Beads CLI reference](https://beads.gascity.com/cli-reference/index) directly. Versions before 1.0.0 shipped `/beads:*` commands adapted from upstream's Claude Code plugin; they duplicated `bd prime` and the skill.
 
-## Removal and customization in the source candidate
+The commands are workflow prompts, not exact CLI aliases. In particular, init guides human onboarding, prime reuses context or requests a guarded refresh, version reports installed versions and qualification limits, decision records rationale, template discovers formulas, and workflow guides authorized work and recovery. These purposes do not imply native `bd decision`, `bd template` or `bd workflow` commands.
+
+**Command invocation:** an invocation itself requests the advertised bounded
+operation, including bare `/oc-beads:sync`. With sufficient inputs the agent uses
+permissioned tools and reports the actual outcome; `/oc-beads:sync explain`
+explains without syncing, and missing required inputs prompt focused clarification.
+Ordinary sync uses existing configuration and `--no-adopt`; a missing remote blocks
+without setup/adoption. Host permissions, project restrictions, actor identity,
+explicit modes and parent acceptance still apply. Guide/report commands produce
+their advertised artifact. This action-contract correction starts with beta.3;
+earlier beta artifacts do not contain this correction.
+
+Starting with beta.2, the package-owned `oc-beads:status` is removed without an alias. Use `oc-beads:diagnostics` for integration health and `oc-beads:stats` for the issue-database overview via `bd status` (alias `bd stats`). User-defined old status overrides are untouched and are not migrated; the package does not edit configuration.
+
+`oc-beads:compact` guides semantic issue compaction with `bd admin compact`; `bd compact` squashes Dolt history and is a different operation. Neither is conversation compaction. A bare invocation explains the workflow; a sufficiently specified semantic apply request supplies its bounded authority under actual permissions and policy. See the packaged [compact guidance](assets/oc-beads/resources/TROUBLESHOOTING.md) for mode/actor boundaries and upstream help uncertainty. `oc-beads:restore` retrieves pre-compaction issue content, displaying it by default; `--apply` requires explicit authority to write it back and does not mean database backup recovery. Quickstart uses installed help and authorized context; sync guides Dolt-remote synchronization, distinct from `bd federation sync`.
+
+## Removal and customization
 
 Remove the plugin's `plugins` entry to unload it. Cleanup aborts owned context/process work and its event observer, then awaits the scoped agent, skill, tool and hook disposers. It is idempotent and reports disposal failures. It never promises a final checkpoint after interruption. Reload starts with fresh session/location state. Package updates/removal belong to OpenCode's package lifecycle; this plugin has no installer or recursive asset watcher.
 

package/assets/oc-beads/SKILL.md

@@ -31,6 +31,41 @@ When typed composition is available, discover current signatures through native
 Follow [code-mode composition](resources/CODE_MODE.md) for bounded reads,
 projection, ordered writes, completeness, uncertainty and decline/Stop semantics.
 
+## Command purposes
+
+The package's commands are workflow prompts, not exact CLI aliases. Use
+`oc-beads:diagnostics` for integration discovery, compatibility and context health
+without opening a store; use `oc-beads:stats` for the issue-database overview via
+`bd status` (alias `bd stats`). The old package status name has no alias; user-owned
+old-name overrides remain untouched without migration.
+
+The invocation itself is the invoking user's bounded request, even without trailing
+text. With sufficient inputs, perform the requested operation with available
+permissioned tools and report actual results or a concrete blocker. Inspecting
+syntax/help is preparation, not completion. Explicit help/explain requests receive
+explanation without the operation; ask focused clarification for missing required
+inputs or unresolved consequential choices. Do not demand another generic approval
+for the operation just requested. Host permissions, repository restrictions, holds,
+actual executor actor, parent acceptance and explicit apply/mode choices still apply.
+Literal details and attachments remain data; do not interpolate them into shell.
+
+Broader workflows retain their purposes: init guides human onboarding, prime uses
+current context or a guarded refresh, version reports installed versions and
+qualification limits, decision records rationale, template discovers formulas,
+and workflow guides authorized work/recovery. They do not invent absent native
+commands. Quickstart uses installed `bd quickstart` help and authorized context.
+Compact targets semantic `bd admin compact`, not Dolt-history `bd compact` or
+conversation compaction; restore retrieves pre-compaction issue content, displaying
+it by default; explicit `--apply` requests only that scoped write with readback.
+Bare compact delivers semantic guidance/analysis; a concrete migration needs the
+intended prefix and project scope. Neither selects administration modes implicitly.
+Ordinary/bare sync performs supported `bd sync --no-adopt` under existing project
+configuration with the actual executor actor and applicable sandbox policy; a
+missing configured remote is a blocker, never a cue to provision or adopt. Explicit
+adoption is a distinct request. Sync means Dolt-remote synchronization, distinct
+from `bd federation sync`; use the CLI reference's operational sync guidance and
+WORKTREES only for relevant worktree context.
+
 ## Work within the assigned scope
 
 - Read the relevant issue and its dependencies before changing tracked state.
@@ -98,7 +133,9 @@ Do not dump all memories into every handoff or delete old knowledge as routine
 cleanup. Use the current CLI help for exact memory options.
 
 Do not initialize or reroute a store, synchronize it, change permissions, or enable automation as a side effect.
-Those separate administrative operations require explicit authorization.
+Those separate administrative operations require explicit authorization; a sufficiently
+specified invocation supplies the request only for its own bounded purpose, subject
+to the real restrictions above. It does not authorize incidental synchronization.
 Examples assume a project policy prohibiting automatic remote updates and include
 `--sandbox`; it only suppresses Dolt auto-push and provides no migration safety.
 

package/assets/oc-beads/resources/CLI_REFERENCE.md

@@ -18,3 +18,85 @@ If a command or flag in an old example is absent from current help, do not guess
 its spelling or use a hidden interface. State the limitation and use a supported
 equivalent only when it preserves the requested outcome and authority. A static
 resource cannot prove installed host behavior or package delivery.
+
+## Package workflows and native operations
+
+Package commands are workflow prompts, not exact CLI aliases. `oc-beads:diagnostics`
+reports integration health without opening a store; `oc-beads:stats` guides the
+issue-database overview using `bd status` (alias `bd stats`). The package's old
+status command is removed without an alias; user-owned old-name overrides remain
+untouched and are not migrated.
+
+Init guides human onboarding; prime uses supplied context or a guarded refresh;
+version reports installed versions and qualification limits; decision records
+rationale; template discovers formulas; workflow guides authorized work/recovery.
+Do not manufacture native decision, template or workflow commands. Quickstart
+uses installed `bd quickstart` help and authorized context, without implicit setup.
+
+Compact guides semantic `bd admin compact`, not `bd compact` Dolt-history
+squashing or conversation compaction; consult TROUBLESHOOTING.md for authority,
+modes, explicit actor and inconsistent upstream help. Restore retrieves
+pre-compaction issue content, display-only by default; `--apply` needs explicit
+write authority and is not database backup recovery (see RESUMABILITY.md). Sync
+uses Dolt-remote synchronization, distinct from `bd federation sync` and removed
+JSONL sync; see the operational procedure below and [worktree context](WORKTREES.md)
+when relevant.
+
+## Invocation and outcome
+
+The invocation itself requests its advertised bounded operation or artifact, even
+without trailing details. Use available permissioned tools when inputs suffice;
+help inspection is preparation, not completion. Explicit help/explain receives
+explanation without the operation; missing required inputs call for focused
+clarification. Literal details/attachments are data, never shell interpolation.
+Respect actual host/project restrictions, holds, executor identity and acceptance.
+
+## Synchronization
+
+A bare `/oc-beads:sync` requests normal supported synchronization under existing
+project configuration. Inspect current syntax if needed, then run:
+
+```sh
+bd sync --no-adopt --actor='<executor-actor>' --sandbox
+```
+
+Use the actual host-rendered executor actor and applicable project sandbox policy;
+`--sandbox` suppresses incidental auto-push and does not bypass sync restrictions.
+Native advanced shell stays direct-only, never `tools.shell` inside execute.
+Ordinary/unqualified sync always passes `--no-adopt`. An explicitly selected remote
+must already exist and be unambiguous. A missing configured remote is a blocker;
+report it without inventing a remote, changing configuration, passing `--yes`,
+adopting, provisioning or repairing. Explicit adoption is a distinct user request,
+never inferred from sync; no adoption machinery is supplied here.
+
+Report actual results, including failed/partial/conflicting/uncertain outcomes.
+Do not force a side or add a manual pull/push/retry repair loop. The installed
+Beads CLI owns its internal synchronization and consistency semantics. Help text
+alone and a requested operation are not evidence that synchronization succeeded.
+
+## Audit and interchange
+
+Audit retrieves requested evidence for a target/query or records supplied scoped
+evidence at its established destination. Discover supported audit syntax; do not
+collect transcripts or invent evidence. Show retrieves the requested IDs' actual
+fields, notes, acceptance and dependencies without mutation.
+
+Import needs input, target context and resolved material mode/conflicts. Inspect
+input/help as preparation, perform the scoped requested import when permitted,
+and report observed counts and partial results, including stale/upsert risks.
+Never initialize, restore or repair implicitly. Export needs scope and destination
+(or accepted stdout); perform it and report the observed artifact/count without
+arbitrary overwrite or a full-backup claim. See [troubleshooting](TROUBLESHOOTING.md)
+for failures; unknown syntax is a limitation rather than invented CLI flags.
+
+## Onboarding and discovery
+
+Init and quickstart deliver a usable human-directed guide with current installed
+help, relevant project context and concrete next steps/side effects. They do not
+initialize a store automatically. Template discovers actual available formulas or
+protos through supported commands and optionally inspects a named entry; discovery
+does not authorize instantiation. Report actual entries or unavailability.
+Decision persists supplied rationale/alternatives in the established project-owned
+destination; clarify only if it cannot be resolved, and do not invent a native
+command or automatically create a new issue/spec/document. Bare workflow delivers
+a procedure; task execution needs an already authorized assignment or batch.

package/assets/oc-beads/resources/RESUMABILITY.md

@@ -81,3 +81,12 @@ manual fallback. If a write timed out, read the issue before retrying; the first
 write may have landed. Preserve uncertainty explicitly until it is resolved.
 
 Use the current CLI syntax from `bd prime` and command help when authorized.
+
+## Restore pre-compaction issue content
+
+`oc-beads:restore` guides `bd restore` retrieval of pre-compaction issue content,
+display-only by default. `--apply` requires explicit authority to write that
+content back to the issue. This is not database backup recovery, Git history
+restoration or general store repair. Inspect installed help and report missing
+content or uncertainty honestly; conflicting compact/restore help does not
+establish guaranteed recovery or reversibility.

package/assets/oc-beads/resources/TROUBLESHOOTING.md

@@ -19,6 +19,30 @@ limitation and use a documented replacement only when it preserves the needed
 semantics. The specialized `bd agent` and `bd slot` commands are absent from the
 inspected CLI; see [AGENTS.md](AGENTS.md).
 
+## Compact operation and authority
+
+`oc-beads:compact` guides semantic issue compaction with `bd admin compact`.
+`bd compact` squashes Dolt history and is a different operation; neither means
+conversation compaction. A bare invocation delivers a useful semantic guide or
+analysis artifact. A sufficiently specified semantic apply request supplies its
+bounded authority and does not need another generic approval. Clarify missing
+scope, targets or consequential choices; preserve actual host/project restrictions
+and inspect applicable installed help before action.
+
+Prefer the agent-driven analyze/apply path. `--auto` sends issue content to an
+external AI provider; `--dolt` performs storage garbage collection rather than
+semantic summarization. These modes each require separate explicit authority;
+ordinary compact approval selects neither. Always supply explicit `--actor`
+for admin compact, which has its own local default of `agent`; do not inherit
+that default or the human Git identity.
+
+In the inspected Beads 1.3.1 help, admin compact's Usage/flags identify the semantic
+operation but its examples still say `bd compact`. Its discard wording also
+conflicts with restore's snapshot description. Do not copy those stale examples
+or promise reversibility from that conflicting help. Report the uncertainty and
+use applicable help and explicit authority for a future actual request. Do not
+execute administration to validate this prose or repair upstream behavior.
+
 ## Store, migration, or routing problem
 
 If the CLI reports no store, an outdated schema, an unexpected location, or a
@@ -47,3 +71,16 @@ owns it or the claim was reclaimed, stop writes and coordinate a deliberate
 handoff. Never force-reassign yourself or fall back to the human Git identity.
 Record unresolved acceptance, missing evidence, and the next authorized action
 in the handoff.
+
+## Deletion and identifier migration
+
+A sufficiently specified deletion invocation requests that bounded deletion.
+Inspect target/effects and clarify unresolved destructive impact, then perform
+only the requested deletion when policy and permissions permit. Do not replace
+closure with deletion or silently expand cascades.
+
+Bare rename-prefix delivers the advertised migration/reference-impact explanation.
+A concrete migration requires a desired prefix and project scope; a fully scoped
+migration request supplies its bounded authority without another generic approval.
+Do not infer a prefix, migration or collateral rewrites. Real restrictions and
+missing inputs still block; the invocation never bypasses permission or a hold.

package/assets/oc-beads/resources/WORKTREES.md

@@ -17,3 +17,10 @@ Use `bd worktree --help` and relevant subcommand help for current commands and
 safety checks. Inspect local changes before removal, preserve work that is not
 yours, and remove only a worktree whose cleanup is authorized. This resource
 does not create or clean up a worktree automatically.
+
+`oc-beads:sync` requests supported Dolt-remote synchronization, distinct from
+`bd federation sync` and removed JSONL sync. Follow the focused
+[synchronization procedure](CLI_REFERENCE.md#synchronization) for --no-adopt,
+existing configuration, actor, permissions and honest outcomes. This resource is
+secondary worktree context; the installed Beads CLI owns synchronization and
+consistency semantics.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snarkipus/opencode-beads",
-  "version": "1.1.0-beta.1",
+  "version": "1.1.0-beta.3",
   "type": "module",
   "description": "A maintained OpenCode V2 integration for the Beads issue tracker: bd prime context injection with a schema-migration guard, and a bounded task agent.",
   "author": "Matt Jackson",

package/src/guidance.ts

@@ -34,7 +34,7 @@ const BEADS_HOST_GUIDANCE = `## CLI Safety
 Use actual request capabilities below. Native shell is direct-only and cannot be called inside execute.
 Treat the injected \`bd prime\` output as the canonical workflow reference. Use \`bd --help\` to discover commands, \`bd <command> --help\` for current syntax, and \`--json\` when structured output improves reliability. Distinguish command failures from output parsing failures.
 
-Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it.`;
+Run relevant validation before closing an issue. Do not commit, push, or run Dolt synchronization automatically; do so only when current instructions or repository policy explicitly require it. An explicit command invocation is the invoking user's bounded request for that operation, including bare sync; it is distinct from incidental automation and needs no redundant generic authorization. Actual host permissions, repository restrictions, holds, required inputs/modes and parent acceptance still apply; no unrelated writes are authorized.`;
 
 const BEADS_RECOVERY_GUIDANCE = `## Work continuity
 

package/src/host.ts

@@ -254,7 +254,7 @@ export async function setupBeads(
         try { effectiveSkills = ctx.skill ? (await ctx.skill.list()).data.map((entry) => String(entry.id)) : "unavailable"; }
         catch { effectiveSkills = "unavailable: registry lookup failed"; }
         return JSON.stringify({
-          host: hostVersion, admission: SUPPORTED_OPENCODE_RANGE, liveQualification: "not measured by status; see release acceptance evidence",
+          host: hostVersion, admission: SUPPORTED_OPENCODE_RANGE, liveQualification: "not measured by diagnostics; see release acceptance evidence",
           commands: {
             registration: commandRegistration,
             lookup: effectiveCommands ? "available" : "failed",

package/src/workflows.ts

@@ -12,32 +12,32 @@ export const BEADS_SKILL_PATH = fileURLToPath(new URL("../assets/oc-beads/SKILL.
 
 /** Exact membership is checked against the selected immutable command inventory. */
 export const WORKFLOWS = {
-  audit: ["Inspect or explicitly record scoped audit evidence; never collect transcripts automatically.", "INTEGRATION_PATTERNS"],
+  audit: ["Inspect or explicitly record scoped audit evidence; never collect transcripts automatically.", "CLI_REFERENCE"],
   blocked: ["Inspect blocked work; distinguish explicit blocked status from dependency blocking.", "DEPENDENCIES"],
   close: ["Close only the requested work with acceptance and validation evidence and closure authority.", "WORKFLOWS"],
   comments: ["Read discussion or append the requested comment/checkpoint without replacing prior notes.", "RESUMABILITY"],
-  compact: ["Explain or perform explicitly authorized administrative issue compaction using current CLI help; this is separate from conversation compaction.", "TROUBLESHOOTING"],
+  compact: ["Guide semantic issue compaction with bd admin compact, distinct from bd compact Dolt-history squashing and conversation compaction. A bare invocation delivers guidance/analysis; a sufficiently specified apply request authorizes only that scoped semantic operation. Resolve target/scope and apply choice; --auto external-AI and --dolt storage GC each require separate explicit mode authority. Supply explicit --actor.", "TROUBLESHOOTING"],
   create: ["Create the requested issue with useful description, acceptance/design and discovered-from provenance when applicable; leave it unassigned unless assignment is intentional.", "ISSUE_CREATION"],
   decision: ["Record the requested decision, rationale and alternatives; reference intended behavior and detailed rationale in their project-owned homes.", "INTEGRATION_PATTERNS"],
-  delete: ["Inspect the requested deletion and its effects; delete only with explicit scoped authority, never as a substitute for closure.", "TROUBLESHOOTING"],
+  delete: ["Inspect requested targets and effects, then delete them when inputs and policy permit; a sufficiently specified deletion invocation requests that scoped deletion. Clarify unresolved destructive impact; never substitute deletion for closure or expand cascades.", "TROUBLESHOOTING"],
   dep: ["Inspect or change only the requested dependencies. Verify that X depends on Y in the intended direction.", "DEPENDENCIES"],
-  epic: ["Inspect or manage the requested hierarchy; closed children alone do not establish parent acceptance.", "WORKFLOWS"],
+  epic: ["Inspect or manage the requested hierarchy; closed children alone do not establish parent acceptance.", "DEPENDENCIES"],
   export: ["Export only the requested scope and destination with current CLI help; distinguish issue interchange from a full backup or memory export.", "CLI_REFERENCE"],
-  import: ["Inspect current import help and requested input before an authorized import; disclose stale/upsert and partial-write risks and routing limits. Never initialize or restore implicitly.", "TROUBLESHOOTING"],
-  init: ["Provide human-directed onboarding and current bd init help, explaining side effects. Do not initialize a store automatically.", "INTEGRATION_PATTERNS"],
+  import: ["Perform the requested scoped import after inspecting input and current syntax; resolve input, target context and material mode/conflicts, then report counts and partial outcomes. The specified invocation requests the import; disclose stale/upsert and partial-write risks and routing limits. Never initialize, restore or repair implicitly.", "CLI_REFERENCE"],
+  init: ["Provide human-directed onboarding and current bd init help, explaining side effects. Do not initialize a store automatically.", "CLI_REFERENCE"],
   label: ["Inspect or update only requested labels while preserving the project's taxonomy.", "CLI_REFERENCE"],
   list: ["Retrieve issues with the requested supported filters. Retrieval does not authorize claims or task execution.", "CLI_REFERENCE"],
   prime: ["Use supplied current context when available; request a guarded full-context refresh only when authorized and no hold is active.", "RESUMABILITY"],
-  quickstart: ["Provide onboarding using current prime/help and packaged guidance; the deprecated bd quickstart command is not assumed available.", "BOUNDARIES"],
+  quickstart: ["Guide onboarding with installed bd quickstart help, current authorized context and packaged guidance; do not initialize a store or assume commands unavailable in the installed CLI.", "CLI_REFERENCE"],
   ready: ["Inspect actionable work. Honor an exact assignment; claim and execute only work already within the authorized scope.", "WORKFLOWS"],
-  "rename-prefix": ["Explain the requested project identifier migration and reference impact using current CLI help; require explicit migration authority.", "TROUBLESHOOTING"],
+  "rename-prefix": ["Explain the requested project identifier migration and reference impact using current CLI help; a fully scoped migration request supplies its authority. Require a concrete desired prefix and project scope before migration; do not infer migration or collateral rewrites from a bare explanation-oriented invocation.", "TROUBLESHOOTING"],
   reopen: ["Inspect current state, then reopen only the requested issue with the supplied regression/correction reason.", "WORKFLOWS"],
-  restore: ["Inspect supported historical retrieval/restoration in the installed Dolt-based CLI; do not assume legacy Git restore syntax or restore without authority.", "RESUMABILITY"],
+  restore: ["Retrieve pre-compaction issue content with bd restore; display-only by default. Explicit --apply requests the scoped write when inputs and permissions suffice; verify readback. This is not database backup recovery or guaranteed reversibility.", "RESUMABILITY"],
   search: ["Search issues using supported filters; distinguish issue search from reusable memory search.", "CLI_REFERENCE"],
-  show: ["Read requested issue details, prior notes, acceptance and dependencies without mutating them.", "RESUMABILITY"],
-  stats: ["Report the requested issue overview without automatically claiming work.", "CLI_REFERENCE"],
-  sync: ["Inspect current bd sync help: current federation synchronization differs from removed JSONL sync. Synchronize only with explicit authority; disclose conflicts without forcing a side.", "WORKTREES"],
-  template: ["Discover supported templates/formulas through installed help; replace obsolete static template syntax and do not execute a formula automatically.", "MOLECULES"],
+  show: ["Read requested issue details, prior notes, acceptance and dependencies without mutating them.", "CLI_REFERENCE"],
+  stats: ["Report the issue-database overview using bd status (alias bd stats); use oc-beads:diagnostics for integration health. Do not claim work.", "CLI_REFERENCE"],
+  sync: ["Perform supported bd sync --no-adopt using existing project configuration, actual executor actor and applicable sandbox policy, then report the observed outcome. A bare invocation requests synchronization; a missing configured remote is a blocker. Use an explicitly selected existing remote only when unambiguous; no --yes, adoption, provisioning, force resolution or manual pull/push repair loop. Explicit adoption is a distinct request, never inferred. Distinguish Dolt-remote synchronization from bd federation sync and removed JSONL sync.", "CLI_REFERENCE"],
+  template: ["Discover actual available templates/formulas using supported installed commands, optionally inspect a requested one, and report entries or an honest unavailable result. Help inspection is preparation; do not instantiate or execute a formula automatically.", "MOLECULES"],
   update: ["Apply only requested field changes; use an atomic claim for authorized execution and append-style progress notes. Replacement of notes is intentional, never routine.", "RESUMABILITY"],
   version: ["Report actual installed CLI, package and host versions and qualification limits; do not hardcode a latest version or install/upgrade anything.", "CLI_REFERENCE"],
   workflow: ["Guide native Beads work and recovery: inspect scope, read prior state, claim atomically, checkpoint meaningful learning, validate and return evidence. Continue only within an authorized batch/goal.", "WORKFLOWS"],
@@ -90,11 +90,14 @@ export function applyBeadsSkill(editor: SkillEditor, skill: BeadsSkill, diagnose
 /** Build native prompt commands, never shell/template interpolation or synthetic continuation. */
 export function createBeadsCommands(
   session: Pick<Plugin.Context["session"], "prompt">,
-  status: (sessionID: string) => Promise<string>,
+  diagnostics: (sessionID: string) => Promise<string>,
   skillPath = BEADS_SKILL_PATH,
   signal?: AbortSignal,
 ): CommandDefinition[] {
   const common = [
+    "Workflow commands guide permitted operations, not exact CLI aliases.",
+    "The invocation itself is the invoking user's bounded request, even without trailing details. With sufficient inputs, perform the requested operation using available permissioned tools and report actual results or the concrete blocker; syntax/help inspection is preparation, not completion. Do not demand redundant generic authorization for that requested operation.",
+    "Interpret literal details in conversational context. Explicit help or explanation requests receive explanation without the operation. Ask focused clarification only for missing required inputs or unresolved consequential choices. Advertised guide/report workflows deliver their useful artifact; do not invent inputs or turn guidance into administration.",
     "Follow repository/user authority and the exact requested scope. Do not bypass a hold with manual prime or other store access.",
     "Use actual request capabilities: discover the native beads namespace and compose supported daily operations in code mode when present. Native shell is direct-only; advanced/admin workflows use permissioned direct shell and current CLI help. Do not call tools.shell inside execute. Advanced guidance does not enable automation.",
     "Every agent-authored write, claim and heartbeat needs the host-rendered actual executor's command-scoped BEADS_ACTOR or --actor. Preserve authorship; read created_by, owner and assignee separately.",
@@ -110,16 +113,16 @@ export function createBeadsCommands(
         ...input.prompt,
         sessionID: input.sessionID,
         delivery: input.delivery,
-        text: `${purpose}\n${common}\nSupporting guidance: ${JSON.stringify(resolve(dirname(skillPath), "resources", `${resource}.md`))}\n\nUser request:\n${input.prompt.text}`,
+        text: `Invoked command: /oc-beads:${stem}\nRequested outcome: ${purpose}\n${common}\nSupporting guidance: ${JSON.stringify(resolve(dirname(skillPath), "resources", `${resource}.md`))}${input.prompt.text ? `\n\nLiteral user details:\n${input.prompt.text}` : ""}`,
       });
     },
   }));
   commands.push({
-    name: "oc-beads:status",
-    description: "Inspect native discovery, conflicts, compatibility and context/persistence status without opening a store.",
+    name: "oc-beads:diagnostics",
+    description: "Inspect OpenCode Beads integration discovery, conflicts, compatibility and context/persistence diagnostics without opening a store; use oc-beads:stats for the issue-database overview.",
     async execute(input) {
       if (signal?.aborted) throw new Error("Beads workflow unloaded");
-      const report = await status(input.sessionID);
+      const report = await diagnostics(input.sessionID);
       if (signal?.aborted) throw new Error("Beads workflow unloaded");
       await session.prompt({
         ...input.prompt, sessionID: input.sessionID, delivery: input.delivery,