Findings: per-agent skills API, memory stack, MOUSE-1 policy, the old office scaffold, the dashboard endpoint

docs/PLAN-INTERFACE.md

@@ -201,3 +201,112 @@ a second language and a second round trip. Worth doing once the functional tests
 **Mouse-1 and Switch.** Still not installed on this machine. Unchanged from the earlier
 note: they would serve cheap repeatable judgement, later, after they are installed and
 measured.
+
+---
+
+# Findings for the next round of decisions, 2026-11-10
+
+Everything below was measured on this machine. Nothing here is proposed without saying so.
+
+## Skills per agent — the API already models it
+
+`GET /api/agents/{id}/skills` returns, for each agent:
+
+```
+mode: "persistent"
+desiredSkills: ["paperclipai/paperclip/paperclip"]
+entries: [
+  { key: "company/<id>/obsidian-cli", runtimeName: "obsidian-cli--b74ae42966",
+    desired: false, managed: true, state: "stale",
+    sourcePath: "…/instances/default/skills/<id>/obsidian-cli",
+    targetPath: "/home/sam/.pi/agent/skills/obsidian-cli--b74ae42966" }
+]
+```
+
+So Paperclip already models exactly what is wanted: a desired set per agent, a managed set
+actually installed, and a state (`stale` today for `obsidian-cli` on `Builder`, which is
+worth fixing on its own). `POST /api/agents/{id}/skills/sync` with `add`, `remove` or
+`replace` sets the desired set; `replace` is the operation that means "this agent gets these
+and nothing else", which is how a sub-agent's context is kept small.
+
+Company level, there is more: `GET/POST /api/companies/{id}/skills` (the catalog),
+`/skills/{id}/versions`, `/skills/{id}/audit`, and `GET/PUT /api/companies/{id}/skill-policy`
+with `/skill-policy/evaluate`, which is a company-wide rule about which skills may be used.
+
+Proposed in the interface: `Agents>agents` settings tab gains two rows — **skills** (the
+desired set, read-only at first, with `add`/`remove` later) and **skill source** (company
+catalog or the agent's own). A full skill browser is a later screen, not a panel.
+
+## Memory — three different things wearing one word
+
+| What | State here | What it does |
+|---|---|---|
+| **engram** | installed, `engram v1.16.1`, MCP server mode, no pi MCP entry yet | persistent memory for agents, over HTTP or MCP |
+| **headroom** | running, `headroom-proxy v0.24.0`, healthy at `192.168.20.13:8787`, memory backend **disabled**, compression enabled | compresses prompts on the way out; it is a proxy, not a store |
+| **pi memctx** | in use in this session | the memory gateway that injects notes into a prompt |
+
+They are not alternatives: engram stores, headroom compresses, memctx injects. For agents,
+the only lever Paperclip gives us is per-agent configuration — `adapterConfig` (the folder,
+the model, the instructions bundle) and `runtimeConfig` — so memory is set per agent by
+pointing that agent at the proxy or the storage it should use, not by a global switch.
+
+Proposed: a **memory** row in `Agents>agents` settings showing which of the three that agent
+uses, read from its adapter configuration; and nothing more until one agent has been run
+both ways and the difference measured.
+
+## MOUSE-1
+
+- `MOUSE_API_KEY` **is** set in `~/.config/environment.d/10-secrets.conf` (name checked, value
+  never printed). `JEV_API_KEY` is set as well.
+- No `mouse`, `mouse1`, `jev` or `switch` binary is installed.
+- The previous project already wrote the policy, in
+  `~/paseo/projects/tuios_coding_harness/plan/*`: MOUSE-1 is **"triage only: label, score,
+  route, escalate. Never a gate, never a permit"**, and explicitly ruled out for deciding a
+  merge or allowing a tool call, because a cheap classifier that fails open on a network
+  error turns a green run into a lie.
+
+That policy is right and should be adopted unchanged. Its place in this interface, if it is
+added: `Board>board` needs-you could be ordered by a MOUSE-1 score, and `Work>review` could
+use it to pre-sort findings. Never the merge, never an approval.
+
+## Lazygit
+
+Already wired: `t` in `Board>board` or `Work>work`, then choose Lazygit. It opens beside the
+pane, in the same workspace, and `q` closes it. Hunk, Yazi, Neovim, fzf, a shell and ocr are
+in the same chooser.
+
+## The old `office` command, and what ours is missing
+
+The previous project's `office` does four things, in order:
+
+1. makes the folder and remembers the host in `<folder>/.harness/host`;
+2. runs `new-project` to write the project scaffold — `settings.toml`, one file per role,
+   `verify.sh`, the per-screen notes — **writing only what is missing, never overwriting**;
+3. refuses to continue if the TUIOS session does not exist, and prints the exact
+   `tuios new <session>` line to run;
+4. runs its `board` to build or repair the pages, then prints how to attach.
+
+Ours does 1, 3 and 4 (with a different file: `.harness/harness.toml`). It does **not** do 2:
+there is no scaffold, no per-role file, no `verify.sh`, no page notes. That is a real gap and
+the cheapest useful one to close.
+
+## Dashboard — the API already answers it
+
+`GET /api/companies/{id}/dashboard` returns 1.8 KB:
+
+```
+agents: {active: 6, running: 0, paused: 0, error: 0}
+tasks:  {open: 8, inProgress: 0, blocked: 4, done: 147}
+costs:  {monthSpendCents: 11, monthBudgetCents: 0, monthUtilizationPercent: 0}
+pendingApprovals: 0
+budgets: {activeIncidents: 0, pendingApprovals: 0, pausedAgents: 0, pausedProjects: 0}
+runActivity: [14 entries]
+```
+
+That is a whole dashboard in one call, and it is cheap enough to poll. Proposal: a
+`Project>overview` panel showing those four blocks and a sparkline of `runActivity`, drawn in
+Go with `tuios.dev/plot` rather than embedding Paperclip's web dashboard.
+
+## Not doing
+
+Artifacts, as instructed. Nothing about them will be added.