Summary
docs/cookbook/06-serving-and-ops.md contains seven ```console blocks showing real command output, and none of them is executed by any test. tests/test_cookbook_serving.py pairs only ```python blocks with their expected output; console blocks are never run. They have already drifted: line 1254 of the doc shows {"status":"ok","version":"0.1.0",...} while grapharc/__init__.py:12 says __version__ = "0.1.1".
Why this matters
This project's documentation is meant to be evidence, not decoration — tests/test_readme.py and tests/test_cookbook_models.py byte-compare command output against the page so it cannot rot quietly. Trustworthy docs are part of the graph engineering discipline this repo argues for: a page that silently contradicts the tool is worse than no page. These seven blocks are the one place that guarantee currently does not reach.
Where in the code
docs/cookbook/06-serving-and-ops.md — the console blocks at roughly lines 1247, 1584, 1645, 1672, 1702 (and the stale version string at 1254)
tests/test_cookbook_serving.py — the harness that currently skips them
tests/test_cookbook_models.py — read this first; it already does exactly this for 02-models.md and is the pattern to copy
Confirm it:
grep -c 'console' docs/cookbook/06-serving-and-ops.md # 7
grep -n '"version"' docs/cookbook/06-serving-and-ops.md # shows 0.1.0
grep -n '__version__' grapharc/__init__.py # says 0.1.1
What to change
- Read how
tests/test_cookbook_models.py marks and executes console blocks (<!-- cookbook shell ... --> / <!-- verified: ... --> markers, _run_console).
- Pick the blocks whose output is deterministic and mark them so the harness runs and compares them.
- For blocks whose output is genuinely machine-dependent (
serve binds a port; models --check probes the host), mark them as varies so they are executed for a zero exit code but not byte-compared.
- Correct the stale
0.1.0 to match the real version.
How to verify
uv run pytest tests/test_cookbook_serving.py -q
uv run pytest -q # nothing else may regress
Then prove the new gate works: change one character of an expected block and confirm the test fails.
Acceptance criteria
Skill level — good first issue
No production code changes at all: you are extending a test harness that already exists and copying a pattern from a sibling file. It is an excellent first contribution because it teaches you the repo's core habit — a claim in the docs must have a test behind it. Comment here if you would like guidance on which blocks to treat as deterministic.
Summary
docs/cookbook/06-serving-and-ops.mdcontains seven```consoleblocks showing real command output, and none of them is executed by any test.tests/test_cookbook_serving.pypairs only```pythonblocks with their expected output;consoleblocks are never run. They have already drifted: line 1254 of the doc shows{"status":"ok","version":"0.1.0",...}whilegrapharc/__init__.py:12says__version__ = "0.1.1".Why this matters
This project's documentation is meant to be evidence, not decoration —
tests/test_readme.pyandtests/test_cookbook_models.pybyte-compare command output against the page so it cannot rot quietly. Trustworthy docs are part of the graph engineering discipline this repo argues for: a page that silently contradicts the tool is worse than no page. These seven blocks are the one place that guarantee currently does not reach.Where in the code
docs/cookbook/06-serving-and-ops.md— theconsoleblocks at roughly lines 1247, 1584, 1645, 1672, 1702 (and the stale version string at 1254)tests/test_cookbook_serving.py— the harness that currently skips themtests/test_cookbook_models.py— read this first; it already does exactly this for02-models.mdand is the pattern to copyConfirm it:
What to change
tests/test_cookbook_models.pymarks and executesconsoleblocks (<!-- cookbook shell ... -->/<!-- verified: ... -->markers,_run_console).servebinds a port;models --checkprobes the host), mark them as varies so they are executed for a zero exit code but not byte-compared.0.1.0to match the real version.How to verify
uv run pytest tests/test_cookbook_serving.py -q uv run pytest -q # nothing else may regressThen prove the new gate works: change one character of an expected block and confirm the test fails.
Acceptance criteria
consoleblock in06-serving-and-ops.mdis either byte-compared or explicitly marked as varyinguv run pytestgreen,uv run ruff check .cleanSkill level — good first issue
No production code changes at all: you are extending a test harness that already exists and copying a pattern from a sibling file. It is an excellent first contribution because it teaches you the repo's core habit — a claim in the docs must have a test behind it. Comment here if you would like guidance on which blocks to treat as deterministic.