@elizaos/app-core 2.0.0-beta.3 → 2.0.3-beta.3

package/platforms/electrobun/docs/capability-collapse-matrix.json

@@ -0,0 +1,318 @@
+{
+  "version": 1,
+  "expertDecision": {
+    "nextAction": "finish plugin-coding-tools grep/glob parity decisions, then first-class edit/patch parity, before adding packages/ui trace renderers",
+    "rationale": "Capability routing is already partially implemented for plugin-coding-tools. The remaining direct local filesystem mechanics are a permission, trace, and behavior-drift risk. Reusable trace components should follow once execution boundaries are coherent."
+  },
+  "pluginCodingToolsFsParity": [
+    {
+      "operation": "ls",
+      "currentPluginBehavior": "Session cwd fallback, sandbox path validation, ignore globs, directory-first ordering, file/dir/symlink display, and a 1000-entry cap.",
+      "currentRemoteParity": "fs.list has root guard, hidden/generated exclusions, limits, typed FileStat entries, ignore patterns, and truncation metadata.",
+      "decision": "Routed through capability-router.fs.list with plugin-owned cwd fallback, sandbox validation, directory-first formatting, and local fallback when the router is absent or explicitly unavailable."
+    },
+    {
+      "operation": "grep",
+      "currentPluginBehavior": "Ripgrep-backed regex search with output modes, glob/type filters, context flags, case-insensitive and multiline options, head limit, and VCS excludes.",
+      "currentRemoteParity": "fs.search is literal case-insensitive substring search with path/root/limit/includeHidden only.",
+      "requiredParityBeforeRouting": [
+        "regex mode",
+        "literal mode",
+        "case-sensitivity control",
+        "multiline support",
+        "include and exclude glob filters",
+        "type filters",
+        "VCS and generated-file exclusion policy",
+        "context-before and context-after output",
+        "head limit",
+        "deterministic ordering",
+        "structured file/line/column match records",
+        "truncation metadata",
+        "explicit unsupported-option errors"
+      ],
+      "decision": "Do not route yet. Add a first-class search method with these semantics or keep plugin-owned search until parity exists."
+    },
+    {
+      "operation": "glob",
+      "currentPluginBehavior": "File globbing with generated/VCS excludes, recent-file ordering by mtime, and a 100-result cap.",
+      "currentRemoteParity": "No direct glob or recursive find method with pattern semantics.",
+      "requiredParityBeforeRouting": [
+        "cwd/root policy",
+        "one or more patterns",
+        "hidden/generated/VCS exclusion policy",
+        "file/dir/symlink filters",
+        "max-results",
+        "deterministic recent-file ordering where requested",
+        "typed file metadata",
+        "truncation metadata",
+        "explicit unsupported-option errors"
+      ],
+      "decision": "Do not route yet. Add a first-class glob/find method before routing."
+    },
+    {
+      "operation": "edit",
+      "currentPluginBehavior": "Must-read-first and stale-read gate, exact substring replacement, optional replace-all, ambiguity protection, secret detection, and first-line reporting.",
+      "currentRemoteParity": "fs.writeText overwrites full text only and has no compare-and-swap, old-string match, patch, secret gate, or read-state contract.",
+      "requiredParityBeforeRouting": [
+        "read-state or expected-digest protection",
+        "exact old-string replacement",
+        "replace-all behavior",
+        "ambiguity detection",
+        "first-changed-line metadata",
+        "secret-pattern rejection",
+        "atomic write behavior",
+        "structured patch errors"
+      ],
+      "decision": "Do not route through generic write. Add a first-class edit/patch method or keep local implementation."
+    }
+  ],
+  "entries": [
+    {
+      "pluginId": "plugin-coding-tools",
+      "path": "plugins/plugin-coding-tools",
+      "capability": "filesystem",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.fs",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": true,
+      "risk": "low",
+      "notes": "FILE list/read/write/edit/search remains the coding tool semantic surface. Desktop file listing, content reads, and writes prefer the capability router and fall back to the existing sandboxed path when no router is registered or FS is explicitly unavailable."
+    },
+    {
+      "pluginId": "plugin-coding-tools",
+      "path": "plugins/plugin-coding-tools",
+      "capability": "terminal",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.pty",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": true,
+      "risk": "medium",
+      "notes": "SHELL remains the agent action. Desktop command execution prefers eliza.pty through the capability router and falls back to the existing local shell path when no router is registered or PTY is explicitly unavailable."
+    },
+    {
+      "pluginId": "plugin-coding-tools",
+      "path": "plugins/plugin-coding-tools",
+      "capability": "git-local",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.git",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": true,
+      "risk": "medium",
+      "notes": "WORKTREE remains the semantic coding action. git worktree add/remove now prefer eliza.git through the capability router and fall back to the existing local Git path when no router is registered or Git is explicitly unavailable."
+    },
+    {
+      "pluginId": "plugin-codex-cli",
+      "path": "plugins/plugin-codex-cli",
+      "capability": "filesystem",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.fs",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Auth/config file storage is implementation. Keep Codex CLI semantics in the plugin and route desktop file access through the router after coding-tools."
+    },
+    {
+      "pluginId": "plugin-codex-cli",
+      "path": "plugins/plugin-codex-cli",
+      "capability": "terminal",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.pty",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "structured-unavailable",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "CLI process execution should route through eliza.pty when running inside the desktop shell."
+    },
+    {
+      "pluginId": "plugin-commands",
+      "path": "plugins/plugin-commands",
+      "capability": "terminal",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.pty",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "structured-unavailable",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Command semantics can remain plugin-owned, but host command execution belongs behind eliza.pty."
+    },
+    {
+      "pluginId": "plugin-github",
+      "path": "plugins/plugin-github",
+      "capability": "github-remote",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": false,
+      "routeTo": "plugin-owned",
+      "collapseMode": "none",
+      "nonDesktopBehavior": "server-supported",
+      "firstRoutingCandidate": false,
+      "risk": "low",
+      "notes": "GitHub API ownership stays in the connector plugin."
+    },
+    {
+      "pluginId": "plugin-github",
+      "path": "plugins/plugin-github",
+      "capability": "git-local",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.git",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "structured-unavailable",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Local repository status, diff, and worktree operations should route through eliza.git. Remote GitHub API calls remain plugin-owned."
+    },
+    {
+      "pluginId": "plugin-documents",
+      "path": "plugins/plugin-documents",
+      "capability": "app-semantics",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": false,
+      "routeTo": "plugin-owned",
+      "collapseMode": "none",
+      "nonDesktopBehavior": "server-supported",
+      "firstRoutingCandidate": false,
+      "risk": "low",
+      "notes": "Document/RAG semantics stay in the app plugin."
+    },
+    {
+      "pluginId": "plugin-documents",
+      "path": "plugins/plugin-documents",
+      "capability": "filesystem",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.fs",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Local file reads and searches should route through eliza.fs when running in the desktop shell."
+    },
+    {
+      "pluginId": "plugin-local-inference",
+      "path": "plugins/plugin-local-inference",
+      "capability": "model-provider",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": false,
+      "routeTo": "plugin-owned",
+      "collapseMode": "none",
+      "nonDesktopBehavior": "provider-owned",
+      "firstRoutingCandidate": false,
+      "risk": "low",
+      "notes": "The actual model runtime/provider layer remains plugin-owned."
+    },
+    {
+      "pluginId": "plugin-local-inference",
+      "path": "plugins/plugin-local-inference",
+      "capability": "local-model-control",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.local-model",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "provider-owned",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Desktop status, activation, download, and routing control should coordinate through eliza.local-model while the provider runtime remains in the plugin."
+    },
+    {
+      "pluginId": "plugin-native-talkmode",
+      "path": "plugins/plugin-native-talkmode",
+      "capability": "voice-pipeline",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": false,
+      "routeTo": "plugin-owned",
+      "collapseMode": "none",
+      "nonDesktopBehavior": "provider-owned",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Talk mode remains the semantic voice participant. eliza.voice observes and coordinates rather than replacing it."
+    },
+    {
+      "pluginId": "plugin-native-screencapture",
+      "path": "plugins/plugin-native-screencapture",
+      "capability": "screen-capture",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "future.eliza.computer",
+      "collapseMode": "needs-owner-decision",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "high",
+      "notes": "Screen capture action semantics may stay plugin-owned, but desktop capture implementation likely belongs behind a future eliza.computer if overlap is confirmed."
+    },
+    {
+      "pluginId": "plugin-native-system",
+      "path": "plugins/plugin-native-system",
+      "capability": "terminal",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.pty",
+      "collapseMode": "needs-owner-decision",
+      "nonDesktopBehavior": "structured-unavailable",
+      "firstRoutingCandidate": false,
+      "risk": "high",
+      "notes": "System command execution should collapse into eliza.pty, but owner review is needed before changing native-system semantics."
+    },
+    {
+      "pluginId": "plugin-native-desktop",
+      "path": "plugins/plugin-native-desktop",
+      "capability": "browser-computer-use",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "future.eliza.computer",
+      "collapseMode": "needs-owner-decision",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "high",
+      "notes": "Desktop host/window implementation is a future eliza.computer candidate. Semantic desktop actions should not be deleted without owner review."
+    },
+    {
+      "pluginId": "plugin-computeruse",
+      "path": "plugins/plugin-computeruse",
+      "capability": "browser-computer-use",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "future.eliza.computer",
+      "collapseMode": "needs-owner-decision",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "high",
+      "notes": "Computer-use action semantics remain plugin-owned. Capture, input, window, and clipboard implementation may collapse behind a future eliza.computer."
+    },
+    {
+      "pluginId": "plugin-browser",
+      "path": "plugins/plugin-browser",
+      "capability": "browser-computer-use",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "future.eliza.computer",
+      "collapseMode": "needs-owner-decision",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "high",
+      "notes": "Browser bridge semantics remain plugin-owned. Desktop browser/window implementation overlap should be audited before any eliza.computer work."
+    },
+    {
+      "pluginId": "plugin-browser",
+      "path": "plugins/plugin-browser",
+      "capability": "filesystem",
+      "semanticLayerShouldRemain": true,
+      "implementationShouldCollapse": true,
+      "routeTo": "eliza.fs",
+      "collapseMode": "facade-over-remote",
+      "nonDesktopBehavior": "existing-plugin-fallback",
+      "firstRoutingCandidate": false,
+      "risk": "medium",
+      "notes": "Companion packaging and workspace artifact reads should use eliza.fs in desktop contexts after core coding paths are routed."
+    }
+  ]
+}

