loadouts 0.2.3 → 0.3.0

package/docs/authoring.md

@@ -1,6 +1,6 @@
 # Authoring Artifacts
 
-This guide covers creating rules, skills, and instructions. The typical workflow:
+This guide covers creating agents, rules, skills, and instructions. The typical workflow:
 
 1. **Create** an artifact (`loadouts rule add`, `loadouts skill add`, etc.)
 2. **Include** it in a loadout (`loadouts add-to <loadout> <artifact>`)
@@ -9,6 +9,71 @@ This guide covers creating rules, skills, and instructions. The typical workflow
 
 ---
 
+## Agents
+
+Agents are self-contained Markdown files under `.loadouts/agents/`. The body is the agent prompt. Top-level frontmatter holds portable fields, while `targets.<tool>` holds harness-specific fields.
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code for correctness, security, and missing tests.
+model: inherit
+readonly: true
+background: false
+
+targets:
+  opencode:
+    mode: subagent
+    steps: 8
+    color: accent
+    permission:
+      bash:
+        "*": ask
+        "git diff*": allow
+
+  cursor:
+    is_background: false
+
+  claude-code:
+    tools: Read, Glob, Grep, Bash
+    maxTurns: 8
+
+  codex:
+    sandbox_mode: read-only
+    model_reasoning_effort: high
+---
+
+Review code like an owner. Prioritize real bugs, behavior regressions,
+security issues, and missing tests.
+```
+
+Project scope renders agents to:
+
+- OpenCode: `.opencode/agents/<name>.md`
+- Cursor: `.cursor/agents/<name>.md`
+- Claude Code: `.claude/agents/<name>.md`
+- Codex: `.codex/agents/<name>.toml`
+
+Markdown targets are symlinked only when the source frontmatter is already native-safe for that harness. If the file contains `targets:` overlays, Loadouts writes a cleaned managed copy for each Markdown harness. Codex always gets generated TOML, with the Markdown body mapped to `developer_instructions`.
+
+After creating an agent manually, add it to a loadout:
+
+```bash
+loadouts add-to backend agents/code-reviewer.md
+```
+
+**Import or migrate existing agents:**
+
+```bash
+loadouts install .opencode/agents/reviewer.md --kinds agent --keep
+loadouts migrate agents --dry-run
+loadouts migrate agents
+```
+
+`install --kinds agent` imports native harness files from outside the target loadout. `migrate agents` converts native files already inside a loadout, such as `opencode/agents/*.md`, `cursor/agents/*.md`, `.claude/agents/*.md`, or `.codex/agents/*.toml`.
+
+---
+
 ## Rules
 
 Rules are scoped advisory files with YAML frontmatter:
@@ -154,7 +219,7 @@ include:
 
 ---
 
-## OpenCode Config And Plugins
+## OpenCode Config, Commands, And Plugins
 
 OpenCode-specific artifacts live under `.loadouts/opencode/` and only render when included in a loadout that targets `opencode`.
 
@@ -169,6 +234,16 @@ OpenCode-specific artifacts live under `.loadouts/opencode/` and only render whe
 
 Project scope renders this to `opencode.jsonc`. Global scope renders it to `~/.config/opencode/opencode.jsonc`. This is whole-file ownership; if you do not include this artifact, loadouts does not touch your OpenCode config file.
 
+**Slash commands:**
+```md
+<!-- .loadouts/opencode/commands/loadouts.md -->
+# /loadouts
+
+Arguments: `$ARGUMENTS`
+```
+
+Project scope renders this to `.opencode/commands/loadouts.md`. Global scope renders it to `~/.config/opencode/commands/loadouts.md`.
+
 **Local plugins:**
 ```ts
 // .loadouts/opencode/plugins/notify.ts
@@ -187,11 +262,53 @@ Project scope renders this to `.opencode/plugins/notify.ts`. Global scope render
 ```yaml
 include:
   - opencode/opencode.jsonc
+  - opencode/commands/loadouts.md
   - opencode/plugins/notify.ts
 ```
 
 NPM plugins belong in the managed `opencode.json(c)` `plugin` array. Local plugin source files belong in `.loadouts/opencode/plugins/`.
 
+**TUI plugins:**
+
+OpenCode TUI plugins are local plugin modules loaded from `tui.json(c)`. They are useful for user-facing UI that should not be added to chat or model-visible prompt context.
+
+```tsx
+// .loadouts/opencode/plugins/status-popup.tsx
+/** @jsxImportSource @opentui/solid */
+
+import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui";
+
+const tui: TuiPlugin = async (api) => {
+  api.keymap.registerLayer({
+    commands: [
+      {
+        name: "status_popup_open",
+        title: "Open status popup",
+        category: "Plugin",
+        namespace: "palette",
+        slashName: "status-popup",
+        run() {
+          api.ui.dialog.setSize("medium");
+          api.ui.dialog.replace(() => <box border paddingLeft={2}>TUI-only popup</box>);
+        },
+      },
+    ],
+  });
+};
+
+export default { id: "status-popup", tui } satisfies TuiPluginModule & { id: string };
+```
+
+```jsonc
+// .loadouts/opencode/tui.jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["./plugins/status-popup.tsx"]
+}
+```
+
+Project scope renders this config to `.opencode/tui.jsonc`. Global scope renders it to `~/.config/opencode/tui.jsonc`. This is whole-file ownership; if you already manage `tui.jsonc`, add the plugin entry there instead of including this artifact.
+
 ---
 
 ## Custom Kinds

package/docs/commands.md

@@ -46,6 +46,22 @@ loadouts info              # Active loadout(s)
 loadouts info backend      # Specific loadout
 ```
 
