@awebai/oats 0.22.12 → 0.22.16

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -44,7 +44,7 @@ const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ sche
 // --help/-h never runs a command here either (the kernel answers it from the
 // manifest since 0.22.6; this keeps an older kernel from spawning a harvester).
 if (process.argv.slice(2).some((a) => a === "--help" || a === "-h")) {
-  process.stdout.write("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never spawns\noats okf status [--json]\n");
+  process.stdout.write("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never runs it\noats okf inspect [--json]  answer this instance's working knowledge (STATE.md, log.md, pending notes) as labeled documents\n");
   process.exit(0);
 }
 const event = process.env.OATS_EVENT || process.argv[2];
@@ -473,6 +473,30 @@ _(the single next action — keep this current; a fresh session on any model res
     if (JSON_MODE) jsonFail(e.code || "E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);
     warnFail(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
   }
+} else if (event === "inspect") {
+  // VIEW OPERATION (kernel contract, docs/design/operations-contract.md):
+  // the instance's working knowledge as labeled documents, read from the
+  // home this command runs in. Text only; paths are provenance for the
+  // reader. Answers the JSON-v1 envelope regardless of --json.
+  try {
+    const CAP = 256 * 1024;
+    const doc = (label, file) => {
+      if (!existsSync(file)) return null;
+      const bytes = readFileSync(file);
+      const truncated = bytes.length > CAP;
+      let text = truncated ? bytes.subarray(0, CAP).toString("utf8") : bytes.toString("utf8");
+      if (truncated && text.endsWith("\uFFFD")) text = text.slice(0, -1);
+      return { label, kind: "markdown", path: file, text, ...(truncated ? { truncated: true, bytes: bytes.length } : {}) };
+    };
+    const documents = [doc("Working state (STATE.md)", join(home, "STATE.md")), doc("Log (log.md)", join(home, "log.md"))].filter(Boolean);
+    const notesDir = join(home, "notes");
+    const notes = existsSync(notesDir) ? readdirSync(notesDir).filter((f) => f.endsWith(".md")).sort() : [];
+    for (const f of notes) { const d = doc(`Pending note: ${f}`, join(notesDir, f)); if (d) documents.push(d); }
+    const summary = documents.length ? `${documents.length} document${documents.length === 1 ? "" : "s"}: ${existsSync(join(home, "STATE.md")) ? "state" : "no state"}, ${existsSync(join(home, "log.md")) ? "log" : "no log"}, ${notes.length} pending note${notes.length === 1 ? "" : "s"}` : "no working memory in this home yet (STATE.md, log.md and notes/ are written by the instance)";
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result: { summary, documents } }) + "\n"); process.exit(0);
+  } catch (e) {
+    process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code: "E_INSPECT_FAILED", message: String(e.message || e).slice(0, 300) } }) + "\n"); process.exit(1);
+  }
 } else if (event === "retire") {
   // Retirement is intentionally a no-op for knowledge (for now): promotion happens
   // continuously via agent-initiated harvest. Uncommitted notes die with the home —
@@ -480,5 +504,5 @@ _(the single next action — keep this current; a fresh session on any model res
   // before finishing.
   out({ meta: {} });
 } else {
-  warn(`unknown event "${event}" (expected soul-scaffold|spawn|retire)`);
+  warn(`unknown event "${event}" (expected soul-scaffold|spawn|retire|harvest|inspect)`);
 }

package/capabilities/oats-okf/oats.json

@@ -1,12 +1,12 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "compatibility": {
     "oats": ">=0.22.3"
   },
   "layer": "knowledge",
-  "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator.",
+  "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator; declares the operations a GUI or schedule may run (inspect, harvest).",
   "requires": [],
   "settings": {
     "harvest-runtime": {
@@ -29,11 +29,26 @@
     "skills"
   ],
   "commands": {
-    "harvest": "bin/oats-okf.mjs harvest"
+    "harvest": "bin/oats-okf.mjs harvest",
+    "inspect": "bin/oats-okf.mjs inspect"
   },
   "inject": "injects/okf.md",
   "hooks": {
     "soul-scaffold": "bin/oats-okf.mjs soul-scaffold",
     "spawn": "bin/oats-okf.mjs spawn"
+  },
+  "operations": {
+    "inspect": {
+      "kind": "view",
+      "command": "inspect",
+      "context": "home",
+      "description": "Show this instance's working knowledge: STATE.md, log.md and pending notes"
+    },
+    "harvest": {
+      "kind": "action",
+      "command": "harvest",
+      "context": "home",
+      "description": "Promote this instance's pending notes (or captured record) into its soul by spawning a memory-harvest worker"
+    }
   }
 }

package/docs/capabilities.md

@@ -503,3 +503,10 @@ The source packages live under `capabilities/`. Acquired packages live under
 `<level>/.agents/capabilities/installed/` (gitignored, restorable); packages
 authored at a scope live under `<level>/.agents/capabilities/owned/`
 (committed where the scope is a git repo). Within one scope `owned/` overrides `installed/` on ID collision.
+
+## Operations a capability declares
+
+A manifest may declare `operations` (named actions or views delegating to
+its own commands) that a GUI or a schedule invokes through `oats operation
+run <layer>:<name>`; `oats inspect --json` reports them with availability.
+See [docs/design/operations-contract.md](design/operations-contract.md).

package/docs/capability-manifest.schema.json

@@ -150,6 +150,38 @@
         "minLength": 1
       }
     },
