loadouts 0.3.0 → 0.4.0

package/docs/runtime.md

@@ -1,107 +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.
-
-## 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:
+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_...
+```
 
-- 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.
+`-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.
 
-## OpenCode-First Flow
+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.
 
-Use OpenCode as the primary runtime consumer in v1:
+## OpenCode dashboard
 
-```bash
-# JSON bridge for plugin/session adapters
-loadouts runtime base backend --tool opencode --json
+Install the bundled integration at either filesystem scope:
 
-# Pre-rendered system block text
-loadouts runtime base backend --tool opencode --system-block
+```sh
+loadouts activate opencode-runtime -g
+# or: loadouts activate opencode-runtime -l
 ```
 
-Recommended integration pattern:
+This renders the package directory `plugins/loadouts/`, containing the server and
+TUI entries. Build from source with `npm run build` before activating a checkout.
 
-- 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:
+Inside OpenCode:
 
 ```text
-/loadouts activate base
-/loadouts a base -l
-/loadouts a release -g
+/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
-/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`.
+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
+```
 
-### Known OpenCode Runtime Semantics
+For automatic project session equips, add to `.loadouts/loadouts.yaml`:
 
-- 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.
+```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.
 
-- 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`
+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,24 +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/`, commands to `.opencode/commands/`, local plugins 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
 
-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.
+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.
 

package/docs/tui-architecture.md

@@ -1,6 +1,8 @@
 # Loadouts TUI Architecture
 
-Status: **Design / RFC** (no implementation yet)
+Status: **Historical design / RFC**. The three-layer core/skin/host architecture is
+implemented. V1 runtime wiring and command names below are superseded by
+[the OpenCode V2 runtime](opencode-v2-runtime.md) and [usage](runtime.md).
 Author: design pass, June 2026
 
 A plan for turning the loadouts TUI from a passive popup into a beautiful, ergonomic,
@@ -133,14 +135,14 @@ src/tui/
       extension.ts    # default ExtensionAPI factory: command + inject + mount
       inject.ts       # before_agent_start system-prompt block
     opencode/
-      route.ts        # api.route.register("loadouts") mounting opentui skin
-      (reuses src/integrations/opencode-runtime/* for command + injection)
+      index.ts        # server entry: Plugin.define({ id, setup })
+      tui.tsx         # TUI entry: router page, slash, slots
 ```
 
-The existing `src/integrations/opencode-runtime/` (bridge, command parser, state,
-system-block injection) is reused as-is by the OpenCode host; the new TUI route is layered
-on top. A parallel `src/integrations/pi-runtime/` (or the `hosts/pi/` module above) provides
-the Pi equivalent.
+The V1-shaped `src/integrations/opencode-runtime/` was replaced by
+`src/integrations/opencode/` (session activator, instruction delta, service client,
+advertisement filter). The Pi equivalent lives in `hosts/pi/` and the shared
+`core/controller.ts` lifecycle.
 
 ---
 
@@ -300,7 +302,7 @@ skills/prompts/themes at runtime — a cleaner injection path than OpenCode's sy
 
 ### 6.2 OpenCode host (existing plugin, upgraded)
 
-Reuse `src/integrations/opencode-runtime/` (command parsing, session state, system-block
+Reuse the shared controller/lifecycle in `src/tui/core/controller.ts` (command parsing, session state, system-block
 injection). Add a TUI route:
 
 | Need                  | OpenCode API                                              |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadouts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Composable configuration bundles for AI coding agents",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "tsc --noEmit",
+    "lint": "tsc --noEmit -p tsconfig.lint.json && tsc --noEmit -p tsconfig.tui.json",
     "loadouts": "node dist/index.js"
   },
   "keywords": [
@@ -37,20 +37,25 @@
     "url": "https://github.com/evatths/loadouts.git"
   },
   "devDependencies": {
+    "@babel/core": "7.28.0",
+    "@babel/preset-typescript": "7.27.1",
     "@earendil-works/pi-coding-agent": "^0.79.7",
-    "@opencode-ai/plugin": "^1.17.8",
-    "@opentui/core": "^0.4.1",
-    "@opentui/keymap": "^0.4.1",
-    "@opentui/solid": "^0.4.1",
+    "@opencode/plugin": "2.0.3",
+    "@opentui/core": "0.5.11",
+    "@opentui/keymap": "0.5.11",
+    "@opentui/solid": "0.5.11",
+    "@opencode/theme": "2.0.3",
     "@types/node": "^20.12.0",
     "@types/update-notifier": "^6.0.8",
+    "babel-preset-solid": "1.9.12",
     "esbuild": "^0.23.1",
-    "solid-js": "^1.9.12",
+    "solid-js": "1.9.15",
     "typescript": "^5.4.0",
     "vitest": "^1.5.0"
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.79.7",
+    "@opencode/client": "2.0.3",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "update-notifier": "^7.3.1",

package/bundled/opencode/commands/loadouts.md

@@ -1,3 +0,0 @@
----
-description: Manage session-local Loadouts runtime activation
----