+### `loadouts runtime [names...]`
+Compile a runtime bundle for inspection (no filesystem activation). Defaults to the root `default` loadout (or `base`).
+```bash
+loadouts runtime                     # Compile default loadout
+loadouts runtime base backend        # Compile multiple loadouts
+loadouts runtime base --tool cursor  # Target a different tool
+loadouts runtime base -l             # Force local/project scope
+loadouts runtime base -g             # Force global scope
+loadouts runtime base --json         # Output RuntimeBundle JSON only
+loadouts runtime base --system-block # Output renderRuntimeSystemBlock(bundle) only
+```
+
+See `docs/runtime.md` for architecture, OpenCode-first integration flow, and per-tool capability flags.
+
+For OpenCode runtime plugin integrations, this is exposed as `/loadouts activate|a|use ...`, `/loadouts list|ls`, `/loadouts info`, and `/loadouts clear`. The bundled fallback command omits `$ARGUMENTS` to reduce model-visible command noise, and runtime JSON/intermediate plugin output should stay hidden. User-visible slash command acknowledgment text may still be model-mediated by OpenCode even when plugin state handling is deterministic.
+
 ### `loadouts diff [name]`
 Preview what would change if a loadout were applied.
 ```bash
@@ -73,10 +89,26 @@ loadouts install ./rule.mdc        # Import a single rule file
 loadouts install --dry-run         # Preview
 loadouts install -i                # Interactive
 loadouts install --rules           # Rules only
+loadouts install --kinds agent     # Import and canonicalize agents
 loadouts install --from cursor     # From specific tool
 loadouts install --keep            # Don't delete originals
 ```
 
