Document one-tool capability bootstrap

doc/architecture-9p.md

@@ -20,6 +20,11 @@ The Ollie namespace is declared in `cmd/olliesrv/internal/fs/spec.go`, materiali
 
 `olliesrv` listens on the Unix socket selected by `$NAMESPACE`. It can also expose the same server on an optional TCP address. The TCP listener speaks the same 9P protocol and namespace; it does not add an HTTP or JSON API.
 
+Agents use the same namespace to bootstrap capabilities. A minimal profile can
+start with only `client_9p`; it loads another tool by writing
+`tool_load <name>` to its own `agent/{name}/ctl` file. The tool becomes callable
+after the runtime refreshes its toolsrv registry revision.
+
 Use `ollie-9p` for direct operations:
 
 ```sh

doc/architecture-core.md

@@ -122,6 +122,7 @@ type Runtime struct {
     Preamble        *Preamble
     Tools           []backend.Tool
     ToolMeta        map[string]protocol.ToolInfo
+    ToolRevision    uint64
     Exec            toolExecutor
     GenParams       backend.GenerationParams
     MaxSteps        int
@@ -135,7 +136,7 @@ type Runtime struct {
 
 `BuildRuntime(cfg, runner, cwd, env)` wires everything together:
 
-1. Lists all tools from the runner
+1. Lists the agent’s currently loaded tools from the runner and records the agent-scoped registry revision
 2. Resolves the system prompt by executing the config's `prompt` commands
 3. Extracts generation parameters from the config
 4. Builds the tool executor closure (routes calls through the runner)
@@ -188,7 +189,15 @@ On the first error, the `turnError` hook fires. If it exits 0 (handled), the loo
 
 ### Tool Execution
 
-Tool calls are dispatched with parallelism awareness:
+Tool calls are dispatched with parallelism awareness. Tool schemas are
+loaded progressively: the default profile starts with `client_9p`, and semantic
+tool hints tell the agent to issue `tool_load <name>` through its agent `ctl`
+file.
+
+After a tool round, the agent compares the toolsrv agent-scoped registry
+revision with `Runtime.ToolRevision`. If the revision changed, it lists the
+loaded tools, rebuilds backend schemas and metadata, and updates the rendered
+tool preamble before the next model request.
 
 1. Classify each call from the tool metadata and dispatch flags.
 2. Batch read-safe calls when the metadata permits parallel execution.

doc/architecture-embedding.md

@@ -89,10 +89,11 @@ each turn
 ```
 
 Relevant skills are injected as a `<skills>` block containing complete skill
-content. Relevant tools are injected as a `<tool-hints>` block containing
+content. Relevant tools are injected as a `<tool-hints>` block containing names and
-callable names and descriptions. The normal tool registry still controls
+descriptions plus the `client_9p` operation needed to load them. Semantic
-whether a tool is loaded and executable; semantic matching only improves what
+matching does not grant capability: the normal per-agent registry still
-the model sees first.
+controls whether a tool is loaded and executable. The model must load a hinted
+tool through the agent `ctl` file before calling it.
 
 The bounded result limits prevent discovery from becoming a prompt-size or
 context-budget problem. This progressive disclosure is especially useful for

doc/architecture-prompting.md

@@ -46,7 +46,10 @@ The default configuration uses installed prompt files under `$XDG_CONFIG_HOME/ol
 
 ## Tool rendering
 
-When tools are enabled, `BuildRuntime` calls the configured `ToolsrvConn` once to obtain tool metadata. The metadata becomes both:
+When tools are enabled, `BuildRuntime` calls the configured `ToolsrvConn` to obtain the
+agent’s currently loaded tool metadata and its registry revision. The default
+profile starts with only `client_9p`; additional tools are loaded through the
+agent `ctl` file and become available after the runtime refreshes its schemas. The metadata becomes both:
 
 - the backend function/tool definitions, with dispatch flags added to each schema; and
 - the rendered `# Tools` preamble section.

doc/architecture-tools.md

