Add introspection and visibility observation

doc/OBSERVATIONS.md

@@ -1,11 +1,42 @@
-# System Observations
+# Observations
 
-## Introspection and State Visibility
+**Filesystem as interface** — if you know how to operate a filesystem, you know how to operate ollie. Any tool that reads and writes files — `ed`, `vim`, Python, `cat`, a shell script — is already a fully capable ollie client. No SDK, no API, no protocol to learn.
 
-A significant architectural strength of Ollie is the total transparency of agent state via the 9P filesystem. When tasked with "introspecting" on a complex, multi-agent session, the orchestrator demonstrated the ability to:
+**Simple front-ends** — A front-end reads `chat`, writes `prompt`, polls `state`. There is no protocol to implement.
 
-1. **Direct Log Inspection**: Use standard file tools (`tail`, `grep`) to read the `chat` and `prompt` files of subagents. This allowed for the recovery of semantic state even when agents failed to use established notification protocols.
-2. **Context Synthesis**: Combine current session memory (what the orchestrator "knew" it had done) with data extracted from peer sessions.
-3. **Cross-Session Verification**: Directly verify that requested changes (e.g., commits, file deletions) were actually performed by inspecting the state of the relevant worktrees and `git` history, rather than merely taking the subagent's word for it.
+**Crash resiliency** — Memory (`m/`) is written to persistent storage outside the session. If a session crashes or is killed mid-task, it is not lost — a fresh session picks up where the previous one left off.
 
-This "God-mode" visibility ensures that "stuck" states or "hallucinations" are not black boxes; they are observable system states that can be diagnosed and corrected through standard administrative primitives.
+**[Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool)** — Anthropic describes code execution as "a foundational primitive for building high-performance agents." ollie takes that literally: `execute_code` is the only built-in tool. It is a pipeline executor — single stage, multi-stage, and parallel fan-out are all the same primitive. New capabilities are added by dropping a script into `t/` and a skill in `sk/`.
+
+**Parallel execution** — `execute_code` accepts a `steps` array of pipeline stages. A `{parallel: [...]}` stage fans out concurrently within the pipeline. Sequential stages chain stdout → stdin. All stages accept inline code and named tool scripts interchangeably.
+
+**Radical transparency** — The rendered system prompt for any session is readable at `s/{id}/systemprompt` — the prompt the agent is actually running with, not a reconstruction. The prompt parts that compose it live in `p/`; the agent can read its own instructions but cannot modify them.
+
+**Discoverability** — `ls s/{id}/` shows every control surface. `cat t/idx` and `cat sk/idx` list available tools and skills. `cat help` explains the rest.
+
+**Composability** — `execute_code` stages chain the same way Unix pipes chain programs. Sessions chain by reading `s/{id}/chat` and writing to another session's `prompt` or `fifo.in`.
+
+**Passive memory** — Every session's chat history accumulates at `s/{id}/chat`, searchable with `grep`. An agent doesn't need to actively decide what to remember. This extends across sessions: an agent can search another session's chat for answers that have already been worked through.
+
+**Sub-agents** — `subagent_spawn` creates an independent session under `s/`, submits a prompt, and returns immediately with the session path. Subagents coordinate with the parent and each other by writing to each other's `prompt` files — direct async message passing over the filesystem. For parallel spawn, a `{parallel: [...]}` stage in `execute_code` starts multiple subagents simultaneously.
+
+**No MCP** — MCP (Model Context Protocol) adds a JSON-RPC client, transport layer, initialization handshake, and subprocess lifecycle management to do what `execute_code {tool: "name"}` already does. Every MCP server can be replaced by a tool script in `t/` and a skill in `sk/`. `x/elevate` proved this: it replaced an MCP server with a shell script. See [doc/NO_MCP.md](NO_MCP.md) for the full justification.
+
+**Introspection and State Visibility** — A significant architectural strength of Ollie is the total transparency of agent state via the 9P filesystem. When tasked with "introspecting" on a complex, multi-agent session, an agent demonstrated the ability to (1) use standard file tools (`tail`, `grep`) to read the `chat` and `prompt` files of subagents to recover semantic state, (2) synthesize current session memory with data extracted from peer sessions, and (3) directly verify that requested work was performed by inspecting worktrees and `git` history. This ensures that hallucinations and stuck states are observable system states that can be diagnosed and corrected through standard administrative primitives.
+
+**AI pipelines with standard tools** — ollie scripts compose into multi-stage AI pipelines via Unix pipes. Proof-of-concept:
+
+```
+; u/optimize -n 2 -cm qwen/qwen3-8b -jm 'anthropic/claude-opus-4.6' 'generate a hello world program. use c++.' >[2]/dev/null | s/bfg
+```
+
+`u/optimize` generates and judges candidate prompts, emitting the best to stdout; `s/bfg` acts on it. Any tool that reads stdin and writes stdout is already a pipeline stage.
+
+**Prompt composition** — `s/bfg` outputs can be nested to arbitrary depth using shell command substitution. The inner prompt completes, its output becomes part of the outer prompt:
+
+```
+; echo 'translate to japanese: '`echo 'say hello' | s/bfg` | s/bfg
+こんにちは！👋
+```
+
+This enables prompt pipelines where each stage transforms, filters, or augments the previous stage's output — all with standard shell syntax.