+Native agent files are converted to canonical `.loadouts/agents/*.md` during import. OpenCode, Cursor, Claude Code, and Codex fields are preserved under `targets.<tool>` overlays where needed.
+
+### `loadouts migrate agents [source]`
+Migrate native harness agent definitions that already live in a loadout tree into canonical `.loadouts/agents/*.md` files.
+
+```bash
+loadouts migrate agents                  # Scan legacy agent paths in current loadout
+loadouts migrate agents --dry-run         # Preview migration
+loadouts migrate agents --keep            # Keep old native files
+loadouts migrate agents --force           # Overwrite existing canonical agents
+loadouts migrate agents ./agents --from opencode
+```
+
+When migrating from a harness-specific source path such as `opencode/agents/reviewer.md`, loadout includes are updated to `agents/reviewer.md` with `tools: [opencode]` to preserve existing behavior. The canonical file still receives compatible fields for other harnesses where Loadouts can infer them.
+
 ### `loadouts create <name>`
 Create a new loadout definition.
 ```bash
@@ -196,6 +228,8 @@ Most state commands (`activate`, `deactivate`, `sync`, `status`, `clear`, `list`
 | `-g, --global` | Global scope only |
 | `-a, --all` | Both scopes |
 
+`runtime` supports `-l/--local` and `-g/--global` only (no `--all`).
+
 When omitted, commands auto-detect scope based on context. Use `--dry-run` to preview behavior before destructive operations.
 
 ---

package/docs/compatibility.md

@@ -4,13 +4,13 @@ Current built-in rendering targets for canonical artifacts.
 
 ## Artifact Paths (Project Scope)
 
-| Tool | Rule | Skill | Instruction |
-|------|------|-------|-------------|
-| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) |
-| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `AGENTS.md` |
-| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `AGENTS.md` |
-| Codex | - (no rule target) | `.agents/skills/<name>/` | `AGENTS.md` |
-| Pi | - (no native rule target) | `.pi/skills/<name>/` | `AGENTS.md` |
+| Tool | Rule | Skill | Agent | Instruction | Extra Artifacts |
+|------|------|-------|-------|-------------|-----------------|
+| Claude Code | `.claude/rules/<name>.md` | `.claude/skills/<name>/` | `.claude/agents/<name>.md` | `CLAUDE.md` (generated wrapper to `AGENTS.md`) | - |
+| Cursor | `.cursor/rules/<name>.mdc` | `.cursor/skills/<name>/` | `.cursor/agents/<name>.md` | `AGENTS.md` | - |
+| OpenCode | `.opencode/rules/<name>.md` | `.opencode/skills/<name>/` | `.opencode/agents/<name>.md` | `AGENTS.md` | `.opencode/commands/<name>.md`, `.opencode/plugins/<name>.{ts,tsx,js}`, `.opencode/tui.json(c)`, `opencode.json(c)` |
+| Codex | - (no rule target) | `.agents/skills/<name>/` | `.codex/agents/<name>.toml` | `AGENTS.md` | - |
+| Pi | - (no native rule target) | `.pi/skills/<name>/` | - | `AGENTS.md` | - |
 
 Global scope uses each tool's configured global base path. Instruction files may render to home-level `AGENTS.md` or `CLAUDE.md` paths depending on the tool.
 
@@ -18,17 +18,24 @@ Global scope uses each tool's configured global base path. Instruction files may
 
 - Canonical rule fields: `description`, `paths`, `activation` (`always` or `scoped`).
 - Canonical skill fields: `name`, `description`, `user-invocable`, `model-invocable`.
+- Canonical agent files are Markdown under `.loadouts/agents/<name>.md`; use top-level portable fields plus `targets.<tool>` overlays for harness-specific config.
 
 Rendered aliases for compatibility:
 
 - Cursor/OpenCode rules: `paths` is mirrored to `globs`.
 - Cursor/OpenCode rules: `activation` is mirrored to `alwaysApply` (`always -> true`, `scoped -> false`).
 - OpenCode skills: `model-invocable` is mirrored to `disable-model-invocation` (inverted boolean).
+- Agent overlays are rendered into each harness' native frontmatter. Codex agents are generated as TOML with the Markdown body mapped to `developer_instructions`.
 
 Transforms add aliases when canonical fields are present and alias fields are not already set.
 
+Agent Markdown targets use symlinks only when the source frontmatter is already native-safe for that harness. Files with `targets:` overlays are rendered as managed copies so tool-specific fields do not leak into other harnesses.
+
+Agent import and migration canonicalize native harness definitions. Compatible fields are inferred when possible: read-only native settings become canonical `readonly: true`, Cursor/Claude background settings become canonical `background`, OpenCode/Codex/Claude reasoning effort settings are mirrored across compatible target overlays, and OpenCode `steps` / Claude `maxTurns` are mirrored between those harnesses.
+
 ## Known Limitations
 
 - Codex and Pi do not currently have a built-in rule output target.
-- Frontmatter aliasing is only applied on transformed targets (currently Cursor/OpenCode rules and OpenCode skills).
+- Pi does not currently have a built-in agent output target.
+- Frontmatter aliasing is only applied on transformed targets.
 - If both canonical and alias fields are set by hand, existing alias values are preserved.

package/docs/concepts.md

@@ -74,22 +74,25 @@ include:
 |------|--------|-------------|
 | `rule` | file | Scoped advisory rules (`.md`) |
 | `skill` | directory | On-demand capabilities with `SKILL.md` |
+| `agent` | file | Specialized agents and subagents |
 | `instruction` | file | Always-on project instructions |
 | `prompt` | file | Slash command templates |
 | `extension` | directory | Runtime code extensions |
 | `theme` | file | UI theme configuration |
+| `opencode-command` | file | OpenCode slash command markdown |
 | `opencode-config` | file | Whole-file OpenCode runtime configuration |
+| `opencode-tui-config` | file | Whole-file OpenCode TUI configuration |
 | `opencode-plugin` | file | Local OpenCode plugin modules |
 
 ## Supported Tools
 
-| Tool | Rules | Skills | Instructions | Extra Artifacts |
-|------|-------|--------|--------------|-----------------|
-| Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `CLAUDE.md` | — |
-| Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `AGENTS.md` | — |
-| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `AGENTS.md` | `opencode.json(c)`, `.opencode/plugins/` |
-| Codex | — | `.agents/skills/` | `AGENTS.md` | — |
-| Pi | `.pi/rules/*.md` | `.pi/skills/` | `AGENTS.md` | `.pi/extensions/`, `.pi/themes/` |
+| Tool | Rules | Skills | Agents | Instructions | Extra Artifacts |
+|------|-------|--------|--------|--------------|-----------------|
+| Claude Code | `.claude/rules/*.md` | `.claude/skills/` | `.claude/agents/*.md` | `CLAUDE.md` | — |
+| Cursor | `.cursor/rules/*.mdc` | `.cursor/skills/` | `.cursor/agents/*.md` | `AGENTS.md` | — |
+| OpenCode | `.opencode/rules/*.md` | `.opencode/skills/` | `.opencode/agents/*.md` | `AGENTS.md` | `opencode.json(c)`, `.opencode/tui.json(c)`, `.opencode/plugins/`, `.opencode/commands/*.md` |
+| Codex | — | `.agents/skills/` | `.codex/agents/*.toml` | `AGENTS.md` | — |
+| Pi | — | `.pi/skills/` | — | `AGENTS.md` | `.pi/prompts/*.md`, `.pi/extensions/`, `.pi/themes/` |
 
 ## Sources (Cross-Project Config)
 

package/docs/examples/opencode-runtime-plugin.ts

@@ -0,0 +1,143 @@
+/**
+ * OpenCode runtime integration scaffold (reference implementation).
+ *
+ * This is intentionally conservative and uses the current CLI JSON bridge:
+ *   loadouts runtime <names...> --tool opencode --json
+ *
+ * Notes:
+ * - API shapes below are placeholders where OpenCode plugin APIs are uncertain.
+ * - This scaffold does not claim native skill hot-swap.
+ * - Skills are exposed as path-discovery references only.
+ */
+
+import { spawn } from "node:child_process";
+
+interface RuntimeBundle {
+  tool: string;
+  fingerprint: string;
+  injection: {
+    instructions: Array<{ relativePath: string; content: string }>;
+    rules: Array<{ relativePath: string; content: string }>;
+    skills: Array<{ name: string; path: string; sourcePath: string }>;
+  };
+  capabilities: {
+    runtimeMode: "native-runtime" | "experimental-runtime" | "filesystem-activation";
+    modelInjection: { instructions: boolean; rules: boolean };
+    skillPathDiscovery: boolean;
+    nativeSkillHotSwap: boolean;
+  };
+}
+
+type SessionRuntimeState = {
+  fingerprint?: string;
+  bundle?: RuntimeBundle;
+};
+
+// Placeholder/uncertain plugin API. Replace with actual OpenCode interfaces.
+interface OpenCodePluginApi {
+  // Possible session lifecycle hook (name/signature may differ).
+  onSessionStart?: (handler: (ctx: { cwd: string; state: SessionRuntimeState }) => Promise<void>) => void;
+  // Possible system prompt composition hook (name/signature may differ).
+  onSystemPrompt?: (handler: (ctx: { state: SessionRuntimeState }) => string | Promise<string>) => void;
+  // Possible skill discovery registration hook (name/signature may differ).
+  registerSkillDiscoveryPath?: (path: string) => void;
+}
+
+export function registerLoadoutsRuntimeScaffold(api: OpenCodePluginApi): void {
+  if (!api.onSessionStart || !api.onSystemPrompt) {
+    return;
+  }
+
+  api.onSessionStart(async ({ cwd, state }) => {
+    const names = ["base"]; // Replace with user/session-selected runtime loadouts.
+    const bundle = await compileRuntimeBundleViaCli(names, cwd);
+
+    state.bundle = bundle;
+    state.fingerprint = bundle.fingerprint;
+
+    if (bundle.capabilities.skillPathDiscovery && api.registerSkillDiscoveryPath) {
+      for (const skill of bundle.injection.skills) {
+        api.registerSkillDiscoveryPath(skill.path);
+      }
+    }
+  });
+
+  api.onSystemPrompt(({ state }) => {
+    const bundle = state.bundle;
+    if (!bundle) return "";
+
+    // Either render your own system block from bundle fields,
+    // or call `loadouts runtime ... --system-block` in environments that prefer text passthrough.
+    return renderRuntimeSystemBlockText(bundle);
+  });
+}
+
+async function compileRuntimeBundleViaCli(names: string[], cwd: string): Promise<RuntimeBundle> {
+  const args = ["runtime", ...names, "--tool", "opencode", "--json", "--local"];
+  const { stdout } = await execFile("loadouts", args, cwd);
+  return JSON.parse(stdout) as RuntimeBundle;
+}
+
+function renderRuntimeSystemBlockText(bundle: RuntimeBundle): string {
+  const lines: string[] = [];
+  lines.push("[loadout-runtime:v1]");
+  lines.push(`tool: ${bundle.tool}`);
+  lines.push(`fingerprint: ${bundle.fingerprint}`);
+  lines.push("");
+  lines.push("## Instructions (Model Injected)");
+
+  if (bundle.injection.instructions.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const item of bundle.injection.instructions) {
+      lines.push(`### ${item.relativePath}`);
+      lines.push(item.content);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Rules (Model Injected)");
+  if (bundle.injection.rules.length === 0) {
+    lines.push("(none)");
+  } else {
+    for (const item of bundle.injection.rules) {
+      lines.push(`### ${item.relativePath}`);
+      lines.push(item.content);
+      lines.push("");
+    }
+  }
+
+  lines.push("## Skills (Path Discovery Only)");
+  lines.push("Native skill hot-swap is not available in runtime v1.");
+  for (const skill of bundle.injection.skills) {
+    lines.push(`- ${skill.name}`);
+    lines.push(`  path: ${skill.path}`);
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function execFile(command: string, args: string[], cwd: string): Promise<{ stdout: string; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(new Error(`loadouts runtime failed (${code}): ${stderr || stdout}`));
+    });
+  });
+}

