docs: align README and prompt docs with the real runtime semantics

README described target-state features that the previous migration
left half-implemented. Now that the runtime actually matches the
promise, the docs can stop overselling: agent messaging is
described as the real live-steer + inbox flow, approvals as the
beforeToolCall gate that actually blocks destructive tools,
sessions as the transformContext-driven compaction plus rotation.
The architecture bullet list grows to name the seams that landed
across this migration — the pi contract wiring, the approval gate,
the workspace lock model, and the stripped startup mutations — so
the README reads like documentation rather than roadmap.

The filesystem prompt doc (`files.en.md`) adds the missing
preamble: every bash/write/edit succeeds into work_products
automatically, and the API endpoints below are only needed for
non-filesystem deliverables. Agents were routinely posting
duplicate work products because nothing told them the projection
already ran.

README.md

@@ -64,7 +64,7 @@ CEO builds the org chart from one goal.
 </p>
 
 ### Agent messaging
-Threads and DMs between agents. Messages land in each recipient's transcript as pi `AgentMessage` turns.
+Threads and DMs between agents. Direct / department / project / company / incident channels resolve to wake targets; each message lands in the recipient's transcript as a pi `AgentMessage` turn. If the recipient is already running, the message is delivered live via pi's steer queue; if not, it waits in the inbox until the next prepareRun.
 
 <p align="center">
   <img src="screenshots/AI-Internal-Realtime-Message.jpeg" width="700" alt="Agent messaging" />
@@ -78,7 +78,7 @@ Goals break into tasks. Agents pick them up, report progress, escalate blockers.
 </p>
 
 ### Approvals
-Hiring, deliverables, plan/scope/strategy reviews, budget overrides, production deploys pause for the board.
+Hiring, deliverables, plan/scope/strategy reviews, budget overrides, production deploys pause for the board. The same approval policy gates the agent's destructive tools (`bash` / `write` / `edit`) via pi's `beforeToolCall` hook, so a pending approval stops file and shell mutations instead of just flagging them after the fact.
 
 <p align="center">
   <img src="screenshots/Approval-by-Human.jpeg" width="700" alt="Approvals" />
@@ -164,9 +164,12 @@ src/
 
 - SQLite local; no external services.
 - `contextIsolation: true`, `nodeIntegration: false`, Zod-validated IPC.
-- Worker constructs `new Agent({...})` from `@mariozechner/pi-agent-core` directly.
-- Sessions persist as `session_entries`; auto-compact via `shouldCompact` / `compact`.
+- Worker constructs `new Agent({...})` from `@mariozechner/pi-agent-core` with the full contract: `sessionId`, `thinkingLevel`, and the `beforeToolCall` / `afterToolCall` / `transformContext` hooks proxied back to `RuntimeBridge` on main.
+- Sessions persist as `session_entries`; long transcripts auto-compact at LLM-call time via a pure `transformContext` reducer, and rotate at the long-cycle boundary.
+- `beforeToolCall` enforces the approval gate plus thread wait-state guard at the tool-execution layer; mid-run messages reach live agents through pi's steering queue.
+- Workspace locks are single-writer-per-repo — every resolved workspace is held exclusively for the duration of the run; contenders queue on the wakeup table.
 - Thread runtime (`conversation_threads` / `conversation_events` / `thread_wait_states`) sits above pi's `AgentMessage` stream.
+- Startup only runs schema migrations plus `interruptStaleRuns`; all other data-repair lives at the transition point or in explicit maintenance paths.
 
 ---
 

src/main/prompt-builder/api-docs/files.en.md

@@ -1,3 +1,8 @@
+### Filesystem artifacts (auto-registered)
+Every successful `write`, `edit`, or `bash` tool call is projected into the task's work_products automatically — you do NOT need to POST /api/work-products for files you create in the workspace. The projector reads workspace paths for `write` / `edit` directly and scans `git status` after `bash`; the desktop UI shows new/modified files without any extra API call.
+
+Use the document / work-product endpoints below only for non-filesystem deliverables (URLs, PRs, external services) or to enrich an auto-registered file (status, reviewState, summary).
+
 ### Create a Document
 POST /api/companies/{{companyId}}/documents
 Body: {