Categories¶
Per-category reference for every product category 961tech indexes (or has decided not to index). Produced for Foundation: category scope decision (#32) alongside ADR-0010, which records the milestone-placement reasoning. This doc is the what per category; the ADR is the why.
1. Scope & method¶
What this is. A per-category structured profile for the M1, M2, and M3 categories, plus a "Deliberately out of scope" subsection covering categories the project decided not to ship. Format mirrors competitive-landscape.md per-competitor profiles and retailers.md per-retailer profiles so the three reference docs read as a coherent set.
What this isn't. Not a feature spec — that lives in #28 page design. Not the category-scope decision itself — that lives in ADR-0010. Not the per-category spec dictionary in full depth — that's #33. The "Key spec dimensions" field on each profile here is the seed for #33, not its final form.
Sources. Empirical floor: personas.md §6.2 for persona-by-category ranking, retailers.md §2-§3 for per-retailer coverage, competitive-landscape.md §3 for competitor patterns, prisma/schema.prisma for current Category enum.
Honest limits. Retailer-coverage claims are based on the retailer audit's category-listing fields, which are observation-grade. Spec dimensions for the M3 categories (laptops, prebuilts, peripherals) are seeded from competitor-pattern + persona-ranking analysis; they will be tightened by #33 when those categories actually ship.
2. Profile template¶
Every category in §3-§5 uses this template:
### N. <Category name>
| | |
|---|---|
| **Enum value** | `<Category enum value>` |
| **Track** | Builder / Casual / Cross-track |
| **Milestone** | M1 / M2 / M3 |
| **Primary persona(s)** | <names from personas.md §6.2> |
| **Secondary persona(s)** | <names> |
| **Key spec dimensions** | <ordered list — most-queried first> |
| **Canonical product shape** | <how a row in the catalog looks — brand + model + key spec set> |
| **Compat-engine relevance** | <yes / no / partial> |
| **Retailer coverage** | <coverage signal across the audited roster> |
| **Notes** | <category-specific quirks, decisions deferred to #33, etc> |
3. M1 — currently shipping¶
The 8 Builder components. Already seeded via prisma/seed.ts; already scraped at all three current retailers; already covered by the matcher and compat engine.
1. CPU¶
| Enum value | CPU |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (FPS-per-dollar, clocks > cores), First-time builder ("will it run [game]?" + "compatible with my motherboard?") |
| Secondary persona(s) | Layla (cores + RAM channel support for editing), Office IT (vendor stability + warranty + per-socket consistency across batch) |
| Key spec dimensions | Socket (AM4 / AM5 / LGA1700 / LGA1851), core count, base + boost clocks, TDP, integrated graphics presence |
| Canonical product shape | brand + model (e.g. "AMD Ryzen 7 7800X3D", "Intel Core Ultra 9 285K") with cpuSocket, tdpWatts typed; full clock/cache spread in specs: Json |
| Compat-engine relevance | Yes — primary. Socket match drives motherboard compat; TDP drives cooler + PSU sizing |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate (retailers.md §3) |
| Notes | Seeded with full AMD AM4/AM5 + Intel LGA1700/LGA1851 ranges. Future: Intel Arrow Lake refresh + AMD Zen ⅚ land in #21 LLM extraction. |
2. GPU¶
| Enum value | GPU |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (FPS at 1080p / 1440p, VRAM, NVIDIA brand preference), First-time builder ("will it run [game]?" + "does it fit?" + "will my PSU handle it?") |
| Secondary persona(s) | Layla (VRAM, CUDA cores, color-accurate output) |
| Key spec dimensions | VRAM, TDP, length (mm), recommended PSU wattage, brand (NVIDIA / AMD), tier within brand |
| Canonical product shape | brand + model (e.g. "NVIDIA GeForce RTX 5080", "AMD Radeon RX 7900 XT") with tdpWatts, lengthMm, psuWattage typed |
| Compat-engine relevance | Yes — primary. Length drives case clearance; TDP drives PSU sizing; recommended PSU wattage drives the headroom warning |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate |
| Notes | Layla's CUDA-cores secondary axis lands in #33 creator-dimension surface (M2+). |
3. Motherboard¶
| Enum value | MOTHERBOARD |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (socket + chipset + connectivity), First-time builder ("does it match my CPU + RAM?" — relies on compat panel) |
| Secondary persona(s) | Layla (RAM channels + I/O for capture / external), Office IT (vendor stability) |
| Key spec dimensions | Socket, chipset, form factor (ATX / Micro-ATX / Mini-ITX / E-ATX), supported RAM type + speed, M.2 slot count, USB / DisplayPort / HDMI counts |
| Canonical product shape | brand + model (e.g. "ASUS ROG STRIX X670E-E", "MSI MAG B760M MORTAR WIFI II") with cpuSocket, ramType, ramSpeedMhz, formFactor typed |
| Compat-engine relevance | Yes — primary. Socket pairs with CPU; form factor pairs with case; RAM type + speed pair with RAM kits |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate |
| Notes | M.2 slot count is a #22 compat-rule input for "you've selected 2× NVMe drives but the board has only 1 M.2 slot." |
4. RAM¶
| Enum value | RAM |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (capacity + speed + brand), First-time builder ("how much do I need?" + "DDR4 vs DDR5?") |
| Secondary persona(s) | Layla (32GB+ for creators, ECC awareness), Office IT (capacity per-machine spec compliance) |
| Key spec dimensions | Type (DDR4 / DDR5), speed (MHz), capacity (GB), kit configuration (1× / 2× / 4× sticks), CL latency |
| Canonical product shape | brand + model (e.g. "Corsair Vengeance LPX 32GB (2×16GB) DDR5-6000 CL30") with ramType, ramSpeedMhz typed |
| Compat-engine relevance | Yes — primary. Type + speed pair with motherboard support |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate. 961Souq carries an unusually deep Kingston-DDR4 long tail. |
| Notes | ECC vs non-ECC stays in specs: Json until Layla creator-dim surface lands (#33 M2+). |
5. Storage¶
| Enum value | STORAGE |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (capacity + NVMe gen for boot drive), First-time builder ("how much space?" + "SSD vs HDD?") |
| Secondary persona(s) | Layla (sustained write speeds for video editing, capacity tiers), Office IT (vendor stability + warranty) |
| Key spec dimensions | Form factor (M.2 / 2.5" / 3.5"), interface (PCIe Gen¾/5 NVMe / SATA), capacity (GB), rated read/write, sustained write |
| Canonical product shape | brand + model (e.g. "Samsung 990 Pro 2TB", "Seagate IronWolf 8TB") with capacity + interface in specs: Json |
| Compat-engine relevance | Partial. Form factor + interface drive M.2 slot vs SATA bay availability per motherboard / case. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate. Microcity's only deep PC-component category. |
| Notes | Sustained-write benchmarks land via #21 LLM extraction (M2+) for Layla's creator-dim surface. |
6. PSU¶
| Enum value | PSU |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (wattage + 80+ rating, Corsair / Seasonic brand preference), First-time builder ("is this enough watts?" — relies on compat panel) |
| Secondary persona(s) | Layla (wattage adequacy for high-end GPU + redundancy), Office IT (wattage adequacy + warranty) |
| Key spec dimensions | Wattage, 80+ rating (White / Bronze / Gold / Platinum / Titanium), modularity (full / semi / non), form factor (ATX / SFX / SFX-L) |
| Canonical product shape | brand + model (e.g. "Corsair RM850x", "Seasonic Focus GX-750") with psuWattage typed |
| Compat-engine relevance | Yes — primary. Wattage with 30% headroom against summed TDP drives the headroom warning. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate |
| Notes | Per PCPartPicker pattern, PSU compat warning shows rule provenance — "PSU 450W under recommended 600W for 30% headroom on 350W TDP system" — not just "mismatch." |
7. Case¶
| Enum value | CASE |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (form factor + GPU clearance + airflow), First-time builder ("will my parts fit?" — relies on compat panel) |
| Secondary persona(s) | Layla (aesthetic + sound dampening), Office IT (form factor + accessibility for service) |
| Key spec dimensions | Form factor support (ATX / Micro-ATX / Mini-ITX / E-ATX), max GPU length (mm), max cooler height (mm), bay count, included fans |
| Canonical product shape | brand + model (e.g. "Lian Li Lancool II Mesh", "Fractal Design North") with formFactor, lengthMm, heightMm typed |
| Compat-engine relevance | Yes — primary. Form factor pairs with motherboard; max GPU length pairs with GPU; max cooler height pairs with cooler. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate |
| Notes | Aesthetic-tier filters (mesh-front / glass-side / silent) are M2+ filter UX work in #28. |
8. Cooler¶
| Enum value | COOLER |
| Track | Builder |
| Milestone | M1 |
| Primary persona(s) | Karim (TDP rating + clearance), First-time builder ("is this enough cooling?") |
| Secondary persona(s) | Layla (TDP + acoustics), Office IT (TDP + warranty) |
| Key spec dimensions | Type (air / AIO liquid), TDP rating (W), height (mm) for air coolers, radiator size (120 / 240 / 280 / 360 mm) for AIOs, supported sockets |
| Canonical product shape | brand + model (e.g. "Noctua NH-D15", "Arctic Liquid Freezer III 360") with tdpWatts, heightMm typed |
| Compat-engine relevance | Yes — primary. TDP rating must clear CPU TDP; height pairs with case max-cooler-height; supported sockets pair with CPU socket. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate |
| Notes | AIO radiator clearance vs case top/front mounts is a #22 compat-rule extension (M2+). |
4. M2 — adds monitors¶
One new category in M2: monitors. The reasoning is in ADR-0010; the profile is here.
9. Monitor¶
| Enum value | MONITOR (planned — to be added to Category enum when M2 catalog work begins; see ADR-0010 References) |
| Track | Cross-track (Builder completion item + Casual single-item buy) |
| Milestone | M2 |
| Primary persona(s) | Karim (gaming refresh rate + resolution at 1080p / 1440p), Layla (color accuracy — severity-3 acute per §5.6) |
| Secondary persona(s) | First-time builder (build-completion item), Casual customer (WFH peripheral upgrade) |
| Key spec dimensions | Size (inch), resolution (1080p / 1440p / 4K / ultrawide variants), refresh rate (Hz), panel type (IPS / VA / OLED / TN), response time (ms), color gamut % (sRGB / DCI-P3 / AdobeRGB), HDR tier, ports |
| Canonical product shape | brand + model (e.g. "LG 27GR95QE-B 27\" QHD 240Hz OLED", "Dell U2723QE 27\" 4K IPS") with size + refresh + panel + color-gamut in specs: Json |
| Compat-engine relevance | No. Monitors do not constrain other build slots. The all-slots-at-once Builder layout treats monitor as an optional, non-compat-checked completion slot. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate. PCAndParts and Macrotronics dedicate homepage real estate to monitors. |
| Notes | First Casual-track-relevant category to ship. Layla's color-gamut filter (sRGB / DCI-P3 / AdobeRGB %) is the unlock; Karim's high-refresh-rate gaming filter is the parallel unlock. UC-13 single-item product detail (no compat panel) is the Casual surface; UC-9 optional completion slot is the Builder surface. The same canonical Product is consumed by both. |
5. M3 — laptops, prebuilts, peripherals¶
Three categories. All Casual-track. All carry persona-acute pains that the M1 + M2 surface cannot reach. Per ADR-0005 + ADR-0010.
10. Laptop¶
| Enum value | LAPTOP (already pre-allocated in Category enum; not yet seeded) |
| Track | Casual |
| Milestone | M3 — driver issue #24 |
| Primary persona(s) | Casual customer (brand line + screen + price — severity-3 acute "forced into builder UX"), Layla (Apple line + RAM + screen color accuracy), Diaspora (gift-shaped purchases — severity-3 acute delivery routing for in-Lebanon recipients), Office IT (vendor + warranty + on-site service + screen + battery — high-LTV outlier per §6.3) |
| Secondary persona(s) | First-time builder (rare — when build budget collapses to laptop) |
| Key spec dimensions | Brand line (ThinkPad / IdeaPad / Legion / MacBook Pro / etc.), screen size (inch), CPU, RAM (GB), storage (GB), GPU (integrated / dGPU brand + tier), battery (Wh / hours), weight (kg), warranty (months), on-site service availability |
| Canonical product shape | brand + line + model (e.g. "Lenovo ThinkPad T14 Gen 5", "Apple MacBook Pro 14\" M4 Pro 16/512") with brand-line awareness — not SKU-only |
| Compat-engine relevance | No. Laptops are sealed configurations; no upstream compat checks apply. The M3 catalog page deliberately omits the compat panel (ADR-0005 §"Compatibility (UC-B) is deliberately absent"). |
| Retailer coverage | All three current retailers stock laptops prominently (PCAndParts homepage devotes a Laptops grid; 961Souq + Macrotronics carry full laptop catalogs). H-tier next-wave: Mojitech, CompuOne, Expert-Zone, Ayoub all carry laptops. Apple-line depth is uneven (Macrotronics + 961Souq strongest). |
| Notes | Brand-line navigation ("compare ThinkPad T14 vs IdeaPad 5 vs Legion 5") is the persona-acute affordance. Variant pricing per RAM/SSD config is the #21 LLM-extraction sweet spot — title parsing alone won't yield clean canonical Products. Mac vs Windows side-by-side is the Layla-specific surface (M3+). |
11. Prebuilt PC¶
| Enum value | PREBUILT (already pre-allocated in Category enum; not yet seeded) |
| Track | Casual |
| Milestone | M3 — driver issue #25 |
| Primary persona(s) | Casual customer (brand + price + spec sheet), Office IT (vendor + warranty + standardization across batch) |
| Secondary persona(s) | First-time builder ("is this a good build for [game]?" — natural off-ramp when self-build anxiety wins) |
| Key spec dimensions | CPU model, GPU model, RAM (GB), storage (GB), tier branding (gaming / workstation / office), warranty, included peripherals |
| Canonical product shape | brand + model (e.g. "PCAndParts Custom Gaming PC RX 7800 XT / R7 7700", "HP Pavilion Desktop TP01-4015") with included-component spec dump in specs: Json |
| Compat-engine relevance | No. Prebuilts are sealed configurations; the included components are listed in specs but not validated against each other (the assembler did that). |
| Retailer coverage | PCAndParts: primary stock. Macrotronics: primary stock. 961Souq: secondary. Mojitech + CompuOne: present. PCBuildingLeb: custom-build assembly is their pitch but stocks individual components too. |
| Notes | Two sub-shapes: (a) retailer-assembled custom builds (PCAndParts, PCBuildingLeb) — which we treat as a single SKU even though the components are listed; (b) OEM prebuilts (HP / Dell / Lenovo / ASUS desktop lines) — which behave more like laptops in the Casual flow. The flow surfaces both under one category but ranks/filters may diverge (#33 decision). |
12. Peripheral¶
| Enum value | PERIPHERAL (planned for M3; final enum split — single value with subcategory in specs: Json vs separate KEYBOARD / MOUSE / HEADSET enum values — deferred to #33) |
| Track | Casual |
| Milestone | M3 |
| Primary persona(s) | Casual customer (brand-led — Logitech / Razer — + price; severity-3 acute brand-first decision style) |
| Secondary persona(s) | Karim (performance-tier — mouse polling rate, keyboard switch type, monitor refresh rate; brand-aware — Logitech G, Razer, SteelSeries), Layla (brand + ergonomics + connectivity), First-time builder ("cheap good keyboard?"), Office IT (brand + warranty + standardization) |
| Key spec dimensions (kbd) | Switch type (mechanical brand + linear / tactile / clicky vs membrane), layout, wireless / wired, RGB, hot-swappable |
| Key spec dimensions (mouse) | DPI, polling rate, button count, weight, wireless / wired, ergonomic shape (ambidextrous / right-handed) |
| Key spec dimensions (headset) | Driver size, wireless / wired, mic boom presence + quality, surround support, platform compatibility |
| Canonical product shape | brand + line + model (e.g. "Logitech MX Master 3S", "Razer DeathAdder V3 Pro", "Keychron K8 Pro") — brand-line awareness is the wedge, not SKU comparison |
| Compat-engine relevance | No. Peripherals are stand-alone purchases; no compat constraints. UC-13 single-item flow only. |
| Retailer coverage | All three current retailers + every H-tier next-wave candidate. CompuOne especially deep on peripherals (221 SKUs in that category alone per retailers.md §3). 961Souq carries deep Logitech / Razer / SteelSeries inventory. |
| Notes | "Logitech MX series vs G series" matters more here than any single-SKU comparison (Personas §3.3). #33 decides whether to split the enum or carry subcategory in specs: Json. Gaming chairs and racing-sim accessories are not included here — see §6 Out of scope. |
6. Deliberately out of scope (v1)¶
Categories the project does not ship. Recorded so future tickets re-open via supersession ADR rather than silently expanding scope. Each entry follows the rejection rationale in ADR-0010 Decision §"Out of scope".
Gaming chairs¶
No primary-persona anchor. Casual customer mentions chairs in gift-purchase contexts but does not rank them as a primary category in §6.2. Retailer coverage is thin — PCBuildingLeb's racing-sim section is the strongest stocked surface in the audit, and PCBuildingLeb is L-tier per retailers.md §3. Comparison axis is brand + price + ergonomic claim, none of which rewards aggregation. Revisit signal: Casual-customer telemetry (M3+) shows a gift-purchase sub-flow that consistently lands chair-shaped queries.
Networking gear¶
Routers, switches, NICs, cables-as-product. Office IT secondary persona only; no primary-persona acute pain. Office IT's wedge per §6.1.6 is Quote mode on existing categories, not networking-as-its-own-page. Stocked at CompuOne / Mojitech / Microcity but always as a secondary in their own catalogs — Lebanese retail networking is dominantly B2B-direct, not B2C-aggregator. Revisit signal: Office-IT-shaped sessions consistently search for networking SKUs that the existing categories don't carry (M3+ telemetry).
Accessories / cables / adapters¶
Commodity. No comparison value. Brand and SKU spread is dominated by no-name imports; matcher cost would dwarf user value. The retailers all carry these but as cart-additions, not as a destination category. Revisit signal: never — commodity categories are structurally a poor fit for an aggregator wedge.
Mining-grade hardware¶
Skip per retailers.md §5 Gamma findings. Gamma's mining-grade ESONIC motherboards are the only mining-specific stock observed across the audit, and Gamma is itself Skip-tier. Anti-persona drift signal in personas.md §5.7 — "telemetry shows >5% of build sessions configuring 4+ GPU slots, dual-CPU, or workstation chipsets" — would re-open this; today, no evidence supports the cohort.
Used market¶
Out of scope per ADR-0005 + competitive §4.2. Olx LB is the de-facto used-parts surface; integration is a v3+ deferred. Karim uses Olx for used GPUs but the cohort split (new vs used) is structurally different and would require a separate trust-signal stack. Revisit signal: Olx LB referrer share >10% of inbound traffic (§5.7 drift).
Phones, POS, security cameras, printers¶
Not consumer PC parts. Mentioned in #32 ticket body for scope clarity. Phones in particular were listed as a v3+ candidate in the original 2026-04-25 aggregator design §3.3 phased category roll-out — they involve a different retailer set (telco shops, Apple resellers, Khoury Home), a different journey, a different purchase frequency. Out through v2.
7. Cross-category implications¶
Patterns that span the roster. Drives #28 page design, #33 per-category criteria, and #37 i18n (deferred per ADR-0004).
- Filter UX must support both specs-first and brand-first browse for the same dataset. Specs-first (Karim, First-timer) needs sliders + multi-select on numeric dims — this is the M1 default. Brand-first (Casual, Layla) needs prominent brand-family navigation — this lands with M2 monitors and matures with M3 peripherals + laptops. Same canonical Product, surfaced two ways.
- Compat-engine relevance is binary across the roster. All 8 Builder components are primary (M1). Storage is partial (form-factor + interface only). Monitors, laptops, prebuilts, peripherals are zero — UC-13 deliberately omits compat per ADR-0005.
- Persona acute pains map cleanly onto category placements.
- Karim: cross-store cart math → #15 cart aggregator (M2 feature, not category)
- First-timer: compat anxiety → existing M1 compat panel + #28 rule-provenance design (M2 feature)
- Casual customer: forced-into-builder UX → resolved at flow level by ADR-0005; resolved at catalog level partially by M2 monitors and fully by M3 laptops + prebuilts + peripherals
- Layla: color accuracy → M2 monitors. Creator dimensions on GPU + RAM + storage land via #33 creator-dim surface, not via new categories
- Office IT: batch quoting → #28 §6.1.6 Quote mode (M2 feature). Laptops + prebuilts (M3) deepen their journey but the wedge is the feature, not the category
- Diaspora: foreign-card payment + delivery routing → flow-level affordances per §6.1.5 and a paid retailer service post-M2 (#41)
- Brand-line awareness is M3-shaped. Monitors land at M2 with brand-as-a-filter (LG / Dell / Samsung) but not brand-line-as-a-nav-axis. Peripherals (M3) is the first category where brand-line navigation (Logitech MX vs G vs Lift) is the wedge, not just a filter. Design system implications for #27 and #28.
specs: Jsoncarries the long tail. The Prisma schema's typed columns (cpuSocket,ramType,tdpWatts, etc. — see data-model.md) hold the most-queried specs for fast filtering and compat. Everything else — clock speeds, cache sizes, port counts, panel types, color gamut %, switch types — lives inspecs: Json. M2 monitors and M3 categories should follow this pattern; new typed columns are added only when a spec dimension joins the compat engine or becomes a primary filter.
8. Open questions¶
These are not decision-blockers for ADR-0010 but do need resolution as M2 and M3 ship.
MONITORenum addition is a follow-up issue. Schema change is implied by M2 catalog work; not performed in this ADR. Filefeat(schema): add MONITOR Category enum valuewhen M2 catalog work begins. Also covers seed entries + a small typed-column decision (probably none — monitors fitspecs: Json).- Peripheral subcategory split. #33 decides between (a) single
PERIPHERALenum +subcategory: 'keyboard' | 'mouse' | 'headset'inspecs: Json, or (b) separateKEYBOARD/MOUSE/HEADSETenum values. Trade-off: filter-UX parity (single category groups them on the casual landing) vs spec-dictionary purity (separate enums letspecs: Jsonshape per subcategory). - Prebuilt sub-shape — retailer-assembled vs OEM. #33 decides whether to split the prebuilt category into
PREBUILT_CUSTOM(PCAndParts custom builds) vsPREBUILT_OEM(HP / Dell / Lenovo desktop lines), or carry the distinction inspecs: Json. The two sub-shapes have different filter axes (custom builds rank by component-tier; OEM by brand-line + warranty). - Variant pricing for laptops. A single Lenovo ThinkPad T14 ships at multiple price points (8GB / 16GB / 32GB RAM × 256GB / 512GB / 1TB SSD). Decide at M3: one canonical Product per variant, or one Product with embedded variant pricing in
specs: Json. Affects matcher behaviour and #21 LLM-extraction prompts. - Apple-line depth. Layla's Mac-comparison-mode (M3+) assumes Apple laptops are first-class citizens. Decide whether to extend Apple coverage to iPads, Mac mini, Mac Studio (Casual customer adjacent), or hold the line at MacBooks. Anti-persona drift signal "Apple-only filter share >20%" (§5.7) is the post-launch trigger.
9. See also¶
- ADR-0010 — Category scope for M1, M2, M3 — the why; this doc is the what
- ADR-0005 — Two parallel use-case tracks — the framing this doc inherits
- Personas §6.2 — persona-by-category ranking, the empirical floor for spec-dimension priorities
- Retailers §2-§3 — per-retailer category coverage
- Competitive landscape §3 — competitor category-roster patterns
- Use cases — UC-9 + UC-13 category bullets updated alongside this doc
- Data model —
Categoryenum future-state note updated alongside this doc