Clarify docs about source of truth

Author: camdecoster

src/types/ARCHITECTURE.md

@@ -36,8 +36,11 @@ re-exports.
 
 The split:
 
-- **Generated types** are the single source of truth for everything in
-  Plotly's attribute schema.
+- **Generated types** are the authoritative TypeScript representation of
+  the runtime schema. The schema itself is produced from Plotly's JS
+  attribute files (`src/.../attributes.js`), which remain the source of
+  truth: chain is **attribute files → `plot-schema.json` → generated
+  types**.
   - **`src/types/generated/schema.d.ts`** contains:
     - **Common enum aliases** discovered from the schema (Calendar, Dash,
       AxisType, PatternShape, XRef, YRef, TransitionEasing, PlotType).

src/types/CONVERTING_ATTRIBUTES.md

@@ -1,17 +1,22 @@
 # Converting Attribute Files to TypeScript
 
 This is the **active workflow** for migrating Plotly's `attributes.js` files
-to TypeScript. Each conversion turns one attribute file into the single
-source of truth for both the runtime schema and the public TypeScript type.
+to TypeScript. Attribute files are the source of truth for the runtime
+schema; the schema in turn drives the generated public TypeScript types.
+Conversion doesn't change that chain — it adds compile-time validation on
+top of it.
 
 ## Why
 
-Today, attribute metadata lives in `src/.../attributes.js` files and the
-matching TypeScript types live separately in `src/types/`. They drift.
+Without `as const satisfies AttributeMap`, malformed attribute objects
+(missing `valType`, typo'd `values` arrays, wrong `dflt` shape, etc.) only
+fail when the runtime tries to use them. Converted attribute files catch
+those structural mistakes at TypeScript-compile time, before they ever
+reach the schema.
 
-After conversion, the `attributes.ts` file is validated against `AttributeMap`
-at compile time, catching structural errors and typos before they reach the
-runtime schema.
+Conversion is also a small step toward typing the rest of the file (and
+eventually the rest of the source tree) in TypeScript, but the immediate
+value is the compile-time structural check.
 
 ## Recipe
 

src/types/SETUP.md

@@ -32,7 +32,7 @@ npm run typecheck         # tsc --noEmit, errors reported, no output
 npm run typecheck-watch   # incremental rechecking on change
 
 npm run schema            # rebuild test/plot-schema.json + regenerate types
-npm run schema-typegen-diff-check      # regenerate + verify no uncommitted drift in schema.d.ts
+npm run schema-typegen-diff-check      # regenerate + verify no uncommitted drift in test/plot-schema.json or schema.d.ts
 npm run bundle            # esbuild → dist/plotly.js
 npm run build             # full production build
 ```