aigpu 0.3.1

package/dist/cli/bin/aigpu.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runCheck } from "../lib/check/run.js";
+import { runDocs } from "../lib/docs/run.js";
+import { runDoctor } from "../lib/doctor/run.js";
+import { runInstallDawn } from "../lib/install-dawn/run.js";
+import { runInstallSoftwareRenderer } from "../lib/install-software-renderer/run.js";
+import { runSnapshotCommand } from "../lib/snapshot/run.js";
+import { runExamples } from "../lib/examples/run.js";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageJson = JSON.parse(readFileSync(resolve(here, "../package.json"), "utf8"));
+
+// In-repo, `../package.json` is packages/aigpu-cli/package.json (`@aigpu/cli`): private, never published,
+// versioned independently of the public `aigpu` package and known to drift from it (see
+// CONTRIBUTING.md). Reporting that version made every in-repo `aigpu examples ...` call fail the
+// server handshake with AIGPU-EXAMPLES-CLI-TOO-OLD, so resolve the public version from the sibling
+// `aigpu-api` package instead -- same try/catch-degrade pattern as computeStamp() in
+// lib/docs/generate/generate.js.
+//
+// In the published tarball, `../package.json` is the synthetic `{type,version}` stamp written by
+// packages/aigpu-api/scripts/copy-cli.mjs, which has no `name` field, so this branch is dead code
+// there and the published version keeps coming from the stamp (guarded by a unit test).
+export function resolveVersion(dir, pkg) {
+  if (pkg.name === "@aigpu/cli") {
+    try {
+      const apiPackageJson = JSON.parse(readFileSync(resolve(dir, "../../aigpu-api/package.json"), "utf8"));
+      return apiPackageJson.version;
+    } catch {
+      // Incomplete checkout (sparse clone, deleted sibling): degrade to our own version, never crash.
+      return pkg.version;
+    }
+  }
+  return pkg.version;
+}
+
+const VERSION = resolveVersion(here, packageJson);
+
+const help = `aigpu ${VERSION}
+
+TypeScript library for WebGPU: typed shader imports, a tiny gpu-first API, and
+the same code running in the browser, headless Node, and your test suite.
+
+## Read the docs
+  npx aigpu docs cat getting-started.md    The guide for using the current API correctly
+  npx aigpu docs find "<topic | symbol | AIGPU-error-code>"
+  npx aigpu docs cat <path>
+
+## Validate shader code
+  npx aigpu check <file.wgsl>              Validate and reflect a WGSL file as JSON
+  npx aigpu check <file.wgsl> --require-validation
+                                          Fail instead of skipping when no WebGPU device is available
+
+## Working examples
+  npx aigpu examples search "<topic>"
+  npx aigpu examples pull <slug> --out <dir>
+
+## Agent tools (MCP)
+  npx aigpu mcp                           Serve docs and examples over stdio
+
+## Node rendering environment
+  npx aigpu doctor
+`;
+
+const comingSoon = (command) => `aigpu ${command} is coming soon.
+
+This package currently ships docs lookup first. Use aigpu, aigpu/node, aigpu/mock,
+aigpu/scene, and the documented slim tooling subpaths. Run \`aigpu --help\` for details.
+`;
+
+export function runCli(args) {
+  const [command, ...rest] = args;
+  if (command === undefined || command === "--help" || command === "-h") return { code: 0, stdout: help };
+  if (command === "--version" || command === "-v") return { code: 0, stdout: `${VERSION}\n` };
+  if (command === "check") return runCheck(rest);
+  if (command === "docs") return runDocs(rest);
+  if (command === "examples") return runExamples(rest, { version: VERSION });
+  if (command === "mcp") {
+    return import("../lib/mcp/stdio.js").then(({ runMcpStdio }) => runMcpStdio(rest, { version: VERSION }));
+  }
+  if (command === "snapshot") return runSnapshotCommand({ args: rest });
+  if (command === "install-dawn") return runInstallDawn(rest);
+  if (command === "install-software-renderer") return runInstallSoftwareRenderer(rest);
+  if (command === "doctor") return runDoctor(rest);
+  if (command === "wgsl") return { code: 1, stderr: comingSoon(command) };
+  return { code: 2, stderr: `Unknown command: ${command}\n\n${help}` };
+}
+
+if (isMain()) {
+  const result = await Promise.resolve(runCli(process.argv.slice(2)));
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.exitCode = result.code;
+}
+
+function isMain() {
+  if (!process.argv[1]) return false;
+  return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+}

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

