aigpu 0.3.1

package/dist/cli/lib/docs/generate/check-drift.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { computeStamp, generateDocs } from "./generate.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "../../../../..");
+const committedSkillDir = resolve(root, "skills/aigpu");
+const committedManifestOut = resolve(root, "packages/aigpu-cli/lib/generated/docs-manifest.generated.js");
+const scratch = mkdtempSync(join(tmpdir(), "aigpu-skill-drift-"));
+const freshSkillDir = join(scratch, "skill");
+const freshManifestOut = join(scratch, "manifest.js");
+
+try {
+  generateDocs({ root, skillDir: freshSkillDir, manifestOut: freshManifestOut, stamp: computeStamp(root) });
+  const issues = [];
+  if (read(committedManifestOut) !== read(freshManifestOut)) issues.push(`docs manifest differs: ${relative(root, committedManifestOut)}`);
+  const committed = files(committedSkillDir);
+  const fresh = files(freshSkillDir);
+  for (const path of fresh) if (!committed.has(path)) issues.push(`missing skill file: skills/aigpu/${path}`);
+  for (const path of committed) if (!fresh.has(path)) issues.push(`stale skill file: skills/aigpu/${path}`);
+  for (const path of committed) {
+    if (!fresh.has(path)) continue;
+    const left = normalizeStamp(path, read(join(committedSkillDir, path)));
+    const right = normalizeStamp(path, read(join(freshSkillDir, path)));
+    if (left !== right) issues.push(`skill content differs: skills/aigpu/${path}`);
+  }
+  if (issues.length) {
+    console.error("AIGpu docs or skill output is out of date. Run `pnpm --dir packages/aigpu-cli generate:docs`.");
+    for (const issue of issues) console.error(`  - ${issue}`);
+    process.exitCode = 1;
+  } else {
+    console.log("AIGpu docs manifest and skill are current.");
+  }
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}
+
+function files(directory) {
+  const result = new Set();
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else result.add(relative(directory, path));
+    }
+  };
+  if (statSync(directory).isDirectory()) walk(directory);
+  return result;
+}
+
+function read(path) {
+  try { return readFileSync(path, "utf8"); } catch { return null; }
+}
+
+function normalizeStamp(path, content) {
+  if (path !== "SKILL.md" || content === null) return content;
+  return content.replace(/^(gitSha|generatedAt): .*$/gmu, "$1: <stamp>");
+}

package/dist/cli/lib/docs/generate/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { computeStamp, generateDocs } from "./generate.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "../../../../..");
+const manifestOut = resolve(root, "packages/aigpu-cli/lib/generated/docs-manifest.generated.js");
+const skillDir = resolve(root, "skills/aigpu");
+const { manifest } = generateDocs({ root, skillDir, manifestOut, stamp: computeStamp(root) });
+const guideCount = manifest.records.filter((record) => record.kind === "guide").length;
+console.log(`docs: ${manifest.records.length} records (${guideCount} guides) → manifest + skill at ${skillDir}`);

package/dist/cli/lib/docs/generate/generate.js

