@shoalrun/cli 0.1.0-beta.1 → 1.1.0

package/adapters/typescript/shoalrun-reference.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/** Static public-entry-point extraction. Never imports or emits documented code. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { validateCodeReference } from '../../dist/code-reference-model.js';
+
+const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+const order = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+export function convertTypeScript({ project, entry, moduleName, root, typescript, onInputs }) {
+  project = fs.realpathSync(project);
+  root = fs.realpathSync(root ?? path.dirname(project));
+  entry = fs.realpathSync(path.resolve(path.dirname(project), entry));
+  if (!inside(root, entry)) throw new Error('Entry must stay inside the declared source root');
+  if (!moduleName || /\s|[\x00-\x1f]/.test(moduleName)) throw new Error('Provide a nonempty module ID without whitespace');
+  const ts = typescript ?? createRequire(project)('typescript');
+  if (!/^5\.9\./.test(ts.version)) throw new Error('This adapter supports TypeScript 5.9.x; install typescript@5.9.3 in the project');
+  const diagnostics = messages => messages.map(message => ts.flattenDiagnosticMessageText(message.messageText, '\n')).join('\n');
+  const configInputs = new Set([project]);
+  const readConfig = file => { if (fs.existsSync(file)) configInputs.add(fs.realpathSync(file)); return ts.sys.readFile(file); };
+  const config = ts.readConfigFile(project, readConfig);
+  if (config.error) throw new Error(diagnostics([config.error]));
+  const parsed = ts.parseJsonConfigFileContent(config.config, { ...ts.sys, readFile: readConfig }, path.dirname(project));
+  // A reference entry need not be included in the project's ordinary build files.
+  const configErrors = parsed.errors.filter(error => error.code !== 18003);
+  if (configErrors.length) throw new Error(diagnostics(configErrors));
+  const program = ts.createProgram({ rootNames: [entry], options: { ...parsed.options, noEmit: true, incremental: false, composite: false } });
+  const files = program.getSourceFiles().map(file => ({ file, path: fs.realpathSync(file.fileName) })).sort((a, b) => order(a.path, b.path));
+  if (files.length > 10000) throw new Error('Source graph exceeds 10,000 files');
+  if (files.reduce((bytes, { file }) => bytes + Buffer.byteLength(file.text), 0) > 32 * 1024 * 1024) throw new Error('Source graph exceeds 32 MiB');
+  onInputs?.([...configInputs, ...files.map(item => item.path)]);
+  const errors = ts.getPreEmitDiagnostics(program).filter(message => message.category === ts.DiagnosticCategory.Error);
+  if (errors.length) throw new Error(diagnostics(errors));
+  const checker = program.getTypeChecker();
+  const source = program.getSourceFile(entry);
+  const entrySymbol = source && checker.getSymbolAtLocation(source);
+  if (!entrySymbol) throw new Error('The entry must be an external TypeScript module with public exports');
+  const canonical = symbol => symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+  const exports = checker.getExportsOfModule(entrySymbol).sort((a, b) => order(a.name, b.name));
+  const ids = new Map();
+  const publicId = symbol => symbol && ids.get(canonical(symbol))?.[0];
+  const format = ts.TypeFormatFlags.NoTruncation | ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope;
+  const text = parts => ts.displayPartsToString(parts ?? []);
+  const description = symbol => text(symbol.getDocumentationComment(checker));
+  const tags = symbol => symbol.getJsDocTags(checker);
+  const declaration = symbol => symbol.valueDeclaration ?? symbol.declarations?.[0];
+  const location = node => {
+    const file = fs.realpathSync(node.getSourceFile().fileName);
+    if (!inside(root, file)) throw new Error('An exported declaration escapes the source root; choose a local public entry');
+    return { path: path.relative(root, file).split(path.sep).join('/'), line: node.getSourceFile().getLineAndCharacterOfPosition(node.getStart()).line + 1 };
+  };
+  const excludedNode = node => !!node && ((node.name && ts.isPrivateIdentifier(node.name)) || ts.isPrivateIdentifier(node) || ts.getJSDocTags(node).some(tag => ['internal', 'private'].includes(tag.tagName.text)) || !!(ts.getCombinedModifierFlags(node) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected)));
+  const visible = symbol => !tags(symbol).some(tag => tag.name === 'internal' || tag.name === 'private') &&
+    !symbol.declarations?.some(node => (node.name && ts.isPrivateIdentifier(node.name)) || ts.getCombinedModifierFlags(node) & (ts.ModifierFlags.Private | ts.ModifierFlags.Protected));
+  for (const exported of exports) {
+    const target = canonical(exported);
+    if (!visible(exported) || !visible(target)) continue;
+    const list = ids.get(target) ?? [];
+    list.push(`${moduleName}.${exported.name}`); ids.set(target, list);
+  }
+  // The snapshot cannot express a partially hidden structural type faithfully.
+  // Fail instead of printing excluded members inside a parent signature.
+  const assertPublicStructure = node => {
+    if (ts.isBlock(node)) return;
+    if (ts.isTypeElement(node)) {
+      const symbol = node.name && checker.getSymbolAtLocation(node.name);
+      if ((symbol && !visible(symbol)) || ts.getJSDocTags(node).some(tag => ['internal', 'private'].includes(tag.tagName.text))) {
+        if (node.parent && ts.isTypeLiteralNode(node.parent)) throw new Error('A structural type contains an @internal or @private member; expose a separate public type');
+        return; // Direct interface/class members are omitted individually.
+      }
+    }
+    ts.forEachChild(node, assertPublicStructure);
+  };
+  const assertPrintable = node => {
+    if (excludedNode(node)) throw new Error('A printed declaration or initializer contains an @internal, @private, private or protected member; expose a separate public value');
+    ts.forEachChild(node, assertPrintable);
+  };
+  const snippet = (node, kind = ts.EmitHint.Unspecified) => {
+    assertPrintable(node);
+    return ts.createPrinter({ removeComments: true }).printNode(kind, node, node.getSourceFile()).trim();
+  };
+  const typeText = (type, node) => {
+    const value = checker.typeToString(type, node, format);
+    const inspect = (current, seen = new Set()) => {
+      if (!current || seen.has(current)) return; seen.add(current);
+      if (current.isUnionOrIntersection()) { for (const part of current.types) inspect(part, seen); return; }
+      if (current.flags & ts.TypeFlags.Substitution) { inspect(current.baseType, seen); inspect(current.constraint, seen); return; }
+      if (current.flags & ts.TypeFlags.Conditional) throw new Error('A conditional type expansion cannot be verified for excluded members; expose a named public type');
+      if (!(current.flags & ts.TypeFlags.Object)) return;
+      for (const argument of current.aliasTypeArguments ?? []) inspect(argument, seen);
+      if (current.objectFlags & ts.ObjectFlags.Reference) for (const argument of checker.getTypeArguments(current)) inspect(argument, seen);
+      // A separately emitted public type is already validated at its own declaration.
+      if (publicId(current.aliasSymbol ?? current.symbol)) return;
+      for (const signature of [...current.getCallSignatures(), ...current.getConstructSignatures()]) {
+        inspect(checker.getReturnTypeOfSignature(signature), seen);
+        for (const parameter of signature.getParameters()) {
+          const decl = declaration(parameter);
+          if (decl) inspect(checker.getTypeOfSymbolAtLocation(parameter, decl), seen);
+        }
+      }
+      // Named references print their name; anonymous structures print their members.
+      if (current.aliasSymbol || current.symbol && !['__type', '__object'].includes(current.symbol.name)) return;
+      for (const property of checker.getPropertiesOfType(current)) {
+        if (!visible(property)) throw new Error('An inferred structural type contains an @internal or @private member; expose a separate public type');
+        const decl = declaration(property);
+        if (decl) inspect(checker.getTypeOfSymbolAtLocation(property, decl), seen);
+      }
+    };
+    inspect(type);
+    if (/import\(["'](?:\/|[A-Za-z]:[\\/])/.test(value)) throw new Error('An inferred public type contains a machine-local import path; declare an exported type explicitly');
+    return value;
+  };
+  const references = new Map();
+  const collectReferences = (node, output) => {
+    if (!node) return;
+    if (ts.isIdentifier(node)) {
+      const symbol = checker.getSymbolAtLocation(node);
+      const target = symbol && publicId(symbol);
+      if (target) output.set(node.text, target);
+    }
+    // Only declarations/types, never walk a function body or initializer.
+    ts.forEachChild(node, child => { if (!ts.isBlock(child) && child !== node.initializer) collectReferences(child, output); });
+  };
+  const symbols = [{ id: moduleName, name: moduleName, kind: 'module', visibility: 'public', source: location(source) }];
+  const append = (symbol, id, name, parent, member = false) => {
+    if (!visible(symbol)) return;
+    const node = declaration(symbol);
+    if (!node) throw new Error(`No declaration for exported symbol ${name}`);
+    const decls = symbol.declarations ?? [node];
+    for (const decl of decls) { location(decl); assertPublicStructure(decl); }
+    const ref = new Map(); references.set(id, ref);
+    const doc = description(symbol);
+    const base = { id, name, parent, visibility: 'public', source: location(node), ...(doc ? { summary: doc.split(/\n\s*\n/)[0].replace(/\s+/g, ' ').slice(0, 1000), description: doc } : {}) };
+    const type = checker.getTypeOfSymbolAtLocation(symbol, node);
+    const declared = checker.getDeclaredTypeOfSymbol(symbol);
+    let signatures = [];
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node) || ts.isMethodSignature(node) || ts.isFunctionTypeNode(node) || type.getCallSignatures().length && !ts.isTypeAliasDeclaration(node)) {
+      base.kind = member ? 'method' : 'function';
+      signatures = checker.getNonNullableType(type).getCallSignatures();
+      base.signatures = signatures.map(signature => `${name}${symbol.flags & ts.SymbolFlags.Optional ? '?' : ''}${checker.signatureToString(signature, node, format, ts.SignatureKind.Call)}`);
+      const parameterDocs = new Map(tags(symbol).filter(tag => tag.name === 'param').flatMap(tag => { const match = /^(\S+)\s+([\s\S]*)$/.exec(text(tag.text)); return match ? [[match[1], match[2]]] : []; }));
+      const primary = signatures.at(-1);
+      if (primary) {
+        base.parameters = primary.getParameters().map(parameter => {
+          const decl = declaration(parameter);
+          const parameterName = decl?.name && (ts.isObjectBindingPattern(decl.name) || ts.isArrayBindingPattern(decl.name)) ? snippet(decl.name) : parameter.name;
+          const initializer = decl?.initializer;
+          const parameterDescription = description(parameter) || parameterDocs.get(parameter.name);
+          collectReferences(decl?.type, ref);
+          return { name: parameterName, type: typeText(checker.getTypeOfSymbolAtLocation(parameter, decl ?? node), decl ?? node),
+            ...(parameterDescription ? { description: parameterDescription } : {}), ...(initializer ? { default: snippet(initializer) } : {}) };
+        });
+        base.returns = { type: typeText(checker.getReturnTypeOfSignature(primary), node) };
+        const returns = tags(symbol).find(tag => ['returns', 'return'].includes(tag.name));
+        if (returns) base.returns.description = text(returns.text);
+      }
+      for (const signature of signatures) {
+        typeText(checker.getReturnTypeOfSignature(signature), node);
+        for (const parameter of signature.getParameters()) typeText(checker.getTypeOfSymbolAtLocation(parameter, declaration(parameter) ?? node), declaration(parameter) ?? node);
+        const decl = signature.getDeclaration();
+        if (decl) collectReferences(decl.type, ref);
+        for (const parameter of decl?.parameters ?? []) collectReferences(parameter.type, ref);
+      }
+    } else if (ts.isClassDeclaration(node) || ts.isInterfaceDeclaration(node)) {
+      base.kind = ts.isClassDeclaration(node) ? 'class' : 'interface';
+      const generics = node.typeParameters?.map(parameter => snippet(parameter)).join(', ');
+      const heritageClauses = decls.flatMap(owner => owner.heritageClauses ?? []);
+      const heritage = [[ts.SyntaxKind.ExtendsKeyword, 'extends'], [ts.SyntaxKind.ImplementsKeyword, 'implements']].map(([token, label]) => { const types = [...new Set(heritageClauses.filter(clause => clause.token === token).flatMap(clause => clause.types.map(type => snippet(type))))]; return types.length ? label + ' ' + types.join(', ') : ''; }).filter(Boolean).join(' ');
+      base.signatures = [`${base.kind} ${name}${generics ? `<${generics}>` : ''}${heritage ? ` ${heritage}` : ''}`];
+      base.bases = heritageClauses.length ? heritageClauses.flatMap(clause => clause.types.map(type => snippet(type))) : undefined;
+      for (const clause of heritageClauses) collectReferences(clause, ref);
+      for (const parameter of node.typeParameters ?? []) collectReferences(parameter, ref);
+      for (const owner of decls.filter(item => ts.isClassDeclaration(item) || ts.isInterfaceDeclaration(item))) for (const member of owner.members) if (!excludedNode(member) && (ts.isCallSignatureDeclaration(member) || ts.isConstructSignatureDeclaration(member) || ts.isIndexSignatureDeclaration(member))) { base.signatures.push(snippet(member)); collectReferences(member, ref); }
+      if (base.kind === 'class') {
+        const constructors = type.getConstructSignatures().filter(ctor => !excludedNode(ctor.getDeclaration() ?? node));
+        if (constructors.length) {
+          base.constructorSignature = constructors.map(ctor => `new ${name}${checker.signatureToString(ctor, node, format, ts.SignatureKind.Call)}`).join('\n');
+          for (const ctor of constructors) {
+            for (const parameter of ctor.getParameters()) {
+              const decl = declaration(parameter);
+              typeText(checker.getTypeOfSymbolAtLocation(parameter, decl ?? node), decl ?? node);
+              if (decl?.initializer) assertPrintable(decl.initializer);
+            }
+            for (const parameter of ctor.getDeclaration()?.parameters ?? []) collectReferences(parameter.type, ref);
+          }
+        }
+      }
+    } else if (ts.isTypeAliasDeclaration(node)) {
+      base.kind = 'type';
+      const generics = node.typeParameters?.map(parameter => snippet(parameter)).join(', ');
+      assertPublicStructure(node.type);
+      const publicType = node.type;
+      base.signatures = [`type ${name}${generics ? `<${generics}>` : ''} = ${snippet(publicType)};`];
+      collectReferences(publicType, ref);
+    } else if (ts.isEnumDeclaration(node)) {
+      base.kind = 'enum'; base.signatures = [`enum ${name}`];
+    } else if (ts.isVariableDeclaration(node) || ts.isPropertyDeclaration(node) || ts.isPropertySignature(node) || ts.isParameter(node) || ts.isGetAccessorDeclaration(node) || ts.isEnumMember(node)) {
+      base.kind = member ? 'property' : 'constant';
+      base.annotation = typeText(type, node);
+      const readonly = ts.getCombinedModifierFlags(node) & ts.ModifierFlags.Readonly || ts.isGetAccessorDeclaration(node) && !symbol.declarations?.some(ts.isSetAccessorDeclaration);
+      base.signatures = [`${readonly ? 'readonly ' : ''}${name}${symbol.flags & ts.SymbolFlags.Optional ? '?' : ''}: ${base.annotation}`];
+      if (ts.isEnumMember(node)) base.kind = 'constant';
+      if (member && !ts.isEnumMember(node)) base.required = !(symbol.flags & ts.SymbolFlags.Optional);
+      if (node.initializer) base.default = snippet(node.initializer);
+      collectReferences(node.type, ref);
+    } else throw new Error(`Unsupported exported declaration ${name}: ${ts.SyntaxKind[node.kind]}`);
+    const examples = tags(symbol).filter(tag => tag.name === 'example').map(tag => ({ code: text(tag.text).replace(/^```(?:ts|typescript|js|javascript)?\s*\n([\s\S]*?)\n```\s*$/, '$1') }));
+    if (examples.length) base.examples = examples;
+    symbols.push(base);
+    const owns = decl => decls.some(owner => { for (let current = decl; current; current = current.parent) if (current === owner) return true; return false; });
+    if (['class', 'interface', 'type'].includes(base.kind) && !(declared.flags & ts.TypeFlags.Union)) {
+      for (const property of checker.getPropertiesOfType(declared).sort((a, b) => order(a.name, b.name))) {
+        if (property.declarations?.some(owns)) { const memberNode = declaration(property); const name = ts.isComputedPropertyName(memberNode.name) ? snippet(memberNode.name) : property.name; append(property, `${id}.${encodeURIComponent(name)}`, name, id, true); }
+      }
+    }
+    if (base.kind === 'class') for (const property of checker.getPropertiesOfType(type).sort((a, b) => order(a.name, b.name))) {
+      if (property.declarations?.some(owns)) { const memberNode = declaration(property); const name = ts.isComputedPropertyName(memberNode.name) ? snippet(memberNode.name) : property.name; const before = symbols.length; append(property, `${id}.static.${encodeURIComponent(name)}`, name, id, true); const added = symbols[before]; if (added?.signatures) added.signatures = added.signatures.map(signature => `static ${signature}`); }
+    }
+    if (base.kind === 'enum') for (const property of checker.getExportsOfModule(symbol)) if (ts.isEnumMember(declaration(property))) append(property, `${id}.${property.name}`, property.name, id, true);
+  };
+  for (const exported of exports) if (visible(exported)) append(canonical(exported), `${moduleName}.${exported.name}`, exported.name, moduleName);
+  const known = new Set(symbols.map(symbol => symbol.id));
+  for (const symbol of symbols) {
+    const mapped = Object.fromEntries([...(references.get(symbol.id) ?? [])].filter(([, target]) => known.has(target)));
+    if (Object.keys(mapped).length) symbol.typeReferences = mapped;
+  }
+  const normalize = value => Array.isArray(value) ? value.map(normalize) : value && typeof value === 'object' ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => order(a, b)).map(([key, item]) => [key, normalize(item)])) : typeof value === 'string' && path.isAbsolute(value) ? (inside(root, value) ? '$ROOT/' + path.relative(root, value).split(path.sep).join('/') : '$EXTERNAL/' + path.basename(value)) : value;
+  const digest = createHash('sha256').update(`typescript:${ts.version}\nentry:${path.relative(root, entry)}\nmodule:${moduleName}\noptions:${JSON.stringify(normalize(program.getCompilerOptions()))}\n`);
+  const evidence = files.map(({ file, path: filePath }) => [inside(root, filePath) ? path.relative(root, filePath).split(path.sep).join('/') : '$EXTERNAL/' + path.basename(filePath), file.text]).sort((a, b) => order(JSON.stringify(a), JSON.stringify(b)));
+  for (const file of evidence) digest.update(JSON.stringify(file));
+  return validateCodeReference({ schemaVersion: 1, kind: 'shoalrun-code-reference', programmingLanguage: 'typescript', producer: { name: 'shoalrun-typescript', version: '1.0.0', extractorVersion: ts.version }, sourceDigest: digest.digest('hex'), symbols });
+}
+
+/** Never overwrite a compiler input, including through an output symlink or parent. */
+export function writeTypeScriptSnapshot(output, snapshot, inputs) {
+  const resolved = fs.existsSync(output) ? fs.realpathSync(output) : path.join(fs.realpathSync(path.dirname(output)), path.basename(output));
+  if (inputs.some(file => fs.realpathSync(file) === resolved)) throw new Error('Snapshot output cannot overwrite a compiler input');
+  const temporary = path.join(path.dirname(output), `.shoalrun-reference-${randomUUID()}.json`);
+  try { fs.writeFileSync(temporary, JSON.stringify(snapshot, null, 2) + '\n', { encoding: 'utf8', flag: 'wx' }); fs.renameSync(temporary, output); }
+  finally { fs.rmSync(temporary, { force: true }); }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const args = {}; const allowed = ['--project', '--entry', '--module', '--root', '--out'];
+    for (let i = 2; i < process.argv.length; i += 2) {
+      const key = process.argv[i], value = process.argv[i + 1];
+      if (!allowed.includes(key) || args[key] || !value || value.startsWith('--')) throw new Error('Usage: node shoalrun-reference.mjs --project tsconfig.json --entry src/index.ts --module sdk --out reference.json [--root DIRECTORY]');
+      args[key] = value;
+    }
+    for (const key of ['--project', '--entry', '--module', '--out']) if (!args[key]) throw new Error(`Missing ${key}`);
+    let inputs;
+    const snapshot = convertTypeScript({ onInputs: value => { inputs = value; }, project: path.resolve(args['--project']), entry: args['--entry'], moduleName: args['--module'], root: args['--root'] && path.resolve(args['--root']) });
+    writeTypeScriptSnapshot(path.resolve(args['--out']), snapshot, inputs);
+    console.log(JSON.stringify({ status: 'ok', symbols: snapshot.symbols.length, programmingLanguage: snapshot.programmingLanguage }));
+  } catch (error) { console.error(error.code === 'MODULE_NOT_FOUND' ? 'Install typescript@5.9.3 in the project before running this optional adapter.' : error.message); process.exitCode = 1; }
+}