@@ -0,0 +1,153 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/**
+ * Runs WGSL reflection/validation for a single entry module and dumps JSON.
+ */
+export async function runCheck(args) {
+  const requireValidation = args.includes("--require-validation");
+  const [entry] = args.filter((arg) => arg !== "--require-validation");
+  if (!entry || entry === "--help" || entry === "-h") {
+    return { code: 1, stderr: "Usage: aigpu check <file.wgsl> [--require-validation]\n" };
+  }
+
+  const absEntry = resolveEntry(entry);
+  try {
+    const { resolveShader } = await loadWgslRuntime();
+    const options = { entry: absEntry, rootDir: dirname(absEntry) };
+    let result;
+    let validationError;
+    try {
+      // Without the flag no `validate` option is passed at all, so the process-wide default
+      // ("auto", or AIGPU_VALIDATE when set) applies untouched.
+      result = await resolveShader({ ...options, ...(requireValidation ? { validate: "require" } : {}) });
+    } catch (error) {
+      if (!isValidationFailure(error)) throw error;
+      // A failing device check must not cost the caller the whole document: re-resolve with
+      // validation off so `check` still prints diagnostics + reflection + wgsl, and report the
+      // failure inside `validation` instead. Keeps the JSON contract identical whether or not the
+      // machine running `check` happens to have a WebGPU device. Exit code stays 1.
+      validationError = error;
+      try {
+        result = await resolveShader({ ...options, validate: "off" });
+      } catch {
+        // The retry failed for some unrelated reason; the validation failure is the useful one.
+        throw error;
+      }
+    }
+    const diagnostics = (result.diagnostics ?? []).map(serializeDiagnostic);
+    const payload = {
+      schemaVersion: 1,
+      entry: absEntry,
+      deps: result.deps,
+      diagnostics,
+      validation: validationError ? failedValidation(requireValidation, validationError) : result.validation,
+      reflection: result.reflection,
+      wgsl: result.wgsl,
+    };
+    const failed = Boolean(validationError) || diagnostics.some((diagnostic) => diagnostic.severity === "error");
+    return { code: failed ? 1 : 0, stdout: `${JSON.stringify(payload, null, 2)}\n` };
+  } catch (error) {
+    return { code: 1, stderr: `${formatError(error)}\n` };
+  }
+}
+
+/**
+ * Failures raised *by validation* — an invalid shader, or (in `"require"` mode) a device that could
+ * not be acquired. Everything else (resolution, reserved paths, an invalid `AIGPU_VALIDATE`) is a
+ * hard error: re-resolving with validation off would hide it rather than describe it.
+ */
+const validationFailureCodes = new Set(["AIGPU-WGSL-NAGA-UNKNOWN", "AIGPU-WGSL-VALIDATE-NO-DEVICE", "AIGPU-WGSL-VALIDATE-ADAPTER-MISSING"]);
+
+function isValidationFailure(error) {
+  return Boolean(error && typeof error === "object" && validationFailureCodes.has(error.code));
+}
+
+function failedValidation(requireValidation, error) {
+  // `--require-validation` always wins over AIGPU_VALIDATE, matching resolveShader's precedence.
+  const mode = requireValidation ? "require" : process.env.AIGPU_VALIDATE || "auto";
+  return { mode, attempted: true, ok: false, error: serializeDiagnostic(error) };
+}
+
+/**
+ * Resolves package-filter invocations back to the workspace root when possible.
+ * Outside a pnpm workspace this intentionally falls back to cwd-relative paths.
+ */
+function resolveEntry(entry) {
+  const fromCwd = resolve(process.cwd(), entry);
+  if (existsSync(fromCwd)) return fromCwd;
+  const workspaceRoot = findWorkspaceRoot(process.cwd());
+  if (!workspaceRoot) return fromCwd;
+  const fromWorkspace = resolve(workspaceRoot, entry);
+  return existsSync(fromWorkspace) ? fromWorkspace : fromCwd;
+}
+
+async function loadWgslRuntime() {
+  try {
+    return await import("@aigpu/wgsl/runtime");
+  } catch (error) {
+    if (isMissingWgslRuntime(error)) {
+      throw new Error("`aigpu check` requires @aigpu/wgsl to be installed. Install it next to @aigpu/cli, for example: pnpm add -D @aigpu/wgsl");
+    }
+    throw error;
+  }
+}
+
+function isMissingWgslRuntime(error) {
+  return Boolean(
+    error &&
+      typeof error === "object" &&
+      error.code === "ERR_MODULE_NOT_FOUND" &&
+      String(error.message ?? "").includes("@aigpu/wgsl"),
+  );
+}
+
+function findWorkspaceRoot(startDir) {
+  for (let dir = startDir;; dir = dirname(dir)) {
+    if (existsSync(resolve(dir, "pnpm-workspace.yaml"))) return dir;
+    if (dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * Diagnostics are `Error` instances, whose `message` is not enumerable and would
+ * otherwise vanish from the JSON payload.
+ */
+function serializeDiagnostic(diagnostic) {
+  if (!diagnostic || typeof diagnostic !== "object") return diagnostic;
+  const payload = {
+    code: diagnostic.code ?? "AIGPU-CHECK-UNKNOWN",
+    message: diagnostic.message ?? String(diagnostic),
+    severity: diagnostic.severity ?? "error",
+    line: diagnostic.line ?? null,
+    column: diagnostic.column ?? null,
+  };
+  if (diagnostic.range) payload.range = diagnostic.range;
+  if (diagnostic.metadata) payload.metadata = diagnostic.metadata;
+  if (diagnostic.relatedDiagnostics) payload.relatedDiagnostics = diagnostic.relatedDiagnostics;
+  if (diagnostic.fix) payload.fix = diagnostic.fix;
+  if (diagnostic.where) payload.where = diagnostic.where;
+  return payload;
+}
+
+function formatError(error) {
+  if (error && typeof error === "object") {
+    const payload = {
+      code: error.code ?? "AIGPU-CHECK-UNKNOWN",
+      message: error.message ?? String(error),
+      severity: error.severity ?? "error",
+      line: error.line ?? null,
+      column: error.column ?? null,
+      metadata: error.metadata,
+      relatedDiagnostics: error.relatedDiagnostics,
+    };
+    if (error.range) payload.range = error.range;
+    if (error.fix) payload.fix = error.fix;
+    if (error.where) payload.where = error.where;
+    if (error.stack && process.env.AIGPU_CHECK_STACK === "1") {
+      payload.stack = error.stack;
+    }
+    return JSON.stringify(payload, null, 2);
+  }
+  return String(error ?? "Unknown error");
+}

package/dist/cli/lib/docs/commands/cat.js

@@ -0,0 +1,12 @@
+import { resolveDocsTarget } from "./resolve.js";
+import { ambiguous, fail, ok } from "./shared.js";
+
+export function catCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs cat <path|symbol>");
+  if (args.length !== 1) return fail("Usage: aigpu docs cat <path|symbol>");
+  const target = args[0];
+  const { resolved, lookup } = resolveDocsTarget(index, target);
+  if (!resolved) return fail(`${lookup === "path" ? "Path" : "Symbol"} not found: ${target}`);
+  if (Array.isArray(resolved)) return ambiguous(target, resolved);
+  return ok(resolved.content.trimEnd());
+}

package/dist/cli/lib/docs/commands/find.js

@@ -0,0 +1,180 @@
+import { packageRank, uniqueByPath } from "../index.js";
+import { fail, ok } from "./shared.js";
+
+// Agents type prose, not identifiers: the dogfood experiment searched "wgsl import", "typescript
+// wgsl", "modern bundlers", "declare module". A single-substring match over symbol+path answered none of
+// them, so find works in three widening steps: every whitespace token must match (1) the route
+// text — symbol, title and the doc's declared keywords, (2) the doc paths, and only when both come
+// back empty (3) the doc body, which is what makes error codes and prose phrases findable.
+//
+// Both tiers share one cap: "gpu" is a substring of "aigpu", so route text matched 134 lines and
+// buried the exact `Gpu` match around line 100. Ranking by match quality is what makes the cap
+// safe — capping alphabetical output would truncate the exact match away entirely.
+const HIT_LIMIT = 20;
+
+export function findCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs find <query>");
+  if (args.length !== 1) return fail("Usage: aigpu docs find <query>");
+  const found = findDocs(index, args[0]);
+  if (found.results.length === 0) return fail(`No docs found for: ${args[0]}`);
+  return ok(withNotice(found.results.map(formatFindResult), found.hiddenCount));
+}
+
+export function findDocs(index, query) {
+  const tokens = query.toLowerCase().split(/\s+/u).filter(Boolean);
+  if (tokens.length === 0) return { results: [], truncated: false, hiddenCount: 0 };
+  const phrase = tokens.join(" ");
+
+  const matchesAll = (haystack) => tokens.every((token) => haystack.includes(token));
+  const symbolHits = index.records
+    .filter((record) => matchesAll(symbolText(record)))
+    .map((record) => ({
+      type: "symbol",
+      record,
+      line: `${record.symbol}\t${record.package}\t${record.virtualPath}`,
+    }));
+  const pathHits = uniqueByPath(index.records)
+    .filter((record) => matchesAll(pathText(record)))
+    .map((record) => ({ type: "path", record, line: pathLine(record) }));
+
+  // Dedupe by line text, first hit wins — the same uniqueness the previous `new Set([...])` gave.
+  const routeHitMap = new Map();
+  for (const hit of [...symbolHits, ...pathHits]) if (!routeHitMap.has(hit.line)) routeHitMap.set(hit.line, hit);
+
+  // INVARIANT (do not move this check): the routing gate is evaluated on the full, UNRANKED,
+  // UNCAPPED, UNFILTERED hit set. Ranking and capping happen only inside this branch and never
+  // remove a hit from consideration, they only reorder it or hide it behind the truncation notice.
+  // If ranking ever filtered hits, a query whose only hits were dropped would silently fall
+  // through to the body-search fallback (#258) — a routing-policy change, not a ranking fix.
+  if (routeHitMap.size > 0) {
+    const hits = [...routeHitMap.values()];
+    const ranked = rankRouteHits(hits, tokens, phrase);
+    const hiddenCount = Math.max(hits.length - HIT_LIMIT, 0);
+    return {
+      results: ranked.slice(0, HIT_LIMIT).map(resultFromHit),
+      truncated: hiddenCount > 0,
+      hiddenCount,
+    };
+  }
+
+  const contentHits = uniqueByPath(index.records)
+    .filter((record) => matchesAll(record.content.toLowerCase()))
+    .map((record) => ({ type: "path", record, line: pathLine(record) }))
+    .sort((left, right) => compareBytes(left.line, right.line));
+  const hiddenCount = Math.max(contentHits.length - HIT_LIMIT, 0);
+  return {
+    results: contentHits.slice(0, HIT_LIMIT).map(resultFromHit),
+    truncated: hiddenCount > 0,
+    hiddenCount,
+  };
+}
+
+function symbolText(record) {
+  return `${record.symbol}\n${record.topicTitle ?? ""}\n${keywordText(record)}`.toLowerCase();
+}
+
+function pathText(record) {
+  return `${record.virtualPath}\n${record.repoPath}\n${keywordText(record)}`.toLowerCase();
+}
+
+function keywordText(record) {
+  return (record.keywords ?? []).join("\n");
+}
+
+function pathLine(record) {
+  return `${record.virtualPath}\t${record.repoPath}`;
+}
+
+function resultFromHit(hit) {
+  if (hit.type === "symbol") {
+    return {
+      kind: "symbol",
+      symbol: hit.record.symbol,
+      package: hit.record.package,
+      virtualPath: hit.record.virtualPath,
+    };
+  }
+  return { kind: "path", virtualPath: hit.record.virtualPath, repoPath: hit.record.repoPath };
+}
+
+function formatFindResult(result) {
+  return result.kind === "symbol"
+    ? `${result.symbol}\t${result.package}\t${result.virtualPath}`
+    : `${result.virtualPath}\t${result.repoPath}`;
+}
+
+// Order (never filter) the route hits so the best match is the line an agent reads first. Ties break
+// on the shared package curation ladder, then page lines before their symbol lines, then a
+// byte-stable line compare — never localeCompare, whose ICU tables make output Node-build dependent.
+function rankRouteHits(hits, tokens, phrase) {
+  return hits
+    .map((hit) => ({ ...hit, tier: tierOf(hit, tokens, phrase) }))
+    .sort((left, right) =>
+      left.tier - right.tier ||
+      packageRank(left.record.package) - packageRank(right.record.package) ||
+      typeOrder(left) - typeOrder(right) ||
+      compareBytes(left.line, right.line));
+}
+
+function typeOrder(hit) {
+  return hit.type === "path" ? 0 : 1;
+}
+
+function compareBytes(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+// Tiers 1-6 from the design: exact symbol, exact page identity, word-boundary in name text,
+// word-boundary in path, substring in name text, substring in path only. Tiers 5/6 need no
+// substring re-check: a symbol hit only exists because it passed matchesAll(symbolText(record)),
+// and a path hit only because it passed matchesAll(pathText(record)).
+function tierOf(hit, tokens, phrase) {
+  if (hit.type === "symbol" && hit.record.symbol.toLowerCase() === phrase) return 1;
+  if (isExactPageIdentity(hit.record, phrase)) return 2;
+  if (everyTokenWordMatches(tokens, nameWords(hit.record))) return 3;
+  if (everyTokenWordMatches(tokens, pathWords(hit.record))) return 4;
+  return hit.type === "symbol" ? 5 : 6;
+}
+
+function isExactPageIdentity(record, phrase) {
+  if ((record.keywords ?? []).some((keyword) => keyword.toLowerCase() === phrase)) return true;
+  if ((record.topicTitle ?? "").toLowerCase() === phrase) return true;
+  if ((record.topic ?? "").toLowerCase() === phrase) return true;
+  return pageBasename(record.virtualPath) === phrase;
+}
+
+function pageBasename(virtualPath) {
+  const segment = (virtualPath ?? "").split("/").pop() ?? "";
+  return segment.replace(/\.docs\.md$/u, "").toLowerCase();
+}
+
+// "whole word or word-prefix" is one startsWith check: a word trivially starts with itself.
+function everyTokenWordMatches(tokens, words) {
+  return tokens.every((token) => words.some((word) => word.startsWith(token)));
+}
+
+function nameWords(record) {
+  return words(`${record.symbol} ${record.topicTitle ?? ""} ${(record.keywords ?? []).join(" ")}`);
+}
+
+function pathWords(record) {
+  return words(`${record.virtualPath} ${record.repoPath}`);
+}
+
+// Split on non-alphanumerics, then on camelCase boundaries, so "WebGPU" yields ["web", "gpu"] and
+// "createNodeAdapter" yields ["create", "node", "adapter"].
+function words(text) {
+  return (text ?? "")
+    .split(/[^a-zA-Z0-9]+/u)
+    .filter(Boolean)
+    .flatMap((chunk) => chunk.match(/[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+|[0-9]+/gu) ?? [chunk])
+    .map((word) => word.toLowerCase());
+}
+
+// Truncation is never silent: an agent must be able to tell 20-of-20 from 20-of-200. Stdout, exit 0,
+// and deliberately free of tabs so the notice can never be parsed as one of the result lines.
+function withNotice(lines, hiddenCount) {
+  if (hiddenCount <= 0) return lines;
+  const plural = hiddenCount === 1 ? "" : "es";
+  return [...lines, `... and ${hiddenCount} more match${plural}; showing the ${HIT_LIMIT} best. Add another word to narrow.`];
+}

package/dist/cli/lib/docs/commands/grep.js

@@ -0,0 +1,49 @@
+import { uniqueByPath } from "../index.js";
+import { fail, ok } from "./shared.js";
+
+export function grepCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs grep [-i] [--package <pkg>] <pattern>");
+  const parsed = parseArgs(args);
+  if (typeof parsed === "string") return fail(parsed);
+  const matches = grepDocs(index, parsed);
+  return matches.length > 0 ? ok(matches.map(formatGrepMatch)) : fail(`No matches for: ${parsed.pattern}`);
+}
+
+export function grepDocs(index, { pattern, ignoreCase = false, packageName }) {
+  const needle = ignoreCase ? pattern.toLowerCase() : pattern;
+  const matches = [];
+  for (const record of uniqueByPath(index.records)) {
+    if (packageName && !matchesPackage(record.package, packageName)) continue;
+    record.content.split("\n").forEach((line, lineIndex) => {
+      const haystack = ignoreCase ? line.toLowerCase() : line;
+      if (haystack.includes(needle)) matches.push({ virtualPath: record.virtualPath, line: lineIndex + 1, text: line });
+    });
+  }
+  return matches.sort((left, right) => compareBytes(formatGrepMatch(left), formatGrepMatch(right)));
+}
+
+function formatGrepMatch(match) {
+  return `${match.virtualPath}:${match.line}:${match.text}`;
+}
+
+function compareBytes(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function parseArgs(args) {
+  let ignoreCase = false;
+  let packageName;
+  const rest = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "-i") ignoreCase = true;
+    else if (args[index] === "--package") packageName = args[++index];
+    else rest.push(args[index]);
+  }
+  if (args.includes("--package") && !packageName) return "Missing value for --package";
+  if (rest.length !== 1) return "Usage: aigpu docs grep [-i] [--package <pkg>] <pattern>";
+  return { ignoreCase, packageName, pattern: rest[0] };
+}
+
+function matchesPackage(recordPackage, filter) {
+  return recordPackage === filter || recordPackage.startsWith(`${filter}/`);
+}

package/dist/cli/lib/docs/commands/ls.js

@@ -0,0 +1,41 @@
+import { normalizePath } from "../index.js";
+import { fail, ok } from "./shared.js";
+
+const ROOT_TIP = "Tip: start with \"aigpu docs cat getting-started.md\"; /guides holds concept guides; @aigpu/render/* is low-level tooling.";
+
+export function lsCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs ls [path]");
+  if (args.length > 1) return fail("Usage: aigpu docs ls [path]");
+  const path = normalizePath(args[0] ?? "/");
+  const entries = listDocs(index, path);
+  if (!entries) return fail(`Path not found: ${path}`);
+  return ok(path === "/" ? [...entries, ROOT_TIP] : entries);
+}
+
+export function listDocs(index, path = "/") {
+  path = normalizePath(path);
+  if (path === "/") return index.packages.map((pkg) => `/${pkg}`);
+  if (path === "/guides") {
+    const guides = index.records.filter((record) => record.kind === "guide").sort(compareGuide);
+    return guides.map((record) => record.virtualPath.slice(path.length + 1));
+  }
+
+  const children = new Set();
+  for (const record of index.records) {
+    if (record.virtualPath === path) return [record.virtualPath];
+    if (!record.virtualPath.startsWith(`${path}/`)) continue;
+    const rest = record.virtualPath.slice(path.length + 1);
+    children.add(rest.includes("/") ? rest.slice(0, rest.indexOf("/")) : rest);
+  }
+  return children.size > 0 ? [...children].sort() : undefined;
+}
+
+function compareGuide(left, right) {
+  if (left.symbol === "getting-started") return -1;
+  if (right.symbol === "getting-started") return 1;
+  const leftOrdered = typeof left.order === "number";
+  const rightOrdered = typeof right.order === "number";
+  if (leftOrdered && rightOrdered) return left.order - right.order || left.virtualPath.localeCompare(right.virtualPath);
+  if (leftOrdered !== rightOrdered) return leftOrdered ? -1 : 1;
+  return left.virtualPath.localeCompare(right.virtualPath);
+}