@@ -0,0 +1,113 @@
+// Shared core for one docs-generation run: builds the manifest from docs/allowlist.txt +
+// docs/topics, then writes the manifest + skill mirror. Used by both cli.js (writes into the
+// repo's committed skills/aigpu) and check-drift.js (writes into a scratch temp dir so it can diff
+// against the committed copy without touching the working tree).
+import { execSync } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createManifest, serializeManifest } from "./manifest.js";
+import { buildSkill } from "./skill.js";
+
+// Writes are atomic (temp file in the same directory, then rename) because this generator runs
+// as `prepack` for both packages/aigpu and packages/aigpu-api. `npm pack` and the docs tests can
+// therefore run it concurrently, and a half-written file would be read by whichever sibling is
+// mid-run. Temp names carry the pid so two runs never collide on one temp path.
+const TEMP_SUFFIX = /\.\d+\.tmp$/u;
+
+function writeAtomic(outPath, content) {
+  mkdirSync(dirname(outPath), { recursive: true });
+  const temp = `${outPath}.${process.pid}.tmp`;
+  writeFileSync(temp, content);
+  renameSync(temp, outPath);
+}
+
+// Regenerate in place and then prune, NOT wipe-and-rebuild: a recursive wipe of this tree races
+// concurrent runs (rimraf fails with ENOTEMPTY when a sibling recreates a file mid-walk, and
+// readers briefly see no docs at all). Writing every file first and only then deleting what the
+// manifest no longer produces keeps the "no stale files" guarantee while making concurrent runs
+// idempotent instead of destructive. Depth-first so directories are considered after their
+// contents.
+function prune(dir, expected) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    if (entry.isDirectory()) {
+      prune(full, expected);
+      try {
+        rmdirSync(full);
+      } catch {}
+    } else if (!expected.has(full) && !TEMP_SUFFIX.test(entry.name)) {
+      rmSync(full, { force: true });
+    }
+  }
+}
+
+/**
+ * Frontmatter stamp for the generated SKILL.md: the aigpu package version + the commit + date this
+ * generation ran from, so a stale installed skill is detectable in the frontmatter by a human or
+ * an agent without diffing anything. gitSha/generatedAt are intentionally volatile — they change on
+ * every run by design — so check-drift.js normalizes them away before comparing; a stamp-only
+ * difference between two generations is never reported as drift.
+ */
+export function computeStamp(root) {
+  // NB: the public "aigpu" package (what `npx -y aigpu` runs) lives at packages/aigpu-api — the
+  // "packages/aigpu" directory is the (private) @aigpu/cli package that hosts this generator.
+  let aigpuVersion = "unknown";
+  try {
+    aigpuVersion = JSON.parse(readFileSync(resolve(root, "packages/aigpu-api/package.json"), "utf8")).version;
+  } catch {}
+
+  let gitSha = "unknown";
+  try {
+    gitSha = execSync("git rev-parse HEAD", { cwd: root, stdio: ["ignore", "pipe", "ignore"] })
+      .toString()
+      .trim();
+  } catch {}
+
+  return { aigpuVersion, gitSha, generatedAt: new Date().toISOString() };
+}
+
+export function loadManifest(root) {
+  const allowlistPath = resolve(root, "docs/allowlist.txt");
+  const topicsDir = resolve(root, "docs/topics");
+  // Guide docs (conceptual topics) are auto-discovered from docs/topics — no allowlist entry needed.
+  const guides = existsSync(topicsDir)
+    ? readdirSync(topicsDir)
+        .filter((file) => file.endsWith(".docs.md"))
+        .sort()
+        .map((file) => `docs/topics/${file}`)
+    : [];
+
+  return createManifest(readFileSync(allowlistPath, "utf8"), {
+    exists: (path) => existsSync(resolve(root, path)),
+    read: (path) => readFileSync(resolve(root, path), "utf8"),
+    guides,
+  });
+}
+
+/**
+ * Runs one full generation: manifest + skill mirror (SKILL.md router + references/<doc>), written
+ * to the given output paths. Returns the manifest so callers can log stats.
+ */
+export function generateDocs({ root, skillDir, manifestOut, stamp }) {
+  const manifest = loadManifest(root);
+  writeAtomic(manifestOut, `export const docsManifest = ${serializeManifest(manifest)};`);
+
+  const expected = new Set();
+  for (const [relativePath, content] of buildSkill(manifest, stamp)) {
+    const outPath = resolve(skillDir, relativePath);
+    expected.add(outPath);
+    writeAtomic(outPath, content);
+  }
+  if (existsSync(skillDir)) prune(skillDir, expected);
+
+  return { manifest };
+}

package/dist/cli/lib/docs/generate/manifest.js

