@snarkipus/opencode-beads 1.1.0-beta.2 → 1.1.0-beta.4

package/README.md

@@ -11,9 +11,9 @@
 
 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 release is **1.1.0-beta.2**, 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.
+This release is **1.1.0-beta.4**, 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.
 
-Beta.2 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.
+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. 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.
 
@@ -45,7 +45,7 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod
 
    ```json
    {
-     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.2"]
+     "plugins": ["@snarkipus/opencode-beads@1.1.0-beta.4"]
    }
    ```
 
@@ -53,7 +53,7 @@ The beta requires OpenCode `>=2.1.1 <2.2` and `bd` 1.3.1 or later. Exact OpenCod
 
    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 beta.2 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.
+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.2",
+      "package": "@snarkipus/opencode-beads@1.1.0-beta.4",
       "options": { "luna": true, "autoMigrate": false }
     }
   ]
@@ -121,9 +121,31 @@ Published stable 1.0.2 registers no slash commands; `bd setup claude` installs n
 
 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.
+
+Beta.4 keeps all 29 `/oc-beads:<workflow>` invocations compact, with
+single-line free text inline and multiline text below, preserving whitespace.
+Full static instructions live in durable `ocBeadsWorkflow` message metadata,
+expanded by existing primary and compaction hooks; retained `ocBeadsSync` v1
+history remains readable. Attachments/skills, prompt hooks and native delivery
+remain normal inputs. Diagnostics retains its observed-report presentation.
+Plugin activation is required for expansion; summaries retain semantic context,
+not guaranteed verbatim snapshots. Native storage/estimates can include copies or
+miss hidden text; this is not a token-savings claim. See the
+[workflow evaluation](docs/workflow-native-context-evaluation.md) and original
+[sync design](docs/sync-native-context-plan.md) / [evaluation](docs/sync-native-context-evaluation.md).
+
 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; action requires explicit operation and authority. 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`.
+`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
 

package/assets/oc-beads/SKILL.md

@@ -39,6 +39,16 @@ without opening a store; use `oc-beads:stats` for the issue-database overview vi
 `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,
@@ -46,9 +56,15 @@ 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 and requiring explicit write authority for `--apply`. Sync means
-Dolt-remote synchronization, distinct from `bd federation sync`. Follow the linked
-CLI reference, troubleshooting, resumability and worktree guidance before action.
+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
 
@@ -117,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

@@ -39,4 +39,64 @@ 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 WORKTREES.md). Inspect installed help and preserve authority.
+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/TROUBLESHOOTING.md

@@ -23,9 +23,11 @@ inspected CLI; see [AGENTS.md](AGENTS.md).
 
 `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 explains the workflow, not authority
-to act. Clarify the operation and scope when a request is ambiguous, and inspect
-applicable installed help before any explicitly authorized action.
+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
@@ -69,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

@@ -18,7 +18,9 @@ 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` guides `bd sync` Dolt-remote synchronization, distinct from
-`bd federation sync` and removed JSONL sync. Inspect current help and synchronize
-only with explicit authority. Report conflicts without forcing a side; the
-installed Beads CLI owns synchronization and consistency semantics.
+`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.2",
+  "version": "1.1.0-beta.4",
   "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
 
@@ -73,6 +73,7 @@ Beads workflow context could not be loaded: \`bd prime\` ${reason}. Beads may st
 /** Added to compaction requests so the summary keeps the Beads work in flight. */
 export const BEADS_COMPACTION_GUIDANCE = `<beads-compaction>
 This session tracks work in Beads (bd). Carry acknowledged durable task/memory references, current scope, attempts, blockers, pending validation and known unsaved or uncertain gaps into the summary or native-provider context. A summary is not a Beads write. Do not persist, wait for permission or a queued write, or request a recursive same-session checkpoint during compaction. Earlier meaningful checkpoints support recovery; no final-write guarantee applies. Fresh guarded context is requested after compaction. Preserve host-owned native replay, metadata.keepID and legacy metadata.recent; do not inject result.native.messages or a replacement result to add references.
