loadouts 0.2.5 → 0.4.0

package/docs/runtime.md

@@ -1,72 +1,137 @@
 # 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.
+Equip loadouts globally, for a project, or for **one OpenCode session**.
+Session switching uses OpenCode V2's durable instruction entries and permission
+rules, so another session at the same directory is unaffected.
+
+## CLI
+
+```sh
+loadouts session list
+loadouts session status --session ses_...
+loadouts session equip backend review --session ses_... -p
+loadouts session equip caveman --session ses_... -g
+loadouts session unequip --session ses_...
+```
 
-## Architecture
+`-g` and `-p` choose the **loadout source scope**; the destination is always the
+named session. Omit `--session` to use the most recently updated root session at
+the current directory. `--json` is available on every subcommand.
+The CLI discovers an already-running authenticated service; start OpenCode first.
 
-Runtime activation follows a resolver-backed bundle compiler:
+Session equips inject only instruction/rule content not already rendered by
+intact Global/Project OpenCode outputs. Skill gates restrict native catalog skill
+access to the selected loadout set while retaining pre-existing restrictions.
+Unsupported session artifacts (commands, MCP, references, plugins) are reported
+as diagnostics; equip those at Global/Project scope.
 
-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`).
+## OpenCode dashboard
 
-Key properties:
+Install the bundled integration at either filesystem scope:
 
-- 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.
+```sh
+loadouts activate opencode-runtime -g
+# or: loadouts activate opencode-runtime -l
+```
 
-## OpenCode-First Flow
+This renders the package directory `plugins/loadouts/`, containing the server and
+TUI entries. Build from source with `npm run build` before activating a checkout.
 
-Use OpenCode as the primary runtime consumer in v1:
+Inside OpenCode:
 
-```bash
-# JSON bridge for plugin/session adapters
-loadouts runtime base backend --tool opencode --json
+```text
+/loadouts                       dashboard (also ctrl+l)
+/loadouts quick                 multi-select session equip
+/loadouts equip caveman -g      replace this session's set
+/loadouts equip backend -p
+/loadouts unequip
+/loadouts status
+/loadouts list
+```
 
-# Pre-rendered system block text
-loadouts runtime base backend --tool opencode --system-block
+The dashboard shows **G / P / S** equipment and **All / Global / Project**
+scope tabs. It opens on **All**. Tabs filter the catalog; in filesystem mode,
+each row automatically equips into its own scope. The action target appears in
+the detail pane. `m` switches **filesystem ↔ session** when a session is selected;
+embedded dashboards open in session mode.
+
+| Keys | Action |
+|---|---|
+| `j` / `k`, `↓` / `↑` | Move within a section |
+| `h` / `l`, `←` / `→`, `Tab` / `Shift+Tab` | Previous / next section |
+| `1` / `2` / `3` | Jump to Active / Available / Issues |
+| `[` / `]` | Previous / next scope tab |
+| `gg` / `G`, `Home` / `End` | First / last row |
+| `Space`, `a` / `d` | Toggle, activate / deactivate the selected row |
+| `m` | Switch filesystem / session mode |
+| `s` / `x` / `D` | Sync / clear / diff the current target |
+| `/`, `t` | Search, cycle tool filter |
+| `Enter`, `e` | Expand artifacts, edit definition |
+| `PgUp` / `PgDn` | Scroll artifact details (or the open overlay) |
+| `u`, `r` | Undo last mutation, refresh |
+| `?` | Help (`j` / `k` scroll) |
+| `Esc` | Close overlay → clear filters → collapse detail → All tab → exit |
+| `q` | Exit (or close the current overlay) |
+
+Filesystem bulk operations use the selected tab. In **All**, a scope chooser
+asks Global or Project (`h/l` or `j/k`, then `Enter`; `Esc` cancels). Search and
+tool filters do not narrow bulk operations. In session mode, bulk actions target
+the session's equipped set; a tab for the other source scope has no session
+equipment to change. Equipping a session loadout from a different scope replaces
+its previous source-scope set, and undo restores that set and scope.
+
+Long sections keep the selected row visible, with row ranges in their headings.
+The footer shows contextual shortcuts and updates from persisted session state
+and native events.
+
+The server plugin also filters skill advertisements (session permission denies
+alone do not hide them on 2.0.3), provides off-disk skills through a catalog
+transform, and supports headless equips.
+
+Optional loadout selections:
+
+```yaml
+name: review
+include:
+  - instructions/AGENTS.review.md
+opencode:
+  agent: reviewer
+  model:
+    providerID: anthropic
+    id: claude-sonnet-4-5
 ```
 