package/agent-docs/.well-known/shoalrun/navigation/project-updates-50f26fe22670.txt

@@ -28,13 +28,17 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Styled PDFs and custom code languages](https://www.shoalrun.com/changelog/pdf-custom-languages.md) — ID: change.pdf-custom-languages. changelog-entry; 487 tokens. Print branded pages, export a complete PDF manual, and highlight your own code language.
 
+- [Shoalrun 1.0 — SDK references and smoother font loading](https://www.shoalrun.com/changelog/code-api-references.md) — ID: change.code-api-references. changelog-entry; 538 tokens. Generate code API references from source and docstrings, choose how readers browse them, and load custom fonts earlier.
+
+- [Build selection and TypeScript references](https://www.shoalrun.com/changelog/facet-typescript.md) — ID: change.facet-typescript. changelog-entry; 694 tokens. Select additional sections for each build, generate TypeScript SDK references, and improve search queries written as questions.
+
 - [Authoring snapshot previews and review reports](https://www.shoalrun.com/changelog/authoring-preview.md) — ID: change.authoring-preview. changelog-entry; 554 tokens. Snapshot previews with coverage and freshness reports.
 
 - [Agent authoring, search, and documentation answers](https://www.shoalrun.com/changelog/authoring-search.md) — ID: change.authoring-search. changelog-entry; 468 tokens. Reviewed agent drafts, search improvements, and answer context.
 
 - [Working-tree authoring tools](https://www.shoalrun.com/changelog/authoring-tools.md) — ID: change.authoring-tools. changelog-entry; 384 tokens. Project discovery and captured working-tree validation.
 
-- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1472 tokens. Compiler, CLI, and reader changes.
+- [Changelog](https://www.shoalrun.com/changelog.md) — ID: reference.changelog. reference; 1610 tokens. Compiler, CLI, and reader changes.
 
 - [MCP hosting, analytics, and component improvements](https://www.shoalrun.com/changelog/2026-10-17-mcp-hosting.md) — ID: change.mcp-hosting. changelog-entry; 1147 tokens. MCP hosting, analytics, and shared component content.
 
@@ -48,4 +52,4 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [Non-goals](https://www.shoalrun.com/non-goals.md) — ID: guide.non-goals. explanation; 821 tokens. Scope limits for skill generation, agent orchestration, and reader-view authorization.
 
-- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1918 tokens. Current capabilities, planned features, and known limits.
+- [Project status](https://www.shoalrun.com/status.md) — ID: guide.status. reference; 1990 tokens. Current capabilities, planned features, and known limits.

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "01614c57a52c0157fb48fc12f434962f27f704e7",
-  "siteBuildId": "30b28d69af454479a90a00f3b015448f97af9be0c46d153441408b899ccaf08f",
-  "manifestDigest": "7337bcec6d88bb4934afff2eb68562244f9391af3d651ead5111fa2bf794c132",
-  "indexDigest": "090e6b3f4bd7c9968b75b609a695e6ebd6f596a66135db41968c3905258a25d6",
-  "packageIntegrity": "sha512-uigk3DRE8FClwgyo5kGeyPtB7CXkpLVEAQGhHxMd0exbFThqvvMxPGGVL7rohJdw+o0xSmFNK0U7/TvwLatyZw=="
+  "sourceCommit": "6198b4fcbc880b56999926ea74c69cd3d122a86a",
+  "siteBuildId": "ead78e4f9fa835d4189aade2c8d34a51b43400308304d415029ae2320db07da4",
+  "manifestDigest": "16d07fdeb5b061d6838131d603e76c475f85fcde040d5625d65516fdc19be7f8",
+  "indexDigest": "d23c76564004ef45e9523730cea63c4ed0e96d6889c2b17a49d207b1063bbb3e",
+  "packageIntegrity": "sha512-oZG3QJeXiQYa/b0Vf6j13lFj/grebtzaeLsRkL+QbLqxGjcmnR/Gs5q/nQDai358sJcDh0XUUAcMFarbPLooHQ=="
 }

package/agent-docs/about.md

@@ -1,7 +1,7 @@
 ---
 id: guide.about
 title: About Shoalrun
-summary: Learn what Shoalrun is exploring and where the beta stands.
+summary: Learn what Shoalrun does and where the project is heading.
 type: overview
 area: project
 subarea: project-overview
@@ -12,7 +12,7 @@ canonical: /about
 
 > Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 I'm CT Smith, and I'm building Shoalrun cause there's no such thing as a perfect doc tool. I have opinions, undirected rage, and curiosity about doc-building tools. I built my first documentation generator back in 2015. It was based on Jekyll and relied heavily (probably too heavily) on general templating and... you guessed it... *page metadata*.
 
@@ -42,7 +42,7 @@ API content follows the same approach. Local OpenAPI files can supply reference
 
 I'm building Shoalrun for tinkerers like me, who will never be fully satisfied with a mass market docs tool. Docs are never one-size-fits-all, on any level.
 
-You can try the beta CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
+You can try the CLI from npm: [Getting started](https://www.shoalrun.com/start.md) walks through installation and your first page. The [project status](https://www.shoalrun.com/status.md) describes what works and what still needs work.
 
 yee haw forever,
 

package/agent-docs/api-docs/code-reference-settings.md

@@ -0,0 +1,160 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow, or use [TypeScript extraction](https://www.shoalrun.com/api-docs/typescript-references.md) for a public source or declaration entry point. This setting is separate from `apis`, which registers OpenAPI sources.
+
+## Catalog settings
+
+Use these fields inside `codeReferences.<catalog-id>`. Catalog IDs use lowercase letters, numbers, and dashes, starting with a letter.
+
+| Field                | Meaning                                                                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `source`             | `{ kind: file, path: ./reference.json }` for the default publication. Paths resolve relative to the declaring config file and must remain inside the project root. |
+| `publications`       | Explicit `{ product?, channel, version, language?, source }` bindings. Declare this or `source`, not both.                                                         |
+| `layout`             | `symbols` (default), `classes`, or `modules`. Changes inline grouping while retaining individual symbol pages.                                                     |
+| `pathPrefix`         | Prefix for generated symbol slugs; defaults to `/reference/code`. Explicit symbol slugs take precedence.                                                           |
+| `include`, `exclude` | Exact symbol IDs to select. Every listed ID must exist. Private symbols and descendants of private symbols aren't published.                                       |
+| `symbols`            | Per-symbol `{ documentId?, slug?, metadata? }` overrides.                                                                                                          |
+| `metadata`           | Ordinary page metadata, including taxonomy, reader filters, `shared`, and feature requirements. Project defaults and enforced metadata still apply.                |
+| `sourceLink.baseUrl` | Optional HTTPS repository directory URL. Must omit credentials, query strings, and fragments.                                                                      |
+| `singlePage`         | An optional object defining a complete reference page. Omit it or use `false` to disable it.                                                                       |
+
+Generated pages have `type: code-reference`. Default document IDs combine the catalog and symbol IDs; IDs outside the simple identifier character set use a deterministic digest. Default slugs combine the path prefix, normalized symbol ID, and a digest. Use explicit overrides when a public URL or content-delivery identity must survive a symbol rename.
+
+## Complete reference page
+
+The `singlePage` object accepts these fields. No complete page is emitted when its selection contains no eligible symbols.
+
+| Field        | Default or behavior                                   |
+| ------------ | ----------------------------------------------------- |
+| `documentId` | `reference.<catalog-id>.complete`                     |
+| `slug`       | `<pathPrefix>/all`                                    |
+| `title`      | `Complete API reference`                              |
+| `summary`    | `Classes, functions, and fields in this publication.` |
+| `metadata`   | Overrides the catalog's metadata for this page.       |
+
+Grouped and complete pages use outline depth two unless frontmatter supplies another depth. Each embedded symbol gets a section heading. Links to embedded symbols target that section; ordinary symbol URLs remain valid for external links and content delivery.
+
+## Publication sources
+
+Bind a snapshot to each interface release. This example assumes the `sdk` product and versions already exist in `publications`:
+
+```yaml
+codeReferences:
+  sdk:
+    publications:
+      - product: sdk
+        channel: production
+        version: v1
+        language: en
+        source: { kind: file, path: ./reference/v1.json }
+      - product: sdk
+        channel: production
+        version: v2
+        language: en
+        source: { kind: file, path: ./reference/v2.json }
+```
+
+Links, member tables, inline details, and complete references stay within the selected catalog and publication. A full snapshot isn't automatically published as a downloadable asset.
+
+## Metadata and selection
+
+A symbol's explicit `shared` or `requires` classification replaces the catalog's classification. Requirements are evaluated separately for each symbol; a parent's feature requirements don't automatically apply to its children. Strictly classified projects need an explicit classification for eligible public symbols and the complete page. Inherited frontmatter defaults don't satisfy that source-classification requirement.
+
+Visibility, feature grants, access policy, and build reader-filter selection apply before references are combined. An excluded type is left as plain text rather than linked to unavailable content. Reader views remain browsing controls; build/profile selection determines which content is published.
+
+## Converter snapshot
+
+A converter writes JSON with `schemaVersion: 1`, `kind: shoalrun-code-reference`, a `programmingLanguage`, producer identity, and a nonempty `symbols` array. The package ships `schemas/code-reference.schema.json`; `shoalrun references check <snapshot.json>` also checks unique IDs, referenced targets, and acyclic parents.
+
+This Kotlin-shaped example illustrates the shared contract. It doesn't imply a bundled Kotlin extractor:
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "shoalrun-code-reference",
+  "programmingLanguage": "kotlin",
+  "producer": { "name": "example-converter", "version": "1.0.0" },
+  "symbols": [{
+    "id": "example.greet",
+    "name": "greet",
+    "kind": "function",
+    "summary": "Create a greeting.",
+    "signatures": ["fun greet(name: String): String"],
+    "parameters": [{ "name": "name", "type": "String", "description": "Reader name." }],
+    "returns": { "type": "String", "description": "A greeting ready to display." }
+  }]
+}
+```
+
+Run a converter explicitly in your workflow, validate its output, then build. Shoalrun doesn't load executable converter plugins during compilation. JavaScript tools can import `validateCodeReference` from `@shoalrun/cli/references`.
+
+## Symbol fields
+
+Each symbol needs `id`, `name`, and `kind`. Supported kinds are `module`, `namespace`, `class`, `interface`, `enum`, `type`, `function`, `method`, `constructor`, `property`, `attribute`, and `constant`.
+
+Use these optional fields to describe the interface without supplying executable markup or an arbitrary syntax tree:
+
+| Field                               | Meaning                                                                                                                                              |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parent`                            | ID of an existing parent symbol. Cycles aren't allowed.                                                                                              |
+| `visibility`                        | `public` by default, or `private`.                                                                                                                   |
+| `summary`, `description`            | Short page summary and inert Markdown description.                                                                                                   |
+| `signatures`                        | Array of declaration strings, including overloads.                                                                                                   |
+| `parameters`                        | Array of `{ name, type?, description?, default? }`.                                                                                                  |
+| `returns`, `yields`                 | `{ type?, description? }`.                                                                                                                           |
+| `raises`                            | Array of `{ name, type?, description?, default? }`.                                                                                                  |
+| `examples`                          | Array of `{ title?, code }`. Examples aren't executed.                                                                                               |
+| `annotation`, `required`, `default` | Field type, whether a value must be supplied, and its default source expression. Unknown requirements stay unmarked. Nullable doesn't mean optional. |
+| `bases`, `constructorSignature`     | Base-type strings and a constructor declaration for a class.                                                                                         |
+| `typeReferences`                    | Mapping from exact type text to an existing symbol ID. Only eligible targets become links; Shoalrun doesn't guess short-name matches.                |
+| `seeAlso`                           | Existing symbol IDs for related reference links.                                                                                                     |
+| `source`                            | `{ path, line? }` with a relative provenance path and optional positive line number.                                                                 |
+
+The snapshot can also include a SHA-256 `sourceDigest`. Unknown fields are rejected. Snapshots are limited to 10,000 symbols and 32 MiB; individual text fields have schema limits.
+
+## Descriptions, type links, and source links
+
+Descriptions don't run MDX or expand project directives. Raw HTML is stripped. Use `[Record](symbol:example.Record)` for a symbol link within the same catalog and publication. External links support HTTPS and mailto; relative links and images aren't supported.
+
+Explicit type references create links in parameter, return, yield, base-class, exception, and field information. Signatures remain copyable code. The Python adapter resolves supported local annotation targets statically and keeps unknown or external targets unlinked.
+
+Set `sourceLink.baseUrl` to a repository URL ending at the directory that contains the relative source paths. Include an immutable commit or release in that URL. A source path `sdk/models.py` with line `12` is appended as `/sdk/models.py#L12`. Shoalrun doesn't fetch or publish source files. Without this setting, source links are omitted.
+
+## Python adapter limits
+
+The packaged adapter requires Python 3.11 or newer and `griffelib==2.4.1`. Its requirements file pins the dependency and archive hash. The source root must contain the requested local module and can't contain symlinks. Extraction rejects roots exceeding 10,000 Python source files or 32 MiB.
+
+Extraction doesn't enable runtime inspection, extensions, external discovery, or alias resolution. The adapter skips aliases and underscore-prefixed members except constructors. It doesn't expand inherited members or execute decorators. Local constructors and supported simple dataclass constructors supply class signatures; unsupported cases stay unspecified. Factory defaults appear as `<factory>` in constructor signatures and retain the source expression in field details.
+
+## HTML, Markdown, and agents
+
+HTML shows symbol context, declarations, member tables, and detailed sections. The tables use local horizontal scrolling instead of shrinking the text on small screens; keyboard readers can focus the scroll region. Copy controls need JavaScript. Grouped pages and complete references keep their content readable without those controls.
+
+Markdown and content exports retain declarations, descriptions, field facts, examples, and links with their resource identity and publication scope. They omit the site's styling and Copy buttons. Agents can read generated pages through discovery tools or content delivery without running the extractor. A caller can select the complete page for export or PDF preparation by its document ID; enabling that page doesn't prebuild PDFs.
+
+## Related reading
+
+### Next steps
+
+- [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) — Extract a Python snapshot and preview both grouped and complete SDK references.

package/agent-docs/api-docs/code-reference-settings.sections/catalog-settings.md

@@ -0,0 +1,50 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) — Extract a Python snapshot and preview both grouped and complete SDK references.
+
+`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow, or use [TypeScript extraction](https://www.shoalrun.com/api-docs/typescript-references.md) for a public source or declaration entry point. This setting is separate from `apis`, which registers OpenAPI sources.
+
+## Catalog settings
+
+Use these fields inside `codeReferences.<catalog-id>`. Catalog IDs use lowercase letters, numbers, and dashes, starting with a letter.
+
+| Field                | Meaning                                                                                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `source`             | `{ kind: file, path: ./reference.json }` for the default publication. Paths resolve relative to the declaring config file and must remain inside the project root. |
+| `publications`       | Explicit `{ product?, channel, version, language?, source }` bindings. Declare this or `source`, not both.                                                         |
+| `layout`             | `symbols` (default), `classes`, or `modules`. Changes inline grouping while retaining individual symbol pages.                                                     |
+| `pathPrefix`         | Prefix for generated symbol slugs; defaults to `/reference/code`. Explicit symbol slugs take precedence.                                                           |
+| `include`, `exclude` | Exact symbol IDs to select. Every listed ID must exist. Private symbols and descendants of private symbols aren't published.                                       |
+| `symbols`            | Per-symbol `{ documentId?, slug?, metadata? }` overrides.                                                                                                          |
+| `metadata`           | Ordinary page metadata, including taxonomy, reader filters, `shared`, and feature requirements. Project defaults and enforced metadata still apply.                |
+| `sourceLink.baseUrl` | Optional HTTPS repository directory URL. Must omit credentials, query strings, and fragments.                                                                      |
+| `singlePage`         | An optional object defining a complete reference page. Omit it or use `false` to disable it.                                                                       |
+
+Generated pages have `type: code-reference`. Default document IDs combine the catalog and symbol IDs; IDs outside the simple identifier character set use a deterministic digest. Default slugs combine the path prefix, normalized symbol ID, and a digest. Use explicit overrides when a public URL or content-delivery identity must survive a symbol rename.

package/agent-docs/api-docs/code-reference-settings.sections/complete-reference-page.md

@@ -0,0 +1,46 @@
+---
+id: reference.code-api-references
+title: Code API reference settings
+summary: Catalog configuration, converter snapshots, Python extraction limits,
+  and generated reference behavior.
+type: reference
+area: api
+subarea: api-generation
+canonical: /api-docs/code-reference-settings
+---
+
+# Code API reference settings
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
+
+**Updated: 2026-11-07.**
+
+**Available since: 1.0.0.**
+
+Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
+
+**Page reading path** — these links apply to the full page.
+
+**Next steps**
+
+- [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) — Extract a Python snapshot and preview both grouped and complete SDK references.
+
+`codeReferences` maps a catalog ID to a local converter snapshot and presentation settings. Start with [Generate code API references](https://www.shoalrun.com/api-docs/code-references.md) for a complete Python workflow, or use [TypeScript extraction](https://www.shoalrun.com/api-docs/typescript-references.md) for a public source or declaration entry point. This setting is separate from `apis`, which registers OpenAPI sources.
+
+## Complete reference page
+
+The `singlePage` object accepts these fields. No complete page is emitted when its selection contains no eligible symbols.
+
+| Field        | Default or behavior                                   |
+| ------------ | ----------------------------------------------------- |
+| `documentId` | `reference.<catalog-id>.complete`                     |
+| `slug`       | `<pathPrefix>/all`                                    |
+| `title`      | `Complete API reference`                              |
+| `summary`    | `Classes, functions, and fields in this publication.` |
+| `metadata`   | Overrides the catalog's metadata for this page.       |
+
+Grouped and complete pages use outline depth two unless frontmatter supplies another depth. Each embedded symbol gets a section heading. Links to embedded symbols target that section; ordinary symbol URLs remain valid for external links and content delivery.