package/docs/index.md

@@ -53,6 +53,7 @@ loadouts check                     # Validate configuration
 loadouts docs quickstart       # Get started in 60 seconds
 loadouts docs concepts         # Loadouts, artifacts, scopes, tools
 loadouts docs commands         # Full command reference
+loadouts docs runtime          # Runtime activation architecture and capabilities
 loadouts docs authoring        # Creating rules, skills, instructions
 loadouts docs compatibility    # Tool paths, frontmatter aliases, limits
 loadouts docs workflows        # Team setup, git, CI/CD

package/docs/runtime.md

@@ -0,0 +1,107 @@
+# Runtime Activation (OpenCode First)
+
+`loadouts runtime` compiles loadouts into a session-time bundle without touching activated outputs on disk. Runtime v1 is designed as an OpenCode-first integration path and a reference surface for other tools.
+
+## Why Runtime Exists
+
+- Keep activation side-effect free for agent sessions.
+- Reuse the existing resolver and include semantics from standard loadout compilation.
+- Make instruction/rule injection explicit and auditable in one JSON payload.
+- Expose skill directories as references (path discovery only), without claiming native skill hot-swap.
+
+## Architecture
+
+Runtime activation follows a resolver-backed bundle compiler:
+
+1. Resolve loadouts exactly like normal activation (`include`, source imports, bundled/global fallback, tool filtering).
+2. Compile supported artifacts into a `RuntimeBundle`.
+3. Return bundle JSON (`--json`) or a model-ready block (`--system-block`).
+
+Key properties:
+
+- Session-local state: caller owns lifecycle in memory/process state.
+- No persistent activation changes: runtime commands do not mutate `.loadouts/.state.json`.
+- No output rendering: runtime does not write `.opencode/`, `AGENTS.md`, or other tool target files.
+- Deterministic fingerprinting: `fingerprint` is stable across `generatedAt` changes for equivalent content.
+
+## OpenCode-First Flow
+
+Use OpenCode as the primary runtime consumer in v1:
+
+```bash
+# JSON bridge for plugin/session adapters
+loadouts runtime base backend --tool opencode --json
+
+# Pre-rendered system block text
+loadouts runtime base backend --tool opencode --system-block
+```
+
+Recommended integration pattern:
+
+- Compile once when a session starts or active runtime loadouts change.
+- Cache by `fingerprint`.
+- Inject `instructions` and `rules` into model/system context.
+- Register `skills[*].path` for discovery only.
+
+### Slash Command UX (`/loadouts`)
+
+The OpenCode runtime path is designed around a deterministic plugin-backed slash command:
+
+```text
+/loadouts activate base
+/loadouts a base -l
+/loadouts a release -g
+/loadouts list
+/loadouts info base
+/loadouts clear
+```
+
+Expected behavior:
+
+- The server plugin maps `/loadouts activate|a|use <names...>` to `loadouts runtime ...` (or equivalent runtime adapter path) and computes session runtime state deterministically.
+- The TUI plugin listens for server plugin events and renders status/results in a TUI-only dialog that is not appended to chat and is not visible to the assistant.
+- `-l/--local` and `-g/--global` are supported as direct scope selectors for runtime compilation.
+- Runtime JSON and intermediate plugin outputs stay hidden from the model-facing response.
+- The server and TUI plugins share persisted runtime state through `~/.cache/loadouts/opencode-runtime/<cwd-hash>.json`; the server plugin uses that state during system-message injection.
+- A bundled scaffold loadout (`opencode-runtime`) renders `.opencode/plugins/loadouts-runtime.ts`, `.opencode/plugins/loadouts-runtime-tui.tsx`, and `.opencode/tui.jsonc`.
+
+### Known OpenCode Runtime Semantics
+
+- The runtime plugin's `command.execute.before` hook is deterministic for parsing `/loadouts` arguments and updating runtime state.
+- In interactive OpenCode, the server plugin owns `/loadouts` command handling and the TUI plugin owns user-visible feedback. If the TUI plugin is not loaded, the server plugin remains the headless/fallback path.
+- OpenCode may still route server slash command text through model-facing flows when the TUI plugin is absent. Treat user-visible server acknowledgment text as host-dependent.
+- OpenCode loads server plugins and TUI plugins at startup. Restart OpenCode after changing or activating runtime plugin or TUI config artifacts.
+- The plugin bridge shells out to `loadouts runtime ...`. Ensure the `loadouts` binary available on OpenCode's `PATH` includes runtime support.
+- The bundled TUI config is whole-file managed like other Loadouts config artifacts. Existing unmanaged `.opencode/tui.jsonc` files are protected by normal shadowing; add `./plugins/loadouts-runtime-tui.tsx` to your existing TUI config if needed.
+
+## Tool Capability Matrix (Runtime v1)
+
+The bundle always includes resolved instructions, rules, and skill references. Capability flags tell consumers what should be treated as native runtime behavior for each tool.
+
+| Tool | Runtime mode | Instruction/rule model injection | Skill path discovery | Native skill hot-swap |
+|------|--------------|----------------------------------|----------------------|-----------------------|
+| OpenCode | `experimental-runtime` | Yes | Yes | No |
+| Pi | `native-runtime` | Yes | Yes | No |
+| Codex | `experimental-runtime` | Yes | Yes | No |
+| Claude Code | `filesystem-activation` | No | No | No |
+| Cursor | `filesystem-activation` | No (not native) | No | No |
+
+For filesystem-first tools, use standard `activate/sync` as the primary path and treat runtime output as inspection/debugging data.
+
+## Runtime v1 Limits
+
+- Supported kinds: `instruction`, `rule`, `skill`.
+- Agents are filesystem-rendered native definitions for supported harnesses; they are not injected through runtime v1.
+- Unsupported kinds are reported as diagnostics, not hard failures.
+- Skills require a `SKILL.md` entrypoint for runtime discovery metadata.
+- Runtime v1 does not implement native skill hot-swap.
+
+## Reference Scaffold
+
+- Bundled OpenCode server runtime plugin: `bundled/opencode/plugins/loadouts-runtime.ts`
+- Bundled OpenCode TUI runtime plugin: `bundled/opencode/plugins/loadouts-runtime-tui.tsx`
+- Bundled OpenCode TUI config: `bundled/opencode/tui.jsonc`
+- Bundled scaffold loadout: `bundled/loadouts/opencode-runtime.yaml`
+- Historical/reference plugin scaffold: `docs/examples/opencode-runtime-plugin.ts`
+- Core compiler implementation: `src/core/runtime.ts`
+- CLI command surface: `src/cli/commands/runtime.ts`

