docs: add progressive disclosure and agentic retrieval tools to architecture docs

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bg6jx9vHNHzB91qyV64GQ7

docs/external/architecture-brief.en.md

@@ -20,13 +20,15 @@ The platform sits between the provincial trading, dispatch and metering systems
 
 ![Agent runtime](img/02-agent-runtime.png)
 
-Workflows are the entry point, not agents. Every business process (day-ahead bidding, review, intraday correction) is a deterministic, durable chain of steps. Agents are invoked at specific steps with a whitelisted tool set. Scheduled and event triggers instantiate workflow templates without touching the LLM. Only manual requests pass through the router agent, whose output is constrained by schema to a registered template ID plus parameters. The LLM decides *what* to do; the engine decides *how*. Every trigger, step, tool call, transition, approval and permit is written to an event-sourced log.
+Workflows are the entry point, not agents. Every business process (day-ahead bidding, review, intraday correction) is a deterministic, durable chain of steps. Agents are invoked at specific steps with a whitelisted tool set: computation skills that produce numbers, and read-only retrieval tools that fetch detail on demand. Scheduled and event triggers instantiate workflow templates without touching the LLM. Only manual requests pass through the router agent, whose output is constrained by schema to a registered template ID plus parameters. The LLM decides *what* to do; the engine decides *how*. Every trigger, step, tool call, transition, approval and permit is written to an event-sourced log.
 
 ## 3. Context management and memory
 
 ![Context and memory](img/03-context-memory.png)
 
-Context for each agent step is assembled by a deterministic upstream step that reads the versioned ledger, immutable snapshots, explicitly declared semantic memory and effective knowledge entries. The agent does not decide what to look up, so every decision is reproducible. Agent output carries numbers only as references into recorded tool-call lineage. The assembler dereferences them, which means LLM text cannot carry a number into a proposal.
+Context for each agent step is assembled by a deterministic upstream step that reads the versioned ledger, immutable snapshots, explicitly declared semantic memory and effective knowledge entries. The agent does not choose its baseline context, so every decision starts from a reproducible footing. Agent output carries numbers only as references into recorded tool-call lineage. The assembler dereferences them, which means LLM text cannot carry a number into a proposal.
+
+Context is built by **progressive disclosure**. The baseline is compact: summaries, identifiers and the few figures a step needs, sized for a conservative context window. Detail is disclosed on demand through **agentic retrieval tools**: read-only, whitelisted registry tools such as rule retrieval, ledger reads, snapshot fetches and forecast lookups that an agent may call when it needs more. Each retrieval is recorded in lineage with its inputs and outputs, so what the agent saw is replayable, and prompt-injection defences treat retrieved content as data, never as instructions. The same principle shapes the operator side: an insight card shows the conclusion first and expands, on request, into the tool outputs and data sources behind it.
 
 Three memory layers serve different lifetimes. Working memory lives for one task. Episodic memory is the event log and time-series store, permanent and queried rather than recalled. Semantic memory holds structured lessons written back by the D+1 review workflow, versioned and injected explicitly by each template. Authoritative operational facts always live in the domain database, never in agent memory.
 

docs/external/diagrams/gen.mjs

