docs(ingest): the chain from ingest to run does not close by itself

Walked Door A from a fresh clone: materializing the file-family golden
manifest writes index.md plus one concept file per extraction, and pointing
the run at the result is refused —

    run refused: IR projection not found in bundle: 'validator-input.json'

A clean fail-fast, but nothing adopter-facing said it was coming, while the
README actively invites it ("swap --bundle-dir for your own bundle"). The
run path needs the bundle's IR projection, which ingest does not and cannot
produce: ingest materializes source documents, the projection states the
candidate measure. Both docs now say so, with the shape reference named.

Also corrects a live-doc claim that was wrong in both halves: the MCP
timeout is `anyio.fail_after` nested inside both task groups, not
`asyncio.wait_for`, and `tests/test_ingest_golden_mcp.py` covers it
(verified — 2 passing timeout tests). And no bundled example ships a
`cost-baseline.json`, so the text no longer implies one does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GyAbxJoyypnLLUDcMvnKh8
This commit is contained in:
Kjell Tore Guttormsen 2026-08-05 11:39:58 +02:00
commit bd221e6349
2 changed files with 37 additions and 1 deletions

View file

@ -79,6 +79,10 @@ uv run python -m portfolio_optimiser.run BYGG-KONTOR-NORD \
Ends in `ValidatedProposal`. Swap `--bundle-dir`/`--docs-dir` for your own bundle to run it over
your own data — that is the point of this door, and the reason it is not the same thing as step 2.
Your bundle needs one file the ingest layer does not write for you: `validator-input.json`, the
candidate the deterministic validator judges (a bundle without it is refused, by design — see
[`docs/extending.md`](docs/extending.md)). Copy the shape from
`shared/examples/bygg-energi-mikro/`.
**4 — Watch it say no.** Raise `claimed_saving_nok` to `250000` in `replies.json` and run the same
command again. The outcome becomes `Rejection`: the deterministic validator refuses a saving the