docs(readme): the okf server as a lookup during a run, with a validated example config

README section with a before/after command and the limits stated plainly (link not yet tried in a
real run, agent adherence not measured, --prepass-payload rejects okf-consumption/2). Adds
examples/okf-server.mcp.json, pinned by a test that loads it through load_mcp_config; the
published-surface pin moves 516 -> 518 for the two new files.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -51,6 +51,7 @@ holds, not that the model reasons well.
 - [Status - v1.2.0](#status---v120)
 - [Install](#install)
 - [Walk the whole chain offline](#walk-the-whole-chain-offline)
+- [Looking things up during a run: the `okf` server](#looking-things-up-during-a-run-the-okf-server)
 - [Non-goals](#non-goals)
 - [Built on an LLM wiki: Karpathy's idea, Google's format](#built-on-an-llm-wiki-karpathys-idea-googles-format)
 - [AI-first, humans on top](#ai-first-humans-on-top)
@@ -350,6 +351,51 @@ per amount, before anything is summed.
 > not run the loop. `--scripted-replies` runs the whole loop. The two are mutually exclusive and
 > passing both is refused rather than one silently winning.
 
+## Looking things up during a run: the `okf` server
+
+`llm-ingestion-okf` v1.1.0 ships an MCP server, `okf mcp --root <folder>`. Point a run at it and
+the agents can look things up in every knowledge base under that folder *while they debate*, instead
+of relying only on the base you passed with `--bundle-dir`. It offers four tools: `okf_list` (which
+bases exist), `okf_describe` (a one-line-per-document map of one base), `okf_ask` (ranked excerpts
+for several sub-questions in one call, with a warning when the base does not seem to cover the
+question) and `okf_fetch` (one concept by name).
+
+**What you need.** `okf` 1.1.0 or newer installed and on your `PATH`. That is separate from the
+library pin in `pyproject.toml`, which does not change. Copy
+[`examples/okf-server.mcp.json`](examples/okf-server.mcp.json), replace the placeholder path in
+`args` with your folder of knowledge bases, and leave the rest.
+
+**Before** - an ordinary run:
+
+```bash
+uv run portfolio-optimiser BYGG-KONTOR-NORD \
+  --bundle-dir shared/examples/bygg-energi-mikro \
+  --mandate mandate.json --run-id demo-01 --outbox-dir out \
+  --profile local --max-rounds 3 --max-tokens 200000
+```
+
+**After** - the same run with one line added, `--mcp-config`:
+
+```bash
+uv run portfolio-optimiser BYGG-KONTOR-NORD \
+  --bundle-dir shared/examples/bygg-energi-mikro \
+  --mandate mandate.json --run-id demo-02 --outbox-dir out \
+  --profile local --max-rounds 3 --max-tokens 200000 \
+  --mcp-config examples/okf-server.mcp.json
+```
+
+Without `--mcp-config` the framework runs exactly as before: no network calls, unchanged tool list.
+With it, the server and each allowed tool are named in the announcement before the first call, and
+`--live-dry-run` opens nothing.
+
+**Limits, stated plainly.**
+
+- The link between this framework and the `okf` server has **not been tried in a real run**. Only
+  the config file is validated (`tests/test_okf_server_example.py`, against the same loader a run
+  uses).
+- It is **not measured** whether the agents follow the way of working the server describes.
+- `--prepass-payload` does not accept the v1.1 format (`okf-consumption/2`). That is a known gap.
+
 ## Non-goals
 
 - **Not a compliance product.** It ships the technical prerequisites — local-only operation,

examples/okf-server.mcp.json

@@ -0,0 +1,12 @@
+{
+  "servers": [
+    {
+      "name": "okf",
+      "transport": "stdio",
+      "command": "okf",
+      "args": ["mcp", "--root", "/path/to/folder/with/your/knowledge-bases"],
+      "allowed_tools": ["okf_list", "okf_describe", "okf_ask", "okf_fetch"],
+      "timeout_seconds": 120
+    }
+  ]
+}

tests/test_b_gate.py

@@ -601,7 +601,7 @@ _WRITERS_DEFINED = 10
 _WRITERS_IN_RUN_PATH = 7
 #: publiserte filer i git-manifestet (uttrekk og arbeidstre gir SAMME tall — det var hele poenget
 #: med å slutte å telle filtreet: 435 i arbeidstreet var to gitignorerte .local.md-filer).
-_PUBLISHED_TODAY = 516
+_PUBLISHED_TODAY = 518
 _UNDECODABLE_TODAY = 1
 
 

tests/test_okf_server_example.py

@@ -0,0 +1,24 @@
+"""The committed example that wires the ``okf`` MCP server into a run must load through the same
+fail-fast loader a real run uses -- a config in the README that ``load_mcp_config`` refuses is a
+broken instruction, not documentation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from portfolio_optimiser.mcp_tools import load_mcp_config
+
+EXAMPLE = Path(__file__).resolve().parent.parent / "examples" / "okf-server.mcp.json"
+
+
+def test_okf_server_example_loads_through_the_run_loader() -> None:
+    (server,) = load_mcp_config(EXAMPLE)
+    assert server.name == "okf"
+    assert server.transport == "stdio"
+    assert set(server.allowed_tools) == {"okf_list", "okf_describe", "okf_ask", "okf_fetch"}
+    assert server.timeout_seconds > 0
+
+
+def test_okf_server_example_carries_a_neutral_placeholder_path() -> None:
+    text = EXAMPLE.read_text(encoding="utf-8")
+    assert "/Users/" not in text and "/home/" not in text