fix(docs): enforce generated documentation

packages/cssforge/moon.yml

@@ -138,5 +138,29 @@ tasks:
   readme-update:
     command: "tsx"
     args: ["./scripts/update-readme.ts"]
+    inputs:
+      - "src/**/*"
+      - "scripts/update-readme.ts"
+      - "package.json"
+      - "tsconfig.json"
+      - "/README.md"
+      - "/pnpm-lock.yaml"
+      - "/tsconfig.base.json"
+      - "README.md"
     options:
       runInCI: false
+      cache: false
+  readme-check:
+    command: "tsx"
+    args: ["./scripts/update-readme.ts", "--check"]
+    inputs:
+      - "src/**/*"
+      - "scripts/update-readme.ts"
+      - "package.json"
+      - "tsconfig.json"
+      - "/README.md"
+      - "/pnpm-lock.yaml"
+      - "/tsconfig.base.json"
+      - "README.md"
+    options:
+      runInCI: "affected"

packages/cssforge/scripts/update-readme.ts

@@ -18,7 +18,9 @@ import type { CSSForgeConfig } from "../src/config.ts";
 import { generateCSS } from "../src/generator.ts";
 
 const PACKAGE_ROOT = process.cwd();
-const README_PATH = resolve(PACKAGE_ROOT, "../../README.md");
+const WORKSPACE_ROOT = resolve(PACKAGE_ROOT, "../..");
+const README_PATH = resolve(WORKSPACE_ROOT, "README.md");
+const PACKAGE_README_PATH = resolve(PACKAGE_ROOT, "README.md");
 
 const START_DEFINITION = "<!-- md:generate defineConfig";
 const START_CODE = "-->";
@@ -62,7 +64,7 @@ function wrapSource(tsSource: string): string {
 	return `${importLine}${normalized}\n`;
 }
 
-async function processReadme(): Promise<boolean> {
+async function processReadme(check: boolean): Promise<boolean> {
 	const original = await readFile(README_PATH, "utf8");
 	const lines = original.split(/\r?\n/);
 
@@ -91,8 +93,7 @@ async function processReadme(): Promise<boolean> {
 	}
 
 	if (blocks.length === 0) {
-		console.log("No md:generate blocks found.");
-		return false;
+		throw new Error("No md:generate blocks found in README.md.");
 	}
 
 	const resultLines: string[] = [];
@@ -143,14 +144,39 @@ async function processReadme(): Promise<boolean> {
 
 	const updated = resultLines.join("\n");
 
+	const packageReadme = await readFile(PACKAGE_README_PATH, "utf8");
+	const stalePaths = [
+		...(updated === original ? [] : ["README.md"]),
+		...(updated === packageReadme ? [] : ["packages/cssforge/README.md"]),
+	];
+
+	if (check) {
+		if (stalePaths.length > 0) {
+			console.error(`Generated README content is stale: ${stalePaths.join(", ")}`);
+			console.error("Run `moon run cssforge:readme-update` and commit the result.");
+			process.exitCode = 1;
+			return false;
+		}
+
+		console.log("Generated README content is up to date.");
+		return true;
+	}
+
 	if (updated !== original) {
 		await writeFile(README_PATH, updated, "utf8");
-		console.log("README.md updated successfully.");
+	}
+
+	if (updated !== packageReadme) {
+		await writeFile(PACKAGE_README_PATH, updated, "utf8");
+	}
+
+	if (stalePaths.length > 0) {
+		console.log(`Updated generated README content: ${stalePaths.join(", ")}`);
 		return true;
 	}
 
-	console.log("README.md had no changes.");
+	console.log("Generated README content had no changes.");
 	return false;
 }
 
-await processReadme();
+await processReadme(process.argv.includes("--check"));

packages/docs/agents.md

@@ -20,10 +20,12 @@ The compact machine-readable route index is available at [`/llms.txt`](/llms.txt
 
 ## Repository sources of truth
 
+The root `README.md` is canonical. Its generated package copy at `packages/cssforge/README.md` should not be edited directly.
+
 - [Public exports](https://github.com/Hebilicious/cssforge/blob/main/packages/cssforge/src/mod.ts)
 - [Configuration types](https://github.com/Hebilicious/cssforge/blob/main/packages/cssforge/src/config.ts)
 - [CLI implementation](https://github.com/Hebilicious/cssforge/blob/main/packages/cssforge/src/cli.ts)
-- [Generated reference source](https://github.com/Hebilicious/cssforge/blob/main/packages/cssforge/README.md)
+- [Generated reference source](https://github.com/Hebilicious/cssforge/blob/main/README.md)
 - [Example projects](https://github.com/Hebilicious/cssforge/tree/main/example)
 
 ## Agent workflow
@@ -39,5 +41,5 @@ The compact machine-readable route index is available at [`/llms.txt`](/llms.txt
 For agents that accept URL context, the complete generated reference remains available from the repository README:
 
 ```text
-@https://raw.githubusercontent.com/Hebilicious/cssforge/refs/heads/main/packages/cssforge/README.md
+@https://raw.githubusercontent.com/Hebilicious/cssforge/refs/heads/main/README.md
 ```

packages/docs/moon.yml

@@ -12,7 +12,7 @@ tasks:
     args: ["./scripts/sync-readme.ts"]
     inputs:
       - "scripts/sync-readme.ts"
-      - "/packages/cssforge/README.md"
+      - "/README.md"
     outputs:
       - "contributing.md"
       - "guide/getting-started.md"
@@ -63,6 +63,11 @@ tasks:
     deps:
       - "~:generate"
       - "~:sync-docs"
+      - "cssforge:readme-check"
+    inputs:
+      - "**/*"
+      - "/README.md"
+      - "/packages/cssforge/README.md"
     outputs:
       - ".vitepress/dist"
     options:

packages/docs/scripts/cloudflare.sh

@@ -31,4 +31,4 @@ if ! command -v proto >/dev/null 2>&1; then
 fi
 
 proto install --yes
-moon run "$cloudflare_task" "$@"
+moon exec --ci false --ignore-ci-checks --force "$cloudflare_task" "$@"

packages/docs/scripts/sync-readme.ts

@@ -25,8 +25,8 @@ interface GeneratedPage {
 
 const root = resolve(import.meta.dirname, "../../..");
 const docsRoot = resolve(root, "packages/docs");
-const readmePath = resolve(root, "packages/cssforge/README.md");
-const sourcePath = "packages/cssforge/README.md";
+const readmePath = resolve(root, "README.md");
+const sourcePath = "README.md";
 const githubBase = "https://github.com/Hebilicious/cssforge/tree/main";
 
 function parseSections(markdown: string, level: number): ParsedMarkdown {