fix(slice-59): align public docs contract

Author: rohans0509

README.md

@@ -18,6 +18,15 @@ dead-ends inside them never compile into anything the next session can
 reference. CodeAlmanac is that reference layer: a wiki that lives in your
 repository, written for your agents, and kept up to date from the work itself.
 
+## At a glance
+
+- Public command: `codealmanac`
+- Python 3.12+
+- Default repo wiki root: `almanac/`
+- Custom repo wiki roots: any safe repo-relative directory via `--root`
+- User state root: `~/.codealmanac/`
+- Cloud commands: `setup`, `login`, `whoami`, `logout`, `capture`.
+
 ## Get started
 
 Install the CLI (Python 3.12+):
@@ -32,6 +41,8 @@ uv tool install codealmanac
 ```bash
 codealmanac init            # build the first wiki for this repo
 codealmanac local setup     # keep it updating from your commits
+codealmanac search "getting"
+codealmanac show getting-started
 ```
 
 **With your team (cloud)** — one shared wiki, updated from everyone's
@@ -55,10 +66,11 @@ your-repo/
 |-- almanac/
 |   |-- README.md          # this repo's notability bar and conventions
 |   |-- topics.yaml        # topic graph
-|   `-- pages/
-|       |-- checkout-flow.md
-|       |-- stripe-webhook-deadlock.md
-|       `-- jwt-vs-sessions.md
+|   |-- manual/            # packaged guidance copied for agents
+|   |-- pages/
+|   |   |-- checkout-flow.md
+|   |   |-- stripe-webhook-deadlock.md
+|   |   `-- jwt-vs-sessions.md
 |-- src/
 `-- ...
 ```
@@ -67,6 +79,10 @@ Every page is one stable concept — a flow, a decision, a gotcha — linked int
 a topic graph with `[[wikilinks]]`. Browse it locally with `codealmanac
 serve`, or in the cloud with `codealmanac open`.
 
+A folder counts as a CodeAlmanac wiki only when it has both `topics.yaml` and `pages/`.
+Derived local state appears when commands need it: `index.db` and
+user-level job records are runtime state, not part of the init scaffold.
+
 ## Principles
 
 1. **Written for your agents.** The primary reader is the AI agent working in
@@ -104,17 +120,27 @@ model and need no credentials.
 |---|---|
 | `codealmanac init` | Build the first wiki for the current repo. |
 | `codealmanac local setup` | Configure local self-updating: branch policy + git hooks. |
+| `codealmanac local setup --branch main` | Configure a specific maintained branch locally. |
 | `codealmanac local update` | Run a local wiki update now. |
+| `codealmanac local update --using codex` | Run a local update with Codex. |
+| `codealmanac local triggers enable dev --delivery commit` | Maintain a branch locally. |
+| `codealmanac local jobs list` | Inspect local update jobs. |
 | `codealmanac search` / `show` / `topics` / `health` | Query the wiki. |
 | `codealmanac serve` | Local wiki viewer. |
 | `codealmanac setup` | Cloud sign-in plus agent instructions. |
-| `codealmanac capture enable\|status\|disable` | Manage session capture. |
+| `codealmanac login` / `whoami` / `logout` | Manage cloud auth. |
+| `codealmanac capture status` | Show capture status. |
+| `codealmanac capture enable --target codex` | Enable Codex session capture. |
+| `codealmanac capture disable` | Disable capture hooks. |
 | `codealmanac repo triggers enable <branch> --delivery pr\|commit` | Choose how cloud updates land. |
 | `codealmanac runs list\|show\|logs` | Inspect cloud update runs. |
 | `codealmanac doctor` | Check install, auth, and wiki health. |
 
 Run `codealmanac <command> --help` for the full flag surface.
-`codealmanac uninstall --yes` removes setup-owned local artifacts.
+Local schedules stay behind explicit local or automation commands.
+`codealmanac uninstall --yes` removes setup-owned local artifacts;
+`codealmanac uninstall --yes --keep-automation` leaves local scheduled
+automation in place.
 
 ## Privacy
 

docs/concepts.md

@@ -93,10 +93,12 @@ Command groups:
 |---|---|---|
 | Read | `list`, `search`, `show`, `topics`, `health`, `serve` | No |
 | Organize | `tag`, `untag`, `topics create/rename/delete/link` | No |
-| Lifecycle | `init`, `build`, `ingest`, `garden`, `sync`, `jobs` | `ingest`, `garden`, and write-capable `sync` |
-| Admin | `setup`, `login`, `whoami`, `logout`, `capture`, `uninstall`, `doctor`, `update`, `automation`, `reindex` | No |
+| Lifecycle | `init`, `sync`, `local update`, `jobs`, `local jobs` | `init`, `sync`, and `local update` |
+| Cloud | `setup`, `login`, `whoami`, `logout`, `capture`, `repo`, `runs`, `open` | No |
+| Admin | `local setup`, `local triggers`, `automation`, `uninstall`, `doctor`, `update`, `reindex` | No |
 
 Scheduled automation is local scheduler state. It runs ordinary `codealmanac
