# Cartography — Information Architecture reference (Mode 4, artifact 1 of 3)

The method + template for `evaluation/information-architecture.md`. Spine + inputs + orchestration are
in [`cartography.md`](cartography.md); the other two artifacts in [`cartography-flows.md`](cartography-flows.md)
and [`cartography-coverage.md`](cartography-coverage.md).

The IA doc is the map of **how the product is organized for the operator**. Walk the live app
(read-only, in-app nav — never a full reload mid-walk, ingestion §9.4); for every reachable surface
record its **depth**, whether it is **promoted** or **buried**, its **operator capability**, its
**route**, the **wire endpoints** it fires, and the **entities** it touches.

---

## The depth taxonomy (the load-bearing measure)

A capability's _depth_ is the product's implicit priority signal — record it **numerically**:

| Depth | Meaning | Example |
| --- | --- | --- |
| **D0** | a top-level nav destination (sidebar / top-bar item) | `Products`, `Settings` |
| **D1** | a list / index under a D0 destination | the product grid; the attributes list |
| **D2** | a detail / editor surface, or a tab within it | a product edit form; an attribute's config |
| **D3+** | a sub-panel, modal, drawer, or nested tab | "Ask AI" panel; a variant-axis editor; a workflow-config sub-tab |

**Promoted** = the capability is a D0/D1 first-class destination. **Buried** = it is only reachable at
≥D2 (often D3+), behind a detail surface or a menu. Depth is what makes the two reconciliations below
computable.

---

## The two reconciliations that matter

1. **Positioning-vs-product (the buried flagship).** A feature the **marketing** promotes — a verb on
   the homepage, a named hero capability — that lives at **≥D3** in the product is a real finding. Name
   it; it feeds `feature-coverage.md`'s _buried flagships_ section. (A "Workflow engine" splashed on the
   site but reached only via a product → menu → sub-tab is the canonical case.)
2. **Unmarketed depth (the inverse).** A deep, powerful surface the marketing **never mentions** (a rich
   admin/config/automation surface, a governance log, a bulk-action engine) is equally a finding — it
   feeds `feature-coverage.md`'s _unmarketed depth_ section.

Both are computed by comparing the **walked nav depth** (this doc) against the **claimed feature
catalog** (`cartography-coverage.md`).

---

## Surface cards (the screen layer that realizes the entity spine)

One card per **primary** surface (each D0 destination + each materially distinct D1 list and D2 detail
surface). The card is the join between the IA and the data model:

```markdown
### <Surface name>   [route · depth Dn · promoted | buried]
- **Capability:** what the operator can do here (read / create / edit / configure / run)
- **Entities:**   the domain entities it surfaces (link → data-model-api-surface.md)
- **Endpoints:**  the app-own wire calls it fires (link → _shared/api-path-catalog.md)
- **Screenshot:** captures/screens/<nn>-<surface>.png   (or: gap — reason)
```

> **Cross-dimension reconciliation (a route that's in the bundle but not in the nav).** Diff the walked
> nav against `deployed-client-bundle`'s `route-table.md`: a route present in the bundle but **never
> reachable in the live nav** is a **dormant / unshipped surface** — a finding, not noise. (On a
> server-rendered / RSC app, a bundle route count can overstate the client surface — fold that into the
> note rather than reporting a phantom "unused routes" gap; ingestion §9.4 RSC check.)

---

## The output template — `evaluation/information-architecture.md`

```markdown
# <Target> — Information Architecture
## TL;DR              (org-shape in 3–5 sentences: how many top-level destinations, what's promoted vs
                       folded, the deepest important surface, the biggest positioning-vs-product gap)
## Nav tree           (the full hierarchy as an indented tree or table: top-level → section → list →
                       detail → sub-tab; tag each node with depth D0/D1/D2/… and [promoted]/[buried])
## Surface cards      (one per primary surface — the card shape above)
## Promoted vs buried  (the headline reconciliation: first-class destinations vs surfaces hidden N
                        levels deep — name the surprises in BOTH directions: buried flagships AND
                        unmarketed depth)
## Admin / settings depth   (the configuration surfaces + how deep they sit)
## Global affordances  (command palette, global search, create-anywhere, keyboard shortcuts — if present)
## Cross-dimension reconciliation  (nav-as-walked vs the bundle route-table / docs IA — dormant/unshipped
                                    routes are findings)
## Open questions
```

> The IA doc **feeds** `feature-coverage.md`: every surface card's route + depth is what the coverage
> matrix's `Located? · Route · depth` columns cite, and the promoted-vs-buried headline is what its
> _buried flagships_ / _unmarketed depth_ sections draw from. Build the IA doc first, then coverage.