package/dist/cli/lib/docs/commands/path.js

@@ -0,0 +1,12 @@
+import { resolveDocsTarget } from "./resolve.js";
+import { ambiguous, fail, ok } from "./shared.js";
+
+export function pathCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs path <symbol|path>");
+  if (args.length !== 1) return fail("Usage: aigpu docs path <symbol|path>");
+  const target = args[0];
+  const { resolved, lookup } = resolveDocsTarget(index, target);
+  if (!resolved) return fail(`${lookup === "path" ? "Path" : "Symbol"} not found: ${target}`);
+  if (Array.isArray(resolved)) return ambiguous(target, resolved);
+  return ok(resolved.virtualPath);
+}

package/dist/cli/lib/docs/commands/resolve.js

@@ -0,0 +1,41 @@
+import { resolvePath, resolveSymbol } from "../index.js";
+
+export function resolveDocsTarget(index, target) {
+  for (const path of candidatePaths(target)) {
+    const record = resolvePath(index, path)[0];
+    if (record) return { resolved: record };
+  }
+
+  for (const symbol of candidateSymbols(target)) {
+    const resolved = resolveSymbol(index, symbol);
+    if (resolved) return { resolved };
+  }
+
+  return { resolved: undefined, lookup: target.startsWith("/") || target.startsWith("guides/") ? "path" : "symbol" };
+}
+
+function candidatePaths(target) {
+  const paths = [];
+  if (target.startsWith("/")) paths.push(target);
+  if (target.startsWith("guides/")) paths.push(`/${target}`);
+
+  for (const path of [...paths]) {
+    if (path.startsWith("/guides/") && path.endsWith(".md") && !path.endsWith(".docs.md")) {
+      paths.push(path.replace(/\.md$/u, ".docs.md"));
+    }
+  }
+
+  return unique(paths);
+}
+
+function candidateSymbols(target) {
+  const symbols = [target];
+  const file = target.split("/").at(-1) ?? target;
+  if (file.endsWith(".docs.md")) symbols.push(file.slice(0, -".docs.md".length));
+  if (file.endsWith(".md")) symbols.push(file.slice(0, -".md".length));
+  return unique(symbols);
+}
+
+function unique(values) {
+  return [...new Set(values)];
+}

