docs: publish Sourcey-generated llms.txt

.gitignore

@@ -17,4 +17,5 @@
 /www/dist/
 /www/node_modules/
 /www/public/demo/
+/www/public/llms.txt
 .vercel

README.md

@@ -827,6 +827,25 @@ overrides are an explicit unanchored source/test trust boundary.
 `spock start` and `spock dev` are the only umbrella lifecycle: one project,
 listener, origin, and coordinated shutdown.
 
+## AI and agent documentation
+
+The canonical [llms.txt](llms.txt) index maps AI tools to Spock's authoritative
+guides, specifications, design records, governance, and source. It is generated
+from the Markdown documentation with Sourcey and published at
+[spock.sh/llms.txt](https://spock.sh/llms.txt) by the website build.
+
+After changing indexed documentation, install the website dependencies and
+regenerate the tracked source:
+
+```sh
+corepack pnpm@10.11.0 -C www install --frozen-lockfile
+corepack pnpm@10.11.0 -C www generate:llms
+```
+
+The production build checks that `llms.txt` is current and copies that exact
+canonical file to the static website, preventing a second hand-maintained copy
+from drifting.
+
 ## Contributing and language evolution
 
 Spock welcomes implementation, documentation, testing, research, and competing

llms.txt

@@ -0,0 +1,39 @@
+# Spock
+
+> Install the Spock toolchain from npm — prebuilt native binaries for macOS, Linux, and Windows, with no build step and no network access at install time.
+
+
+## Start here
+
+- [Project and framework overview](/docs/): What Spock is, its current scope, and its documentation map.
+- [Getting started](/docs/start/): Installation, a quickstart, and the complete tutorial.
+- [Spock v0 language specification](/docs/spec/v0/): The normative definition of current language behavior.
+- [GraphQL dialect specification](/docs/spec/graphql/): The normative GraphQL exposure contract.
+- [Design records](https://github.com/gridaco/spock/tree/main/docs/rfd): Accepted and historical design records in the source repository.
+- [Governance](/docs/governance/project/): Project authority, process, and decision making.
+- [Contributing](/docs/contributing/): How to report problems and contribute changes.
+- [GitHub source](https://github.com/gridaco/spock): Source code, issues, and releases.
+
+## Documentation
+
+- [Install](/docs/start/install/): Install the Spock toolchain from npm — prebuilt native binaries for macOS, Linux, and Windows, with no build step and no network access at install time.
+- [Quickstart](/docs/start/quickstart/): Scaffold a project, declare a two-table authority, serve it, and meet your first derived error — in about ten minutes.
+- [Tutorial: build a mini-Instagram backend](/docs/start/tutorial/): Build a mini-Instagram backend — users, posts, likes, comments — from an empty project to a contract with a named refusal, one verified step at a time.
+- [Identity: the actor seam](/docs/language/actor/): How Spock v0 carries identity — the auth table anchor, the X-Spock-Actor header, spock_actor(), = me, and the impersonation workflow.
+- [The derived API](/docs/language/derived-api/): Every table derives a contract, REST reads, a GraphQL schema, and a pre-declared error vocabulary — none of it authored by you.
+- [Functions and refusals](/docs/language/functions/): How Spock functions declare typed contracts over SQL escape bodies — polarity, return shapes, records, product errors, and refusals.
+- [Seed and disposable state](/docs/language/seed/): How seed blocks populate a program's world through its own contract, and why replay — not migration — is the state life cycle.
+- [Tables, types, and defaults](/docs/language/tables/): Declaring durable truth in Spock: tables, builtin types, keys, defaults, uniqueness, references, closed sets, and validator checks.
+- [CLI](/docs/reference/cli/): Every spock command — check, new, init, start, dev, run, build, and gen — with flags, defaults, and the output each one prints.
+- [Error codes](/docs/reference/errors/): The complete Spock error vocabulary — derived, reserved, and product runtime codes, both wire envelopes, and every compile-time diagnostic.
+- [HTTP API](/docs/reference/http/): Every endpoint the runtime serves — the meta surface, REST reads and filter operators, rpc, the GraphQL binding, wire errors, and the storage plane.
+- [spock.toml](/docs/reference/spock-toml/): The strict version-1 spock.toml manifest — schema, validation diagnostics, the canonical scaffolds, and how commands discover a project.
+- [Project status](/docs/status/): What is stable, experimental, in progress, and deliberately absent in Spock v0 — plus the project vocabulary.
+- [Uhura](/docs/uhura/): What Uhura is, what it owns versus Spock, and what ships with the spock CLI today.
+- [Examples](/docs/examples/): The example portfolio — what each harness demonstrates, what runs, and what is deliberately not a program yet.
+- [Spock v0 — language specification](/docs/spec/v0/): Status: normative for the v0 toolchain. Scope: the implemented declarations — `table`/`auth table`, `record`, `fn`/`mut fn`, and `seed` — one embedded-SQLite runtime, and a minimal HTTP protocol. Future declarations such as `view`, `role`, and `policy` remain deliberately absent and reserved (§2.3) so v0 programs stay forward-compatible.
+- [The GraphQL surface — dialect specification](/docs/spec/graphql/): Status: **normative**. This document specifies the GraphQL dialect Spock derives, independent of what any given toolchain version has implemented. The v0 runtime implements **Tier 1** (§7); higher tiers are the target. `docs/spec/v0.md` §8.2 records the v0 protocol binding (mount, page discipline, error envelope); §9 here records the executed migration from the pre-dialect surface.
+- [Spock design principles](/docs/governance/design-principles/): These principles turn the README doctrine into a review rubric. They do not replace judgment. They make judgment explainable, consistent, and open to challenge with evidence.
+- [Language change process](/docs/governance/language-change-process/): Spock is intentionally small, unconventional, and opinionated. Language evolution therefore starts with a demonstrated problem and proceeds through published judgment. Implementations and syntax sketches may be evidence, but the first working patch or most popular spelling does not decide adoption.
+- [Language Design Committee](/docs/governance/language-design-committee/): The Language Design Committee is Spock's permanent language-design authority. Its legal and administrative relationship to the Project Lead, membership rules, voting thresholds, conflicts, and appeals are defined in GOVERNANCE.md. This charter describes how the committee operates.
+- [Current adoption defaults](/docs/governance/commonly-declined/): This page records current adoption defaults for recurring questions. It is deliberately small. It is not a blacklist, a permanent verdict, a substitute for committee judgment, or a list of every rejected RFD. Spock is pre-1.0; experiments that test these assumptions are welcome.

scripts/generate-llms.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  copyFileSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const canonicalPath = join(repoRoot, 'llms.txt');
+const publicPath = join(repoRoot, 'www', 'public', 'llms.txt');
+const sourceyCli = join(
+  repoRoot,
+  'www',
+  'node_modules',
+  'sourcey',
+  'dist',
+  'cli.js',
+);
+const check = process.argv.includes('--check');
+const publish = process.argv.includes('--publish');
+
+const startHere = `## Start here
+
+- [Project and framework overview](/docs/): What Spock is, its current scope, and its documentation map.
+- [Getting started](/docs/start/): Installation, a quickstart, and the complete tutorial.
+- [Spock v0 language specification](/docs/spec/v0/): The normative definition of current language behavior.
+- [GraphQL dialect specification](/docs/spec/graphql/): The normative GraphQL exposure contract.
+- [Design records](https://github.com/gridaco/spock/tree/main/docs/rfd): Accepted and historical design records in the source repository.
+- [Governance](/docs/governance/project/): Project authority, process, and decision making.
+- [Contributing](/docs/contributing/): How to report problems and contribute changes.
+- [GitHub source](https://github.com/gridaco/spock): Source code, issues, and releases.`;
+
+if (!existsSync(sourceyCli)) {
+  throw new Error(
+    'Sourcey is not installed. Run corepack pnpm@10.11.0 -C www install first.',
+  );
+}
+
+const outputDir = mkdtempSync(join(tmpdir(), 'spock-sourcey-'));
+
+try {
+  const result = spawnSync(
+    process.execPath,
+    [sourceyCli, 'build', '--config', 'sourcey.config.ts', '--output', outputDir],
+    { cwd: repoRoot, stdio: 'inherit' },
+  );
+
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status ?? 1);
+
+  const generatedPath = join(outputDir, 'llms.txt');
+  const sourceyOutput = readFileSync(generatedPath, 'utf8').trimEnd();
+  const lines = sourceyOutput.split('\n');
+  const firstSection = lines.findIndex((line) => line.startsWith('## '));
+
+  if (firstSection === -1) {
+    throw new Error('Sourcey output did not contain a documentation section');
+  }
+
+  const canonical = [
+    ...lines.slice(0, firstSection),
+    '',
+    startHere,
+    '',
+    ...lines.slice(firstSection),
+  ].join('\n') + '\n';
+  const current = existsSync(canonicalPath)
+    ? readFileSync(canonicalPath, 'utf8')
+    : undefined;
+
+  if (check && current !== canonical) {
+    console.error('llms.txt is stale; run: corepack pnpm@10.11.0 -C www generate:llms');
+    process.exitCode = 1;
+  } else {
+    if (!check && current !== canonical) {
+      writeFileSync(canonicalPath, canonical, 'utf8');
+      console.log('Updated llms.txt from Sourcey output.');
+    } else {
+      console.log('llms.txt is up to date.');
+    }
+
+    if (publish) {
+      copyFileSync(canonicalPath, publicPath);
+      console.log('Published the canonical file to www/public/llms.txt.');
+    }
+  }
+} finally {
+  rmSync(outputDir, { recursive: true, force: true });
+}

sourcey.config.ts

@@ -0,0 +1,65 @@
+import { defineConfig, markdown } from "sourcey";
+
+export default defineConfig({
+  name: "Spock",
+  siteUrl: "https://spock.sh",
+  prettyUrls: "slash",
+  repo: "https://github.com/gridaco/spock",
+  editBranch: "main",
+  navigation: {
+    tabs: [
+      {
+        tab: "Documentation",
+        slug: "",
+        source: markdown({
+          groups: [
+            {
+              group: "Getting started",
+              pages: [
+                "docs/start/install",
+                "docs/start/quickstart",
+                "docs/start/tutorial",
+              ],
+            },
+            {
+              group: "Language guides",
+              pages: [
+                "docs/language/actor",
+                "docs/language/derived-api",
+                "docs/language/functions",
+                "docs/language/seed",
+                "docs/language/tables",
+              ],
+            },
+            {
+              group: "Reference",
+              pages: [
+                "docs/reference/cli",
+                "docs/reference/errors",
+                "docs/reference/http",
+                "docs/reference/spock-toml",
+              ],
+            },
+            {
+              group: "Project guides",
+              pages: ["docs/status", "docs/uhura", "docs/examples"],
+            },
+            {
+              group: "Normative specifications",
+              pages: ["docs/spec/v0", "docs/spec/graphql"],
+            },
+            {
+              group: "Governance",
+              pages: [
+                "docs/governance/design-principles",
+                "docs/governance/language-change-process",
+                "docs/governance/language-design-committee",
+                "docs/governance/commonly-declined",
+              ],
+            },
+          ],
+        }),
+      },
+    ],
+  },
+});

vercel.json

@@ -6,6 +6,12 @@
   "buildCommand": "bash scripts/build-www.sh",
   "outputDirectory": "www/dist",
   "headers": [
+    {
+      "source": "/llms.txt",
+      "headers": [
+        { "key": "Content-Type", "value": "text/plain; charset=utf-8" }
+      ]
+    },
     {
       "source": "/demo/api/editor/state",
       "headers": [

www/README.md

@@ -10,6 +10,10 @@ loader publishes the selected files from `../docs/` and the root governance
 documents, preserving their normative, decision-record, governance, or
 non-normative status. Do not copy those sources into `www/`.
 
+The same rule applies to `../llms.txt`: Sourcey generates the tracked canonical
+file, and the website build verifies and copies it to `public/llms.txt`. The
+published copy is generated and ignored; do not edit or commit it.
+
 ## Local development
 
 From the repository root:

www/package.json

@@ -10,10 +10,12 @@
   },
   "scripts": {
     "dev": "astro dev",
+    "generate:llms": "node ../scripts/generate-llms.mjs",
+    "check:llms": "node ../scripts/generate-llms.mjs --check",
     "check:demo": "node scripts/check-demo.mjs",
     "smoke:demo": "node scripts/smoke-www-demo.mjs",
     "check": "astro check",
-    "build": "node scripts/check-demo.mjs && astro check && astro build",
+    "build": "node ../scripts/generate-llms.mjs --check --publish && node scripts/check-demo.mjs && astro check && astro build",
     "preview": "astro preview"
   },
   "dependencies": {
@@ -28,6 +30,7 @@
     "@astrojs/check": "^0.9.9",
     "@tailwindcss/vite": "^4.3.2",
     "playwright": "1.61.1",
+    "sourcey": "3.6.5",
     "tailwindcss": "^4.3.2",
     "typescript": "^6.0.3"
   }