@taprootio/site-authoring 0.1.1 → 0.3.0

package/README.md

@@ -39,8 +39,8 @@ resolve a different contract than the CLI was tested against.
 `taproot-site --help` lists every verb and the configuration contract.
 `taproot-site help` is the offline reference family agents read before
 authoring: page types, components, navigation, media, previews, themes,
-appearance, and the footer, each with `--json` for stable machine-readable
-output.
+appearance, the footer, and the offline fixture contract, each with `--json`
+for stable machine-readable output.
 
 ```bash
 taproot-site help
@@ -58,6 +58,23 @@ appearance, header, brand, and footer, and fixture-local image identities. It
 does not prove authorization, site ownership, concurrency, server round trips,
 or rendering; a real pull and an authorized preview do that.
 
+The package ships one, so `validate` is runnable the moment the install
+finishes. `taproot-site help fixture` states the manifest contract and prints
+the shipped fixture's absolute path along with the exact command to validate
+it:
+
+```bash
+taproot-site help fixture
+taproot-site validate "$(npm root --global)/@taprootio/site-authoring/examples/riverbend-wellness"
+```
+
+The fixture is a fictional wellness studio — `example.test` hostnames, a
+reserved `555-01xx` telephone number, an invented street and town — with two
+free-form pages, a three-item navigation tree, and all four settings
+documents. Nothing in it describes a real business. Copy the directory
+somewhere writable before you edit it; `validate` never writes to the fixture
+it reads.
+
 ## Authorize
 
 Sign in once. `login` starts a device-style authorization: it prints an
@@ -208,11 +225,15 @@ whose approval code and URL exist only as progress). Stdout carries exactly
 one JSON object per run, schema version `1`: `ok`, the CLI name and version,
 the verb, and the verb's own result on success; a stable `error.code` with an
 optional `field`, `status`, and classified `refusal` on failure. Exit codes are
-`0` success, `1` failure, and `2` usage fault. The four refusal classes an
+`0` success, `1` failure, and `2` usage fault. The five refusal classes an
 automation should branch on are `platform_paused` (external authoring is
 paused; retry later), `credential_rejected` (stop and re-issue),
-`plan_limit` (the plan's published-page allowance, surfaced at deploy), and
-`throttled` (back off).
+`capability_missing` (the credential is valid and correctly scoped but was
+not exchanged for a capability the request needs; the refusal carries
+`field: "GrantedCapabilities"`, and the CLI's human progress names the
+granted and required capabilities, so report the verb's declared set rather
+than re-issuing the key), `plan_limit` (the plan's published-page allowance,
+surfaced at deploy), and `throttled` (back off).
 
 When `GITHUB_OUTPUT` names the runner's existing output file, every
 operational verb appends the same JSON under `taproot_site_result` through a

package/examples/riverbend-wellness/manifest.fixture.json

@@ -0,0 +1,74 @@
+{
+  "manifestVersion": 5,
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "pulledAt": "2026-09-04T00:00:00.000Z",
+  "pages": [
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000010",
+      "resourceId": "a0000000-0000-4000-8000-000000000011",
+      "path": "",
+      "title": "Riverbend Wellness",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_FREE_FORM",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example home page for the offline authoring fixture.",
+      "file": "pages/index.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    },
+    {
+      "pageId": "a0000000-0000-4000-8000-000000000012",
+      "resourceId": "a0000000-0000-4000-8000-000000000013",
+      "path": "visit",
+      "title": "Visit the studio",
+      "status": "PAGE_STATUS_DRAFT",
+      "templateType": "TEMPLATE_TYPE_FREE_FORM",
+      "hasDraft": true,
+      "isGenerated": false,
+      "description": "An example second page for the offline authoring fixture.",
+      "file": "pages/visit.md",
+      "sourceFormat": "markdown",
+      "workspaceMode": "editable"
+    }
+  ],
+  "pagesTruncated": false,
+  "navigation": {
+    "file": "nav.json",
+    "items": 3
+  },
+  "settings": [
+    {
+      "settingsType": "SETTING_TYPE_TAPROOT_STYLES",
+      "file": "settings/taproot-styles.json",
+      "entityId": "a0000000-0000-4000-8000-000000000020"
+    },
+    {
+      "settingsType": "SETTING_TYPE_BRAND",
+      "file": "settings/brand.json",
+      "entityId": "a0000000-0000-4000-8000-000000000021"
+    },
+    {
+      "settingsType": "SETTING_TYPE_SITE_HEADER",
+      "file": "settings/site-header.json",
+      "entityId": "a0000000-0000-4000-8000-000000000022"
+    },
+    {
+      "settingsType": "SETTING_TYPE_SITE_PUBLISHING_PREFERENCES",
+      "file": "settings/site-publishing-preferences.json",
+      "entityId": "a0000000-0000-4000-8000-000000000023"
+    }
+  ],
+  "settingsSkipped": [],
+  "fixture": {
+    "contractVersion": 1,
+    "imageIds": [
+      "a0000000-0000-4000-8000-0000000000a0",
+      "a0000000-0000-4000-8000-0000000000a1",
+      "a0000000-0000-4000-8000-0000000000a2"
+    ],
+    "deliveryOrigins": [
+      "https://static.example.test"
+    ]
+  }
+}

package/examples/riverbend-wellness/nav.json

@@ -0,0 +1,26 @@
+{
+  "siteId": "a0000000-0000-4000-8000-000000000001",
+  "navItems": [
+    {
+      "id": "a0000000-0000-4000-8000-000000000030",
+      "kind": "NAV_ITEM_KIND_PAGE",
+      "title": "Home",
+      "resourceId": "a0000000-0000-4000-8000-000000000011",
+      "children": []
+    },
+    {
+      "id": "a0000000-0000-4000-8000-000000000031",
+      "kind": "NAV_ITEM_KIND_PAGE",
+      "title": "Visit",
+      "resourceId": "a0000000-0000-4000-8000-000000000013",
+      "children": []
+    },
+    {
+      "id": "a0000000-0000-4000-8000-000000000032",
+      "kind": "NAV_ITEM_KIND_EXTERNAL_URL",
+      "title": "Book a class",
+      "externalUrl": "https://schedule.example.test/riverbend",
+      "children": []
+    }
+  ]
+}

package/examples/riverbend-wellness/pages/index.md

@@ -0,0 +1,93 @@
+---
+title: Riverbend Wellness
+path: ""
+description: An example home page for the offline authoring fixture.
+---
+
+```component:hero-section
+{
+  "overline": "Riverbend Wellness · Elm Harbor",
+  "title": "An example site you can validate before you have one.",
+  "titleSize": "display",
+  "lead": "Riverbend Wellness is invented. It exists so taproot-site validate has a complete workspace to check on a machine that has never pulled a real site.",
+  "primaryAction": {
+    "label": "Visit the studio",
+    "url": "/visit"
+  },
+  "secondaryAction": {
+    "label": "Book a class",
+    "url": "https://schedule.example.test/riverbend"
+  },
+  "alignment": "start",
+  "media": {
+    "imageId": "a0000000-0000-4000-8000-0000000000a2",
+    "src": "https://static.example.test/site/img/riverbend-studio-1280.webp",
+    "urls": [
+      {
+        "minWidth": 640,
+        "url": "https://static.example.test/site/img/riverbend-studio-640.webp"
+      },
+      {
+        "minWidth": 1280,
+        "url": "https://static.example.test/site/img/riverbend-studio-1280.webp"
+      }
+    ],
+    "width": 1600,
+    "height": 1067,
+    "alt": "An example photograph placeholder for the fixture studio"
+  },
+  "mediaArrangement": "split",
+  "mediaPosition": "after",
+  "mediaWidth": "equal"
+}
+```
+
+:::section {"context":"subtle","contentPadding":"standard","surface":"none"}
+## What this fixture is for
+
+Every value here is fictional. The studio, the street, the telephone number,
+and the image delivery host are all invented, and the image identities are
+declared in `manifest.fixture.json` under the `fixture` block so `validate`
+can bind them without a network.
+
+Run `taproot-site help fixture` for the manifest contract this directory
+follows, and `taproot-site help page free-form` for the document vocabulary
+these pages are written in.
+
+```inline-facts
+[
+  {
+    "value": "2 pages",
+    "label": "Free-form sources"
+  },
+  {
+    "value": "(555) 555-0147",
+    "label": "Reserved example number",
+    "url": "tel:+15555550147"
+  },
+  {
+    "value": "12 Alder Street, Elm Harbor",
+    "label": "Invented address"
+  }
+]
+```
+:::
+
+:::section {"context":"inverted","contentPadding":"standard","surface":"none"}
+## Change one thing and watch it fail
+
+The fastest way to learn the contract is to break it. Point a navigation item
+at a resource identity this fixture does not declare, or set
+`defaultScheme` to a value outside `system`, `light`, and `dark`, and
+`validate` names the file and the field it refused.
+
+```component:cta
+{
+  "heading": "Then put it back.",
+  "description": "Copy this directory somewhere writable before you edit it; validate never writes to the fixture it reads.",
+  "buttonText": "Visit the studio",
+  "buttonUrl": "/visit",
+  "variant": "primary"
+}
+```
+:::

package/examples/riverbend-wellness/pages/visit.md

@@ -0,0 +1,33 @@
+---
+title: Visit the studio
+path: visit
+description: An example second page for the offline authoring fixture.
+---
+
+:::section {"contentPadding":"standard","surface":"none"}
+## Visit the studio
+
+Riverbend Wellness is a fictional studio in the fictional town of Elm Harbor.
+Nothing on this page describes a real place, and no address, telephone number,
+or hostname here resolves to one.
+
+- **12 Alder Street, Elm Harbor** — an invented address
+- **(555) 555-0147** — from the reserved example telephone range
+- **hello@example.test** — a reserved example domain
+
+This page exists so the fixture binds more than one page identity: the
+navigation tree points at both, the footer links to both, and `validate`
+proves every reference resolves inside the fixture.
+:::
+
+:::section {"context":"raised","contentPadding":"standard","surface":"elevated"}
+## Hours
+
+| Day | Doors | Last class |
+| --- | --- | --- |
+| Monday to Friday | 6:00 AM | 7:30 PM |
+| Saturday | 7:30 AM | 4:00 PM |
+| Sunday | 8:00 AM | 2:00 PM |
+
+Every figure above is invented for the fixture.
+:::

package/examples/riverbend-wellness/settings/brand.json

@@ -0,0 +1,7 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000021",
+  "settingsType": "SETTING_TYPE_BRAND",
+  "settings": {
+    "faviconId": "a0000000-0000-4000-8000-0000000000a0"
+  }
+}

package/examples/riverbend-wellness/settings/site-header.json

@@ -0,0 +1,21 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000022",
+  "settingsType": "SETTING_TYPE_SITE_HEADER",
+  "settings": {
+    "headerLayout": "standard",
+    "headerWidth": "contained",
+    "navDrawerStyle": "full-screen",
+    "navDrawerTransition": "fade",
+    "brandText": "Riverbend Wellness",
+    "logoAlt": "Riverbend Wellness",
+    "navMenuDisplay": "auto",
+    "headerPosition": "sticky",
+    "showThemeToggle": true,
+    "showBrandText": true,
+    "brandLogoSize": "standard",
+    "brandHoverGrow": false,
+    "brandColor": "--esp-color-headings",
+    "lightBrandColor": "--esp-color-headings",
+    "darkBrandColor": "--esp-color-headings"
+  }
+}

package/examples/riverbend-wellness/settings/site-publishing-preferences.json

@@ -0,0 +1,107 @@
+{
+  "entityId": "a0000000-0000-4000-8000-000000000023",
+  "settingsType": "SETTING_TYPE_SITE_PUBLISHING_PREFERENCES",
+  "settings": {
+    "footerSettings": {
+      "enabled": true,
+      "showBrand": true,
+      "showBrandText": true,
+      "asideCta": {
+        "id": "a0000000-0000-4000-8000-000000000040",
+        "label": "Book a class",
+        "externalUrl": "https://schedule.example.test/riverbend"
+      },
+      "bottomLinks": [
+        {
+          "id": "a0000000-0000-4000-8000-000000000041",
+          "label": "Visit",
+          "pageResourceId": "a0000000-0000-4000-8000-000000000013"
+        }
+      ],
+      "light": {
+        "backgroundColor": "--esp-color-layer-1",
+        "textColor": "--esp-color-text",
+        "headingColor": "--esp-color-headings",
+        "linkColor": "--esp-color-link",
+        "linkHoverColor": "--esp-color-link-hover",
+        "backgroundImageId": "",
+        "backgroundImageOpacity": 0,
+        "backgroundPresentation": "FOOTER_BACKGROUND_PRESENTATION_COVER",
+        "backgroundFade": "FOOTER_FADE_MODE_NONE",
+        "backgroundRepeatHeightPx": 160,
+        "additionalTopPaddingRem": 1
+      },
+      "dark": {
+        "backgroundColor": "--esp-color-layer-1",
+        "textColor": "--esp-color-text",
+        "headingColor": "--esp-color-headings",
+        "linkColor": "--esp-color-link",
+        "linkHoverColor": "--esp-color-link-hover",
+        "backgroundImageId": "",
+        "backgroundImageOpacity": 0,
+        "backgroundPresentation": "FOOTER_BACKGROUND_PRESENTATION_COVER",
+        "backgroundFade": "FOOTER_FADE_MODE_NONE",
+        "backgroundRepeatHeightPx": 160,
+        "additionalTopPaddingRem": 1
+      },
+      "linkColumns": [
+        {
+          "id": "a0000000-0000-4000-8000-000000000042",
+          "groups": [
+            {
+              "id": "a0000000-0000-4000-8000-000000000043",
+              "heading": "Studio",
+              "links": [
+                {
+                  "id": "a0000000-0000-4000-8000-000000000044",
+                  "label": "Home",
+                  "pageResourceId": "a0000000-0000-4000-8000-000000000011"
+                },
+                {
+                  "id": "a0000000-0000-4000-8000-000000000045",
+                  "label": "Visit",
+                  "pageResourceId": "a0000000-0000-4000-8000-000000000013"
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "asideHeadingContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "Everything here is invented.",
+                "bold": true
+              }
+            ]
+          }
+        ]
+      },
+      "asideBodyContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "Riverbend Wellness is a fictional studio used to demonstrate the authoring contract offline."
+              }
+            ]
+          }
+        ]
+      },
+      "bottomContent": {
+        "paragraphs": [
+          {
+            "runs": [
+              {
+                "text": "An example fixture. Not a real business."
+              }
+            ]
+          }
+        ]
+      },
+      "featureImage": null
+    }
+  }
+}