Publish verified versioned machine resources from canonical Docs

Author: konojunya

.gitignore

@@ -18,6 +18,7 @@ docs/.vitepress/cache
 .stack-specification
 .stack-docs
 /public/docs-source.json
+/public/machine/
 docs/**/*.md
 
 # Editor directories and files

README.md

@@ -69,6 +69,17 @@ Review command behavior, then run `STACK_CLI_BIN=/absolute/path/to/the/verified/
 
 The required CI baseline compares the pin against GitHub's latest stable release and resolved tag commit, executes documentation commands using both the pinned source and the attested published Linux archive, and verifies that an unsupported flag fails the documentation smoke. Offline documentation builds check locale version consistency without contacting GitHub. The read-only `Release freshness` workflow checks daily and on manual dispatch, so a CLI-only release cannot remain silently stale until someone edits this repository. A failed run requires a synchronization PR and a verified Web deployment; this workflow does not auto-merge or auto-publish. GitHub scheduled runs may be delayed, and GitHub Actions notification preferences govern failure notifications.
 
+## Machine resources
+
+The pinned Docs bundle also supplies `/machine/index.json` and immutable versioned
+grammar/schema/diagnostic/example manifests. Both llms indexes link to discovery
+and the [canonical distribution policy](https://github.com/stack-sh/docs/blob/main/MACHINE_RESOURCES.md).
+Generated machine JSON is not hand-edited here. The output gate verifies every
+deployed machine file against the provider manifest and checks the discovery
+digest. Static headers allow public cross-origin reads, revalidate discovery, and
+cache version 1.0.0 artifacts immutably. Keep old versioned files when updating the
+Docs pin; publisher CI forbids rewriting them.
+
 ## Coding agent skill
 
 Install the focused diagram skill with `npx skills add stack-sh/cli` in the target project. It provides instructions, not a CLI binary. See the [coding agent guide](https://stack-diagram.com/docs/guide/coding-agents) for the usage workflow. Docs generates both the skill distributed by CLI and the workflow displayed here from one source. Web verifies and executes the same Docs bundle's skill commands alongside documentation examples against the published CLI.

docs/public/llms.txt

@@ -24,6 +24,9 @@ These Markdown pages are the public user-facing reference. Examples marked as `s
 
 ## Reference
 