package/platforms/electrobun/docs/capability-collapse-matrix.md

@@ -0,0 +1,129 @@
+# Capability Collapse Matrix
+
+This matrix tightens the convergence audit by separating semantic plugin interfaces from desktop implementation paths. The rule is: collapse implementation, not meaning.
+
+## Executive Summary
+
+Plugins remain the elizaOS runtime extension layer. They own agent-facing actions, providers, services, routes, events, model handlers, connector semantics, and app/product semantics.
+
+Remotes own desktop/system implementation behind the Electrobun host boundary. A plugin should use a shared capability router when it needs local filesystem, terminal, local Git, or local model host coordination in the desktop shell. The router targets `eliza.runtime`, and `eliza.runtime` brokers to the concrete Remote.
+
+The first implemented routes are narrow `plugin-coding-tools` paths: FILE ls/read/write prefers `eliza.fs`, SHELL command execution prefers `eliza.pty`, and WORKTREE local Git helpers prefer `eliza.git` through the shared capability router. If the router is absent or explicitly unavailable, the existing local implementation remains the fallback.
+
+## Collapse Immediately Candidates
+
+| Plugin | Capability | Route | Mode | Risk |
+| --- | --- | --- | --- | --- |
+| `plugin-coding-tools` | filesystem list/read/write | `eliza.fs` | facade-over-remote | low |
+| `plugin-coding-tools` | terminal | `eliza.pty` | facade-over-remote | medium |
+| `plugin-coding-tools` | local Git | `eliza.git` | facade-over-remote | medium |
+
+These implementation paths are intentionally narrow. The FILE, SHELL, and WORKTREE actions still own agent-facing semantics, policy, output formatting, history/session state, secret rejection, and worktree stack behavior. Host filesystem, terminal, and local Git execution can come from Remotes through the capability router.
+
+## Facade-Over-Remote Candidates
+
+| Plugin | Capability | Route | Notes |
+| --- | --- | --- | --- |
+| `plugin-codex-cli` | filesystem | `eliza.fs` | Auth/config files are implementation details. |
+| `plugin-codex-cli` | terminal | `eliza.pty` | CLI process execution belongs behind PTY in desktop mode. |
+| `plugin-commands` | terminal | `eliza.pty` | Command semantics remain plugin-owned. |
+| `plugin-github` | local Git | `eliza.git` | GitHub API remains plugin-owned; local repo work routes to Git. |
+| `plugin-documents` | local files | `eliza.fs` | RAG/document semantics remain plugin-owned. |
+| `plugin-local-inference` | desktop model control | `eliza.local-model` | Provider runtime remains plugin-owned; desktop control routes through the Remote. |
+| `plugin-browser` | packaging/artifact filesystem | `eliza.fs` | Browser bridge semantics remain plugin-owned. |
+
+## Keep Plugin-Owned Candidates
+
+| Plugin | Capability | Reason |
+| --- | --- | --- |
+| `plugin-github` | GitHub API | External connector semantics stay in the connector. |
+| `plugin-documents` | document/RAG semantics | App/plugin semantics stay in the plugin. |
+| `plugin-local-inference` | model provider/runtime | Actual provider runtime stays plugin-owned. |
+| `plugin-native-talkmode` | voice pipeline semantics | `eliza.voice` observes and coordinates; it does not replace talk mode. |
+| connector plugins | connector | Discord, Google, Farcaster, Matrix, iMessage, and similar connectors stay plugins. |
+| provider plugins | model/provider | OpenAI, OpenRouter, Ollama, LM Studio, MLX, and similar providers stay plugins. |
+| app plugins | app semantics | Documents, training, task/workflow, browser-style app bundles stay app plugins. |
+
+## Future eliza.computer Candidates
+
+These are not Phase 19 implementation targets. They need overlap review before a new Remote exists.
+
+| Plugin | Capability | Decision |
+| --- | --- | --- |
+| `plugin-computeruse` | screen, input, windows, clipboard | Semantic actions stay plugin-owned; host implementation may route to future `eliza.computer`. |
+| `plugin-browser` | browser/window host implementation | Browser bridge semantics stay plugin-owned; desktop implementation overlap needs review. |
+| `plugin-native-screencapture` | screen capture/recording | Capture action semantics may stay as plugin facade. |
+| `plugin-native-desktop` | desktop/window/system host access | Needs owner decision before collapse. |
+
+## Needs Owner Decision
+
+- Whether `eliza.computer` is justified after comparing `plugin-computeruse`, `plugin-browser`, `plugin-native-screencapture`, `plugin-native-camera`, `plugin-native-canvas`, and `plugin-native-desktop`.
+- Whether `plugin-native-system` has semantic actions worth preserving before command execution collapses into `eliza.pty`.
+- Whether `plugin-codex-cli` should keep local auth-file implementation in server mode while routing desktop mode through `eliza.fs`.
+
+## Do-Not-Collapse List
+
+- Connector plugins as connector semantics.
+- Provider plugins as provider semantics.
+- App plugins as app/product semantics.
+- `packages/app` production UI.
+- `packages/core` runtime ownership.
+- `packages/app-core/platforms/electrobun` shell ownership.
+- `eliza.surface`, which remains dev/admin only.
+- `plugin-local-inference` as the actual local model provider/runtime.
+- `plugin-native-talkmode` as the semantic voice-mode participant.
+
+## First Routing Implementation
+
+The routed paths are:
+
+```text
+plugin-coding-tools FILE ls/read/write
+  -> runtime.getService("capability-router")
+  -> router.fs.list() / router.fs.readText() / router.fs.writeText()
+  -> eliza.runtime fs.list / fs.readText / fs.writeText
+  -> eliza.fs
+
+plugin-coding-tools SHELL
+  -> runtime.getService("capability-router")
+  -> router.pty.runCommand()
+  -> eliza.runtime pty.command.run
+  -> eliza.pty
+
+plugin-coding-tools WORKTREE
+  -> runtime.getService("capability-router")
+  -> router.git.commandRun()
+  -> eliza.runtime git.command.run
+  -> eliza.git
+```
+
+If no router is registered, or if the router returns `CAPABILITY_UNAVAILABLE`, the existing sandboxed local implementation remains active. If the router is present and fails for any other reason, the action reports an `io_error` and does not bypass the failure through the local path.
+
+## Non-Desktop Behavior
+
+The shared fallback router returns structured `CAPABILITY_UNAVAILABLE` errors. Plugins with safe existing implementations may continue using those implementations when no router is registered. Plugins without a safe non-desktop implementation should return structured unavailable results instead of trying to reach Electrobun internals.
+
+## Remaining Conflicts
+
+- `plugin-coding-tools` still has direct local edit/search paths that need per-operation Remote parity before routing.
+- `plugin-browser` and `plugin-computeruse` overlap with possible future `eliza.computer` scope.
+- `plugin-local-inference` must keep provider ownership while `eliza.local-model` controls desktop status/routing.
+- `plugin-native-system` needs owner review before any implementation collapse.
+
+## plugin-coding-tools FS Parity Decision
+
+Do not route the remaining edit/search paths through `eliza.fs` as a batch. Route them only after explicit per-method parity is in place.
+
+| Path | Current plugin behavior | Current `eliza.fs` parity | Decision |
+| --- | --- | --- | --- |
+| `FILE action=ls` | Session cwd fallback, absolute path validation, ignore globs, directory-first ordering, file/dir/symlink display, 1000-entry cap. | `fs.list` has root guard, hidden/generated exclusions, limits, typed stats, ignore patterns, and truncation metadata. `plugin-coding-tools` still owns cwd fallback, sandbox validation, and output formatting. | Routed through `capability-router.fs.list()` with local fallback when the router is absent or explicitly unavailable. |
+| `FILE action=grep` | Ripgrep-backed regex search with output modes, glob/type filters, context flags, case-insensitive and multiline options, head limit, VCS excludes. | `fs.search` is literal case-insensitive substring search with path/root/limit/includeHidden only. | Do not route yet. Add a first-class search method with regex mode, literal mode, case sensitivity, multiline support, include/exclude glob filters, type filters, VCS/generated exclusion policy, context-before/context-after, head limit, deterministic ordering, structured file/line/column match records, truncation metadata, and explicit unsupported-option errors. |
+| `FILE action=glob` | File globbing with VCS/generated excludes, recent-file ordering by mtime, 100-result cap. | No direct glob/list-recursive method with pattern semantics. | Do not route yet. Add a first-class glob/find method with cwd/root policy, one or more patterns, hidden/generated/VCS exclusion policy, file/dir/symlink filters, max-results, deterministic recent-file ordering where requested, typed file metadata, truncation metadata, and explicit unsupported-option errors. |
+| `FILE action=edit` | Must-read-first/stale-read gate, exact substring replacement, optional replace-all, ambiguity protection, secret detection, line reporting. | `fs.writeText` overwrites full text only and has no compare-and-swap, old-string match, patch, secret gate, or read-state contract. | Do not route through generic write. Add a first-class edit/patch method with read-state or expected-digest protection, exact old-string replacement, replace-all behavior, ambiguity detection, first-changed-line metadata, secret-pattern rejection, atomic write behavior, and structured patch errors. |
+
+Safe routing order:
+
+1. `grep` and `glob`, only after search/glob semantics are explicit rather than approximated.
+2. `edit`, only after the Remote has a first-class edit/patch operation with stale-read or expected-content protection.
+
+The review boundary stays small: each method should land as its own commit with focused tests.