package/docs/troubleshooting.md

@@ -51,7 +51,24 @@ loadouts sync      # Re-render if needed
 
 **Cursor:** Rules need `.mdc` extension — loadouts handles this automatically. Restart Cursor if rules don't appear immediately.
 
-**OpenCode:** Rules render to `.opencode/rules/`. Local plugins render to `.opencode/plugins/`, and NPM plugins are configured with the `plugin` array in `opencode.json(c)`.
+**OpenCode:** Rules render to `.opencode/rules/`, commands to `.opencode/commands/`, local plugins to `.opencode/plugins/`, and NPM plugins are configured with the `plugin` array in `opencode.json(c)`.
+
+### `/loadouts` not working in OpenCode runtime
+
+If `/loadouts` exists but does not activate runtime behavior, verify the full chain:
+
+1. Runtime artifacts are rendered in the expected scope:
+   - Local server plugin: `.opencode/plugins/loadouts-runtime.ts`
+   - Local TUI plugin/config: `.opencode/plugins/loadouts-runtime-tui.tsx` and `.opencode/tui.jsonc`
+   - Global server plugin: `~/.config/opencode/plugins/loadouts-runtime.ts`
+   - Global TUI plugin/config: `~/.config/opencode/plugins/loadouts-runtime-tui.tsx` and `~/.config/opencode/tui.jsonc`
+2. Runtime scaffold is active in the same scope (`loadouts info -l` or `loadouts info -g`).
+3. Restart OpenCode after activation or plugin/TUI config changes (startup-time plugin loading).
+4. Check the `loadouts` binary on OpenCode's `PATH` supports runtime:
+```bash
+loadouts runtime base --tool opencode --json
+```
+5. In interactive OpenCode, the server plugin owns `/loadouts` and the TUI plugin listens for server events to render a user-only dialog. If command acknowledgment text looks model-generated, the TUI plugin is probably not loaded; the deterministic fallback is still server plugin state update and runtime system injection.
 
 **Claude Code:** Verify rules exist in `.claude/rules/`. May require restarting the session.