refactor(samples): replace raw WMS shell runner

.github/workflows/validate.yml

@@ -3,6 +3,7 @@ name: validate
 on:
   pull_request:
     paths:
+      - "README.md"
       - "samples/**"
       - "schemas/**"
       - "scripts/**"
@@ -12,6 +13,7 @@ on:
   push:
     branches: [trunk]
     paths:
+      - "README.md"
       - "samples/**"
       - "schemas/**"
       - "scripts/**"
@@ -26,6 +28,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Enforce maintained documentation command policy
+        run: |
+          if git grep -n -i -w curl -- '*.md' '*.mdx' '*.rst' '*.txt'; then
+            echo "::error::Maintained documentation must use supported SDK, CLI, or API-reference workflows."
+            exit 1
+          fi
+
       - uses: actions/setup-node@v4
         with:
           node-version: "22"

README.md

@@ -221,13 +221,10 @@ honua-server has no published, purchasable license mechanism for this repo
 yet, so the overlay uses its documented dev/test bypass instead --
 `Licensing__DevGrantEdition` (backed by `DevLicenseEntitlementService` in
 honua-server), which fails closed outside `Development`/`Staging`
-environments. Verify it took effect:
-
-```bash
-curl -s -H "X-API-Key: $HONUA_ADMIN_PASSWORD" \
-  http://localhost:8080/api/v1/admin/license/status | jq '.data.edition'
-# => "Pro"
-```
+environments. Verify the effective edition in Console under **Operate →
+Licensing**, or use the generated API explorer's
+`GET /api/v1/admin/license/status` operation with the configured admin key;
+the returned `data.edition` value should be `Pro`.
 
 `scripts/run-samples.mjs --edition <community|pro|enterprise>` (default
 `community`) is the other half: a sample whose manifest `edition` exceeds the
@@ -325,7 +322,8 @@ A detail page doesn't just describe an honua-sdk-js sample -- when a verified
 build exists, it runs it live in an iframe (honua-io/honua-samples#11),
 consuming honua-sdk-js's `sample-bundles-latest` GitHub Release
 ([honua-io/honua-sdk-js#642](https://github.com/honua-io/honua-sdk-js/issues/642)/[#648](https://github.com/honua-io/honua-sdk-js/issues/648)):
-a `sample-bundles.v1.json` manifest (per-sample entrypoint, data mode,
+a `sample-bundles.v2.json` manifest (with a compatibility fallback for legacy
+`sample-bundles.v1.json`), per-sample entrypoint, data mode,
 `builtFrom` commit/version, and per-file `{path, bytes, sha256, integrity}`)
 plus a `sample-bundles.tar.gz` of the built static files. This repo never
 builds sdk-js source itself -- only the already-built, already-CI-verified
@@ -431,12 +429,10 @@ Gallery embeds: [#11](https://github.com/honua-io/honua-samples/issues/11)
 (staging/integrity/embed pipeline implemented and verified end-to-end against
 a synthetic fixture release matching honua-sdk-js's manifest schema exactly --
 see that PR's description. Honest current state: honua-sdk-js's real
-`sample-bundles-latest` release does not exist yet, because its
-"Publish sample bundles release" job needs the "JS SDK" job, which has been
-failing on every honua-sdk-js trunk push since #648 merged (an unrelated
-evidence-neutral-checkout gate failure). Every gallery deploy therefore
-degrades honestly to "no runnable build published yet" for every sdk-js entry
-until that upstream job is fixed; nothing here is blocked on this repo).
+`sample-bundles-latest` release has moved to manifest schema v2 and is consumed
+by this repo. If either release publication or fetch fails for any reason,
+the gallery degrades honestly to "no runnable build published yet" for every
+sdk-js entry; that behavior remains by design.
 
 ## License
 

config/sdkjs-catalog.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "Committed fallback snapshot consumed by scripts/lib/sdkjs-catalog.mjs (via scripts/build-gallery.mjs) when the live fetch of samples/catalog.v2.json fails, so samples.honua.io deploys never break on an sdk-js-side hiccup. Rewritten automatically whenever the live fetch succeeds -- commit the change to keep the offline fallback current. See honua-io/honua-samples#3.",
   "sourceUrl": "https://raw.githubusercontent.com/honua-io/honua-sdk-js/trunk/samples/catalog.v2.json",
-  "fetchedAt": "2026-07-31T23:05:07.729Z",
+  "fetchedAt": "2026-08-05T22:29:04.597Z",
   "catalog": {
     "$schema": "./contract/v2/schemas/sample-catalog.schema.json",
     "format": "honua.sdk.sample-catalog.v2",
@@ -218,6 +218,21 @@
         },
         "sourcePath": "examples/ai-spatial-app-builder",
         "docsPath": "examples/ai-spatial-app-builder/README.md",
+        "playground": {
+          "projectPath": "playgrounds/ai-spatial-app-builder",
+          "providers": [
+            {
+              "id": "stackblitz",
+              "title": "StackBlitz",
+              "url": "https://stackblitz.com/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/ai-spatial-app-builder"
+            },
+            {
+              "id": "codesandbox",
+              "title": "CodeSandbox",
+              "url": "https://codesandbox.io/s/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/ai-spatial-app-builder"
+            }
+          ]
+        },
         "capabilities": [
           "agent-approval",
           "agent-planning",
@@ -279,7 +294,7 @@
               "npm run demo:ai-spatial-builder:live-evidence"
             ],
             "evidencePath": "examples/ai-spatial-app-builder/evidence/live-skipped.v1.json",
-            "expiresAt": "2026-08-15T18:00:00.000Z"
+            "expiresAt": "2026-10-08T18:00:00.000Z"
           }
         },
         "expectedDegradation": "Missing host endpoints produce a structured skip; mutation, realtime, and generated-app effects stay disabled without separate host policy.",
@@ -860,7 +875,7 @@
               "npm run evidence:cog:live"
             ],
             "evidencePath": "samples/evidence/imagery-cog-quickstart/live.v1.json",
