docs: add subsystem-local docs for progressive-discovery refactor

Create three new topical docs that will absorb content currently
inlined in CLAUDE.md, so agents only pay the context cost for the
subsystem they're actually touching:

- katana_mcp_server/docs/prefab/README.md — DataTable mustache
  binding, browser-test wire shape via make_tool_result,
  register_preview_tool + meta=UI_META contract, help.py drift.
- katana_mcp_server/docs/typed_cache/README.md — archive/deleted
  opt-in flags + derived bools, cross-entity ID collisions,
  Cached<Name> siblings (don't pollute API spec).
- katana_public_api_client/docs/spec-authoring.md — OpenAPI 3.1
  conventions, use-site descriptions, ListResponse schema,
  generator/spec regen lockstep, privacy, fix-at-source rule.

Extend two existing docs with content that didn't have a topical
home yet:

- katana_public_api_client/docs/guide.md — new "Response Handling"
  section with unwrap helpers, when-to-use table, anti-patterns,
  and exception hierarchy. Also fix four stale status_code == 200
  example blocks in this file to use unwrap_as / unwrap_data /
  is_success per the rule we're now codifying.
- .github/agents/guides/shared/COMMIT_STANDARDS.md — add
  First-Push Safety (HEAD:refs/heads/<name> form), Lockfile Drift
  (uv.lock bundling), and Generator/spec regen lockstep sections.

No content is removed from CLAUDE.md yet; that move lands in the
next commit so the two halves of the refactor are reviewable
independently.

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

Author: dougborg

.github/agents/guides/shared/COMMIT_STANDARDS.md

@@ -215,28 +215,27 @@ Before version 1.0.0, breaking changes still bump MINOR (not MAJOR):
 ## Schema and Generator Changes
 
 Edits to the OpenAPI spec (`docs/katana-openapi.yaml`) or to the generator scripts
-(`scripts/generate_pydantic_models.py`, `scripts/regenerate_client.py`) can ripple
-into the **public client surface** in ways that break consumers — even when each
-individual change reads as a "fix" or "chore". Those ripples must be captured in
-the commit message so the auto-generated changelog flags them.
+(`scripts/generate_pydantic_models.py`, `scripts/regenerate_client.py`) can ripple into
+the **public client surface** in ways that break consumers — even when each individual
+change reads as a "fix" or "chore". Those ripples must be captured in the commit message
+so the auto-generated changelog flags them.
 
 ### What counts as a breaking schema change
 
-Use `feat(client)!:` (or `fix(client)!:`) **with a `BREAKING CHANGE:` footer**
-whenever a spec or generator edit causes any of the following in the regenerated
-client output:
+Use `feat(client)!:` (or `fix(client)!:`) **with a `BREAKING CHANGE:` footer** whenever
+a spec or generator edit causes any of the following in the regenerated client output:
 
-- A previously-exported class **disappears** (e.g., a `StrEnum` was deduped into
-  a structurally identical sibling — see #414 / `OutsourcedRecipeIngredientAvailability`
+- A previously-exported class **disappears** (e.g., a `StrEnum` was deduped into a
+  structurally identical sibling — see #414 / `OutsourcedRecipeIngredientAvailability`
   collapsed into `OutsourcedPurchaseOrderIngredientAvailability`)
-- A field **type narrows** in a way that makes previously-valid values raise
-  (e.g., `type: string` → `$ref` to a `StrEnum` — see #410)
+- A field **type narrows** in a way that makes previously-valid values raise (e.g.,
+  `type: string` → `$ref` to a `StrEnum` — see #410)
 - A field is **renamed** or **removed** on a response or request schema
 - An endpoint path is **removed**
 - A required field becomes **optional** (changes parse semantics) or vice versa
 
-The footer must list the affected name(s) so a consumer searching the
-changelog for the broken import or attribute can find the change:
+The footer must list the affected name(s) so a consumer searching the changelog for the
+broken import or attribute can find the change:
 
 ```
 fix(client)!: dedupe collapses OutsourcedRecipeIngredientAvailability
@@ -256,24 +255,79 @@ Refs #409
 
 - Adding a new endpoint or field (purely additive)
 - Adding a value to an existing enum (parse stays tolerant; old values still work)
-- Generated-file diff is byte-identical (e.g., a docstring tweak in the generator
-  that doesn't change emitted code)
-- Internal-only refactors that don't change the surface (e.g., consolidating
-  generator config dicts — see #407)
+- Generated-file diff is byte-identical (e.g., a docstring tweak in the generator that
+  doesn't change emitted code)
+- Internal-only refactors that don't change the surface (e.g., consolidating generator
+  config dicts — see #407)
 
 ### Why this matters pre-1.0
 
-The package is pre-1.0, so breaking changes bump MINOR (per the
-"Pre-1.0 Special Rules" section above) — *not* MAJOR. That's a smaller
-version-number signal than a 1.x → 2.x bump, so the **changelog entry** carries
-the discoverability for affected consumers. Without the breaking-change footer,
-the change shows up in the changelog as a normal `fix:` line and consumers hit
-an `ImportError` (or `ValueError`, etc.) without a breadcrumb to follow.
-
-When in doubt, run `uv run poe regenerate-client && uv run poe generate-pydantic`
-and inspect `git diff katana_public_api_client/`. If the diff removes any
-top-level class, removes any `__all__` entry, or changes a field's type
-annotation in a non-additive way, use `!` and `BREAKING CHANGE:`.
+The package is pre-1.0, so breaking changes bump MINOR (per the "Pre-1.0 Special Rules"
+section above) — *not* MAJOR. That's a smaller version-number signal than a 1.x → 2.x
+bump, so the **changelog entry** carries the discoverability for affected consumers.
+Without the breaking-change footer, the change shows up in the changelog as a normal
+`fix:` line and consumers hit an `ImportError` (or `ValueError`, etc.) without a
+breadcrumb to follow.
+
+When in doubt, run `uv run poe regenerate-client && uv run poe generate-pydantic` and
+inspect `git diff katana_public_api_client/`. If the diff removes any top-level class,
+removes any `__all__` entry, or changes a field's type annotation in a non-additive way,
+use `!` and `BREAKING CHANGE:`.
+
+### Generator/spec edits must commit the regen in the same PR
+
+Whenever you edit a generator script or the OpenAPI spec, run the regen, run
+`uv run poe check` (or at minimum `agent-check` + `uv run poe test`), and commit the
+regenerated output **in the same PR**. The input and its output stay locked together at
+every commit so the cause-and-effect chain is reviewable.
+
+- Pushing a generator/spec change **without** its regen leaves CI green-but-stale until
+  the next time someone runs the generator.
+- Pushing regen output **without** the input change drifts in the other direction.
+
+Note the generated-file impact in the PR description (e.g., "byte-identical except X" or
+list affected files). Before editing the spec, audit upstream drift via the workflow in
+[`docs/upstream-specs/README.md`](../../../docs/upstream-specs/README.md)
+(`poe refresh-upstream-spec` → `poe audit-spec` → `poe validate-response-examples` →
+`poe validate-examples`).
+
+## Lockfile Drift
+
+When `uv.lock` shows up modified but you didn't touch dependencies (e.g., a
+sibling-package release on `main` bumped a workspace version), `git add uv.lock` and
+bundle it into your current commit.
+
+**Don't `git checkout -- uv.lock` to drop it**: pre-commit's auto-stash/restore fights
+with the lockfile being regenerated mid-hook (pytest's `uv run` re-syncs it), producing
+confusing "files were modified by this hook" failures where nothing was actually wrong
+with the staged content. The lockfile must stay in sync with `pyproject.toml` at every
+commit anyway, so bundling is always the right call.
+
+## First-Push Safety
+
+When a local branch was created via `git checkout -b <name> origin/main`, its upstream
+is set to `origin/main`. A subsequent `git push -u origin <name>` then resolves to its
+tracked upstream and **pushes the local tip straight to `main`** — bypassing PR review
+and triggering semantic-release.
+
+This actually happened: commit `30f3fd86` reached main + tagged `mcp-v0.44.1` +
+published to PyPI before the pipeline could be cancelled.
+
+**Always use the explicit destination ref for first-time pushes:**
+
+```bash
+# Wrong — pushes to whatever the local branch tracks (may be main)
+git push -u origin chore/foo
+
+# Right — explicit destination, creates the remote branch
+git push -u origin HEAD:refs/heads/chore/foo
+```
+
+A `pre-push` hook at `.pre-commit-config.yaml`'s `pre-push` stage enforces this for
+contributors who run pre-commit; **do not bypass with `--no-verify`**. The
+`Protect Main` ruleset has `bypass_mode: always` for the Admin role (required by
+semantic-release's PAT-based pushes); tightening that bypass is tracked in #429 (GitHub
+App migration). Until #429 lands, the local hook is the only mechanical guardrail.
 
 ## Multi-Package Changes
 

katana_mcp_server/docs/prefab/README.md

@@ -0,0 +1,99 @@
+# Prefab UI — Rendering Pitfalls and Contracts
+
+Prefab cards are emitted by MCP tools as JSON envelopes that the host (Claude Desktop,
+Cowork, the browser-render harness) hydrates into a React tree inside an iframe. The
+JSON wire is forgiving (it accepts most pydantic shapes); the JS renderer is not. The
+rules below come from real production failures — cards that passed unit tests but
+crashed in the host, or tools that promised a widget in their docstring and silently
+emitted none.
+
+When you change anything that emits a Prefab card, run `uv run poe test-browser` (needs
+one-time `uv run playwright install chromium`) — the browser-render harness in
+`katana_mcp_server/tests/browser/` is the only thing that exercises the real JS
+renderer.
+
+Related tests:
+
+- `katana_mcp_server/tests/test_prefab_ui.py` — unit tests on the wire envelope.
+- `katana_mcp_server/tests/browser/` — headless Chromium harness that proves cards
+  actually mount.
+
+______________________________________________________________________
+
+## `DataTable.rows` requires mustache `{{ key }}`, never a bare string
+
+The Python pydantic field type accepts `rows: str` either way, but the JS renderer
+**crashes the entire iframe** with `t.some is not a function` if it sees a bare
+state-key string — it treats the string as the rows array itself, calls `.some()` on a
+string, and the React tree never mounts.
+
+Always use the mustache form for state-bound rows:
+
+```python
+DataTable(rows="{{ items }}")
+DataTable(rows="{{ stock.by_location }}")  # dotted paths supported
+```
+
+`_assert_state_bindings_resolve` in `tests/test_prefab_ui.py` enforces this on every
+state-bound `DataTable`. The browser-render harness then proves the rendered card
+actually mounts in headless Chromium — the prior unit-test contract (`to_json()` returns
+a dict with `$prefab`) was insufficient because the wire envelope can be "valid but
+unrenderable."
+
+Discovered while investigating #629; bit every state-bound DataTable in the repo
+(search, inventory, verification, batch_recipe, modification card).
+
+______________________________________________________________________
+
+## Browser-test tool stubs must mirror production wire shape via `make_tool_result`
+
+When stubbing an MCP tool in `tests/browser/render_test_server.py`, return
+`make_tool_result(response_pydantic, ui=ui_card)` — exactly like real tool code in
+`src/katana_mcp/tools/foundation/`. A hand-built
+`ToolResult(content="ok", structured_content=raw_dict)` silently passes browser tests
+but misses production-shape bugs.
+
+In particular, `$result` in the `on_success` Rx context resolves to the apply tool's
+`structured_content` — a `PrefabApp` wire envelope keyed by `$prefab` / `view` / `state`
+— **not** the raw `ModificationResponse` shape. A stub that returns a raw
+`ModificationResponse` therefore exposes an `actions` field that doesn't exist in
+production, so the rail's `Rx("$result.actions")` looks like it resolves correctly in
+test but doesn't in real life.
+
+Rule: **a stub that doesn't match production wire shape is worse than no stub.**
+Discovered via Copilot review on #634; the broken live-tick that "passed" against the
+bad stub is tracked for proper fix in #645.
+
+______________________________________________________________________
+
+## A tool's docstring promises must match the UI it actually emits
+
+`register_preview_tool` auto-appends "Preview→apply: ... returns a Prefab card with
+Confirm/Cancel buttons" to the tool's docstring. Hosts read that promise and look for a
+widget. If the tool is registered with `register_preview_tool` but **without**
+`meta=UI_META` (or it returns via `make_simple_result` with no Prefab envelope), the
+host's widget-fetch fails — Claude Desktop crashes its internal `read_widget_context`
+with `tool_name=undefined` because no widget exists for the tool the host believed was
+emitting one. The tool result still returns successfully, but the iframe renders
+nothing.
+
+The contract is bidirectional:
+
+- Every `register_preview_tool` call **must** pair `meta=UI_META` with a real Prefab
+  card (built via `make_tool_result(response, ui=...)`) — never the docstring without
+  the card.
+- Conversely, tools that emit no UI must use plain `mcp.tool(...)`, **not**
+  `register_preview_tool` — the docstring promise has to match reality.
+
+Caught via a live Claude Desktop session against `create_stock_adjustment` (fixed in
+#649); the same misregistration still applies to `create_stock_transfer` — tracked in
+#639. (`fulfill_order` is correctly wired with `meta=UI_META`; its remaining work is the
+direct-apply rail migration in #638, not this misregistration.)
+
+______________________________________________________________________
+
+## Help resource drift
+
+`katana_mcp_server/.../resources/help.py` contains hardcoded tool documentation. When
+adding or modifying tool parameters, also update the help resource content to stay in
+sync. The `pr-preparer` agent flags this on PR readiness.

katana_mcp_server/docs/typed_cache/README.md

@@ -0,0 +1,110 @@
+# Typed Cache — Patterns and Pitfalls
+
+The typed cache is a SQLite-backed mirror of Katana's wire state, with per-entity tables
+(`product`, `material`, `supplier`, `manufacturing_order`, …) generated from the same
+pydantic models the API client uses. It exists so MCP tools can serve queries without
+round-tripping to Katana for every read, and so FTS5 fuzzy search has something to
+index.
+
+The rules below are about how the cache layer relates to the API layer (the spec, the
+generated pydantic, the attrs models) — what belongs where, and what surprises bite when
+those layers blur.
+
+Related code:
+
+- `katana_mcp_server/src/katana_mcp/typed_cache/sync.py` — attrs → API pydantic → cache
+  pydantic conversion.
+- `scripts/generate_pydantic_models.py` — emits both the API pydantic class and the
+  sibling `Cached<Name>` class with `table=True` per entity. See
+  `duplicate_cache_tables_as_cached_siblings`.
+
+______________________________________________________________________
+
+## Archive / deleted state — opt-in flags + derived booleans
+
+Katana represents soft-state as nullable timestamps on the wire: `archived_at` (the
+user-toggleable archive lifecycle — exposed on catalog items, inventory rows, and a few
+other archivable entities) and `deleted_at` (soft-delete, exposed on most entities
+including catalog items *and* transactional entities like POs, SOs, MOs, stock
+transfers, stock adjustments). The two are independent — an entity can be both archived
+and soft-deleted.
+
+Two MCP-side conventions surface this; **keep them symmetric**:
+
+### Query-param flags for opting into soft-state rows (default `False`)
+
+Items use `include_archived` (`search_items`, catalog cache). After #472 Phase D the
+canonical wiring is the typed cache's `CatalogQueries` adapter — `parent_archived_at` is
+denormalized onto `CachedVariant` at sync time (via the variant `attrs_postprocess` hook
+in `typed_cache/sync.py`) and the adapter's default `include_archived=False` /
+`include_deleted=False` filters push the `archived_at IS NULL` / `deleted_at IS NULL`
+predicates down to SQL.
+
+Transactional entities use `include_deleted` on `list_purchase_orders` /
+`list_sales_orders` / `list_manufacturing_orders` / `list_stock_adjustments`, filtering
+at the same typed-cache query layer.
+
+### Response-side derived booleans
+
+Every response model that exposes `archived_at` / `deleted_at` should also expose a
+convenience `is_archived` / `is_deleted` bool derived from `<timestamp> is not None`,
+saving callers from the timestamp/null inspection.
+
+**Note the asymmetry**: `is_archived` mirrors Katana's *write* convention
+(`update_<entity>` request bodies accept `is_archived: bool`, so round-tripping through
+`modify_<entity>` with `{"update_header": {"is_archived": false}}` works). `is_deleted`,
+by contrast, is *read-side only* — Katana exposes deletion through DELETE endpoints, not
+as a writable boolean on update bodies. Items expose `is_archived` on `ItemInfo` and
+`ItemDetailsResponse` as of #526.
+
+Don't add a new opt-in flag without the matching derived bool, and vice versa.
+
+**Known gaps** (filed for follow-up):
+
+- `list_stock_transfers` lacks `include_deleted` parity (#484).
+- `check_inventory` and the inventory reporting tools lack `include_archived` and the
+  `is_archived` row field (#539).
+- Transactional response models lack the `is_deleted` derived bool (#540).
+
+______________________________________________________________________
+
+## Cache IDs are not globally unique — never merge cross-entity maps by numeric ID alone
+
+The typed cache stores each entity type in its own table (`product`, `material`,
+`supplier`, …), so a product with `id=42` and a material with `id=42` are both legal.
+When enriching a list of variants with parent context (or any other cross-entity batch
+fetch), keep separate per-type maps (`products`, `materials`) and select based on which
+ID the variant carries (`v.product_id` vs `v.material_id`).
+
+Merging into a single dict via `{**products, **materials}` mis-attaches parents on
+collision — Python dict-unpack iterates left-to-right and later keys win, so the
+material entry silently overwrites the product entry on shared IDs. The bug is symmetric
+in practice: every product variant whose ID also exists as a material ID looks up the
+material's data instead (and vice versa if you reorder the unpack).
+
+Caught in #542 (variant card redesign) by Copilot review; regression test pins the case
+in `test_items.py::test_enrich_variants_keeps_product_and_material_maps_separate`.
+
+______________________________________________________________________
+
+## Don't pollute the API spec/models with cache-only fields
+
+The OpenAPI spec at `docs/katana-openapi.yaml` and the generated pydantic models in
+`katana_public_api_client/models_pydantic/_generated/*.py` reflect Katana's actual wire
+contract. **Never** add fields to the spec or inject fields into the API pydantic
+classes to satisfy cache-schema, MCP-tool, or other consumer needs.
+
+Cache schemas live on sibling `Cached<Name>` classes emitted by the same generator pass
+— the API class stays pure pydantic, the cache class carries `table=True`, foreign keys,
+relationships, JSON columns, and any cache-only fields. See
+`scripts/generate_pydantic_models.py::duplicate_cache_tables_as_cached_siblings` and
+`katana_mcp_server/src/katana_mcp/typed_cache/sync.py::_attrs_<entity>_to_cached` for
+the conversion pattern: attrs → API pydantic (via the registry) → cache pydantic (via
+`model_dump`/`model_validate`), with relationship fields set after construction since
+SQLModel `Relationship` descriptors don't accept input via `__init__`.
+
+If a bug surfaces in `sync.py` but originates in generated client code (attrs, pydantic,
+`from_attrs`, `Cached*` schemas), fix it at the generator/spec layer — not in `sync.py`.
+See
+[Fix bugs at the client/generator layer](../../../katana_public_api_client/docs/spec-authoring.md#fix-bugs-at-the-clientgenerator-layer-when-the-root-cause-lives-there)
+in the spec-authoring guide.