> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module 0 · The Six Layers

> Why a P&C starter exists at all: the headline numbers are contested by construction. "What’s our loss ratio?" isn’t one query — it depends on paid vs. incurred losses, written v… (~15 min)

Why a P\&C starter exists at all: **the headline numbers are contested by construction.** "What's our loss ratio?" isn't one query — it depends on paid vs. incurred losses, written vs. earned premium, and accident vs. calendar year, and a naive answer silently mixes them. The starter pins one governed definition for each contested metric, externalizes the NAIC line and peril rollups so they aren't hard-coded, makes fair-pricing and PII behavior the default, and writes down the reasoning so a stakeholder can argue with the *definition*, not the number.

## The six layers

<table>
  <tr><th>Layer</th><th>Where</th><th>What</th></tr>
  <tr><td>**1 — Entity spine**</td><td>`ontology/schema.tql`, `ontology/relations/`</td><td>Policyholder, Policy, Coverage, Premium (earned), Claim, Claim transaction, Producer.</td></tr>
  <tr><td>**2 — Metrics**</td><td>`ontology/queries/`</td><td>Governed surfaces: earned premium, loss ratio, combined ratio, claim frequency, claim severity, reserve position, retention rate, new business, policies in force.</td></tr>
  <tr><td>**3 — Classification**</td><td>`ontology/dimensions/`, `filters/`, `reference/terminology/`</td><td>**The heart.** NAIC line-of-business + peril/cause-of-loss grouping (with cat flag) + geography — as dimensions, filters & committed seeds.</td></tr>
  <tr><td>**4 — Governance & PII**</td><td>`ontology/notes/governance-pii.md`, `config/org_context.md`</td><td>Identifier inventory, \<5 small-cell suppression, fair-pricing/redlining, medical-claim sensitivity, reserve MNPI.</td></tr>
  <tr><td>**5 — Decision records**</td><td>`ontology/notes/`</td><td>Why each metric is defined the way it is — loss-ratio basis, written-vs-earned, case-vs-IBNR reserves, frequency×severity; plus the glossary, grain, and identity guides.</td></tr>
  <tr><td>**6 — Validation**</td><td>`validation/`</td><td>`validate_tql.py` (every surface checked against your live schema + compiled), golden queries with pinned values, the dry-run prompt.</td></tr>
</table>

<Note>
  **Standards alignment** — `STANDARDS.md` maps the model to the industry standards it aligns with (ACORD, NAIC annual statement, FIBO, ISO statistical plans, SAP/GAAP). The semantic layer (metrics, routing, classification) is **fully separated from the physical mapping**: every physical table name lives in **one file**, `ontology/schema.tql` — re-point it and the metric logic stays put. The starter is authored against a generic policy-admin + claims model with ANSI/Spark-portable SQL; `MIGRATION.md` is the 8-step re-point checklist and works the same on Redshift, BigQuery, Snowflake, or **Databricks** (budget: about a half-day with warehouse access). For a deep technical tour, read `DEEP_DIVE.md`.
</Note>

### ✅ Checkpoint

* [ ] You can name the six layers and find each one in the repo
* [ ] You know which classification ships in the box vs. needs your own licensed feed (ISO/PCS)
* [ ] You know the default model (generic policy-admin + claims, ANSI/Spark-portable) and where re-point lives (schema.tql)

<Note>
  **Two rules for a long, live session** — **1 · Checkpoint every couple of modules.** Long threads have a ceiling. After every module or two, ask Ana: *“Save a handoff document summarizing what we've built, what we decided, and what's next — so we can continue in a new thread.”* If a thread ever maxes out, you lose nothing.<br /><br />
  **2 · Pin the scope in every prompt.** Name the **entity** and the **source-of-truth tables** in each prompt (“…for \[entity X], using the \[base] tables, not the summary table”) — otherwise Ana may drift to a convenient summary table or query every source at once.
</Note>