openplanr 3.2.0 → 3.3.0

package/lib/host-packages/claude/openplanr/runtime/plan/scripts/design-protocol-contracts.mjs

@@ -156,6 +156,7 @@ var VALIDATION_KEYWORDS = [
   "maxContains",
   "required",
   "properties",
+  "propertyNames",
   "additionalProperties",
   "maxProperties",
   "dependentRequired",
@@ -224,6 +225,7 @@ var KEYWORD_SHAPES = {
   maxContains: ["a non-negative integer", isCount],
   required: ["an array of unique strings", isUniqueStrings],
   properties: ["an object of schemas", isSchemaMap],
+  propertyNames: ["a schema", isSchema],
   additionalProperties: ["a schema", isSchema],
   maxProperties: ["a non-negative integer", isCount],
   dependentRequired: [
@@ -492,6 +494,8 @@ var validateNode = (value, schema6, path, errs, context) => {
     }
     const props = schema6.properties || {};
     for (const [k, v] of Object.entries(value)) {
+      if (schema6.propertyNames !== void 0)
+        validateNode(k, schema6.propertyNames, `${path}.${k}`, errs, context);
       if (Object.hasOwn(props, k)) evaluated.add(k);
       else if (schema6.additionalProperties !== void 0) evaluated.add(k);
       if (!Object.hasOwn(props, k)) {
@@ -4552,7 +4556,7 @@ var DESIGN_DOCUMENT_V1_SCHEMA = freeze({
     }
   }
 });
-var DESIGN_DOCUMENT_SCHEMA = freeze({
+var DESIGN_DOCUMENT_V120_SCHEMA = freeze({
   ...DESIGN_DOCUMENT_V1_SCHEMA,
   $id: "https://openplanr.dev/schemas/v1.20.0/design-document.schema.json",
   "x-openplanr-contract": { id: "design-document", version: "1.20.0" },
@@ -4611,6 +4615,78 @@ var DESIGN_DOCUMENT_SCHEMA = freeze({
     coordinate: { type: "number", minimum: -1e7, maximum: 1e7 }
   }
 });
+var PROP_TOKEN_SCHEMA = {
+  type: "string",
+  minLength: 1,
+  maxLength: 128,
+  pattern: "^[a-z][a-z0-9-]*(?![\\s\\S])"
+};
+var propTokenPattern = new RegExp(PROP_TOKEN_SCHEMA.pattern, "u");
+var currentDocument = (
+  /** @type {{ properties: Record<string, unknown>; [key: string]: unknown }} */
+  structuredClone(DESIGN_DOCUMENT_V120_SCHEMA)
+);
+currentDocument.$id = "https://openplanr.dev/schemas/v1.22.0/design-document.schema.json";
+currentDocument["x-openplanr-contract"] = { id: "design-document", version: "1.22.0" };
+currentDocument.properties.schemaVersion = { enum: ["1.0.0", "1.1.0"] };
+var screenSchema = (
+  /** @type {{ items: { properties: Record<string, unknown> } }} */
+  currentDocument.properties.screens
+);
+screenSchema.items.properties.props = {
+  type: "object",
+  propertyNames: PROP_TOKEN_SCHEMA,
+  additionalProperties: {
+    oneOf: [
+      {
+        type: "object",
+        additionalProperties: false,
+        required: ["type", "options", "default"],
+        properties: {
+          type: { const: "enum" },
+          options: {
+            type: "array",
+            minItems: 1,
+            uniqueItems: true,
+            items: PROP_TOKEN_SCHEMA
+          },
+          default: PROP_TOKEN_SCHEMA
+        }
+      },
+      {
+        type: "object",
+        additionalProperties: false,
+        required: ["type", "default"],
+        properties: { type: { const: "boolean" }, default: { type: "boolean" } }
+      }
+    ]
+  }
+};
+var variantSchema = (
+  /** @type {{ items: { properties: Record<string, unknown> } }} */
+  currentDocument.properties.variants
+);
+variantSchema.items.properties.props = {
+  type: "object",
+  propertyNames: { $ref: "#/$defs/id" },
+  additionalProperties: {
+    type: "object",
+    propertyNames: PROP_TOKEN_SCHEMA,
+    additionalProperties: { anyOf: [PROP_TOKEN_SCHEMA, { type: "boolean" }] }
+  }
+};
+currentDocument.allOf = [
+  {
+    if: { properties: { schemaVersion: { const: "1.1.0" } }, required: ["schemaVersion"] },
+    else: {
+      properties: {
+        screens: { items: { not: { required: ["props"] } } },
+        variants: { items: { not: { required: ["props"] } } }
+      }
+    }
+  }
+];
+var DESIGN_DOCUMENT_SCHEMA = freeze(currentDocument);
 
 // packages/protocol/src/workspace-contracts.mjs
 var DESIGN_WORKSPACE_VERSION = "1.0.0";
@@ -5385,6 +5461,7 @@ export {
   canonicalizeJson,
   assertPlainData,
   validateJson,
+  DESIGN_DOCUMENT_V120_SCHEMA,
   DESIGN_DOCUMENT_SCHEMA,
   DESIGN_REVIEW_BUNDLE_SCHEMA,
   LARGE_OBJECT_LIMITS

package/lib/host-packages/claude/openplanr/runtime/plan/scripts/design.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import {
   DESIGN_DOCUMENT_SCHEMA,
+  DESIGN_DOCUMENT_V120_SCHEMA,
   DESIGN_REVIEW_BUNDLE_SCHEMA,
   LARGE_OBJECT_LIMITS,
   assertPlainData,
@@ -382,13 +383,40 @@ var currentDesign = (
 );
 for (const key of ["frames", "layout"])
   currentDesign.properties[key] = /** @type {Record<string, unknown>} */
-  DESIGN_DOCUMENT_SCHEMA.properties[key];
-bundleCurrent.$defs = structuredClone(DESIGN_DOCUMENT_SCHEMA.$defs);
+  DESIGN_DOCUMENT_V120_SCHEMA.properties[key];
+bundleCurrent.$defs = structuredClone(DESIGN_DOCUMENT_V120_SCHEMA.$defs);
 var currentEntries = (
   /** @type {{ items: { properties: Record<string, unknown> } }} */
   bundleCurrent.properties.entries
 );
 currentEntries.items.properties.height = { const: "auto" };
+var bundleProps = (
+  /** @type {MutableSchema} */
+  structuredClone(bundleCurrent)
+);
+bundleProps.$id = "https://openplanr.dev/schemas/v1.22.0/design-review-bundle.schema.json";
+bundleProps["x-openplanr-contract"] = { id: "design-review-bundle", version: "1.22.0" };
+var propsDesign = (
+  /** @type {MutableSchema} */
+  bundleProps.properties.design
+);
+var authoredProperties = (
+  /** @type {Record<string, unknown>} */
+  DESIGN_DOCUMENT_SCHEMA.properties
+);
+propsDesign.properties.schemaVersion = authoredProperties.schemaVersion;
+for (const key of ["screens", "variants"]) {
+  const projected = (
+    /** @type {{ items: { properties: Record<string, unknown> } }} */
+    propsDesign.properties[key]
+  );
+  const authored = (
+    /** @type {{ items: { properties: Record<string, unknown> } }} */
+    authoredProperties[key]
+  );
+  projected.items.properties.props = authored.items.properties.props;
+}
+propsDesign.allOf = structuredClone(DESIGN_DOCUMENT_SCHEMA.allOf);
 var item = closed(
   {
     pinId: id,

package/lib/host-packages/claude/openplanr/runtime/plan/scripts/runtime/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openplanr/protocol",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "type": "module",
   "description": "Canonical OpenPlanr schemas, registries, typed errors, and portable contract validation",
   "license": "MIT",
@@ -153,7 +153,7 @@
   "devDependencies": {
     "esbuild": "0.28.2",
     "miniflare": "4.20260730.0",
-    "playwright": "1.64.0",
+    "playwright": "1.64.1",
     "typescript": "6.0.2"
   }
 }

package/lib/host-packages/claude/openplanr/skills/design/references/design-system.md

@@ -54,8 +54,23 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshotting needs network access while authoring. When it is unavailable, or a
-license is unclear, use the role's system stack and name that fallback in the return:
+Snapshot with the bundled helper, run from the skill directory (see
+[utilities.md](utilities.md)):
+
+```sh
+node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+```
+
+It is the one command to ask approval for. A host that allowlists network access by
+domain needs `raw.githubusercontent.com`, `fonts.googleapis.com` and
+`fonts.gstatic.com`. It enforces the rules above, verifies each
+license from the Google Fonts catalog, writes `fonts.css`, and prints the files and
+total bytes. Start the design stylesheet with `@import "assets/fonts/fonts.css";`
+(relative to that stylesheet), then use the families by name. Nothing is fetched when
+a design opens.
+
+When the host denies network access, the command fails, or it refuses a license, use
+the role's system stack and name that fallback in the return:
 
 | Role | System stack |
 | --- | --- |

package/lib/host-packages/claude/openplanr/skills/design/references/generation.md

@@ -10,7 +10,8 @@ Use a versioned `design-document.json` and the bundled schema exposed by the
 local HTML/CSS/JavaScript, assets, screen order, responsive frames, interaction
 flows, selected direction, brief provenance and design-system references. Inspect
 the schema before creating the document; validate it before rendering. Use
-`schemaVersion: "1.0.0"` when authoring, revising, migrating or arranging documents.
+`schemaVersion: "1.1.0"` for documents with screen or variant props. Documents without
+props may keep `schemaVersion: "1.0.0"`.
 
 Read [team-review.md](team-review.md) and author a sibling `review-context.json`
 for every new design. Its welcome purpose and review questions belong to this
@@ -19,7 +20,9 @@ design, updating only what changed. Render it with the same revision as the
 screens so the shared welcome and implementation guidance describe that revision.
 
 Place source in a sibling `source/` directory. Shared CSS and components belong in
-shared source; variants write disjoint directories. Preserve IDs during evolution.
+shared source. Distinct design directions may use disjoint directories; theme,
+partial and state instances share a screen source through typed props. Preserve
+IDs during evolution.
 All document source paths are local and relative to its directory; import the
 required asset snapshots rather than referring outside it or to remote resources.
 Fonts are asset snapshots too; follow [design-system.md](design-system.md).
@@ -57,6 +60,61 @@ observable. If the requested deliverable is an architecture or decision diagram
 rather than a product interface, route that content to the diagram workflow instead
 of styling documentation as a product screen.
 
+## Typed screen props
+
+Declare reusable screen state in `screens[].props`. An enum declaration requires
+`type: "enum"`, nonempty unique string `options`, and a `default` from those options.
+A boolean declaration requires `type: "boolean"` and a boolean `default`. Prop names,
+enum options and enum defaults must be lowercase tokens matching
+`^[a-z][a-z0-9-]*$`, with at most 128 characters. Use `is-dark` and `dark-mode`,
+for example; uppercase letters, spaces and underscores are invalid. Use props for
+theme, partial content and state variants instead of copying HTML sources.
+
+Set instance values in `variants[].props`, keyed first by screen ID and then prop
+name. Omitted values use the screen defaults. For example:
+
+```json
+{
+  "schemaVersion": "1.1.0",
+  "screens": [
+    {
+      "id": "overview",
+      "title": "Overview",
+      "source": { "html": "source/overview.html" },
+      "props": {
+        "theme": { "type": "enum", "options": ["light", "dark"], "default": "light" },
+        "partial": { "type": "boolean", "default": false }
+      }
+    }
+  ],
+  "variants": [
+    { "id": "light", "label": "Light", "status": "ready" },
+    {
+      "id": "dark",
+      "label": "Dark",
+      "status": "ready",
+      "props": { "overview": { "theme": "dark", "partial": true } }
+    }
+  ]
+}
+```
+
+Each source with props needs exactly one explicit `<body>` screen root. The
+renderer writes effective values onto that body as `data-prop-theme="dark"`,
+`data-prop-partial="true"`, `prop-theme-dark` and `prop-partial-true`; false booleans
+also receive an attribute and class. Names and values are written unchanged,
+without case conversion or encoding. A prop named `is-dark` becomes
+`data-prop-is-dark="true"` and `prop-is-dark-true`; scripts read it as
+`document.body.dataset.propIsDark`. Branch CSS and local scripts on these values.
+A `variants[].sources[screenId]` override still selects the source; props
+apply to that selected source, otherwise to `screens[].source`. Board keys,
+screen order, responsive frames and existing source overrides retain their roles.
+
+Lint warns about copied screens only when their source files are byte-identical
+after removing body `data-theme="light"` or `data-theme="dark"` attributes and
+`theme-light` or `theme-dark` body classes. Other markup, styles, scripts and assets
+must match. Use a shared source with a theme prop for those instances.
+
 ## Views
 
 | View | Purpose | Required behavior |

package/lib/host-packages/claude/openplanr/skills/design/references/utilities.md

@@ -2,7 +2,8 @@
 
 Run the linked design helper from the skill entrypoint relative to the skill's
 directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
+downloads anything, and only when run; nothing is fetched when a design opens.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 
@@ -15,8 +16,17 @@ node scripts/design.mjs feedback <design-document.json> --action inspect --json
 node scripts/design.mjs view-context <design-document.json> --json
 node scripts/design.mjs studio <design-document.json> --action status --json
 node scripts/design.mjs studio <design-document.json> --action stop --json
+node scripts/design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
 ```
 
+`fonts fetch` snapshots at most two OFL or Apache families, three weights each, as
+Latin `woff2` files with their license files and a local `fonts.css`. It needs network
+access; ask the user to approve that one command. A host that allowlists domains needs
+`raw.githubusercontent.com` (license check), `fonts.googleapis.com` (font CSS) and
+`fonts.gstatic.com` (font files). It refuses an existing non-empty
+`--dest` and leaves nothing behind when any request fails. See
+[design-system.md](design-system.md) for the fallback.
+
 Use `--view prototype` or `--view walkthrough` to select the initial presentation.
 When an `openplanr` CLI is available, prefer its public `openplanr artifact` route for
 opening the document; otherwise use this bundled script. Both compose the same

package/lib/host-packages/claude/openplanr/skills/design/schemas/design-document.schema.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://openplanr.dev/schemas/v1.20.0/design-document.schema.json",
+  "$id": "https://openplanr.dev/schemas/v1.22.0/design-document.schema.json",
   "x-openplanr-contract": {
     "id": "design-document",
-    "version": "1.20.0"
+    "version": "1.22.0"
   },
   "title": "OpenPlanr authored design document",
   "type": "object",
@@ -26,7 +26,10 @@
       "const": "openplanr-design-document"
     },
     "schemaVersion": {
-      "const": "1.0.0"
+      "enum": [
+        "1.0.0",
+        "1.1.0"
+      ]
     },
     "id": {
       "$ref": "#/$defs/id"
@@ -158,6 +161,66 @@
           },
           "anchors": {
             "$ref": "#/$defs/ids"
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 128,
+              "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+            },
+            "additionalProperties": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "options",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "enum"
+                    },
+                    "options": {
+                      "type": "array",
+                      "minItems": 1,
+                      "uniqueItems": true,
+                      "items": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                      }
+                    },
+                    "default": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 128,
+                      "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                    }
+                  }
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "type",
+                    "default"
+                  ],
+                  "properties": {
+                    "type": {
+                      "const": "boolean"
+                    },
+                    "default": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              ]
+            }
           }
         }
       }
@@ -232,6 +295,34 @@
             "additionalProperties": {
               "$ref": "#/$defs/source"
             }
+          },
+          "props": {
+            "type": "object",
+            "propertyNames": {
+              "$ref": "#/$defs/id"
+            },
+            "additionalProperties": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128,
+                    "pattern": "^[a-z][a-z0-9-]*(?![\\s\\S])"
+                  },
+                  {
+                    "type": "boolean"
+                  }
+                ]
+              }
+            }
           }
         },
         "if": {
@@ -375,5 +466,41 @@
       "minimum": -10000000,
       "maximum": 10000000
     }
-  }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "schemaVersion": {
+            "const": "1.1.0"
+          }
+        },
+        "required": [
+          "schemaVersion"
+        ]
+      },
+      "else": {
+        "properties": {
+          "screens": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          },
+          "variants": {
+            "items": {
+              "not": {
+                "required": [
+                  "props"
+                ]
+              }
+            }
+          }
+        }
+      }
+    }
+  ]
 }

package/lib/host-packages/claude/openplanr/skills/design-loop/references/design-system.md

@@ -54,8 +54,23 @@ while authoring:
 - at most two families and three weights each; one variable file can cover a
   family's weights.
 
-Snapshotting needs network access while authoring. When it is unavailable, or a
-license is unclear, use the role's system stack and name that fallback in the return:
+Snapshot with the bundled helper, run from the skill directory (see
+[utilities.md](utilities.md)):
+
+```sh
+node scripts/design.mjs fonts fetch --family "Inter:400,600" --family "Source Serif 4:400" --dest <design>/source/assets/fonts
+```
+
+It is the one command to ask approval for. A host that allowlists network access by
+domain needs `raw.githubusercontent.com`, `fonts.googleapis.com` and
+`fonts.gstatic.com`. It enforces the rules above, verifies each
+license from the Google Fonts catalog, writes `fonts.css`, and prints the files and
+total bytes. Start the design stylesheet with `@import "assets/fonts/fonts.css";`
+(relative to that stylesheet), then use the families by name. Nothing is fetched when
+a design opens.
+
+When the host denies network access, the command fails, or it refuses a license, use
+the role's system stack and name that fallback in the return:
 
 | Role | System stack |
 | --- | --- |

package/lib/host-packages/claude/openplanr/skills/design-loop/references/generation.md

@@ -10,7 +10,8 @@ Use a versioned `design-document.json` and the bundled schema exposed by the
 local HTML/CSS/JavaScript, assets, screen order, responsive frames, interaction
 flows, selected direction, brief provenance and design-system references. Inspect
 the schema before creating the document; validate it before rendering. Use
-`schemaVersion: "1.0.0"` when authoring, revising, migrating or arranging documents.
+`schemaVersion: "1.1.0"` for documents with screen or variant props. Documents without
+props may keep `schemaVersion: "1.0.0"`.
 
 Read [team-review.md](team-review.md) and author a sibling `review-context.json`
 for every new design. Its welcome purpose and review questions belong to this
@@ -19,7 +20,9 @@ design, updating only what changed. Render it with the same revision as the
 screens so the shared welcome and implementation guidance describe that revision.
 
 Place source in a sibling `source/` directory. Shared CSS and components belong in
-shared source; variants write disjoint directories. Preserve IDs during evolution.
+shared source. Distinct design directions may use disjoint directories; theme,
+partial and state instances share a screen source through typed props. Preserve
+IDs during evolution.
 All document source paths are local and relative to its directory; import the
 required asset snapshots rather than referring outside it or to remote resources.
 Fonts are asset snapshots too; follow [design-system.md](design-system.md).
@@ -57,6 +60,61 @@ observable. If the requested deliverable is an architecture or decision diagram
 rather than a product interface, route that content to the diagram workflow instead
 of styling documentation as a product screen.
 
+## Typed screen props
+
+Declare reusable screen state in `screens[].props`. An enum declaration requires
+`type: "enum"`, nonempty unique string `options`, and a `default` from those options.
+A boolean declaration requires `type: "boolean"` and a boolean `default`. Prop names,
+enum options and enum defaults must be lowercase tokens matching
+`^[a-z][a-z0-9-]*$`, with at most 128 characters. Use `is-dark` and `dark-mode`,
+for example; uppercase letters, spaces and underscores are invalid. Use props for
+theme, partial content and state variants instead of copying HTML sources.
+
+Set instance values in `variants[].props`, keyed first by screen ID and then prop
+name. Omitted values use the screen defaults. For example:
+
+```json
+{
+  "schemaVersion": "1.1.0",
+  "screens": [
+    {
+      "id": "overview",
+      "title": "Overview",
+      "source": { "html": "source/overview.html" },
+      "props": {
+        "theme": { "type": "enum", "options": ["light", "dark"], "default": "light" },
+        "partial": { "type": "boolean", "default": false }
+      }
+    }
+  ],
+  "variants": [
+    { "id": "light", "label": "Light", "status": "ready" },
+    {
+      "id": "dark",
+      "label": "Dark",
+      "status": "ready",
+      "props": { "overview": { "theme": "dark", "partial": true } }
+    }
+  ]
+}
+```
+
+Each source with props needs exactly one explicit `<body>` screen root. The
+renderer writes effective values onto that body as `data-prop-theme="dark"`,
+`data-prop-partial="true"`, `prop-theme-dark` and `prop-partial-true`; false booleans
+also receive an attribute and class. Names and values are written unchanged,
+without case conversion or encoding. A prop named `is-dark` becomes
+`data-prop-is-dark="true"` and `prop-is-dark-true`; scripts read it as
+`document.body.dataset.propIsDark`. Branch CSS and local scripts on these values.
+A `variants[].sources[screenId]` override still selects the source; props
+apply to that selected source, otherwise to `screens[].source`. Board keys,
+screen order, responsive frames and existing source overrides retain their roles.
+
+Lint warns about copied screens only when their source files are byte-identical
+after removing body `data-theme="light"` or `data-theme="dark"` attributes and
+`theme-light` or `theme-dark` body classes. Other markup, styles, scripts and assets
+must match. Use a shared source with a theme prop for those instances.
+
 ## Views
 
 | View | Purpose | Required behavior |

package/lib/host-packages/claude/openplanr/skills/design-loop/references/utilities.md

@@ -2,7 +2,8 @@
 
 Run the linked design helper from the skill entrypoint relative to the skill's
 directory. It contains deterministic operations and all required assets. It needs
-Node.js 22.13 or later, with no global CLI, provider credentials or runtime downloads.
+Node.js 22.13 or later, with no global CLI or provider credentials. Only `fonts fetch`
+downloads anything, and only when run; nothing is fetched when a design opens.
 Use `--help` to inspect the installed command interface before writing documents
 or invoking operations; the installed contract is authoritative.
 
@@ -15,8 +16,17 @@ node scripts/design.mjs feedback <design-document.json> --action inspect --json
 node scripts/design.mjs view-context <design-document.json> --json
 node scripts/design.mjs studio <design-document.json> --action status --json
 node scripts/design.mjs studio <design-document.json> --action stop --json
+node scripts/design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <design>/source/assets/fonts --json
 ```
 
+`fonts fetch` snapshots at most two OFL or Apache families, three weights each, as
+Latin `woff2` files with their license files and a local `fonts.css`. It needs network
+access; ask the user to approve that one command. A host that allowlists domains needs
+`raw.githubusercontent.com` (license check), `fonts.googleapis.com` (font CSS) and
+`fonts.gstatic.com` (font files). It refuses an existing non-empty
+`--dest` and leaves nothing behind when any request fails. See
+[design-system.md](design-system.md) for the fallback.
+
 Use `--view prototype` or `--view walkthrough` to select the initial presentation.
 When an `openplanr` CLI is available, prefer its public `openplanr artifact` route for
 opening the document; otherwise use this bundled script. Both compose the same