rag-wright 0.10.0__tar.gz → 0.11.0__tar.gz

{rag_wright-0.10.0 → rag_wright-0.11.0}/.claude/skills/authoring-a-capability/SKILL.md

@@ -28,6 +28,13 @@ authoring surface from `rag_wright.api`: `CapabilityManifest`, `register_capabil
 `engine_capabilities`, `register_canonical_slugs`, `canonical_capability_slugs`, `load_reference_pack`,
 `reference_pack` (the same objects as in `capabilities/manifests.py` and `capabilities/registry.py`).
 
+**In a product** (the usual case for a new domain): your capabilities live in your own pack package, for example
+`src/<product>/pack/subgraphs/<slug>.py` and `src/<product>/pack/capabilities/<slug>.py`, with a
+`src/<product>/pack/__init__.py` exposing `register()`; everything below applies unchanged, with your pack module in
+place of the engine's `packs/...` paths. Name your slugs with your product's prefix (`<product>_<capability>`), so they
+can never collide with the engine's or the reference pack's. If your subgraph imports `langgraph` directly, declare it
+in your own dependencies (`uv add langgraph`): a transitive dependency of the engine is not yours to rely on.
+
 ## The four surfaces (the definition of done)
 
 A finished capability touches these: 1 (implementation) is for EVERY kind; 2 (the invoke factory + `impl_ref`) is
@@ -71,6 +78,10 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
    kind that invoker serves (`KeyError` / `ValueError` otherwise), then imports the `impl_ref` via
    `capabilities.invoke.capability_impl` — AND exposable over MCP (surface 4b), with **zero engine edits**.
 
+5. **The eval, written first** (`creating-evals`): the capability's executable acceptance, run through the
+   capability layer (`ainvoke_subgraph` / `ainvoke_model`), so it measures what production runs. A capability without
+   one is not done.
+
 4b. **MCP exposure** (optional) — any invokable capability is already an MCP tool with zero extra code via
    `api/mcp.py::build_capability_mcp(slug, resources=ws)` (EP-RT-2). Write a bespoke FastMCP server only
    when you want a CURATED, typed tool signature instead of the generic opaque-`inputs` surface.
@@ -109,8 +120,9 @@ MCP) follows automatically for invokable kinds; 4b (a bespoke MCP server) is opt
   `packs/compliance/skills/compliance_judgment/SKILL.md`) + the agent runtime (e.g. `skills/rlm/`). It is LOADED (progressive
   disclosure), not called: no `ResponseBounds`. Declare `requires=(...)` for a closure over other skills and
   `skill_runtime` (`SkillRuntime`, from `rag_wright.pack_sdk`) for its intrinsic runtime.
-- A product's agent (a Deep Agents harness) is not a capability kind yet: an `agent` kind is a later engine workstream
-  (PS-33, engine ADR-0139). Build agents in the product, on `agent_chat_model` for their model.
+- A product's agent is not a capability kind yet (an `agent` kind is a later engine workstream, PS-33). Build it on the
+  engine's harness tier, `rag_wright.harness` (an `AgentDefinition` run with `start_run` / `resume_run`; the
+  `building-an-agent-harness` skill); its tools call your capabilities by name, through your operations.
 
 ### mcp_tool — a capability exposed over MCP
 - A distinct ARD identity (`<slug>_mcp`) for the same underlying capability exposed as a cross-agent MCP tool.

rag_wright-0.11.0/.claude/skills/building-a-product-backend/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: building-a-product-backend
+description: The architecture of a product backend over a retrieval engine - the four units and the one dependency law, the placement test for every new operation, the operation layer that gives a route and an agent one implementation, tenancy that cannot be forgotten, jobs as a queue of items, and the guards that make each of these fail loudly instead of drifting. Load at the START of a new product's backend and before adding any route, operation, table or engine call. Pairs with building-a-product-frontend and building-an-agent-harness.
+---
+
+# Building a product backend over an engine
+
+Repository paths in this skill (`docs/`, `src/`) are in the engine repository: read them there or on GitHub, at the tag matching your installed engine.
+
+> **This skill was distilled from a shipped backend and is written for a DIFFERENT product.** It ships in the
+> engine wheel; link it into your repo's `.claude/skills/` (`docs/installation.md`).
+>
+> **Every rule below was paid for**, and the measurements are kept because they are why anybody follows the
+> rule. Its two companions cover the other surfaces: `building-a-product-frontend` and
+> `building-an-agent-harness`.
+>
+> **The one sentence.** Your backend is not thin HTTP over engine calls. It is where **product policy**
+> lives, and almost every decision below is about making sure that policy has exactly one home and cannot
+> be re-derived, forgotten or bypassed.
+
+## Four units, one dependency law
+
+| unit | owns |
+|---|---|
+| **engine** | capabilities, the ontology machinery, the generic ingestion and query primitives, the capability registry |
+| **agent harness** | the loop, memory, delegation, interrupts, deadlines, run grading: the engine's `rag_wright.harness` tier |
+| **UI core** | shell, workspaces, users, roles, the chat surface, the table and state primitives |
+| **product** | your domain pack (`.ttl` + capabilities), the routes for your deterministic use cases, the operations behind them, the agent's definition (tools, workers, prompts, rules) |
+
+**Product -> Harness -> Engine, and Product -> Engine. Never upward.** The engine and its harness tier enforce
+their half with import contracts; your half is a boundary test in your repo: product code imports only
+`rag_wright.api`, `rag_wright.pack_sdk` (pack code) and `rag_wright.harness` (agent code).
+
+**Fix the UI core / product boundary inside your repo on day one**, so a later split is a move rather than an
+untangling. The failure mode is "keep it in mind as a requirement": in the product this comes from, zero of
+seventeen architecture decisions governed the front end, its conventions lived in recall, and it drifted. **A
+convention is only enforced when violating it fails loudly.**
+
+## Where your domain's pipelines live: your pack, on the engine's primitives
+
+The engine is domain-neutral. It ships three kinds of thing, and a new domain uses each differently:
+
+| kind | examples | what you do |
+|---|---|---|
+| **mechanism** | the store, model profiles, tracing, encoders, the registry, document parsing | use it as is |
+| **generic primitives** | `build_ingestion` and its hooks, hybrid search, graph query, answer generation, span judging, the decision model | compose them |
+| **the reference pack** | a contract-ingestion pipeline, a compliance check | read it as a worked example; never your domain |
+
+**Your domain's composites are your pack's capabilities.** An ingestion pipeline for your documents is
+`build_ingestion` plus your extractor and hooks; a query workflow is your capability composing the engine's
+primitives; both are registered with the engine (`register_capability`, `load_pack`) so a route, an agent and
+an eval all invoke them by name. The `authoring-a-capability` and `building-an-ingestion-capability` skills
+carry the how.
+
+**Do not re-implement a primitive, and do not reach past the public tiers for one.** The measured reason: a
+domain pipeline that imported 21 engine internals broke at runtime, on a customer's corpus, when the engine
+removed ONE of them, while the product's suite reported 644 passed, 1 failed (a monkeypatch test). Through the
+public tiers that change is a named diff in your surface snapshot instead.
+
+**When a primitive does not fit, that is an engine request, not a fork.** Write it in your
+`docs/engine-requests/` with the evidence, and meanwhile drop to the next primitive down in your own
+capability; never copy engine code into the product.
+
+**IP exposure is a packaging question, not a placement one.** A domain workflow that must stay proprietary is
+your closed pack, depending on the open engine; it never needs the engine to know about it.
+
+## The placement test, for every new user operation
+
+> **Product policy -> product. Use-case shape -> engine.**
+>
+> - Does it depend on **tenancy, roles, workspace selection, billing, or a UI or agent affordance**?
+>   **Product.**
+> - Is it domain knowledge or a domain pipeline (vocabulary, schema, extraction, a typed query)? **Your
+>   pack**: the `.ttl` plus capabilities registered with the engine, invoked by name.
+> - Would any product of any domain reuse it unchanged, and does no public primitive cover it? **An engine
+>   request.**
+
+**Tenancy is the sharpest discriminator.** The engine owns the mechanism (a store, a document filter); the
+product supplies the values (which store, and which documents this workspace selected).
+
+Apply it in both directions and trust the answer. Grading, coverage, corpus-wide sweeps, export and named
+conditions all stayed in the product here, because **what counts as a match is a product judgement** and
+burying it in the seam would have made it unreviewable. Same test, opposite answer, and it was right.
+
+## The operation layer: one implementation, two callers
+
+**This is the most important decision in this skill.** You have two drivers - a click and an agent turn -
+and they must be the same code.
+
+| layer | holds |
+|---|---|
+| `workflows/` (primitives) | `grade`, `coverage`, `search`, `correct`, `export_*`. **Pure, tenancy-free, unit-testable.** |
+| **`operations/`** | **composition and policy.** One function per user operation, taking a tenant and scope context, returning a typed result. |
+| `api/routes/` | **HTTP only.** Parse, call the operation, serialize, status codes. |
+
+**The route calls the operation. The agent's tool IS the same operation.** Identical output by construction
+rather than by discipline.
+
+**The measurement that forces it.** One route here was 76 lines composing SIX steps: canonicalise the inputs,
+run the search against the tenant's graph, **grade** the results against product policy, resolve display
+names scoped to the customer, compute **coverage over what was SUBMITTED rather than what retrieval
+returned**, and assemble. An agent calling the underlying primitive would get raw results and have to
+re-derive four of those - so **the same question would return a different answer depending on whether the
+user clicked or typed, and the chat answer would be the one with no grading policy behind it.**
+
+**Enforce it:** a route module may not import the primitives. It reaches them only through an operation.
+That one import rule is what makes the layer real.
+
+**Make the operations a registry, and prove the two callers agree.** Give each operation an id, a version, typed
+parameters (with the sources of their dropdown values), a result shape and whether it writes; the UI's menu and the
+agent's tool surface are both built from it. Then a **parity test** invokes each read-only operation both ways (the
+route, the agent's tool) on fixed data and asserts identical results, and a second test asserts no operation that
+writes is on the agent's tool surface unless the spec says so: a store write reached from chat is a write no person
+confirmed.
+
+## The API is the product, so make the claim CHECKABLE
+
+Saying "the API is the product" changes nothing. Two ratchets do:
+
+1. **Every table has a route.** A data model with no way to reach it is a feature that does not exist.
+2. **Every route in the published schema is named by at least one test**, with an **empty** exemption map and
+   exact equality.
+
+**Write the second one carefully, because the first draft of ours was vacuous.** It scanned every test file
+including itself, and its own docstring named the one untested route - so it passed on exactly the broken
+surface it was built to catch. **A guard satisfiable by its own prose proves nothing.** Exclude the guard's
+own file, and prove it with an **assembled** sentinel path so the file's text cannot satisfy its own scan.
+
+Fixed, it immediately found a second untested route. And the untested route it was written for had been
+returning **500 on every real request for five tasks of green suites**: the pieces either side had fifteen
+tests and three tests respectively. **What nobody tested was the wiring between them**, which is all a
+handler is.
+
+## Tenancy you cannot forget
+
+**Derive the per-customer store name; never store one.** A pure function of the tenancy key. Ids are unique,
+so two customers cannot produce one name, and there is **no stored value to go stale, be copied between
+environments, or be left empty**. Route every resolution through **one choke point**.
+
+**If you support a per-customer override, make the column UNIQUE.** Then two customers pointing at one store
+is impossible rather than unlikely. (And any test that sets such an override must release it on teardown, or
+the next run fails on the constraint rather than on anything it was testing.)
+
+**Deny by default, as a database fact.** Membership is a row in a link table and its absence is a refusal.
+Give it a **composite primary key** so "one membership per user per workspace" is enforced by the database
+rather than by an `if not already_a_member` somebody has to remember.
+
+### The corpus belongs to the CUSTOMER; a workspace is a SELECTION over it
+
+Ingestion puts an item in the customer's corpus **once**. Membership in a workspace is a separate
+many-to-many fact: one item may be selected into several workspaces.
+
+(A single-tenant product with one shared corpus still benefits from the selection model the day a second
+team or project arrives; if you defer it, record the decision.)
+
+**This is the decision a new product most often gets wrong**, by attaching documents to a workspace directly.
+Get it right and re-use costs nothing, scoping is one join, and "the same document in two workspaces" is not a
+duplicate ingest.
+
+### Resolve the scope INSIDE the operation, never take it as an argument
+
+The operation asks the store which items this workspace may search and passes that list into every query. A
+caller that forgot would query the whole customer's corpus **with nothing on screen to say so**.
+
+**And short-circuit an empty selection before touching the engine.** This is a correctness fix, not an
+optimisation: found by opening the page in a browser, a workspace with nothing ingested returned **HTTP
+500**, because the first thing a graph traversal touches is a type that a database nobody has ingested into
+does not have. So the **first thing a new customer sees** failed with "Internal Server Error". Short-circuit
+in the product rather than catching the engine's error: an empty selection is a legitimate state you already
+know about, and swallowing a store exception would also hide a genuinely broken store.
+
+**No route may take a client-supplied handle without scoping it**, and the durable half is a guard that
+proves the *next* route will too. A test that two routes call the check is worth much less than a test that
+every route must.
+
+## Jobs: product-owned, and the unit of queuing is ONE ITEM
+
+The product owns the job lifecycle end to end: the record, its status, stage, counts and tenancy.
+
+**A bulk operation is not one row.** Make it a **parent** coordinator row that processes nothing and holds
+the batch outcome, plus **N child** rows, each carrying one item's storage key and a foreign key back to the
+parent. One row per batch cannot be resumed, cannot report per-item progress, and cannot be retried
+selectively.
+
+**A lost item is its VERDICT, not its job status.** Define one predicate - with a SQL twin so the API and the
+database agree - for "this item was lost": the job failed, **or** the work's own verdict says it failed.
+**A partial result is not a loss**, and that boundary belongs to the engine's own outcome type: a partially
+ingested item is written and can be queried, it simply lost some extractions, and calling it a failure offers
+a retry that re-ingests something already in the graph.
+
+**Lease fields go in typed columns**, because the queue filters and orders on them.
+
+## The data model: typed columns for the spine, JSONB for the volatile
+
+Decide per field with a stated test rather than by taste. **A typed column** if any of these holds: the store
+**filters, orders, joins or aggregates** on it; it must be **constrained** (not-null, unique, a foreign key, a
+bounded set). **JSONB** for the rest - payloads, reports, volatile nested shapes.
+
+**Then walk the metadata in a test**, so the principle cannot be violated accidentally. A principle nobody
+*can* break beats one everybody has to remember.
+
+### Two schemas, one database, one owner each
+
+If a framework creates its own tables (a checkpointer, a queue, a cache), **give it its own schema**.
+
+The failure otherwise is severe and quiet: your migration autogenerator walks your models, finds tables in
+its schema with no model behind them, and writes a `drop_table` for each. A routine migration then **deletes
+every suspended run**. In a separate schema they are simply not reflected.
+
+## Identity: two paths, one session
+
+Federated sign-in and password sign-in converge on **one server-side, revocable session record**, with a
+token in an HttpOnly cookie. Two paths, one session, one revocation story.
+
+- **A signup records an ATTEMPT; confirming the emailed token is what provisions the account.** Hold the
+  pending signup with an already-hashed password and its own hashed, single-use, short-lived token.
+- **Consume every single-use token atomically**: one `UPDATE ... WHERE used_at IS NULL RETURNING`. Not a read
+  then a write.
+- **A federated callback that reads an email and issues a session IS an account-takeover primitive** unless
+  something asserts the person owns that address. The provider's verified-email claim is the only thing that
+  does. Gate linking on it.
+
+**Uploads go client-to-storage through a signed URL.** The API issues the URL and handles control traffic
+only; bytes never pass through your process. It removes a whole class of timeout, memory and size problems
+before they exist.
+
+## Policy stays in the product, even when the engine could hold it
+
+The pattern to copy: **the engine reports the FACT, the product decides the GROUPING.** The engine judges
+each result against a condition and returns a verdict with a rationale and a confidence; the product decides
+which verdicts count as matched, possible or not-found, and what that means for the user.
+
+Keep it in the product and it is reviewable, testable and changeable per product. Bury it in the seam and
+nobody can see what the number meant.
+
+**Related: do not cache what the layer below already caches correctly.** Read the engine's caching before
+adding yours. A second cache is a second answer to one question, which is the failure the single-home rule
+above exists to prevent.
+
+## The seam, and reaching for an internal honestly
+
+One module is the engine's door. Import the engine's **public API** and nothing deeper; assert it with a
+boundary test.
+
+When you genuinely need something the public tiers do not carry yet, **write the engine request** and keep
+your interim on the public surface (a coarser primitive, a product-side composition), recorded with the
+request it waits on, and a ratchet that **fails the moment the engine publishes it**. Then adoption is a
+*deletion* - drop the fallback, drop the line - rather than something to remember. Never import an engine
+internal to bridge the gap. Also snapshot the engine's public surface (`rag_wright.api.__all__`, and the
+`pack_sdk` and `harness` tiers you use) so drift is a named diff rather than a mystery failure three layers
+into a call site.
+
+**And a moved engine is normal.** Guard the thing that can reach you - the published surface - not the
+commit. A guard that fires on every unrelated release is a guard people learn to ignore.
+
+## Testing a product over an engine
+
+**Put a LIVE test on every engine seam.** Fakes prove your mapping; only a live run proves the integration.
+The measurement: of four defects in one seam task, **three were invisible to unit tests**, and the worst - a
+model of the wrong type passed where another was required - failed as an **opaque error inside the engine's
+own guard**, so the fast suite stayed green while the integration was broken.
+
+**Keep the expensive markers out of the default run, and then actually run them.** Three tests here sat
+broken across three tasks because a retrieval signature changed while the default suite - which deselects
+the database-marked tests - kept reporting green. **Run the database-marked suite before committing anything
+that touches a route, a shared fixture or the seam.**
+
+**Separate "needs a database" from "spends money".** Tests carrying both markers perform real ingests and
+spend real credits on every run. Exclude the paying ones by default and run them deliberately.
+
+**Salt a live ingest fixture.** Fixed bytes pin a live test to a stale artefact from a previous engine
+version, which here cost three wrong conclusions in one day.
+
+**And never run the browser suite against the same database as the integration suite.** There is one queue:
+the browser harness starts a real worker, the worker claims the integration tests' jobs, and three of them
+fail with the correct code in front of you.
+
+## Build order
+
+1. **The relational store and the migration tool**, with the schema split decided up front.
+2. **The data-model guard** that walks your metadata. It is cheap now and an audit later.
+3. **Identity and the session**, both paths, with the single-use token consumed atomically.
+4. **Tenancy**: the derived name, the one choke point, membership deny-by-default.
+5. **The seam**, the public-surface snapshot and the boundary test.
+6. **The customer corpus and the workspace-as-selection tables.** Before any ingest.
+7. **Jobs**: parent and child rows, leases in typed columns, the lost-item predicate.
+8. **Uploads via signed URLs.**
+9. **One operation end to end** - primitive, operation, route - and the import rule that keeps routes out of
+   the primitives.
+10. **The two API ratchets**, each proved by planting its violation.
+11. **A live seam test**, before you trust any of the above.
+12. **Then the rest of the operations.** The shape is set and each one is cheap.
+
+## What goes in your project's own child skill
+
+- your placement-test decisions, by operation, with the answer and the reason
+- your seam's interim list and the engine gaps each waits on
+- the commands: migrations, the marked suites, the live seam test, provisioning an account
+- the defects that recurred in **your** backend, with the evidence for each
+- which policy decisions are deliberately the product's, so nobody "simplifies" one into the seam
+
+## Verification checklist
+
+- [ ] Product code imports the engine only through `rag_wright.api`, `rag_wright.pack_sdk` and `rag_wright.harness` (tested)
+- [ ] No route module imports a primitive; it reaches them through an operation (tested)
+- [ ] Each read-only operation returns the same result from the route and from the agent's tool (a parity test)
+- [ ] No store-writing operation is on the agent's tool surface unless the spec says so (tested)
+- [ ] Every table is reachable by a route (tested)
+- [ ] Every route in the published schema is named by a test, exemption map EMPTY, and the guard excludes
+      its own file
+- [ ] The per-customer store name is derived, not stored, and resolved in one place
+- [ ] Any per-customer override column is UNIQUE
+- [ ] Membership absence is a refusal, with a composite primary key behind it
+- [ ] Every operation resolves its own scope and short-circuits an empty selection before the engine
+- [ ] No route accepts a client-supplied handle without scoping it (tested for ALL routes, not two)
+- [ ] Single-use tokens are consumed by one atomic statement
+- [ ] Federated linking is gated on a verified-email claim
+- [ ] Every field is in a typed column or JSONB by the stated test, and a guard walks the metadata
+- [ ] Any framework-owned tables live in their own schema
+- [ ] A partial result is not reported as a loss
+- [ ] Every engine seam has a LIVE test
+- [ ] The database-marked suite was run before committing a route, fixture or seam change
+- [ ] Every new guard was proved by planting its violation and watching it fail

rag_wright-0.11.0/.claude/skills/building-a-product-frontend/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: building-a-product-frontend
+description: The architecture and build ORDER for a product front end over a retrieval/agent engine - the core/product seam, generating the API client from the schema, the URL as state of record, one data-access layer, and the three test tiers in the order you need them. Load at the START of a new product's UI, and before changing the shape of an existing one. Craft (composition, a11y, states) is frontend-ui-engineering, which still applies.
+---
+
+# Building a product front end over an engine
+
+Repository paths in this skill (`docs/`, `src/`) are in the engine repository: read them there or on GitHub, at the tag matching your installed engine.
+
+> **This skill was distilled from a shipped product and is written for a DIFFERENT one.** It ships in the
+> engine wheel; link it into your repo's `.claude/skills/` (`docs/installation.md`). Its companion craft skill,
+> `frontend-ui-engineering`, is one of the shared way-of-working skills. The agent surface it ends with is built
+> on the engine's `rag_wright.harness` tier (`building-an-agent-harness`).
+>
+> **It is PRODUCT-AGNOSTIC on purpose, and every number in it is measured.** Each decision below was paid
+> for once, by shipping; the measurements are kept because they are why anybody follows the rule. What is
+> specific to a single codebase -- its locked choices, its primitives, its paths -- belongs in a
+> project-scoped child skill of your own, never in this file. The last section says what to put there.
+>
+> **It is the ARCHITECTURE skill, not the craft skill.** `frontend-ui-engineering` covers composition,
+> accessibility, spacing, states, and the ways UI defects hide from a green suite. Load both. Where that
+> skill already says something, this one points at it rather than repeating it.
+
+## The shape every one of these products has
+
+A front end over a document-retrieval-plus-agent engine is, every time, the same six things:
+
+1. **Identity**: password and federated sign-in, one session, email verification, password reset.
+2. **Tenancy**: an account, workspaces inside it, membership and roles, deny-by-default authorization.
+3. **A corpus**: upload, ingestion progress, a library of what has been ingested, a per-item detail view
+   with the source rendered and its extracted records beside it.
+4. **Deterministic operations**: menu-driven, parameterised, reached by a click. Each returns a result that
+   cites its evidence.
+5. **An agent surface**: chat that can pick up from a deterministic result, ask for more, take feedback, and
+   answer open questions.
+6. **Housekeeping**: settings, members, usage and spend.
+
+**What changes between products is the entities and the operations. The structure around them does not.**
+That is why this skill exists, and it is also the exact limit of what can be shared: see the seam below.
+
+## Decision 1: two directories, and the dependency arrow points one way
+
+```
+src/core/      knows NOTHING about the domain. Shell, layout, tables, auth pages, theme,
+               data-access plumbing, settings. The thing you carry to the NEXT product.
+src/product/   the domain. Entity names, the operation surfaces, the copy, the registries.
+```
+
+**The core reads registries the product populates.** Navigation is the first one: the product declares its
+surfaces (path, label, icon, which ones appear in nav) and the shell renders whatever it is given. The core
+never imports from the product; the product imports from the core.
+
+**Enforce it with a scan, not with intent.** A test that greps the core directory for the domain's own words
+-- comments and docstrings included -- and fails on any hit. Two properties make it work:
+
+- **Comments count.** A core component commented "this is where the invoice total goes" is coupled; the next
+  person writes code to match the comment.
+- **Strip paths and references before scanning**, or a legitimate pointer to a domain document trips it and
+  somebody adds an exemption, and then the exemption list is the guard.
+
+Write this test with the second directory, on the first day. Retrofitting it means auditing everything.
+
+### The seam is a discipline, NOT a framework
+
+**Do not build a plugin loader, dynamic module registration, a theming engine, or config-driven forms.**
+Adaptation is **import-then-customize**: the next product copies or depends on the core, declares its own
+registries, and writes its own result surfaces.
+
+This is the most tempting decision to get wrong, so here is the reason in full. A result surface looks
+generic -- read a parameter from the URL, run a query, render loading/error/empty, group the rows, cite each
+one. Most of it is. But a small number of branches in those pages encode **domain truths, not layout**:
+
+- *"Not found is not the same as none."* An unrecognised name must not render like a clean, empty result:
+  one says "we have nothing on this", the other says "you are exposed to nothing", and only one of them is
+  true. A typo must never read as an all-clear.
+- *"These two groups must never be merged."* A parent organisation and its subsidiary are different parties;
+  pooling their records into one total misstates who is responsible for what. The separation is a fact about
+  the world, enforced in the rendering.
+
+A configuration schema has two options for a rule like that. It cannot express it -- and the generated page
+is plausible, well laid out, and wrong, which is the most expensive kind of wrong in a product people make
+decisions from. Or it can express it, and the configuration is now a programming language with no type
+checker, no tests and no reviewer. **Generalise the shell, the plumbing and the primitives; write the result
+surfaces.** They are the cheapest part and the part that carries the meaning.
+
+## Decision 2: GENERATE the API client from the schema
+
+If the backend publishes a machine-readable schema -- and a modern Python or TypeScript backend does, for
+free -- **the client is generated, never hand-mirrored.**
+
+Measured, on the product this skill comes from: a hand-written client reached **1,154 lines, 87 exports and
+24 endpoint string literals**, and its own header comment admitted the schema was the real source of truth
+"if they ever drift". They had already drifted: a comment two-thirds down recorded that the field names
+there had gone stale behind the backend **twice**.
+
+The discipline that makes generation work in practice:
+
+- **Commit the generated file.** A diff in a pull request is how a breaking backend change becomes visible
+  instead of a runtime surprise.
+- **Regenerate in CI and fail on a dirty tree.** Otherwise the generated file is a hand-written file with
+  extra steps.
+- **Hand-write only the thin layer above it**: auth headers, error normalisation, the query-key factory.
+- **Change the client type in the SAME commit as the backend type.** A field that became optional while the
+  client still types it as required is a dereference that survives a full green suite and a clean build.
+
+## Decision 3: the URL is the state of record
+
+Page, filters, sort, selection, which panel is open, which tab is active -- all of it in the URL, none of it
+in component state.
+
+Three reasons, and the third is the one people forget: it is shareable, the back button is correct by
+construction, and **an agent can hand the user a link to what it just did**. In a product where a chat turn
+and a click are both first-class ways to reach a surface, state the agent cannot address is state the agent
+cannot hand back.
+
+**Write the guard when the first consumer lands.** Deferring it is reasonable while there is nothing to
+guard; what fails is the deferral with a named trigger that nobody checks. If you defer, write the trigger
+down where the next person will look, not only in the ticket.
+
+## Decision 4: one data-access layer, two guards
+
+A query-key factory is the only place keys are built; no component calls `fetch` directly. Both guards are a
+source scan, both take minutes, and both are provable by planting their violation:
+
+- no inline key array outside the factory
+- no `fetch(` in a component
+
+A library's own `refetch()` goes *through* the layer and is the opposite of a violation -- make sure the
+guard knows the difference, or it will be disabled by the first person it annoys.
+
+## Decision 5: one table primitive, and the allow-list that must not grow
+
+Build the table once, and allow a raw `<table>` element in exactly that one file. Everything else that needs
+a table uses the primitive; if the primitive cannot do it, extend the primitive.
+
+**Adding a file to the allow-list without it BEING the primitive is how a rule becomes an exemption list.**
+The guard should make that edit conspicuous: one line, in a file whose name says what it is for.
+
+Make pagination props optional. An unpaginated listing that renders "N rows" is better than a pager over a
+single page -- and see the arithmetic warning below before you let a page size anywhere near a count.
+
+## The three test tiers, and the ORDER is the lesson
+
+| tier | answers | structurally blind to |
+|---|---|---|
+| **unit / jsdom** | does this component behave? | **anything visual -- jsdom computes no CSS** |
+| **browser, against the BUILT artifact** | does what we already know to check still hold? | anything nobody thought to assert |
+| **a person or agent looking at it** | **what did nobody think to check?** | regressions -- it runs once |
+
+`frontend-ui-engineering` has the detail on what each tier cannot see and how to pick between them. What
+belongs here is the **sequencing**, because this is the thing a new product gets wrong:
+
+**Stand up the browser tier before your second surface, not after your ninth.** Adopted late, it arrives as
+a backlog of surfaces nobody has ever watched render -- and the first run finds defects on all of them at
+once, in a batch too large to attribute to the change that caused each one. Measured on the product this
+comes from: once the discovery tier existed, it found a real defect on **every single surface built**, and
+the majority were invisible to every automated tier in the repo -- an invisible sign-in button, a duplicated
+main landmark, every control under the minimum hit area, a document rendered at a third of its intended
+size, two adjacent controls reading as one, a content region narrower than the panel beside it, and a white
+screen on a page whose component tests were entirely green.
+
+**The browser tier runs against the production build**, not the dev server. The server harness for it:
+
+- its **own** database, created and migrated for the run -- never the development database
+- the test account provisioned through the **real** provisioning command, so the path under test is the path
+  users take
+- a **build**, then serve the build the way production serves it
+- **rebuild on every run**, or a planted source change never reaches the browser and a guard you are proving
+  cannot fail
+- **kill any hand-started dev server first.** A harness that reuses an existing server will serve a stale
+  build, and the fix you just made appears to fail
+
+Two traps worth naming in advance: a production build does **not** double-invoke effects, so anything that
+only manifests under development-mode strict rendering belongs in the jsdom tier and could never fail in the
+browser; and an accessibility sweep over *mocked* pages never renders the real shell, which is how nested
+landmarks survive indefinitely.
+
+**Drive the browser by element reference. Never by screen coordinates.** Locator-first frameworks make the
+mistake inexpressible; a browser-automation plugin will happily take a pixel, and nothing but this rule
+stops you. A stale reference is the signal to re-read the page, never to reach for coordinates. And after a
+click that navigates or submits, wait and confirm before the next step -- racing a sign-in request with a
+navigation makes a route guard bounce it, which looks exactly like broken authentication.
+
+**Anything the discovery tier finds becomes a browser test in the same change.** A finding left as an
+anecdote is a defect that comes back; the repeated pattern is a human finding the same fault three times
+because no run of it ever became an assertion.
+
+## Rules that each cost a real defect, in portable form
+
+**A feature ends at the surface.** A backend change whose UI lands "next task" does not land. Ship the
+surface in the same commit, and check what neighbouring commits touched before calling a task done. A
+structural guard helps -- a new table with no route fails -- but nothing enforces "and a person can reach
+it" except looking.
+
+**A failed load must never render as an empty result.** "You have none" and "we could not read what you
+have" are different claims, and in a product people act on, one of them is a false assurance. Same shape
+everywhere: "no results" versus "no such record"; "not retained" versus "retention expired".
+
+**Every data surface defines loading, empty AND error.** Guard it by scanning for the three states, and make
+any exemption a written line in the file that says why -- a surface addressed by an id has no "no results"
+case. A silent exemption is how "every data surface" becomes "most of them".
+
+**A page size is a presentation choice and must never become an arithmetic one.** A list capped at 100
+feeding a coverage numerator reports "100 of 100 processed" for a 500-item job. If a number means coverage,
+it comes from the count, never from the page.
+
+**Never present text the user did not write as theirs.** An assembled excerpt shown under "in your document"
+attributes words to somebody in an order they never used. If the backend labels which spans are verbatim and
+which are reconstructed, read the label instead of guessing, and never invent a filename for pasted input.
+
+**Hit areas: measure them, do not eyeball them.** Every control in the product this comes from was under the
+minimum until one was measured in a real browser. A text input is its own target and cannot borrow an
+adjacent button's padding.
+
+**A list the UI owns is a capability the UI will silently lack**, and **any guard with a hand-maintained list
+goes stale silently**. Both are in `frontend-ui-engineering` with the mechanics; they are listed here because
+they bite hardest in exactly this kind of product, where the backend's capability set grows every week.
+
+## The build order for a new product
+
+Doing these out of order is what costs the rework:
+
+1. **Scaffold, then the seam.** Two directories and the vocabulary scan over the core, before the second
+   component exists.
+2. **Generate the client.** Before any surface. Everything downstream types against it.
+3. **The data-access layer and its two guards.** Cheap now, an audit later.
+4. **Identity and tenancy surfaces.** They are the most portable code you will write and they exercise the
+   shell, routing and the session end to end.
+5. **The shell: regions, navigation registry, theme tokens.** Resist centring the content region if a detail
+   panel will ever sit beside it -- then make each surface constrain its own measure, and assert it.
+6. **The table primitive**, with its allow-list guard, before the second listing.
+7. **The browser-tier harness** -- own database, real provisioning, build, serve, rebuild per run.
+8. **The first corpus surface** (upload, progress, library, detail). This is where ingestion contracts get
+   real.
+9. **One deterministic operation end to end**, with citations, through all three tiers. Look at it in a
+   browser before calling it done.
+10. **Then the rest of the operations.** By now the shape is set and each one is cheap.
+11. **The agent surface last**, because it needs the operations to exist and the URL state to be addressable.
+
+## What goes in your project's own child skill
+
+This skill carries what is true of any product of this shape. Put in the project-scoped child the things a
+reader cannot derive:
+
+- your locked decisions, with what a violation looks like, and the fact that changing one needs a recorded
+  decision rather than a judgement call
+- your primitives, by path: the table, the shell, the query-key factory, the states helper
+- the commands: how to run each tier, where specs live, what the e2e server script does
+- the defects that have actually recurred in **your** codebase, with the evidence that makes them stick
+- current debts: a guard that was deferred, a decision made but not yet built
+
+Keep that file in front of the person *before* they write code, not in review. A decision recorded only in
+an architecture document is a decision that gets violated with the document already in place.
+
+## Verification checklist
+
+- [ ] The core directory has a vocabulary scan over it, comments included, and it passes
+- [ ] Nothing in the core imports from the product
+- [ ] The API client is generated from the published schema, committed, and regenerated in CI
+- [ ] Any client type mirroring a backend contract changed in the SAME commit as the backend
+- [ ] Navigation-shaped state is in the URL, not component state
+- [ ] Reads go through the query-key factory; no `fetch(` in a component
+- [ ] No raw table outside the primitive; the allow-list did not grow
+- [ ] Every data surface has loading, empty and error, or a written exemption saying why
+- [ ] A failed load renders as a failure, never as an empty result
+- [ ] Anything visual is asserted in a browser against the BUILT artifact, not in jsdom
+- [ ] The guard for whatever changed was proved by planting its violation and watching it fail
+- [ ] A new or substantially changed surface was OPENED and looked at, and anything found became a browser
+      test in the same change
+- [ ] No screen-coordinate interaction anywhere in the change or its tests
+- [ ] The backend change this belongs to ships its surface in the same commit