docs(slice-65): dogfood readme quickstart

Author: rohans0509

README.md

@@ -45,7 +45,7 @@ Inside a repository:
 
 ```bash
 codealmanac init
-codealmanac search "auth"
+codealmanac search "getting"
 codealmanac show getting-started
 codealmanac serve
 ```

docs/python-port/idea-evolution.md

@@ -1535,3 +1535,29 @@ Follow-up test:
 Keep public-contract tests close to user-facing claims, not only forbidden
 words. When a README section describes command effects, add a guard for the
 actual file or command contract.
+
+## 2026-06-30 - Quickstarts Are Executable Use Cases
+
+Old hypothesis:
+After the README scaffold tree was fixed, remaining public-doc work was likely
+only wording polish.
+
+New hypothesis:
+Treat quickstarts as runnable use cases. A public README command sequence is
+wrong if it exits successfully but teaches a new user an empty first result.
+
+Evidence that forced the change:
+A temp repo initialized with `codealmanac init` returned `# 0 results` for the
+README's `codealmanac search "auth"` command. The same starter wiki returned
+`getting-started` for `codealmanac search "getting"` and rendered
+`# Getting Started` through `codealmanac show getting-started --lead`.
+
+Code or product assumption affected:
+The README quickstart now uses a search term that matches the starter wiki.
+Public-contract tests guard the quickstart section directly instead of only
+checking that the README mentions `codealmanac search`.
+
+Follow-up test:
+For future public examples, distinguish runnable quickstart commands from
+illustrative daily-use commands. Runnable examples should be dogfooded in a
+fresh temp repo.

docs/python-port/next-agent-brief.md

@@ -561,6 +561,9 @@ Behavior:
   recreate a deleted configured root
 - Slice 64 README scaffold accuracy, public-contract guard for init-created
   source files versus derived runtime state, and live temp `init` tree dogfood
+- Slice 65 README quickstart dogfood, public-contract guard for the starter
+  search term, and live temp proof that `search "getting"` returns
+  `getting-started` after init
 
 ## Next Move
 

docs/python-port/public-release-readiness.md

@@ -84,6 +84,9 @@ unless a gate below exposes a boundary problem.
   dogfood showed it mixed initialized wiki source files with later runtime
   state. The README now separates init-created source files from derived
   `index.db`/`jobs/` state, and public-contract tests guard the distinction.
+- Slice 65 dogfooded the README quickstart in a fresh temp repo. The old
+  `search "auth"` example returned zero results after `init`; the quickstart
+  now searches `getting`, which returns the starter `getting-started` page.
 
 ## Next Useful Pressure Tests
 

docs/python-port/slice-65-readme-quickstart-dogfood.md

@@ -0,0 +1,47 @@
+# Slice 65 - README Quickstart Dogfood
+
+Date: 2026-06-30
+
+## Scope
+
+Make the README quickstart executable against a fresh starter wiki.
+
+## Finding
+
+The README quickstart ran:
+
+```bash
+codealmanac init
+codealmanac search "auth"
+codealmanac show getting-started
+codealmanac serve
+```
+
+Live temp-repo dogfood showed that `search "auth"` returns `# 0 results`
+immediately after `init`, because the starter wiki only contains
+`getting-started`.
+
+## Decision
+
+The quickstart now uses:
+
+```bash
+codealmanac search "getting"
+```
+
+This makes the first search command return `getting-started` in the initialized
+starter wiki. The later daily-use examples can still use domain-like queries
+such as `auth` or `checkout timeout` because those are illustrative examples
+after a wiki has real pages.
+
+## Guard
+
+`tests/test_public_contract.py` now checks that the README quickstart uses
+`search "getting"` and does not use `search "auth"`.
+
+## Cosmic Python Note
+
+Chapter 4's Service Layer chapter stresses testing use cases at the service
+boundary instead of trusting lower-level pieces in isolation. This slice treats
+the README quickstart as a public use case: fresh init, search, show. The
+correct proof is the end-to-end command path returning the starter page.

docs/python-port/verification-matrix.md

@@ -803,3 +803,15 @@ means the goal remains active.
 | Full tests | `uv run pytest` | 243 passed |
 | Full lint | `uv run ruff check .` | passed |
 | Diff hygiene | `git diff --check` | passed |
+
+## Gates For Slice 65 README Quickstart Dogfood
+
+| Gate | Command | 2026-06-30 result |
+|---|---|---|
+| Quickstart mismatch repro | isolated temp `HOME`; temp repo; `codealmanac init`; `codealmanac search "auth"`; `codealmanac search "getting"`; `codealmanac show getting-started --lead` | passed; `search "auth"` returned `# 0 results`, while `search "getting"` returned `getting-started` and `show --lead` rendered `# Getting Started` |
+| Public contract tests | `uv run pytest tests/test_public_contract.py -q` | 18 passed; quickstart section now guards `search "getting"` and rejects `search "auth"` |
+| Fixed quickstart dogfood | isolated temp `HOME`; temp repo; `codealmanac init`; `codealmanac search "getting"`; `codealmanac show getting-started --lead` | passed; search returned `getting-started` and show rendered `# Getting Started` |
+| Cosmic note relay | `doppler run --project almanac --config dev -- relayforge reply --config ../relayforge/relay.config.json --binding rohan-almanac-main ...` | passed; sent the Chapter 4 Service Layer note and how it maps to README quickstart as a public use case |
+| Full tests | `uv run pytest` | 244 passed |
+| Full lint | `uv run ruff check .` | passed |
+| Diff hygiene | `git diff --check` | passed |

docs/python-port/worklog.md

@@ -733,6 +733,12 @@ A live temp-repo `codealmanac init` created `.gitignore`, `README.md`,
 `config.toml`, `jobs/`, or `index.db`. The README now separates
 `What Gets Created By Init` from `Runtime State`, and public-contract tests
 guard that the init section stays source-only.
+Slice 65 dogfoods the README quickstart itself. A fresh temp repo proved that
+`codealmanac search "auth"` returns zero results immediately after `init`,
+because the starter wiki contains `getting-started`, not an auth page. The
+quickstart now uses `codealmanac search "getting"` so a new user sees the
+starter page on the first search. Public-contract tests guard the quickstart
+section against drifting back to a non-starter search term.
 
 ## Next Hypothesis
 

tests/test_public_contract.py

@@ -27,7 +27,7 @@
     "Python 3.12+",
     "uv tool install codealmanac",
     "codealmanac init",
-    "codealmanac search",
+    'codealmanac search "getting"',
     "codealmanac serve",
     "## What Gets Created By Init",
     "Derived local state appears when commands need it:",
@@ -118,6 +118,16 @@ def test_readme_keeps_init_scaffold_separate_from_runtime_state():
     assert "config.toml" not in init_section
 
 
+def test_readme_quickstart_uses_search_that_works_after_init():
+    readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+
+    quickstart = readme_section(readme, "## Quickstart")
+
+    assert 'codealmanac search "getting"' in quickstart
+    assert 'codealmanac show getting-started' in quickstart
+    assert 'codealmanac search "auth"' not in quickstart
+
+
 def test_release_guide_documents_python_package_release_surface():
     release_guide = (PROJECT_ROOT / "RELEASE.md").read_text(encoding="utf-8")