-sync` or `codealmanac garden` commands; it is not hosted sync.
-`codealmanac setup --install-automation` can install those scheduler entries,
-and `codealmanac uninstall --keep-automation` leaves them in place.
+sync` jobs; it is not hosted sync. Root `codealmanac setup` is cloud setup and
+agent instructions only. Local schedules stay behind explicit local or
+automation commands, and `codealmanac uninstall --keep-automation` leaves them
+in place.

tests/test_public_contract.py

@@ -41,7 +41,7 @@
     "codealmanac local update --using codex",
     "codealmanac local triggers enable dev --delivery commit",
     "codealmanac local jobs list",
-    "## What Gets Created By Init",
+    "## What gets created",
     "A folder counts as a CodeAlmanac wiki only when it has both",
     "`topics.yaml` and `pages/`",
     "Derived local state appears when commands need it:",
@@ -155,7 +155,7 @@ def test_default_user_state_paths_are_product_specific(isolated_home: Path):
     )
 
 
-def test_readme_documents_python_local_public_surface():
+def test_readme_documents_python_cloud_first_public_surface():
     readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
 
     for fragment in README_REQUIRED_FRAGMENTS:
@@ -178,7 +178,7 @@ def test_user_facing_docs_do_not_advertise_node_or_old_state_paths():
     assert "uv sync" in docs["CONTRIBUTING.md"]
     assert "uv run pytest" in docs["CONTRIBUTING.md"]
     assert "codealmanac init --root <path>" in docs["docs/concepts.md"]
-    assert "codealmanac setup --install-automation" in docs["docs/concepts.md"]
+    assert "Root `codealmanac setup` is cloud setup" in docs["docs/concepts.md"]
     assert "codealmanac uninstall --keep-automation" in docs["docs/concepts.md"]
     for body in docs.values():
         assert "npm install" not in body
@@ -191,7 +191,7 @@ def test_user_facing_docs_do_not_advertise_node_or_old_state_paths():
 def test_readme_keeps_init_scaffold_separate_from_runtime_state():
     readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
 
-    init_section = readme_section(readme, "## What Gets Created By Init")
+    init_section = readme_section(readme, "## What gets created")
 
     assert "|   |-- README.md" in init_section
     assert "|   |-- topics.yaml" in init_section
@@ -205,7 +205,7 @@ def test_readme_keeps_init_scaffold_separate_from_runtime_state():
 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")
+    quickstart = readme_section(readme, "## Get started")
 
     assert 'codealmanac search "getting"' in quickstart
     assert "codealmanac show getting-started" in quickstart
@@ -214,7 +214,7 @@ def test_readme_quickstart_uses_search_that_works_after_init():
 
 def test_readme_lifecycle_examples_parse_public_local_commands():
     readme = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
-    updating = readme_section(readme, "## Updating The Wiki")
+    commands = readme_section(readme, "## Commands")
     parser = build_parser()
 
     parser.parse_args(("local", "setup", "--branch", "main"))
@@ -231,9 +231,9 @@ def test_readme_lifecycle_examples_parse_public_local_commands():
     )
     parser.parse_args(("local", "jobs", "list"))
 
-    assert "docs/adr.md" not in updating
-    assert "codealmanac ingest" not in updating
-    assert "codealmanac garden" not in updating
+    assert "docs/adr.md" not in commands
+    assert "codealmanac ingest" not in commands
+    assert "codealmanac garden" not in commands
 
 
 def test_next_agent_brief_tracks_latest_python_port_slice():