@@ -0,0 +1,218 @@
+import { readFileSync } from "node:fs";
+import { MANIFEST_VERSION } from "../model.js";
+
+export function parseAllowlist(text) {
+  return text.split(/\r?\n/u).map((line) => line.trim()).filter(Boolean).map((line) => {
+    const [packageName, symbol, repoPath, ...extra] = line.split(/\s+/u);
+    if (!packageName || !symbol || !repoPath || extra.length > 0) throw new Error(`Invalid allowlist line: ${line}`);
+    return { package: packageName, symbol, repoPath };
+  });
+}
+
+export function virtualPathFor(entry) {
+  return `/${entry.package}/${entry.repoPath.split("/").at(-1)}`;
+}
+
+// Guide docs are conceptual topics (not tied to an exported symbol). They live under the synthetic
+// "guides" package; the symbol is the file slug so `aigpu docs cat <slug>` resolves.
+export function guideEntryFor(repoPath) {
+  const file = repoPath.split("/").at(-1);
+  return { package: "guides", symbol: file.replace(/\.docs\.md$/u, ""), repoPath };
+}
+
+export function guideVirtualPathFor(repoPath) {
+  return `/guides/${repoPath.split("/").at(-1)}`;
+}
+
+/**
+ * Builds the docs manifest from the allowlist (per-symbol API docs) and an optional list of guide
+ * doc paths (conceptual topics under docs/topics). Every record carries a `kind` ("api" | "guide").
+ */
+export function createManifest(allowlistText, options = {}) {
+  const read = options.read ?? ((path) => readFileSync(path, "utf8"));
+  const exists = options.exists ?? (() => true);
+  const load = (repoPath) => {
+    if (!exists(repoPath)) throw new Error(`Missing docs file: ${repoPath}`);
+    return read(repoPath).replace(/\r\n/gu, "\n");
+  };
+
+  const apiRecords = parseAllowlist(allowlistText).map((entry) => enrichRecord({
+    ...entry,
+    kind: "api",
+    virtualPath: virtualPathFor(entry),
+    content: load(entry.repoPath),
+  }));
+
+  const guideRecords = (options.guides ?? []).map((repoPath) => enrichRecord({
+    ...guideEntryFor(repoPath),
+    kind: "guide",
+    virtualPath: guideVirtualPathFor(repoPath),
+    content: load(repoPath),
+  }));
+
+  const records = withUniqueAnchors([...apiRecords, ...guideRecords].sort(compareRecord));
+  return { schemaVersion: MANIFEST_VERSION, generatedFrom: "docs/allowlist.txt + docs/topics", records };
+}
+
+export function serializeManifest(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+function enrichRecord(record) {
+  const { body, frontmatter } = parseFrontmatter(record.content);
+  const topic = topicForRecord(record);
+  const topicTitle = frontmatter.title ?? firstHeading(body) ?? titleFromSlug(topic);
+  const anchor = headingAnchorForSymbol(body, record.symbol) ?? slugifyHeading(record.symbol);
+  const section = sectionForAnchor(body, anchor) ?? body;
+
+  return {
+    ...record,
+    summary: frontmatter.summary ?? firstParagraph(section) ?? firstParagraph(body) ?? "",
+    snippet: firstCodeBlock(section) ?? firstCodeBlock(body) ?? "",
+    anchor,
+    topic,
+    topicTitle,
+    ...(frontmatter.keywords === undefined ? {} : { keywords: parseKeywords(frontmatter.keywords) }),
+    ...(frontmatter.order === undefined ? {} : { order: parseOrder(frontmatter.order, record.repoPath) }),
+    ...(frontmatter.websitePath === undefined ? {} : { websitePath: parseWebsitePath(frontmatter.websitePath, record.repoPath) }),
+    symbolKind: frontmatter.symbolKind ?? inferSymbolKind(record.symbol),
+  };
+}
+
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n?/u);
+  if (!match) return { body: markdown, frontmatter: {} };
+  const frontmatter = {};
+  for (const line of match[1].split("\n")) {
+    const item = line.match(/^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/u);
+    if (!item) continue;
+    const [, key, rawValue] = item;
+    frontmatter[key] = rawValue.trim().replace(/^['"]|['"]$/gu, "");
+  }
+  return { body: markdown.slice(match[0].length), frontmatter };
+}
+
+// Comma-separated search phrases a doc claims for `aigpu docs find`. They exist so a guide can own
+// the words an agent types ("modern bundlers", "wgsl loader", "declare module") even when the body words
+// differ from the query.
+function parseKeywords(value) {
+  return [...new Set(value.split(",").map((keyword) => keyword.trim().toLowerCase()).filter(Boolean))];
+}
+
+function parseOrder(value, repoPath) {
+  if (!/^-?\d+(?:\.\d+)?$/u.test(value)) {
+    throw new Error(`Invalid numeric order in ${repoPath}: ${value}`);
+  }
+  const order = Number(value);
+  if (!Number.isFinite(order)) throw new Error(`Invalid numeric order in ${repoPath}: ${value}`);
+  return order;
+}
+
+function parseWebsitePath(value, repoPath) {
+  if (!/^\/[a-z0-9]+(?:-[a-z0-9]+)*(?:\/[a-z0-9]+(?:-[a-z0-9]+)*)*$/u.test(value)) {
+    throw new Error(`Invalid website path in ${repoPath}: ${value}`);
+  }
+  return value;
+}
+
+function topicForRecord(record) {
+  return topicForRepoPath(record.repoPath);
+}
+
+function topicForRepoPath(repoPath) {
+  const parts = repoPath.split("/");
+  const file = parts.at(-1);
+  if (file === "index.docs.md") return parts.at(-2);
+  return file.replace(/\.docs\.md$/u, "");
+}
+
+function firstHeading(markdown) {
+  return markdown.match(/^#\s+(.+)$/mu)?.[1]?.trim();
+}
+
+function titleFromSlug(slug) {
+  return slug.split(/[-_]/u).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+
+function headingAnchorForSymbol(markdown, symbol) {
+  const symbolSlug = slugifyHeading(symbol);
+  const entry = headingEntries(markdown).find((heading) => heading.text === symbol || slugifyHeading(heading.text) === symbolSlug);
+  return entry?.anchor ?? null;
+}
+
+function sectionForAnchor(markdown, anchor) {
+  const headings = headingEntries(markdown);
+  const current = headings.find((heading) => heading.anchor === anchor);
+  if (!current) return null;
+  const next = headings.find((heading) => heading.index > current.index && heading.level <= current.level);
+  return markdown.slice(current.index, next?.index ?? markdown.length);
+}
+
+function headingEntries(markdown) {
+  const counts = new Map();
+  return [...markdown.matchAll(/^(#{1,6})\s+(.+)$/gmu)].map((match) => {
+    const baseAnchor = slugifyHeading(match[2]);
+    const count = counts.get(baseAnchor) ?? 0;
+    counts.set(baseAnchor, count + 1);
+    return {
+      level: match[1].length,
+      text: match[2].trim(),
+      index: match.index ?? 0,
+      anchor: count === 0 ? baseAnchor : `${baseAnchor}-${count + 1}`,
+    };
+  });
+}
+
+function firstParagraph(markdown) {
+  const withoutHeading = markdown.replace(/^#{1,6}\s+.+$/mu, "");
+  for (const block of withoutHeading.split(/\n{2,}/u)) {
+    const paragraph = block.trim();
+    if (!paragraph) continue;
+    if (/^(#{1,6}\s+|```|\||-|\*|>|<)/u.test(paragraph)) continue;
+    return paragraph.replace(/\s+/gu, " ");
+  }
+  return null;
+}
+
+function firstCodeBlock(markdown) {
+  const match = markdown.match(/```[^\n]*\n([\s\S]*?)```/u);
+  return match?.[1]?.trim() ?? null;
+}
+
+function inferSymbolKind(symbol) {
+  if (/Options$/u.test(symbol)) return "options";
+  if (/^[a-z]/u.test(symbol)) return "function";
+  if (/^(Gpu|Device|Buffer|Texture|Queue|EditableMesh)$/u.test(symbol)) return "class";
+  return "type";
+}
+
+function withUniqueAnchors(records) {
+  const seenByTopic = new Map();
+  return records.map((record) => {
+    const key = `${record.package}\0${record.repoPath}`;
+    const seen = seenByTopic.get(key) ?? new Map();
+    const count = seen.get(record.anchor) ?? 0;
+    seen.set(record.anchor, count + 1);
+    seenByTopic.set(key, seen);
+
+    if (count === 0) return record;
+    return { ...record, anchor: `${record.anchor}-${count + 1}` };
+  });
+}
+
+export function slugifyHeading(value) {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/gu, "")
+    .replace(/\s+/gu, "-")
+    .replace(/-+/gu, "-");
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function compareRecord(a, b) {
+  return `${a.package}\0${a.symbol}\0${a.repoPath}`.localeCompare(`${b.package}\0${b.symbol}\0${b.repoPath}`);
+}

package/dist/cli/lib/docs/generate/skill.js

@@ -0,0 +1,150 @@
+// Renders a Claude-style skill (SKILL.md router + references/<doc>, one file per doc) from the docs
+// manifest. Same source of truth as the `aigpu docs` CLI — this is just a static, loadable mirror.
+// The router stays small on purpose: it lists the guides + an API index and tells the agent to load
+// one doc at a time (via references/ or the CLI), instead of reading everything.
+
+/**
+ * @param {object} manifest
+ * @param {{ aigpuVersion: string, gitSha: string, generatedAt: string }} [stamp] - Frontmatter stamp
+ *   for SKILL.md (aigpu package version + generation commit + date). Optional so callers that only
+ *   care about the reference files (e.g. unit tests) can omit it; the CLI and drift-check always
+ *   pass one.
+ * @returns {Map<string, string>} relative skill path → file content
+ */
+export function buildSkill(manifest, stamp) {
+  const docs = uniqueDocs(manifest.records);
+  const files = new Map();
+  for (const doc of docs) {
+    files.set(`references${doc.virtualPath}`, referenceFile(doc));
+  }
+  files.set("SKILL.md", router(docs, stamp));
+  return files;
+}
+
+// Many allowlist symbols can map to the same .docs.md; collapse to one reference per file and keep
+// the list of symbols it documents.
+function uniqueDocs(records) {
+  const byPath = new Map();
+  for (const record of records) {
+    const existing = byPath.get(record.virtualPath);
+    if (existing) {
+      existing.symbols.push(record.symbol);
+    } else {
+      byPath.set(record.virtualPath, { ...record, symbols: [record.symbol] });
+    }
+  }
+  return [...byPath.values()];
+}
+
+function referenceFile(doc) {
+  const provenance = `> Source: \`${doc.virtualPath}\` — generated by \`aigpu generate:docs\`. Edit the source .docs.md, not this file.\n\n`;
+  return provenance + doc.content.trimEnd() + "\n";
+}
+
+function router(docs, stamp) {
+  const guides = docs.filter((d) => d.kind === "guide");
+  const concepts = guides.filter((d) => d.symbol.startsWith("concepts-")).sort(byOrderThenSymbol);
+  const cliGuides = guides.filter((d) => d.symbol === "cli");
+  const performanceGuides = guides.filter((d) => !d.symbol.startsWith("concepts-") && d.symbol !== "cli").sort(bySymbol);
+  const api = docs.filter((d) => d.kind === "api");
+  const packages = [...new Set(api.map((d) => d.package))].sort();
+  const symbolCount = api.reduce((n, d) => n + d.symbols.length, 0);
+
+  const out = [
+    "---",
+    "name: aigpu",
+    "description: >-",
+    "  Build and optimize WebGPU apps with the aigpu package and entrypoints aigpu/node,",
+    "  aigpu/mock, aigpu/scene, and aigpu/client. Use @aigpu/render/inspect, /utils, /edit,",
+    "  and /perf only as slim tooling subpaths. Bundles performance guides and the API",
+    "  reference; load one doc at a time.",
+    // Stamp: lets a human or agent tell a stale installed skill in one glance. gitSha/generatedAt
+    // are volatile by design (change on every regeneration) — check-drift.js normalizes them away
+    // before diffing, so they never cause a false drift failure on their own.
+    ...(stamp
+      ? [`aigpuVersion: ${stamp.aigpuVersion}`, `gitSha: ${stamp.gitSha}`, `generatedAt: ${stamp.generatedAt}`]
+      : []),
+    "---",
+    "",
+    "# aigpu",
+    "",
+    "Generated from the aigpu `.docs.md` source. Each entry maps to a file in `references/` and to a",
+    "doc you can load on demand with the CLI — **load only what you need, don't read the whole skill**:",
+    "",
+    "aigpu is layered: aigpu/core (thin WebGPU wrappers) → aigpu (main API with WGSL reflection) → aigpu/scene (geometry/camera helpers). Lower layers are always accessible and interoperable.",
+    "",
+    "Glossary: **Surface** means a canvas-backed render target (swapchain) created with `surface(gpu, canvas)`; do not confuse it with the general phrase ‘API surface’.",
+    "",
+    "```sh",
+    "npx -y aigpu docs find <query>    # search doc paths + symbols",
+    "npx -y aigpu docs grep -i <term>  # search doc CONTENT",
+    "npx -y aigpu docs cat <symbol>    # print one doc, e.g. `cat Frame`, `cat performance-model`",
+    "```",
+    "",
+    "## Core concepts",
+    "",
+  ];
+  for (const guide of concepts) {
+    out.push(`- **${guide.topicTitle}** — ${summarize(guide.content)}  \`references${guide.virtualPath}\``);
+  }
+  out.push("");
+  out.push("## CLI reference");
+  out.push("");
+  for (const guide of cliGuides) {
+    out.push(`- **${guide.topicTitle}** — ${guide.summary || summarize(guide.content)}  \`references${guide.virtualPath}\``);
+  }
+  out.push("");
+  out.push("## Performance guides");
+  out.push("");
+  out.push("Writing or optimizing a shader? Read **performance-model** first, then the rest as needed.");
+  out.push("");
+  for (const guide of performanceGuides) {
+    out.push(`- **${guide.topicTitle}** — ${summarize(guide.content)}  \`references${guide.virtualPath}\``);
+  }
+  out.push("");
+  out.push("## API reference");
+  out.push("");
+  out.push(`${symbolCount} symbols across ${packages.length} packages — open \`references/<package>/<file>\` or \`npx -y aigpu docs cat <symbol>\`:`);
+  out.push("");
+  for (const pkg of packages) {
+    const symbols = api
+      .filter((d) => d.package === pkg)
+      .flatMap((d) => d.symbols)
+      .sort((a, b) => a.localeCompare(b));
+    out.push(`- \`${pkg}\` — ${symbols.join(", ")}`);
+  }
+  out.push("");
+  return out.join("\n");
+}
+
+function summarize(content) {
+  // Collect the first prose paragraph (sentences may wrap across source lines), skipping frontmatter,
+  // headings and blockquotes, then take its first sentence.
+  const body = content.replace(/^---\n[\s\S]*?\n---\n?/u, "");
+  let paragraph = "";
+  for (const raw of body.split("\n")) {
+    const line = raw.trim();
+    if (line.startsWith("#") || line.startsWith(">")) continue;
+    if (!line) {
+      if (paragraph) break;
+      continue;
+    }
+    paragraph = paragraph ? `${paragraph} ${line}` : line;
+  }
+  const plain = paragraph
+    .replace(/\[([^\]]+)\]\([^)]*\)/gu, "$1") // [text](url) -> text
+    .replace(/\*\*/gu, "")
+    .replace(/`/gu, "")
+    .replace(/\s+/gu, " ");
+  const sentence = plain.match(/^(.*?\.)(?:\s|$)/u);
+  const text = sentence ? sentence[1] : plain;
+  return text.length > 150 ? `${text.slice(0, 147).trimEnd()}…` : text;
+}
+
+function byOrderThenSymbol(a, b) {
+  return (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY) || bySymbol(a, b);
+}
+
+function bySymbol(a, b) {
+  return a.symbol.localeCompare(b.symbol);
+}

package/dist/cli/lib/docs/help.js

@@ -0,0 +1,21 @@
+export const docsHelp = `Usage: aigpu docs <command> [args] [flags]
+
+Start here: aigpu docs cat getting-started.md   (the guide for using the latest API correctly)
+
+Commands:
+  ls [path]                  List packages or docs under a virtual path
+  cat <path|symbol>          Print docs by virtual path or unique symbol
+  grep [-i] [--package <pkg>] <pattern>
+                             Search docs content; case-sensitive unless -i is used
+  find <query>               Find docs by name, keyword, or phrase (all words must match)
+  path <symbol|path>         Resolve a symbol or virtual path for shell usage
+  symbols                    List indexed symbols
+  help                       Show this help
+
+Examples:
+  aigpu docs cat getting-started.md
+  aigpu docs ls /guides
+  aigpu docs ls
+  aigpu docs cat /@aigpu/core/Buffer.docs.md
+  aigpu docs grep -i --package @aigpu/wgsl minify
+  aigpu docs path Buffer`;

package/dist/cli/lib/docs/index.js

@@ -0,0 +1,62 @@
+import { docsManifest } from "../generated/docs-manifest.generated.js";
+
+export function loadManifest() {
+  return docsManifest;
+}
+
+export function buildIndex(manifest = loadManifest()) {
+  const paths = new Map();
+  const symbols = new Map();
+  const packages = new Set();
+  for (const record of manifest.records) {
+    packages.add(record.package);
+    push(paths, record.virtualPath, record);
+    push(symbols, record.symbol, record);
+  }
+  return { records: manifest.records, packages: [...packages].sort(comparePackage), paths, symbols };
+}
+
+export function resolveSymbol(index, symbol) {
+  const records = index.symbols.get(symbol);
+  if (!records || records.length === 0) return undefined;
+  const unique = uniqueByPath(records);
+  return unique.length === 1 ? unique[0] : unique;
+}
+
+export function resolvePath(index, path) {
+  return uniqueByPath(index.paths.get(normalizePath(path)) ?? []);
+}
+
+export function uniqueByPath(records) {
+  return [...new Map(records.map((record) => [record.virtualPath, record])).values()];
+}
+
+export function normalizePath(path) {
+  if (path === "/") return path;
+  return path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+// The repo's declared "what matters most" curation ladder. Exported so `docs find`'s ranking and
+// `docs ls`'s package ordering share one source of truth instead of drifting apart.
+export function packageRank(name) {
+  if (name === "guides") return 0;
+  if (name === "aigpu") return 1;
+  if (name === "aigpu/scene") return 2;
+  if (name === "aigpu/core") return 3;
+  if (name === "@aigpu/wgsl") return 4;
+  if (name === "@aigpu/wgsl/runtime") return 5;
+  if (name.startsWith("@aigpu/wgsl/loader-")) return 6;
+  if (name.startsWith("@aigpu/wgsl-std/")) return 7;
+  if (name.startsWith("@aigpu/render/")) return 8;
+  return 9;
+}
+
+function comparePackage(left, right) {
+  return packageRank(left) - packageRank(right) || left.localeCompare(right);
+}
+
+function push(map, key, value) {
+  const values = map.get(key) ?? [];
+  values.push(value);
+  map.set(key, values);
+}

package/dist/cli/lib/docs/model.js

@@ -0,0 +1,7 @@
+export const MANIFEST_VERSION = 3;
+
+/** @typedef {"api" | "guide"} DocsKind */
+/** @typedef {"class" | "function" | "type" | "options"} DocsSymbolKind */
+/** @typedef {{ package: string, symbol: string, repoPath: string, virtualPath: string, content: string, kind: DocsKind, summary: string, snippet: string, anchor: string, topic: string, topicTitle: string, symbolKind: DocsSymbolKind, keywords?: string[] }} DocsRecord */
+/** @typedef {{ schemaVersion: 3, generatedFrom: string, records: DocsRecord[] }} DocsManifest */
+/** @typedef {{ records: DocsRecord[], packages: string[], paths: Map<string, DocsRecord[]>, symbols: Map<string, DocsRecord[]> }} DocsIndex */

package/dist/cli/lib/docs/run.js

@@ -0,0 +1,24 @@
+import { catCommand } from "./commands/cat.js";
+import { findCommand } from "./commands/find.js";
+import { grepCommand } from "./commands/grep.js";
+import { lsCommand } from "./commands/ls.js";
+import { pathCommand } from "./commands/path.js";
+import { fail, ok } from "./commands/shared.js";
+import { symbolsCommand } from "./commands/symbols.js";
+import { docsHelp } from "./help.js";
+import { buildIndex } from "./index.js";
+
+export function runDocs(args) {
+  const [command, ...rest] = args;
+  if (!command || command === "help" || command === "--help" || command === "-h") return ok(docsHelp);
+  const index = buildIndex();
+  switch (command) {
+    case "ls": return lsCommand(index, rest);
+    case "cat": return catCommand(index, rest);
+    case "grep": return grepCommand(index, rest);
+    case "find": return findCommand(index, rest);
+    case "path": return pathCommand(index, rest);
+    case "symbols": return symbolsCommand(index, rest);
+    default: return fail(`Unknown docs command: ${command}\n\n${docsHelp}`);
+  }
+}