package/dist/cli/lib/docs/commands/shared.js

@@ -0,0 +1,13 @@
+export function ok(lines = "") {
+  const stdout = Array.isArray(lines) ? lines.join("\n") : lines;
+  return { code: 0, stdout: stdout.length > 0 ? `${stdout}\n` : "" };
+}
+
+export function fail(message) {
+  return { code: 1, stderr: `${message}\n` };
+}
+
+export function ambiguous(symbol, records) {
+  const candidates = records.map((record) => `${record.symbol}\t${record.package}\t${record.virtualPath}`);
+  return fail(`Ambiguous symbol: ${symbol}\nCandidates:\n${candidates.join("\n")}`);
+}

package/dist/cli/lib/docs/commands/symbols.js

@@ -0,0 +1,25 @@
+import { ok } from "./shared.js";
+
+export function symbolsCommand(index, args) {
+  if (args.includes("--help") || args.includes("-h")) return ok("Usage: aigpu docs symbols");
+  if (args.length !== 0) return { code: 1, stderr: "Usage: aigpu docs symbols\n" };
+  return ok(listDocSymbols(index).map(formatSymbol));
+}
+
+export function listDocSymbols(index) {
+  const symbols = new Map();
+  for (const record of index.records) {
+    const symbol = { symbol: record.symbol, package: record.package, virtualPath: record.virtualPath };
+    const line = formatSymbol(symbol);
+    if (!symbols.has(line)) symbols.set(line, symbol);
+  }
+  return [...symbols.values()].sort((left, right) => compareBytes(formatSymbol(left), formatSymbol(right)));
+}
+
+function formatSymbol(symbol) {
+  return `${symbol.symbol}\t${symbol.package}\t${symbol.virtualPath}`;
+}
+
+function compareBytes(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

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

@@ -0,0 +1,8 @@
+export class DocsError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "DocsError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+}