-Recommended integration pattern:
+For automatic project session equips, add to `.loadouts/loadouts.yaml`:
 
-- 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.
+```yaml
+opencode:
+  defaultSession: [backend]
+```
 
-## Tool Capability Matrix (Runtime v1)
+## Standalone and Pi
 
-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.
+`loadouts tui` uses pi-tui and works without OpenCode. If a running service is
+available, press `S` to select a conversation at the current directory, then use
+session mode. Global/Project activation works independently of the service.
+The standalone dashboard requires Node 22.19+.
 
-| 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 |
+Pi's bundled `loadouts-runtime` extension uses the same dashboard and layers.
+Session equipment is persisted in Pi custom entries, keyed by the actual session
+ID, and injected through `before_agent_start`. Resuming/switching a Pi session
+reconstructs its own equipment. Pi skills remain path-discovery references.
 
-For filesystem-first tools, use standard `activate/sync` as the primary path and treat runtime output as inspection/debugging data.
+## Inspect compiled bundles
 
-## Runtime v1 Limits
+The existing compiler command remains useful independently of activation:
 
-- 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.
+```sh
+loadouts runtime base --tool opencode --json
+loadouts runtime base --tool pi --system-block
+```
 
-## Reference Scaffold
+OpenCode supports native per-session instruction entries and skill gating, plus
+location-wide skill hot reload. Pi supports session system-prompt injection.
+Other tools retain their existing compiler/filesystem capability flags.
 
-- Example OpenCode plugin scaffold: `docs/examples/opencode-runtime-plugin.ts`
-- Core compiler implementation: `src/core/runtime.ts`
-- CLI command surface: `src/cli/commands/runtime.ts`
+See [OpenCode V2 implementation details](opencode-v2-runtime.md) for ownership,
+rollback, concurrency limits, cache behavior, probes and verification scripts.

package/docs/troubleshooting.md

@@ -51,7 +51,26 @@ 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 V2:** Rules render to `.opencode/rules/`, commands to `.opencode/commands/`, local plugins to `.opencode/plugins/`, and NPM plugins are configured with the `plugins` array in `opencode.json(c)`. Global instructions render to `~/.config/opencode/AGENTS.md`. OpenCode hot-reloads these sources.
+
+### `/loadouts` not working in OpenCode runtime
+
+1. Verify `plugins/loadouts/{package.json,index.js,tui.js}` exists under the
+   project's `.opencode/` or global `~/.config/opencode/` directory.
+2. Check `loadouts info -l` or `loadouts info -g` for `opencode-runtime` and
+   `loadouts status` for shadowed/missing output. A source checkout needs
+   `npm run build` before activation.
+3. Open OpenCode's Plugins dialog and inspect the server/TUI entries. Local
+   plugin directories do not install server dependencies; use the built,
+   self-contained artifact rather than copying `src/tui/hosts/opencode/`.
+4. Test the independent HTTP path with
+   `loadouts session status --session ses_...`.
+5. `/loadouts` and `ctrl+l` are client-side commands. The server entry is needed
+   for clean per-session skill advertisements; native permission denies alone
+   still leave skills listed on OpenCode 2.0.3.
+
+If permissions were edited after equip, unequip preserves those edits and reports
+it. See [runtime ownership and recovery](opencode-v2-runtime.md#persistence-and-ownership).
 
 **Claude Code:** Verify rules exist in `.claude/rules/`. May require restarting the session.