+    "operations": {
+      "description": "Named operations a GUI or scheduler may invoke through `oats operation run`, each delegating to one of this manifest's commands. kind \"view\" answers { documents: [{label, kind, path, text}] }; \"action\" (default) runs something. context \"home\" (default) runs in an instance home, \"scope\" in the config scope.",
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["command"],
+        "additionalProperties": false,
+        "properties": {
+          "command": { "type": "string", "minLength": 1 },
+          "kind": { "enum": ["action", "view"] },
+          "context": { "enum": ["home", "scope"] },
+          "description": { "type": "string" },
+          "args": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["name"],
+              "additionalProperties": false,
+              "properties": {
+                "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+                "flag": { "type": "string", "pattern": "^--[a-z][a-z0-9-]*$" },
+                "required": { "type": "boolean" },
+                "description": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    },
     "hooks": {
       "type": "object",
       "properties": {

package/docs/design/2026-09-07-architecture-reassessment.md

@@ -0,0 +1,131 @@
+# Architecture reassessment: usable agents with replaceable services
+
+Assessment of main `76c0ea4`, September 7, 2026. Requested by Juan after
+operating the Desktop; incorporates Pepe's terminal, shortcut, split and soul
+management feedback. This records the direction and implementation gaps, not a
+claim that every item below has shipped.
+
+The requirements authority for this assessment is Juan's September 3
+“Architecture simplification and generlization” in his OATS project KB:
+souls carry instructions and capabilities; a harvester converts ephemeral
+state into knowledge accessible through the selected knowledge capability;
+packages distribute souls and capabilities; OATS constructs and operates
+instances across runtimes and platforms. The private Bookshelf README points
+to September 1's adoption/sovereignty strategy. Its relevant constraint is that
+changing a runtime or service provider must not erase the team's relationships
+or working knowledge. The older August proposals about genomes, clothes and
+turn-record experiments are background, not reasons to expand this release.
+
+## Decision
+
+Keep the existing package and capability-layer mechanism. Correct the places
+where the CLI and GUI bypass it. The architecture is broadly right; the
+operator experience and some service boundaries are incomplete. More
+abstractions will not fix a terminal that cannot accept a screenshot.
+
+| Component | Owns | Must not assume |
+|---|---|---|
+| OATS kernel | Soul/instance construction, configuration, lifecycle, host placement, scheduling, capability resolution | A particular knowledge provider, messaging service, or GUI |
+| Session backend | Durable terminal, attach/detach, resize, literal input, observation | OATS soul/package semantics or task success |
+| Knowledge capability | Knowledge access and representation; its harvester and promotion policy | Every installation uses OKF or stores memory in the same files |
+| Messaging capability / aweb | Durable messages, identities, event subscriptions and delivery policy | A particular model harness or an open Desktop window |
+| Task capability | Durable work and task semantics | A particular terminal backend |
+| Desktop | Inspect effective configuration; explicit operator actions; terminal input, files, layout | Provider names, SSH commands, or a second lifecycle implementation |
+
+Scheduling belongs to OATS, and a scheduled harvest is one use of scheduling.
+Harvesting behavior belongs to the knowledge capability. Starting an agent,
+writing a prompt, and producing reviewed knowledge are different outcomes.
+The UI must retain those distinctions.
+
+## What already fits, and what does not
+
+`lib/core.mjs` already selects exclusive knowledge/messaging/tasks layers by
+manifest, resolves scoped capability settings, dispatches lifecycle hooks, and
+materializes runtime instructions. Jira and Linear demonstrate that a layer
+can have alternative implementations. OKF's harvester is already an exported
+capability agent. There is no reason to replace this machinery.
+
+The remaining coupling is concrete:
+
+- The retire receipt reads `hookResults.meta["oats.okf"].harvested`, although
+  current OKF does not supply a retire hook. Remove the dead provider-specific
+  inference; do not invent successful harvesting at retirement.
+- Remote capability routing recognizes `okf harvest` specifically in
+  `bin/oats.mjs` and `lib/servers.mjs`.
+- Desktop harvest actions and scheduled-harvest definitions construct
+  `oats okf harvest`; the editor recognizes that exact argv.
+- The “brain” view presents `STATE.md`, `log.md` and `notes/` as universal
+  knowledge structure. These are conventions of the current setup.
+
+The next service contract should expose the **effective knowledge provider and
+its supported operations for a specific soul/home**. Discovering a capability
+command namespace alone is insufficient: it does not promise a `harvest` verb
+or a shared file layout. A provider may offer harvest, different operations,
+or read-only access. Desktop must show only declared operations and route
+execution through the selected CLI capability. The same resolution must apply
+locally, remotely, and when a scheduled operation runs.
+
+Keep that change small: explicit operation metadata, scoped discovery, and one
+invocation route using the existing capability engine. Do not add a plugin
+framework, generic workflow language, or a second knowledge store. Demonstrate
+replaceability with a tiny alternative-provider fixture that uses a different
+command and storage layout; a full second product is unnecessary.
+
+## tmux and Herdr
+
+The current kernel defaults to a shared tmux session (`pi-agents`) with a
+window per instance. An agent does not require another tmux server. The GUI
+creates a temporary session linking only the selected window. That isolates
+viewers: switching a terminal elsewhere cannot redirect a GUI tab to another
+agent, and an agent exiting cannot silently expose a sibling under its label.
+The `oatsdesk-*` name in Juan's screenshot is this viewer. Its status bar can
+be hidden with a viewer-local setting. Do not alter global tmux settings or
+merge/move live agent sessions to solve a display defect.
+
+Herdr 0.8.2 is a separate terminal runtime, not a tmux-compatible superset.
+Its documented direct terminal attachment, socket API, events and SSH support
+are useful. Its semantic agent state comes from detection and/or integrations;
+it is richer evidence, not proof that a particular message was consumed.
+The [socket API](https://herdr.dev/docs/socket-api/) explicitly distinguishes
+agent-state waits from arbitrary command completion. The
+[remote documentation](https://herdr.dev/docs/persistence-remote/) also
+separates a local thin client from running a client entirely on the server;
+only the former can directly bridge the local desktop clipboard.
+
+Keep one OATS session contract and both existing adapters for now. Do not add
+another supervisor above them. Qualify Herdr's actual literal multi-line
+input, exact occupant checks, detach, resize, process exit and remote behavior
+before selecting it as the default for new instances. Inspect `pane run`
+implementation before replacing it merely because its name sounds like shell
+execution. Removing tmux is a later deployment choice, not a prerequisite for
+consistent UI or remote agents. Existing tmux agents stay where they are.
+
+## Desktop correction sequence
+
+1. **Terminal essentials.** Hide viewer chrome, accept dropped files and pasted
+   images without pressing Enter, upload remote files to the execution host,
+   preserve the destination tab across async work, and show transfer failures.
+   Keep a single GUI and bounded viewers. This is the immediate implementation.
+2. **Keyboard and splits.** Restore Ctrl+Tab navigation inside Mac terminals;
+   let an already-open terminal fill an empty split without a second attach;
+   expose draggable and keyboard-operable separators. Follow up specific
+   keyboard reports with real input tests, especially terminal editing keys
+   and non-US layouts. App shortcuts must not silently steal terminal edits.
+3. **Souls & capabilities.** Replace the launch-centric roster with a management
+   surface showing souls, installed capabilities, effective layer providers,
+   source/version, scoped activation and runtime defaults. Inspect and launch
+   are distinct actions. Edits use existing CLI operations with the exact scope
+   visible; installing a capability must not silently activate it. This is not
+   a marketplace or Team Builder project.
+4. **Provider-neutral operations.** Introduce the scoped operation contract
+   above, then use it for manual harvest, schedules and knowledge inspection.
+   No second hardcoded default is accepted as a generalization.
+5. **Operating rollout.** Enable schedules per team with the owner's learning
+   policy. Capture-lock recovery is a separate reliability issue affecting
+   unattended harvesting; it does not block arbitrary scheduled wakes.
+
+Acceptance must include real Electron file objects, actual terminal bytes,
+remote transfer hashes, split focus/resize without extra PTYs, and a provider
+replacement fixture. Unit tests of mocked argv alone do not establish these
+boundaries. Reuse the existing agents and GUI sparingly; no model is needed to
+exercise attachment transport or terminal layout.

package/docs/design/2026-09-07-desktop-souls-capabilities.md

@@ -0,0 +1,50 @@
+# Souls and capabilities in Desktop
+
+Selecting a soul opens its details. Launch and Schedule are explicit actions;
+Quick Open and Enter inspect instead of launching. The existing local Files
+browser remains available. It is separate from provider knowledge inspection.
+
+The inspector reads the kernel's `oats inspect --json` answer on selection,
+Refresh, or after an explicit mutation. The roster's eight-second poll never
+rescans capabilities or replaces an editor. Workspace changes invalidate old
+responses. Same-named souls are addressed by name plus agents root; instances
+are addressed by their exact home.
+
+The Capabilities button inspects workspace defaults, with a member-scope
+selector where a workspace contains several roots. Installed version, source
+and health are separate from effective activation, provenance and settings.
+Enable, explicit disable and return to inheritance call `oats use`; layer-wide
+disable is distinct from excluding a single capability, and is available only
+when inspecting a workspace or member scope, never an individual soul. These changes apply to
+future instances. Existing homes retain their captured bindings and settings.
+
+Authored souls expose only the fields the kernel reports as editable. Desktop
+edits runtime, model, backend, YOLO, description and instructions through
+`oats soul set`. Packaged souls remain read-only and explain where their source
+must be changed. Instructions use a private temporary file; the CLI owns remote
+transfer and mutation. Desktop does not modify YAML or resolve capabilities.
+
+An instance's action menu opens Knowledge & capabilities. The kernel supplies
+its snapshot, differences from current configuration, and declared provider
+operations. View operations return labeled documents; Desktop renders their
+text and treats remote paths as provenance, never as local files to open. Actions
+without required arguments can run here. Operations requiring arguments explain
+that they need the CLI. No provider is assumed to support harvesting.
+
+Schedules store an operation address and exact home with the kernel's generic
+`operation` job kind. The form discovers declared, available actions on demand.
+The server verifies that declaration again at save time, and the kernel resolves
+and validates the provider at execution time. Existing command schedules remain
+visible and runnable, but the GUI does not reverse-parse their argv to edit them.
+
+Every capability request requires an exact advertised workspace. Remote requests
+require its saved server registration and the CLI's operations API feature; all
+routing stays in OATS. The consumer never performs SSH or silently substitutes a
+local workspace. The proxy allows the CLI's bounded operation to return its
+receipt before timing out.
+
+Validation: scope/identity and remote-route refusal; private instructions and
+failure cleanup; declared schedule actions; stale inspection/save responses;
+provider text rendering; explicit launch and existing runtime flows. Native
+Electron rendering is checked with a temporary fixture frame in the existing
+GUI, without starting a model, agent, or another application instance.

package/docs/design/operations-contract.md

@@ -0,0 +1,123 @@
+# Provider operations and inspection contract
+
+Implemented 2026-09-07 on the existing capability engine. The kernel
+resolves providers; a GUI reads one answer and calls the commands below.
+Nothing here names a provider: what a knowledge, messaging or tasks
+capability offers is what its manifest declares.
+
+## Manifest: operations
+
+```json
+"operations": {
+  "harvest": { "kind": "action", "command": "harvest", "context": "home", "description": "Promote this instance's notes into its soul" },
+  "inspect": { "kind": "view",   "command": "inspect", "context": "home", "description": "Show this instance's working knowledge" }
+}
+```
+
+`command` names one of the manifest's `commands`. `kind` is `action`
+(default) or `view`. `context` is `home` (default; runs in an instance
+home) or `scope` (runs in the config scope). Optional `args` declare
+`{name, flag, required, description}`; the runner passes `--arg name=value`
+pairs as those flags and refuses unknown or missing required ones. A view
+must answer `{ documents: [{ label, kind: "markdown"|"text", path?, text? }],
+summary? }`; the kernel validates that shape and relays it. Paths are
+provenance for the reader; the kernel reads nothing for a view. Validation
+happens when the manifest loads (`docs/capability-manifest.schema.json`).
+
+## oats inspect
+
+`oats inspect [--dir <scope>] [--soul <name> [--agents-root <abs>]] [--home
+<abs>] [--server <id>] --json` answers, in one envelope: `scope` (context,
+workspace, team, chain, agentsRoots); `souls` (persistent, local and
+packaged, each with runtime defaults, `editable {fields, instructions,
+reason}`, instances, and for the selected soul its `instructions {file,
+text, sha256, bytes, truncated, error}` capped at 256 KiB of bytes on a
+character boundary); `layers` (effective provider per layer); `capabilities`
+(installed state and `health` from the package engine, `missingRequires`,
+and separately `activation {enabled, source, target, level, provenance,
+settings, declaredAt}` plus `operations` with `available` and a `reason`);
+`knowledge` (the effective knowledge provider's operations); `snapshot` and
+`currentConfig` with `--home`; `problems`.
+
+A `--home` answer is authoritative for that home: activation, settings,
+layers and operation availability come from the home's captured bindings
+with the currently acquired manifests and current trust, marked `source:
+"snapshot"`; the live config is `currentConfig`, and `snapshot.drift`
+lists activation, settings and integrity differences. The home selects its
+own soul under its own agents root (its recorded work repository may be
+another repository); `--dir`, if given, must be the recorded repository or
+the workspace of that root, and `--agents-root` must be that root
+(`E_HOME_MISMATCH`). Without a home, `--dir` is the config context and
+same-named souls under two member roots need `--agents-root`
+(`E_SOUL_AMBIGUOUS`). The ambient `PI_AGENTS_ROOT` never redirects these
+commands. Integrity scanning happens only in this command.
+
+## oats operation run
+
+`oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir
+<scope>] [--agents-root <abs>]) [--arg k=v ...] --json` resolves the
+provider that fills `<layer>` for the home (captured bindings and settings)
+or for the soul in the scope (config), requires the operation to be declared
+(`E_OPERATION_UNKNOWN`), a provider to exist (`E_OPERATION_UNAVAILABLE`,
+also for a home-context operation without `--home`), the executable surface
+to be trusted (`E_CAPABILITY_BLOCKED`) and its `requires` to be on PATH
+(`E_CAPABILITY_REQUIRES`), then runs the provider's own command exactly as
+`oats <ns> <cmd>` would, with cwd and identity set to the selected target
+(`OATS_HOME`, `OATS_INSTANCE`, `OATS_AGENT`, `OATS_SOUL`, `OATS_ROOT`,
+`OATS_CONTEXT`, `OATS_WORKSPACE`, `OATS_OPERATION`, `OATS_SETTINGS`,
+`OATS_CLI_BIN`, team variables) and every ambient identity of the invoking
+process removed. The answer is `{ operation, capability, version, argv,
+cwd, target: {home, instance}|null, result, instance?, home? }`; top-level
+`instance`/`home` appear only when the provider's answer names something it
+launched, never the source home.
+
+The receipt must be exactly one JSON-v1 envelope on stdout from a process
+that exits 0. Otherwise the outcome is unconfirmed: `E_OPERATION_TIMEOUT`
+(240 s, below every wrapper) or `E_OPERATION_RESULT` (no valid envelope,
+contaminated output, or a success envelope contradicted by the exit
+status), with `error.details {unconfirmed: true, exit, envelope?, stderr?}`
+carrying what was observed. A provider's own `ok: false` is relayed with
+its code.
+
+## Schedules
+
+Kind `operation` `{operation: "<layer>:<name>", home}` runs `oats operation
+run <op> --home <home>` as a command job: same admission, tracking and
+reconciliation. An unconfirmed outcome keeps the slot as unknown and any
+name the provider answered is kept for `oats schedule reconcile`.
+
+## Mutations
+
+`oats use ... --json` answers `{ capability, action: enable|disable|
+layer-none|inherit, target, layer, level, file, settings, before, after
+{..., effective}, remaining?, note?, missingRequires }`. `--inherit`
+removes only the addressed target at this level; other bindings stay and
+are listed. `use none --layer l` is a level statement and takes no soul or
+type. A layer bound to another capability at a level is never overwritten
+(`E_LAYER_BOUND` with the exact remedy).
+
+`oats soul set <name> [--dir] [--agents-root] [--runtime] [--model |
+--no-model] [--yolo | --no-yolo] [--backend] [--description |
+--no-description] [--instructions-file <path>] --json` edits only the given
+`soul.yaml` lines and replaces `AGENTS.md`; packaged souls are refused
+(`E_SOUL_READONLY`). The receipt carries before/after and sha256s.
+
+## Remote
+
+`inspect`, `operation`, `use` and `soul` route with `--server <id>` through
+the saved route. The gate is the destination's `features` list containing
+`operations` and its `operationsApi: 1` (`E_REMOTE_INCOMPATIBLE` before
+anything is sent): `features` describes what a kernel can do locally, which
+is what runs on the host. The probe's `remote` list describes what a CLI
+can ROUTE to a server and is what a GUI checks on the local CLI before
+offering remote actions; it is not a gate on the destination. An explicit `--dir` is the exact member context and
+travels as is; `--home` is its own context; otherwise the registered
+workspace is the scope. Soul instructions travel as bytes on the ssh stdin
+(`--instructions-stdin` on the host), never as a local path.
+
+## Replaceability
+
+`test/inspect.test.mjs`, `test/operation.test.mjs` and
+`test/operations-routing.test.mjs` use an owned alternative knowledge
+provider (namespace `notes`, one `MEMORY.md`, operations `harvest` and
+`inspect`) and never mention the official provider.

package/docs/desktop.md

@@ -211,3 +211,19 @@ certificate auto-discovery disabled) and
 marked build-verify mode (inventory + strict codesign verification +
 node-pty ABI, no GUI launch); a local
 interactive run may also exercise the launch phase.
+
+### Attach files and screenshots
+
+Drop a file onto an agent terminal to insert its path into that agent's draft.
+Pasting an image from the clipboard uses the same attachment path. Neither
+operation presses Enter. Text paste continues to use the terminal's normal
+paste behavior. A drop targets the pane under the pointer, including a visible
+pane in a split.
+
+Local files are referenced in place. Clipboard images are saved privately in
+Desktop's application-data `attachments` directory and retained so an agent can
+read them later. For remote terminals, Desktop calls the installed CLI's
+`session upload` operation; it inserts the returned path only after the file
+has reached the execution host. Both CLI installations must advertise
+`session-upload`. A failed transfer leaves the draft unchanged and shows an
+error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.

package/docs/execution-targets.md

@@ -181,6 +181,27 @@ pane in that exact window. Herdr additionally verifies the original terminal ID.
 The broker owns busy/approval policy and must not interpret `submitted` as
 processing acknowledgement.
 
+### Attachments
+
+A viewer that drops a file or pastes an image gives the agent a path, never
+terminal input. `oats session upload --file <local> --home <abs>` stores a
+copy as a private file under `<home>/.oats-attachments/` (directory 0700,
+file 0600, `name-2` on collision) and answers `{path, bytes, sha256}`; the
+caller pastes `path` into the still-live session itself. With `--server <id>`
+and `--instance <name>` (or `--home`), the same saved route as attach is
+resolved, the remote must list `session-upload` in both its `remote` and
+`features` probe arrays, and the bytes travel on ssh stdin into `oats session
+receive --home <abs> --name <file>` on the execution host. Each side holds
+the whole file in memory up to the 64 MiB kernel bound (this is a bounded
+transfer, not end-to-end streaming); the receiver reads stdin event-driven,
+refuses above the bound before writing, and allocates the destination
+exclusively (`name-2`, `name-3` when taken), so simultaneous uploads of one
+name never overwrite each other and a planted symlink is never followed. The
+attachments directory must be a real directory inside the home. The local
+side refuses the result unless the remote's size and sha256 equal the local
+file's. A remote file is never a local path over SSH. Attachments live and
+die with the home.
+
 Capability spawn hooks register a pending home before runtime allocation;
 inspection becomes available once its receipt is persisted. Retire hooks
 unregister after quiescence. The broker must tolerate this lifecycle order and

package/docs/release-notes/v0.22.13.md

@@ -0,0 +1,44 @@
+# OATS v0.22.13
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/docs/release-notes/v0.22.14.md

@@ -0,0 +1,48 @@
+# OATS v0.22.14
+
+The same reviewed content as the unpublished v0.22.13 tag, whose hosted
+run failed in one Desktop test pin before anything was published; the
+test now checks the behaviour instead of the source text.
+
+Terminal essentials for the Desktop and one kernel operation behind them:
+attachments reach the agent as a path, never as typed input.
+
+## Attachments (kernel)
+
+`oats session upload --file <local> --home <abs>` copies a file into the
+instance home's private `.oats-attachments/` directory (0700, file 0600,
+`name-2` when the name is taken) and answers `{path, bytes, sha256}`. With
+`--server <id> --instance <name>` (or `--home`), the same saved route as
+`session attach` is resolved, the remote must advertise the new
+`session-upload` feature, and the bytes travel on ssh stdin into
+`oats session receive --home <abs> --name <file>` on the execution host,
+which reads stdin event-driven, enforces the 64 MiB kernel bound before
+writing anything, allocates the destination exclusively so simultaneous
+uploads never overwrite each other, refuses a symlinked or redirected
+attachments directory, and reports the path only after the bytes are
+synced. The local side refuses the answer unless size and sha256 equal the
+local file's. Each side buffers the whole file up to the bound; a remote
+file is never a local path over SSH. Upload never sends terminal input.
+`oats version --json` lists `session-upload` in `remote` and `features`.
+The CLI's temporary tmux viewer session hides its status line; the agents'
+session and the operator's tmux settings are untouched.
+
+## Desktop
+
+Drop files or paste clipboard images onto an agent terminal: the paths are
+inserted into the draft with bracketed paste and no Enter, local files in
+place, clipboard images saved privately under the app's data directory, and
+remote terminals uploaded through the installed CLI first (both CLIs must
+advertise `session-upload`; a failed transfer leaves the draft unchanged and
+never inserts a local path). Up to 16 files and 25 MB per drop. The viewer's
+tmux status bar is hidden. Ctrl+Tab stays tab navigation inside terminals
+on macOS while other Ctrl chords stay with the program. An already-open
+terminal fills an empty split without a second attach; separators resize by
+pointer or keyboard. Guide: docs/desktop.md, "Attach files and screenshots".
+
+## Design
+
+docs/design/2026-09-07-architecture-reassessment.md records the direction:
+keep the package and capability-layer machinery, fix the places where the
+CLI and GUI bypass it, one session contract with both tmux and Herdr
+adapters until Herdr is qualified, and the Desktop correction sequence.

package/docs/release-notes/v0.22.15.md

@@ -0,0 +1,48 @@
+# OATS v0.22.15
+
+Souls and capabilities become something you inspect and manage, through
+one kernel contract, and knowledge providers declare what they can do.
+
+## Provider operations and inspection (kernel)
+
+`oats inspect --json` answers everything a GUI needs in one envelope for a
+scope, a selected soul or a running home: souls with runtime defaults,
+editability and instructions; installed capabilities with health from the
+package engine, separately from their effective activation, provenance and
+settings; effective layer bindings; and the operations each provider
+declares, with availability and the reason when unavailable. For a home the
+answer is its captured bindings (with current manifests and trust), the live
+config beside it, and the drift between them. Same-named souls in member
+repositories are addressed by name plus agents root; a home selects its own
+soul under its own root.
+
+`oats operation run <layer>:<name>` resolves the provider that fills a layer
+for a home or a soul, checks declaration, trust and host requirements, runs
+the provider's own command in the right place with the right identity, and
+relays its receipt; a view answers labeled documents. Unconfirmed outcomes
+carry what was observed and a scheduled operation keeps its slot until
+reconciled. Manifests declare `operations`. Schedules gain kind
+`operation`. `oats use --json` answers receipts and `--inherit` returns a
+level to inheritance; `oats soul set` edits an editable soul's defaults and
+instructions in place. All four route to a registered server through the
+saved route; the probe advertises `operations` and `operationsApi: 1`. The
+retire receipt no longer implies a harvest. See
+docs/design/operations-contract.md.
+
+## oats.okf 1.6.0
+
+The official knowledge provider declares `inspect` (a view of STATE.md,
+log.md and pending notes) and `harvest` (the existing action); the catalog
+pins v1.6.0. Existing scopes keep their locked 1.5.2 until their owners
+update them; the GUI then shows no operations for those providers, which is
+the truthful state.
+
+## Desktop
+
+Souls & capabilities replaces the launch-centric roster: select a soul to
+inspect it, Launch and Schedule are explicit, defaults and instructions are
+editable where the kernel says so, installed capabilities are shown apart
+from activation with enable, disable and inherit at an exact scope, an
+instance's menu opens Knowledge & capabilities, provider views render as
+text, and schedules run declared provider operations. See
+docs/design/2026-09-07-desktop-souls-capabilities.md.