fix(docs): the auto-loading codegen rule taught metadata that no longer loads

`.claude/rules/codegen-architecture.md` loads itself into a Claude Code session
on any codegen path match, unprompted. Its "Source-aware entities + projections"
section was written before the v2 source paradigm and never revisited, so the
file an agent doing codegen reads FIRST taught three spellings that are now
illegal:

  - `source.dbTable` / `source.dbView` — retired subtypes (ADR-0007). There is
    one subtype, `source.rdb`, and read-only-ness comes from `@kind`.
  - `@name` for the physical name — it is the kind-matching alias, `@table` /
    `@view` (ADR-0018).
  - a projection as an `object.entity extends Program` with a view source —
    which is now `ERR_ENTITY_PRIMARY_SOURCE_READONLY` outright (ADR-0028 B4b).
    A read-only derived representation is `object.projection`.

Every example in that block had stopped loading. Corrected, and the dispatch
list now states the projection route contract (GET list + GET by id; write
verbs answer 405) and points at the two corpora that gate it.

`AGENTS.md` carried the same retired `source.dbView` in its file-organization
section.

Closes the gap that let it rot. `scripts/check-doc-examples.ts` exists to fail
the build when shipped metadata examples stop loading, and its SCAN_ROOTS are
described as "trees whose fenced metadata examples ship to a reader or to an
agent" — but it read only `docs` and `agent-context`. `.claude/rules` is the
most agent-facing prose in the repo and was the one such tree it did not read.
This is exactly what #337 cost in agent-context, in the one place still
unguarded. Adding the root takes the gate from 100 examples over 72 blocks to
103 over 75, all green.

Found while building the F22 projection corpus — the stale block is the
projection-authoring guidance.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015NrWUxA6euwvnFcwKxcK6A

Author: dmealing

.claude/rules/codegen-architecture.md

@@ -113,34 +113,54 @@ const { data } = useSubscribers({
 
 **Architecture:** `parseFilterParams` (in `@metaobjectsdev/runtime-ts/drizzle-fastify`) translates parsed qs into a Drizzle expression tree. `buildFilterQs` (in `@metaobjectsdev/runtime-web` and `@metaobjectsdev/tanstack`) serializes a typed filter object back to a bracketed qs URL.
 
-### Source-aware entities + projections (Project E)
+### Source-aware objects + projections (Project E)
 
-`source` is a top-level metadata type describing where an object's data lives. Subtypes: `dbTable` (writable, default) and `dbView` (read-only).
+`source` is a top-level metadata type describing where an object's data lives.
+There is ONE subtype — **`source.rdb`** (the v2 paradigm, ADR-0007) — and
+read-only-ness comes from **`@kind`**: `table` (writable, the default) vs
+`view` / `materializedView` / `storedProc` / `tableFunction` (read-only).
+The physical name is the **kind-matching alias** (`@table` / `@view` / …,
+ADR-0018), never `@name`.
 
-**Authoring a projection:**
+> The pre-v2 `source.dbTable` / `source.dbView` subtypes are **RETIRED** and no
+> longer load. Multi-source objects use `@role` (exactly one `primary`).
+
+**Authoring a projection.** A read-only derived representation is
+**`object.projection`**, not an entity: an `object.entity`'s primary source must
+be a writable `@kind`, so an entity whose only source is a view is
+`ERR_ENTITY_PRIMARY_SOURCE_READONLY` (ADR-0028 B4b). Its fields are
+`extends`-bound or `origin`-derived, and its identity extends the base entity's.
 
 ```jsonc
-{ "object.entity": {
+{ "object.projection": {
     "name": "ProgramSummary",
-    "extends": "Program",
     "children": [
-      { "source.dbView": { "@name": "v_program_summary" }},
+      { "source.rdb": { "@kind": "view", "@view": "v_program_summary" }},
+      { "field.string": { "name": "title", "extends": "Program.title" }},
       { "field.int": { "name": "weekCount", "children": [
         { "origin.aggregate": {
             "@agg": "count", "@of": "Week.id", "@via": "Program.weeks" }}
       ]}},
-      { "identity.primary": { "@fields": ["id"] }}
+      { "identity.primary": { "name": "pk", "extends": "Program.pk" }}
     ]
 }}
 ```
 
-**`origin`** subtypes: `passthrough` (cross-entity field reference) and `aggregate` (count/sum/avg/min/max). Origins drive view DDL.
+**`origin`** subtypes: `passthrough`, `aggregate`, `collection`, `computed`,
+`first` (`base` is the abstract root). Origins drive view DDL. The four assembly
+origins live on `object.projection` only.
 
 **Source-aware codegen dispatch:**
-- Projection (dbView only) → read-only Zod, read-only routes, read-only hooks.
-- Write-through (dbTable + dbView) → mutations target table, queries target view.
+- Projection (read-only `@kind` only) → read-only Zod, read-only routes (GET list
+  + GET by id; every write verb answers `405 {"error":"method_not_allowed"}`),
+  read-only hooks.
+- Write-through (`@role:primary` table + `@role:replica` view) → mutations target
+  the table, reads route through the view.
 - Vanilla entity → standard behavior.
 
+Gated end-to-end by `fixtures/api-contract-conformance/projection/` (view-only)
+and `.../write-through/` (table + replica view).
+
 **`columnNamingStrategy`** in `metaobjects.config.ts`: `snake_case` (default) | `literal` | `kebab-case`.
 
 ### Currency (Project F)

AGENTS.md

@@ -284,7 +284,7 @@ import { EntityFetcherProvider, EntityGrid } from "@metaobjectsdev/tanstack";
 
 ## File organization
 
-**Default convention**: one file per domain concept under `metaobjects/`. Multiple objects per file when they share a domain. Projections (`source.dbView`) live inline with their base entity.
+**Default convention**: one file per domain concept under `metaobjects/`. Multiple objects per file when they share a domain. Projections (`object.projection` with a read-only `source.rdb @kind`) live inline with their base entity.
 
 `metaobjects/` is the **default value** of `sources` in `.metaobjects/config.json` — never a requirement. A project declaring `sources` explicitly can point anywhere (and need not have such a directory at all); `"sources": []`, which is what `meta init` scaffolds, takes the default.
 

scripts/check-doc-examples.ts

@@ -85,6 +85,16 @@ const SCAN_ROOTS = [
   // the entire corpus it was BUILT for — #337 was about the agent-context docs teaching
   // retired vocabulary, which is exactly what stops being checked.
   "agent-context",
+  // The auto-loading Claude Code rules. These are the MOST agent-facing prose in
+  // the repo — `.claude/rules/*.md` loads itself into a session on a path match,
+  // unprompted — and they were the one such tree this gate did not read. It cost
+  // exactly what #337 cost in agent-context: `codegen-architecture.md` taught
+  // `source.dbView` / `@name` / a view-sourced `object.entity` long after the v2
+  // paradigm (ADR-0007) retired the first two and B4b (ADR-0028) made the third
+  // `ERR_ENTITY_PRIMARY_SOURCE_READONLY`. Every example it shipped had stopped
+  // loading, and the file that teaches codegen is the file an agent doing codegen
+  // reads first.
+  ".claude/rules",
 ];
 
 /**