docs(readme): name the okf 1.1 server by full path -- a bare okf finds the 0.8.5 dependency

The example config now has the placeholder `/path/to/okf` for `command`, and the README explains
how to find the real path (`command -v okf` outside this project's environment). It also explains
why the bare name fails under `uv run`: it resolves to this framework's own okf 0.8.5, which has
no `mcp` command. A new pin asserts that the example's command is an absolute path; it was red at
daccdbe. The xfail smoke test stays as the measurement behind the rule.

Chose this over lifting the okf dependency to 1.1: it fixes the startup failure without a version
bump and without touching --prepass-payload.

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

README.md

@@ -360,10 +360,17 @@ bases exist), `okf_describe` (a one-line-per-document map of one base), `okf_ask
 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.
+**What you need.** `okf` 1.1.0 or newer, installed as its own tool (for example
+`uv tool install`). 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) and replace its two
+placeholders:
+
+- `command`: the **full path** to the `okf` 1.1 executable. Find it with `command -v okf` in a
+  shell where this project's environment is not active (after `uv tool install` it is usually
+  `~/.local/bin/okf`, written out in full). Do not write just `okf`. This framework depends on an
+  older `okf` library (0.8.5) whose own `okf` command has no `mcp`. Under `uv run` that one is
+  found first, and the server fails at startup with `invalid choice: 'mcp'`.
+- `args`: your folder of knowledge bases.
 
 **Before** - an ordinary run:
 
@@ -393,10 +400,8 @@ With it, the server and each allowed tool are named in the announcement before t
 - **Measured without a model** (`tests/test_okf_server_smoke.py`, against a small invented
   collection): through the same loader and tool builder a run uses, `okf` 1.1 offers exactly the
   four tools, `allowed_tools` narrows what is offered, `okf_list` names the collection and one
-  `okf_ask` returns the excerpt. **This works only when `command` is the full path to the `okf`
-  1.1 executable.** With the bare `okf` shown above, a run started with `uv run` or from an
-  activated environment finds this framework's own `okf` dependency (0.8.5) first. That version
-  has no `mcp` command, and the server fails at startup (`invalid choice: 'mcp'`).
+  `okf_ask` returns the excerpt. The same test shows that a bare `okf` in `command` fails under
+  `uv run`, which is why the example asks for the full path.
 - 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.
 

examples/okf-server.mcp.json

@@ -3,7 +3,7 @@
     {
       "name": "okf",
       "transport": "stdio",
-      "command": "okf",
+      "command": "/path/to/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_okf_server_example.py

@@ -22,3 +22,10 @@ def test_okf_server_example_loads_through_the_run_loader() -> None:
 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
+
+
+def test_okf_server_example_names_the_server_by_full_path() -> None:
+    """A bare ``okf`` resolves to this project's own okf 0.8.5 dependency (no ``mcp``) under
+    ``uv run`` or an activated environment -- measured in ``test_okf_server_smoke.py``."""
+    (server,) = load_mcp_config(EXAMPLE)
+    assert server.command is not None and Path(server.command).is_absolute()

tests/test_okf_server_smoke.py

@@ -155,14 +155,14 @@ async def test_allowed_tools_is_load_bearing_against_the_real_server(
     strict=True,
     raises=ToolException,
     reason=(
-        "MEASURED 2026-09-21: with the README's bare `okf` command and this environment's bin "
+        "MEASURED 2026-09-21 (why the README asks for a full path): with a bare `okf` command and this environment's bin "
         "first on PATH (as under `uv run` or an activated venv), the name resolves to the `okf` "
         "script of po's own dependency llm-ingestion-okf 0.8.5, which has no `mcp` subcommand: "
         "stderr `okf: error: argument command: invalid choice: 'mcp'`, and MAF raises "
         "ToolException '... failed to initialize: Connection closed' on `async with`."
     ),
 )
-async def test_readme_bare_okf_command_reaches_the_1_1_server(
+async def test_bare_okf_command_reaches_the_1_1_server(
     tmp_path: Path, okf_1_1: str, invented_root: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:
     monkeypatch.setenv("PATH", VENV_BIN + os.pathsep + os.environ.get("PATH", ""))