package/platforms/electrobun/docs/capability-routing.md

@@ -0,0 +1,86 @@
+# Capability Routing
+
+Capability routing keeps semantic plugin interfaces separate from desktop/system implementation.
+
+```text
+Agent
+  -> plugin action/provider/service
+  -> capability-router runtime service
+  -> eliza.runtime broker method
+  -> first-party Remote
+```
+
+Plugins do not import Electrobun main-process modules and do not call individual Remotes directly. The desktop router calls runtime methods such as `fs.list`, `fs.readText`, `fs.writeText`, `pty.command.run`, `git.status`, `git.diff`, `git.command.run`, and `model.status`. In Electrobun, `eliza.runtime` forwards those methods to `eliza.fs`, `eliza.pty`, `eliza.git`, or `eliza.local-model`.
+
+## Plugin Layer
+
+Plugins keep meaning:
+
+- connector protocols and remote APIs
+- model/provider semantics
+- app/plugin product semantics
+- voice-mode semantics
+- coding/document/workflow actions the agent can understand
+
+Implementation-only desktop paths can collapse behind the router without deleting the plugin action.
+
+## Remote Layer
+
+Remotes keep desktop/system implementation:
+
+- `eliza.fs`: local filesystem roots, lists, reads, writes, and search
+- `eliza.pty`: terminal sessions and command execution
+- `eliza.git`: local repository status, diff, log, and commands
+- `eliza.local-model`: desktop model status, catalog, activation, routing, and downloads
+
+`eliza.runtime` remains the broker. Plugins target the router, the router targets `eliza.runtime`, and `eliza.runtime` invokes the concrete Remote.
+
+## Fallback Behavior
+
+The shared fallback router returns structured `CAPABILITY_UNAVAILABLE` errors. A plugin may keep a safe existing fallback when no router is registered. A plugin should not silently fake successful desktop work when a registered router fails.
+
+## Routed Paths
+
+`plugin-coding-tools` FILE `ls` now prefers `capability-router.fs.list()` when the runtime has a `capability-router` service. FILE read prefers `capability-router.fs.readText()`. FILE write prefers `capability-router.fs.writeText()`. The action still owns:
+
+- the FILE semantic action
+- path validation through its sandbox service
+- session cwd fallback
+- directory-first listing output
+- read-state tracking for write/edit safety
+- numbered-line output formatting
+- secret-pattern rejection before write
+
+For `ls`, the router receives the validated directory path, ignore globs, and the requested listing limit. The effective cap remains governed by `eliza.fs` policy. If the router is absent or explicitly unavailable, the previous local implementation remains the fallback.
+
+Search remains plugin-owned until `eliza.fs` has method parity:
+
+| Path | Required `eliza.fs` parity before routing |
+| --- | --- |
+| `FILE action=grep` | A first-class search method with regex mode, literal mode, case sensitivity, multiline support, include/exclude glob filters, type filters, VCS/generated exclusion policy, context-before/context-after, head limit, deterministic ordering, structured file/line/column match records, truncation metadata, and explicit unsupported-option errors. The current literal `fs.search` method is not enough. |
+| `FILE action=glob` | A first-class glob/find method with cwd/root policy, one or more patterns, hidden/generated/VCS exclusion policy, file/dir/symlink filters, max-results, deterministic recent-file ordering where requested, typed file metadata, truncation metadata, and explicit unsupported-option errors. Directory `fs.list` is not enough. |
+| `FILE action=edit` | A first-class edit/patch method with read-state or expected-digest protection, exact old-string replacement, replace-all behavior, ambiguity detection, first-changed-line metadata, secret-pattern rejection, atomic write behavior, and structured patch errors. Generic `fs.writeText` is not enough and must not be used for edit routing. |
+
+`plugin-coding-tools` SHELL now prefers `capability-router.pty.runCommand()` for command execution. The action still owns command parsing, timeout selection, terminal support checks, history recording, and output formatting.
+
+`plugin-coding-tools` WORKTREE now prefers `capability-router.git.commandRun()` for `git worktree add` and `git worktree remove --force`. The action still owns the worktree stack, sandbox root registration, and session cwd transitions.
+
+## Remaining Work
+
+- Route remaining `plugin-coding-tools` edit/search file operations through `eliza.fs` only where the Remote has matching primitives.
+- Route local file reads/search in documents/browser-adjacent plugins through `eliza.fs` where desktop-only.
+- Keep GitHub API, provider APIs, app semantics, and voice semantics plugin-owned.
+- Decide whether `eliza.computer` is justified before changing computer-use, browser, or native screen/camera/canvas implementation.
+
+## Audited Follow-Up Candidates
+
+The current safe immediate routing set is still `plugin-coding-tools` FILE `ls/read/write`, SHELL, and WORKTREE Git. The next candidates need narrower interfaces before code moves:
+
+| Area | Current owner | Decision |
+| --- | --- | --- |
+| `plugin-coding-tools` grep/glob | `plugin-coding-tools` | Keep plugin-owned until `eliza.fs` exposes first-class search and glob/find methods with the documented parity. |
+| `plugin-coding-tools` edit | `plugin-coding-tools` | Keep plugin-owned until `eliza.fs` exposes a first-class edit/patch method. Do not route through generic `writeText`. |
+| `plugin-agent-orchestrator` coding sessions | `plugin-agent-orchestrator` | Keep session, workspace, runner, and credential semantics plugin-owned. Route only low-level process/filesystem work after a coding-session adapter is explicit. |
+| `plugin-computeruse` desktop control | `plugin-computeruse` | Keep plugin-owned until a reviewed `eliza.computer` surface exists. Screen, input, windows, clipboard, and app control are not just PTY calls. |
+| `plugin-codex-cli` auth files | `plugin-codex-cli` | Keep credential/auth semantics plugin-owned. File access can route later only if credential storage semantics stay intact. |
+| `plugin-github` credentials/API | `plugin-github` | Keep connector credentials and GitHub API plugin-owned. Route local repo operations only when they are actual local Git, not GitHub API work. |