-            "expiresAt": "2026-08-25T20:47:36.447Z"
+            "expiresAt": "2026-09-05T13:39:53.733Z"
           }
         },
         "expectedDegradation": "Credential-bearing URLs, CORS, missing or oversized range responses, unsupported CRS/format, and nodata return structured outcomes while published imagery remains usable. Public live proof covers classified COG inspection and a bounded decoded window in EPSG:32621; browser-side UTM reprojection and a georeferenced live MapLibre mount remain explicitly unclaimed.",
@@ -1108,7 +1123,7 @@
               "npm run evidence:first-map:live"
             ],
             "evidencePath": "samples/evidence/maplibre-quickstart/live.v1.json",
-            "expiresAt": "2026-08-25T20:45:58.688Z"
+            "expiresAt": "2026-09-05T13:37:48.259Z"
           }
         },
         "expectedDegradation": "Capability misses, plan warnings, and bounded fallback are shown rather than silently returning an empty map.",
@@ -1230,7 +1245,7 @@
               "npm run evidence:migration-workbench:live"
             ],
             "evidencePath": "samples/evidence/migration-workbench/live.v1.json",
-            "expiresAt": "2026-08-25T20:47:54.208Z"
+            "expiresAt": "2026-09-05T13:40:16.879Z"
           }
         },
         "expectedDegradation": "Unsupported ArcGIS modules are reported as manual work, never silently removed.",
@@ -1550,6 +1565,60 @@
           "npm run demo:oauth-signin:build"
         ]
       },