@@ -119,22 +119,24 @@ const out = {}
 // ---------- 3. context & memory ----------
 {
   let b = ''
-  b += group(30, 40, 1140, 210, 'Context assembly for one agent step')
+  b += group(30, 40, 1140, 275, 'Context assembly for one agent step · deterministic baseline + progressive disclosure')
   const src = [['Position ledger', 'versioned read'], ['Time-series / snapshots', 'immutable, checksummed'], ['Semantic memory', 'lessons declared by template'], ['Knowledge base (RAG)', 'effective rules only']]
   src.forEach(([t, s], i) => { b += box(50 + i * 180, 70, 165, 60, t, [s], { fill: C.slate, tsize: 12.5, ssize: 11 }) })
-  b += box(50, 170, 705, 55, 'fetchContext step (deterministic, reproducible)', ['the agent does not decide what to look up'], { fill: C.tealSoft, stroke: C.teal, tsize: 13 })
+  b += box(50, 170, 705, 55, 'fetchContext step (deterministic, reproducible)', ['compact baseline: summaries, identifiers, the few figures a step needs'], { fill: C.tealSoft, stroke: C.teal, tsize: 13 })
+  b += box(50, 240, 705, 55, 'Agentic retrieval tools · read-only · whitelisted · every call logged into lineage', ['rule retrieval · ledger read · snapshot fetch · forecast lookup — detail disclosed on demand, retrieved content tagged as data'], { fill: C.white, stroke: C.teal, tsize: 12.5, ssize: 11 })
+  b += arrow(755, 267, 790, 267, '', { both: true })
   for (let i = 0; i < 4; i++) b += arrow(132 + i * 180, 130, 132 + i * 180, 170)
-  b += box(790, 70, 170, 155, 'Agent step', ['prose + tool calls', 'numbers only as', '{toolCallId, path}', 'references'], { fill: C.amberSoft, stroke: C.amber, tag: 'LLM' })
+  b += box(790, 70, 170, 225, 'Agent step', ['prose + tool calls', 'numbers only as', '{toolCallId, path}', 'references'], { fill: C.amberSoft, stroke: C.amber, tag: 'LLM' })
   b += arrow(755, 197, 790, 197)
-  b += box(995, 70, 160, 155, 'Assembler', ['dereferences refs', 'from recorded lineage', '→ Proposal', 'LLM text cannot', 'carry a number'], { fill: C.tealSoft, stroke: C.teal })
+  b += box(995, 70, 160, 225, 'Assembler', ['dereferences refs', 'from recorded lineage', '→ Proposal', 'LLM text cannot', 'carry a number'], { fill: C.tealSoft, stroke: C.teal })
   b += arrow(960, 147, 995, 147)
 
-  b += group(30, 280, 1140, 165, 'Three memory layers')
-  b += box(50, 315, 355, 105, 'Working memory', ['current task context, intermediate results', 'runtime memory · task lifetime', 'step-to-step parameters preferred over memory'], { fill: C.white })
-  b += box(423, 315, 355, 105, 'Episodic memory', ['operating states, trading, control, responses', 'event log + time-series · permanent (audit)', 'queried through fetchContext, not recalled'], { fill: C.white })
-  b += box(796, 315, 355, 105, 'Semantic memory', ['structured lessons from D+1 review', 'knowledge + strategy store · versioned', 'written by ReviewFinding, injected explicitly'], { fill: C.white })
-  b += text(30, 475, 'Authoritative facts live in the domain database, never in agent memory (invariant I8). No automatic memory recall feeds production decisions.', { size: 12, fill: C.ink2, anchor: 'start', italic: true })
-  out['03-context-memory'] = svg(1200, 495, b)
+  b += group(30, 345, 1140, 165, 'Three memory layers')
+  b += box(50, 380, 355, 105, 'Working memory', ['current task context, intermediate results', 'runtime memory · task lifetime', 'step-to-step parameters preferred over memory'], { fill: C.white })
+  b += box(423, 380, 355, 105, 'Episodic memory', ['operating states, trading, control, responses', 'event log + time-series · permanent (audit)', 'queried through fetchContext, not recalled'], { fill: C.white })
+  b += box(796, 380, 355, 105, 'Semantic memory', ['structured lessons from D+1 review', 'knowledge + strategy store · versioned', 'written by ReviewFinding, injected explicitly'], { fill: C.white })
+  b += text(30, 540, 'Authoritative facts live in the domain database, never in agent memory (invariant I8). No automatic memory recall feeds production decisions.', { size: 12, fill: C.ink2, anchor: 'start', italic: true })
+  out['03-context-memory'] = svg(1200, 560, b)
 }
 
 // ---------- 4. safety chain state machine ----------

docs/external/system-architecture.en.md

@@ -130,6 +130,8 @@ This compresses non-determinism to the smallest necessary scope: the LLM decides
 
 Two further disciplines are enforced in code. Context for each agent step is assembled deterministically by upstream steps (database queries, ledger reads, knowledge retrieval), so decisions are reproducible. And agent outputs carry numeric fields only as references to recorded tool calls, which the proposal assembler dereferences. The LLM cannot type a number into a proposal.
 
+Context follows progressive disclosure. The deterministic baseline is compact and sized for a conservative context window: summaries, identifiers and the few figures a step needs. Beyond it, an agent can pull detail on demand through agentic retrieval tools, which are read-only, whitelisted registry tools such as rule retrieval, ledger reads, snapshot fetches and forecast lookups. Every retrieval is recorded in lineage with its inputs and outputs, so what the agent saw is replayable, and retrieved content enters the prompt tagged as data rather than instructions.
+
 ### 5.2 The five agents
 
 Each agent is defined by a role, a context-building strategy, a set of workflow templates, a whitelisted tool set, a memory view and the business objects it produces.