package/platforms/electrobun/docs/database-boot-policy.md

@@ -0,0 +1,90 @@
+# Database Boot Policy
+
+Database startup is Electrobun launch infrastructure. It is not a Remote and
+it is not onboarding.
+
+## Resolution Order
+
+1. `POSTGRES_URL` wins and starts the runtime in Postgres mode.
+2. `DATABASE_URL` maps to `POSTGRES_URL` when `POSTGRES_URL` is missing.
+3. `ELIZA_DB_MODE=memory` selects `PGLITE_DATA_DIR=memory://`.
+4. `PGLITE_DATA_DIR` selects explicit PGlite mode.
+5. Packaged desktop uses persistent PGlite under app state:
+
+```text
+<appState>/database/pglite
+```
+
+Development without a database env is reported as `unknown`; the child runtime
+keeps its own development policy, and launch diagnostics records the warning.
+
+## PGlite Path
+
+Packaged desktop never stores PGlite under the repo, cwd, temp directory, or app
+bundle resources. The parent process creates and verifies the app-state path
+before spawning the agent runtime.
+
+## Startup Lock
+
+Persistent PGlite startup uses an adjacent startup lock:
+
+```text
+<pgliteDataDir>.startup.lock
+```
+
+The lock records pid and timestamp. A live lock blocks a second startup owner.
+A stale lock can be removed during the next explicit startup attempt.
+
+## Migration Visibility
+
+Agent stderr is parsed for plugin-sql migration lifecycle messages. Launch
+diagnostics reports:
+
+```text
+starting
+migrating
+migration-failed
+ready
+locked
+corrupt
+permission-error
+path-error
+```
+
+Database failure is shown as launch failure. It must not send the user back to
+onboarding.
+
+## Recovery
+
+Recovery actions are explicit:
+
+```text
+retry
+open-logs
+backup
+reset-pglite
+switch-to-postgres
+```
+
+Reset creates a backup first under:
+
+```text
+<database>/pglite-backups/<timestamp>
+```
+
+The reset helper refuses memory mode, app bundle paths, broad paths, and paths
+that do not end in `pglite` or `.elizadb`.
+
+## Diagnostics
+
+`LaunchSnapshot.database`, `desktop:getStartupDiagnostics`, and database RPCs
+expose the same `DatabaseSnapshot`:
+
+```text
+database:status
+database:recoveryPreview
+database:backupPglite
+database:resetPglite
+```
+
+Credential-bearing Postgres URLs are redacted before logging or diagnostics.