+- [Machine resource discovery](https://stack-diagram.com/machine/index.json): Versioned grammar, schemas, diagnostics, example sources, implementation capabilities, and SHA-256 integrity.
+- [Machine resource policy](https://github.com/stack-sh/docs/blob/main/MACHINE_RESOURCES.md): Compatibility, immutable versions, caching, and a verified resource consumer example.
+
 - [Diagnostics and limits](https://stack-diagram.com/docs/reference/diagnostics-and-limits.md): Stable diagnostic codes, source ranges, warnings, and bounded-input limits.
 - [Versioning and safety](https://stack-diagram.com/docs/reference/versioning-and-safety.md): Compatibility policy, trust boundaries, escaping, and package responsibilities.
 

public/_headers

@@ -0,0 +1,13 @@
+# Static asset response rules: https://developers.cloudflare.com/workers/static-assets/headers/
+/machine/*
+  Access-Control-Allow-Origin: *
+  X-Content-Type-Options: nosniff
+
+/machine/index.json
+  Cache-Control: public, max-age=0, must-revalidate
+
+/machine/v1.0.0/*
+  Cache-Control: public, max-age=31536000, immutable
+
+/docs-source.json
+  Cache-Control: public, max-age=0, must-revalidate

public/llms.txt

@@ -6,6 +6,9 @@ Stack source describes components, boundaries, relationships, themes, and layout
 
 ## Documentation
 
+- [Machine resource discovery](https://stack-diagram.com/machine/index.json): Versioned grammar, schemas, diagnostics, example sources, implementation capabilities, and SHA-256 integrity.
+- [Machine resource policy](https://github.com/stack-sh/docs/blob/main/MACHINE_RESOURCES.md): Compatibility, immutable versions, caching, and a verified resource consumer example.
+
 - [Coding agents](https://stack-diagram.com/docs/guide/coding-agents.md): Install the Stack diagram skill or copy a minimal instruction; generate, validate, and render with the published local CLI.
 
 - [Stack documentation](https://stack-diagram.com/docs/llms.txt): Curated guides, complete language reference, diagnostics, limits, versioning, and safety information.

scripts/docs-source.json

@@ -1,5 +1,5 @@
 {
   "repository": "stack-sh/docs",
-  "revision": "cd7ba0356de8a70d8932036b0e6ea37519577fd0",
-  "manifestSha256": "4187e92ff990702d53586db14658dc15a3721c69d42501a4d5b4c615a8e31552"
+  "revision": "ba212b68ae52ca08c5593ad3f82ce634e876a4ad",
+  "manifestSha256": "dd79651f87ce53ae626b101bd57f0fcec7cc42879de2e3f0ded1e169e9097710"
 }

scripts/docs-source.mjs

@@ -26,7 +26,7 @@ export function validateManifest(bytes, lock) {
   for (const file of manifest.files) {
     assert.match(
       file.path,
-      /^(?:site\/(?:[a-z0-9-]+\/)*[a-z0-9-]+\.md|guide\/agent-workflow\.md|skills\/stack-diagrams\/SKILL\.md)$/,
+      /^(?:site\/(?:[a-z0-9-]+\/)*[a-z0-9-]+\.md|guide\/agent-workflow\.md|skills\/stack-diagrams\/SKILL\.md|machine\/(?:index\.json|v\d+\.\d+\.\d+\/[a-z0-9.-]+\.json))$/,
     )
     assert.ok(!seen.has(file.path), "Duplicate Docs path")
     seen.add(file.path)
@@ -83,7 +83,9 @@ export async function syncDocs(directory = root, lock = docsSource, fetchResourc
       ? `docs/${file.slice(5)}`
       : file === "skills/stack-diagrams/SKILL.md"
         ? ".stack-docs/SKILL.md"
-        : null
+        : file.startsWith("machine/")
+          ? `public/${file}`
+          : null
     if (!relative) continue
     const target = path.join(directory, relative)
     await mkdir(path.dirname(target), { recursive: true })

scripts/docs-source.test.mjs

@@ -10,7 +10,12 @@ function fixture(change = (manifest) => manifest) {
   const manifest = change({
     schemaVersion: "1.0",
     cli: { repository: "stack-sh/cli", revision: "b".repeat(40), version: "0.4.0" },
-    files: ["site/index.md", "skills/stack-diagrams/SKILL.md"].map((file) => ({
+    files: [
+      "site/index.md",
+      "skills/stack-diagrams/SKILL.md",
+      "machine/index.json",
+      "machine/v1.0.0/manifest.json",
+    ].map((file) => ({
       path: file,
       sha256: digest(source),
     })),
@@ -25,7 +30,7 @@ function fixture(change = (manifest) => manifest) {
     assert.ok(
       url.startsWith(`https://raw.githubusercontent.com/stack-sh/docs/${lock.revision}/generated/`),
     )
-    return new Response(url.endsWith("manifest.json") ? bytes : source)
+    return new Response(url.endsWith("/generated/manifest.json") ? bytes : source)
   }
   return { source, bytes, lock, fetchResource }
 }
@@ -37,6 +42,11 @@ test("retrieves verified immutable content and supplies only generated build inp
   await syncDocs(directory, f.lock, f.fetchResource)
   assert.equal(await readFile(path.join(directory, "docs/index.md"), "utf8"), f.source)
   assert.equal(await readFile(path.join(directory, ".stack-docs/SKILL.md"), "utf8"), f.source)
+  assert.equal(await readFile(path.join(directory, "public/machine/index.json"), "utf8"), f.source)
+  assert.equal(
+    await readFile(path.join(directory, "public/machine/v1.0.0/manifest.json"), "utf8"),
+    f.source,
+  )
   assert.deepEqual(
     JSON.parse(await readFile(path.join(directory, "public/docs-source.json"), "utf8")),
     f.lock,
@@ -50,6 +60,14 @@ test("rejects mutable pins, traversal, duplicate paths, and unsupported manifest
     (m) => ({ ...m, schemaVersion: "2.0" }),
     (m) => ({ ...m, files: [...m.files, m.files[0]] }),
     (m) => ({ ...m, files: [{ path: "site/../../README.md", sha256: "a".repeat(64) }] }),
+    (m) => ({
+      ...m,
+      files: [...m.files, { path: "machine/v1.0.0/../../outside.json", sha256: "a".repeat(64) }],
+    }),
+    (m) => ({
+      ...m,
+      files: [...m.files, { path: "machine/latest/manifest.json", sha256: "a".repeat(64) }],
+    }),
   ]) {
     const invalid = fixture(change)
     assert.throws(() => validateManifest(invalid.bytes, invalid.lock))
@@ -72,7 +90,7 @@ test("fails on missing or altered resources before writing build inputs", async
     syncDocs(
       directory,
       f.lock,
-      async (url) => new Response(url.endsWith("manifest.json") ? f.bytes : "altered"),
+      async (url) => new Response(url.endsWith("/generated/manifest.json") ? f.bytes : "altered"),
     ),
     /content integrity/,
   )

scripts/validate-docs-output.mjs

@@ -3,10 +3,25 @@ import path from "node:path"
 
 import { validateDocumentationContract } from "./docs-contract.mjs"
 import { documentationContract } from "./docs-validation.config.mjs"
+import { digest, readDocsManifest } from "./docs-source.mjs"
 
 const outputRoot = path.resolve("dist/docs")
 const siteOutputRoot = path.resolve("dist")
 const docsRoot = path.resolve("docs")
+const sourceManifest = readDocsManifest()
+const machineFiles = sourceManifest.files.filter((file) => file.path.startsWith("machine/"))
+if (machineFiles.length < 4) throw new Error("Machine distribution is incomplete")
+for (const file of machineFiles) {
+  const bytes = await readFile(path.join(siteOutputRoot, file.path))
+  if (digest(bytes) !== file.sha256) throw new Error(`Built machine asset drift: ${file.path}`)
+}
+const machineIndex = JSON.parse(
+  await readFile(path.join(siteOutputRoot, "machine/index.json"), "utf8"),
+)
+const manifestPath = new URL(machineIndex.current.url).pathname.slice(1)
+const machineManifest = await readFile(path.join(siteOutputRoot, manifestPath))
+if (digest(machineManifest) !== machineIndex.current.sha256)
+  throw new Error("Machine discovery digest mismatch")
 const localePages = [
   ["index.html", "en-US"],
   ["ja/index.html", "ja-JP"],