+      {
+        "id": "offline-region-reference",
+        "title": "Network-disabled offline region reference",
+        "summary": "Proves that a persisted IndexedDB region, a durable queued edit, and a bounded host-owned application shell survive reload after browser networking is disabled, then replays that edit exactly once against a loopback fixture transport on reconnect and reports one composed local-first state.",
+        "sourceKind": "docs-example",
+        "track": "fixture",
+        "supportTier": "experimental",
+        "lifecycle": {
+          "state": "active",
+          "reason": "Retain as browser evidence for the disconnected-read, offline edit capture and reconnect replay, and composed local-first state acceptance slices of the experimental offline region contract."
+        },
+        "sourcePath": "docs/examples/offline-region-reference",
+        "docsPath": "docs/examples/offline-region-reference/README.md",
+        "capabilities": [
+          "offline",
+          "provenance"
+        ],
+        "protocols": [
+          "honua"
+        ],
+        "renderers": [
+          "none"
+        ],
+        "data": {
+          "mode": "fixture",
+          "authMode": "none",
+          "configurationStatus": "not-required",
+          "config": [],
+          "provenance": "One committed integrity-, length-, and version-pinned fixture served from an isolated loopback origin and persisted through the public IndexedDB offline contract; edit replay is bound to a loopback fixture endpoint that mirrors the documented acknowledgement shape and keeps no replica, upload cursor, or conflict store.",
+          "attribution": "Honua deterministic incident fixture.",
+          "freshness": "Explicit online observation time and stale disconnected diagnostic time.",
+          "configClassifications": []
+        },
+        "evidence": {
+          "fixture": {
+            "mode": "fixture",
+            "status": "executed",
+            "commands": [
+              "npx playwright test test/playwright/offline-indexeddb.spec.mjs"
+            ]
+          },
+          "live": {
+            "mode": "unavailable",
+            "status": "not-applicable",
+            "commands": []
+          }
+        },
+        "expectedDegradation": "A missing persisted region renders an explicit offline cache miss and a partial/missing-regions local-first state that a queued edit cannot mask, and a conflicted, mismatched, or retryable acknowledgement leaves durable typed queue state instead of a silent drop; the fixture does not synthesize an empty success and its loopback replay endpoint does not claim replica synchronization or end-to-end exactly-once server semantics.",
+        "validationProfile": "browser-fixture",
+        "validation": [
+          "npx playwright test test/playwright/offline-indexeddb.spec.mjs"
+        ],
+        "capabilityKeys": []
+      },
       {
         "id": "overture-geoparquet",
         "title": "Overture GeoParquet",
@@ -1754,6 +1823,21 @@
         },
         "sourcePath": "examples/react-quickstart",
         "docsPath": "examples/react-quickstart/README.md",
+        "playground": {
+          "projectPath": "playgrounds/react-quickstart",
+          "providers": [
+            {
+              "id": "stackblitz",
+              "title": "StackBlitz",
+              "url": "https://stackblitz.com/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/react-quickstart"
+            },
+            {
+              "id": "codesandbox",
+              "title": "CodeSandbox",
+              "url": "https://codesandbox.io/s/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/react-quickstart"
+            }
+          ]
+        },
         "capabilities": [
           "map",
           "query",
@@ -2068,7 +2152,7 @@
               "npm run demo:service-explorer:live-evidence"
             ],
             "evidencePath": "samples/evidence/service-explorer/live.v1.json",
-            "expiresAt": "2026-08-25T20:48:34.517Z"
+            "expiresAt": "2026-09-05T13:41:16.616Z"
           }
         },
         "expectedDegradation": "Partial discovery and unsupported source actions remain visible with structured state, code, and reason; the sample does not synthesize success.",
@@ -2154,6 +2238,21 @@
         },
         "sourcePath": "examples/sketch-editing",
         "docsPath": "examples/sketch-editing/README.md",
+        "playground": {
+          "projectPath": "playgrounds/sketch-editing",
+          "providers": [
+            {
+              "id": "stackblitz",
+              "title": "StackBlitz",
+              "url": "https://stackblitz.com/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/sketch-editing"
+            },
+            {
+              "id": "codesandbox",
+              "title": "CodeSandbox",
+              "url": "https://codesandbox.io/s/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/sketch-editing"
+            }
+          ]
+        },
         "capabilities": [
           "editing",
           "sketch",
@@ -2364,7 +2463,7 @@
               "npm run demo:spatial-analytics:live-evidence"
             ],
             "evidencePath": "examples/spatial-analytics-workbench/evidence/live-skipped.v1.json",