@@ -179,7 +179,17 @@ A metadata-only tool needs only the first command. Test its command contract wit
 echo '{"pattern":"TODO"}' | bash -c 'YOUR_CMD'
 ```
 
-Agent profiles can load tools at startup with `autoLoad`. See [`architecture-toolsrv.md`](architecture-toolsrv.md) for discovery, loading, registry, and execution architecture.
+Agent profiles may load tools at startup with `autoLoad`, but the default profile
+uses an empty list and starts with only `client_9p`. Semantic tool hints tell the
+agent to load additional tools through its own `ctl` file:
+
+```text
+client_9p(op="rdwr", path="session/$OLLIE_SESSION_ID/agent/$OLLIE_UNAME/ctl", data="tool_load <name>")
+```
+
+After loading, the agent refreshes its model-facing schemas when the toolsrv
+registry revision changes. See [`architecture-toolsrv.md`](architecture-toolsrv.md)
+for discovery, loading, registry, and execution architecture.
 
 ## Repository examples
 

doc/architecture-toolsrv.md

@@ -80,6 +80,7 @@ The Ollie client generates a secret for the first connection, saves it for recon
 ├── tools
 ├── all
 ├── info
+├── tools_rev
 ├── bypass/
 │   ├── pending
 │   └── resolve
@@ -102,6 +103,7 @@ The Ollie client generates a secret for the first connection, saves it for recon
 | `tools` | read/write | write an agent ID, then read its loaded tool list as JSON |
 | `all` | read | list all host-available tools and descriptions |
 | `info` | read | return `platform` and `arch` |
+| `tools_rev` | read/write | write an agent ID, then read that agent’s loaded-tool registry revision |
 
 `tools` reads the registry for the supplied agent ID. `all` calls metadata discovery directly and is not the per-agent loaded set.
 
@@ -145,7 +147,10 @@ type Registry struct {
 
 The registry is deliberately separate from discovery. Discovery describes every tool available on the host. Loading makes a tool callable for one agent. `Load` resolves current metadata and increments that agent's revision. `Unload` removes the tool and increments the revision. `Loaded` returns tools sorted by name. `Lookup` resolves one loaded tool.
 
-The agent client polls or reads the tool listing after loading changes. The registry does not inspect executable contents.
+The agent client reads `tools_rev` after tool rounds and refreshes its loaded-tool
+schemas only when the agent-scoped revision changes. A zero revision means the
+revision endpoint is unavailable, so the client falls back to refreshing. The
+registry does not inspect executable contents.
 
 ## Request payloads and results
 

doc/evolution.md

@@ -97,6 +97,7 @@ gantt
     Split session/agent indexes    :done, 2026-08-17, 1d
     Agent peers + consensus        :done, 2026-08-19, 1d
     Embedding-guided discovery     :done, 2026-08-20, 1d
+    One-tool bootstrap discovery   :done, 2026-08-21, 1d
 ```
 ## Phase 1: Monorepo Bootstrap (Apr 11)
 Started as independent git repos unified under a monorepo with submodules.
@@ -1956,3 +1957,41 @@ disclosure keeps the prompt bounded. The embedding model is local and separate
 from the conversational backend, so provider choice does not affect discovery.
 
 ---
+
+## Phase 36: One-Tool Bootstrap and Progressive Capability Loading (Aug 21)
+
+The default agent profile now starts with exactly one callable tool: `client_9p`.
+The previous static `autoLoad` list was removed. This makes the runtime
+capability surface explicit: the agent can begin with the namespace client and
+load everything else through its own agent `ctl` file.
+
+Semantic matching remains a hint, not an implicit capability grant. When a
+request matches a tool description, the agent receives the tool name and the
+9P operation required to load it. The model calls `client_9p` with:
+
+```text
+rdwr session/$OLLIE_SESSION_ID/agent/$OLLIE_UNAME/ctl
+tool_load <name>
+```
+
+The agent runtime refreshes its model-facing schemas after a load or unload.
+`toolsrv` exposes an agent-scoped `tools_rev` request/response file so the
+client can detect registry changes without rebuilding tool state on every tool
+round. A revision of zero is treated as unavailable and preserves the safe
+refresh behavior.
+
+This completes the progressive-disclosure path:
+
+```text
+client_9p → agent ctl → toolsrv registry → loaded tool schema → tool call
+```
+
+The important boundary is unchanged. `olliesrv` still owns prompting and the
+agent loop; `toolsrv` remains authoritative for discovery, loading, execution,
+sandboxing, and process state. The change removes ambient startup capability
+without adding a new orchestration subsystem.
+
+The `client_9p` script also expands `$OLLIE_SESSION_ID` and `$OLLIE_UNAME` in
+virtual namespace paths. This is required because JSON argument parsing does not
+perform shell expansion, and keeps the documented namespace examples directly
+callable by the model.