+Preserve an active /oc-beads workflow invocation's requested outcome, unresolved inputs or explicit modes, and applicable authority limits in the summary.
 </beads-compaction>`;
 
 /** Observed after native request filtering; selective operation permission remains per call. */

package/src/host.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from "@opencode/plugin";
-import { applyBeadsSkill, createBeadsCommands, loadBeadsSkill, type SkillLoadDependencies } from "./workflows";
+import { applyBeadsSkill, createBeadsCommands, expandBeadsWorkflowContext, loadBeadsSkill, type SkillLoadDependencies } from "./workflows";
 import { applyBeadsAgents, beadsAgents, BEADS_TASK_AGENTS } from "./agents";
 import { BEADS_COMPACTION_GUIDANCE, UNKNOWN_CAPABILITIES, type RequestCapabilities } from "./guidance";
 import {
@@ -334,6 +334,7 @@ export async function setupBeads(
 
     registrations.push(await ctx.session.hook("context", async (event) => {
       if (abort.signal.aborted) return;
+      expandBeadsWorkflowContext(event.messages);
       if (ctx.session.get) {
         try {
           const info = await ctx.session.get({ sessionID: event.sessionID });
@@ -373,7 +374,9 @@ export async function setupBeads(
     }));
 
     registrations.push(await ctx.session.hook("compaction", (event) => {
-      if (!abort.signal.aborted && beadsSessions.get(event.sessionID)?.has(event.agent)) {
+      if (abort.signal.aborted) return;
+      expandBeadsWorkflowContext(event.messages);
+      if (beadsSessions.get(event.sessionID)?.has(event.agent)) {
         event.system.push({ type: "text", text: BEADS_COMPACTION_GUIDANCE });
         const known = references.get(event.sessionID);
         const gap = gapFor(event.sessionID);

package/src/workflows.ts

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Plugin } from "@opencode/plugin";
+import type { SessionContext } from "@opencode/plugin/promise/session";
 import type { CommandDefinition } from "@opencode/plugin/promise/command";
 
 type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
@@ -12,32 +13,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: ["Guide semantic issue compaction with bd admin compact only when explicitly authorized; bd compact squashes Dolt history and is a different operation. This is not 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: ["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.", "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: ["Retrieve pre-compaction issue content with bd restore; display-only by default. Use --apply only with explicit authority to write that content back; this is not database backup recovery.", "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"],
+  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: ["Inspect current bd sync help for Dolt-remote synchronization, distinct from bd federation sync and 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"],
+  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"],
@@ -87,7 +88,29 @@ export function applyBeadsSkill(editor: SkillEditor, skill: BeadsSkill, diagnose
   editor.add(skill);
 }
 
-/** Build native prompt commands, never shell/template interpolation or synthetic continuation. */
+/** Expand supported workflow/legacy snapshots only in transient user request copies. */
+export function expandBeadsWorkflowContext(messages: SessionContext["messages"]): void {
+  for (const [index, message] of messages.entries()) {
+    if (message.role !== "user") continue;
+    const metadata = { ...message.metadata };
+    let instructions: string | undefined;
+    for (const key of ["ocBeadsSync", "ocBeadsWorkflow"]) {
+      const snapshot = metadata[key];
+      if (!snapshot || typeof snapshot !== "object" || !("version" in snapshot) || snapshot.version !== 1
+        || !("instructions" in snapshot) || typeof snapshot.instructions !== "string") continue;
+      instructions = snapshot.instructions;
+      delete metadata[key];
+    }
+    if (instructions === undefined) continue;
+    messages[index] = {
+      ...message,
+      metadata,
+      content: [{ type: "text", text: instructions }, ...message.content],
+    };
+  }
+}
+
+/** Build native prompt commands with compact text and durable static workflow instructions. */
 export function createBeadsCommands(
   session: Pick<Plugin.Context["session"], "prompt">,
   diagnostics: (sessionID: string) => Promise<string>,
@@ -96,6 +119,8 @@ export function createBeadsCommands(
 ): 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.",
@@ -107,11 +132,13 @@ export function createBeadsCommands(
     description: purpose,
     async execute(input) {
       if (signal?.aborted) throw new Error("Beads workflow unloaded");
+      const instructions = `Invoked command: /oc-beads:${stem}\nRequested outcome: ${purpose}\n${common}\nSupporting guidance: ${JSON.stringify(resolve(dirname(skillPath), "resources", `${resource}.md`))}`;
       await session.prompt({
         ...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: `/oc-beads:${stem}${input.prompt.text ? `${/[\r\n]/.test(input.prompt.text) ? "\n" : " "}${input.prompt.text}` : ""}`,
+        metadata: { ocBeadsWorkflow: { version: 1, instructions } },
       });
     },
   }));