-            "expiresAt": "2026-08-01T08:00:00.000Z"
+            "expiresAt": "2026-11-01T08:34:51.355Z"
           }
         },
         "expectedDegradation": "Remote fixtures are labeled replayed, bounded-local execution is capped, unsafe materialization is rejected, and OGC/DuckDB planner execution is a structured #389 follow-on.",
@@ -2389,6 +2488,21 @@
         },
         "sourcePath": "examples/stac-imagery-browser",
         "docsPath": "examples/stac-imagery-browser/README.md",
+        "playground": {
+          "projectPath": "playgrounds/stac-imagery-browser",
+          "providers": [
+            {
+              "id": "stackblitz",
+              "title": "StackBlitz",
+              "url": "https://stackblitz.com/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/stac-imagery-browser"
+            },
+            {
+              "id": "codesandbox",
+              "title": "CodeSandbox",
+              "url": "https://codesandbox.io/s/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/stac-imagery-browser"
+            }
+          ]
+        },
         "capabilities": [
           "cog",
           "imagery",
@@ -2553,6 +2667,21 @@
         },
         "sourcePath": "examples/temporal-playback",
         "docsPath": "examples/temporal-playback/README.md",
+        "playground": {
+          "projectPath": "playgrounds/temporal-playback",
+          "providers": [
+            {
+              "id": "stackblitz",
+              "title": "StackBlitz",
+              "url": "https://stackblitz.com/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/temporal-playback"
+            },
+            {
+              "id": "codesandbox",
+              "title": "CodeSandbox",
+              "url": "https://codesandbox.io/s/github/honua-io/honua-sdk-js/tree/trunk/playgrounds/temporal-playback"
+            }
+          ]
+        },
         "capabilities": [
           "map",
           "realtime",

samples/hello-featureserver-rest/README.md

@@ -2,7 +2,7 @@
 
 Plain-REST sample: no SDK, just `fetch()`. Demonstrates the full
 import -> publish -> query loop against a composed Honua Server, then asserts
-the round trip instead of just eyeballing curl output.
+the round trip instead of just eyeballing a raw response.
 
 ## What it does
 

samples/wms-getmap-check/README.md

@@ -1,8 +1,8 @@
 # wms-getmap-check
 
-Plain bash+curl sample: no SDK, no scripting language beyond curl/jq/od.
-Demonstrates classic WMS `GetCapabilities`/`GetMap` the way a shell-scripted
-smoke test would actually be written.
+Zero-dependency Node.js sample using the platform `fetch()` API. Demonstrates
+classic WMS `GetCapabilities`/`GetMap` with assertions suitable for a headless
+smoke test.
 
 ## What it does
 
@@ -28,11 +28,10 @@ From the repo root, with a composed server already running (see the
 [top-level README](../../README.md#local-dev)):
 
 ```bash
-bash samples/wms-getmap-check/src/run.sh
+node samples/wms-getmap-check/src/run.mjs
 ```
 
-Requires `curl`, `jq`, and GNU/uutils `od` (all preinstalled on GitHub
-Actions `ubuntu-latest` runners).
+Requires Node.js 22 or later; there are no npm dependencies.
 
 Environment variables (all optional):
 

samples/wms-getmap-check/sample.json

@@ -1,7 +1,7 @@
 {
   "id": "wms-getmap-check",
-  "title": "WMS GetCapabilities + GetMap check (bash + curl)",
-  "description": "Plain bash+curl walkthrough of classic WMS: imports a tiny GeoJSON dataset, publishes it, requests GetCapabilities and GetMap, and asserts a real, correctly-sized PNG comes back -- not just a 200 status.",
+  "title": "WMS GetCapabilities + GetMap check (Node.js)",
+  "description": "Zero-dependency Node.js walkthrough of classic WMS: imports a tiny GeoJSON dataset, publishes it, requests GetCapabilities and GetMap, and asserts a real, correctly-sized PNG comes back -- not just a 200 status.",
   "capabilities": [
     "import.file",
     "serve.wms"
@@ -14,8 +14,8 @@
   ],
   "edition": "community",
   "entrypoint": {
-    "type": "script",
-    "command": "bash src/run.sh"
+    "type": "node",
+    "command": "node src/run.mjs"
   },
   "status": "active"
 }