@shoalrun/cli 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0 — 2026-11-07
+
+- Select additional sections with [ForFacet](https://www.shoalrun.com/author/components/for-facet)
+  and existing build facets, without customer profiles. Omit unmatched content
+  before rendering, indexing, and dependency expansion.
+- Generate [TypeScript SDK references](https://www.shoalrun.com/api-docs/typescript-references)
+  from public declarations and JSDoc. Preserve overloads, optional methods,
+  readonly properties, and linked types. The authoring skill covers extraction
+  and build selection; the website includes the generated content client API.
+- Add project skill discovery links, explicit loading instructions, and short
+  task checklists for the bundled agent workflows.
+- Improve browser and CLI keyword ranking for queries written as questions.
+- Mark intentional HTML-only blocks for compatible parity checks while retaining
+  tooltip and info-hint comparison.
+
+Upgrade to CLI `1.1.0` and rebuild the site and application exports. TypeScript
+extraction requires an explicit `typescript@5.9.3` development dependency;
+normal builds consume the saved snapshot without running extraction.
+
 ## 1.0.0 — 2026-11-06
 
 - Generate [code API references](https://www.shoalrun.com/api-docs/code-references)

package/CODE-REFERENCES.md

@@ -24,6 +24,25 @@ Use `--style google`, `--style numpy`, or `--style sphinx` for the docstring con
 
 The adapter emits locally defined symbols, skips aliases and underscore-prefixed members except constructors, and rejects symlinks in its declared source root. It doesn't expand inherited members, execute decorators, resolve external re-exports, or infer undocumented behavior. Its example SDK stores records in memory and doesn't contact a live service.
 
+## Generate TypeScript references
+
+The optional TypeScript adapter follows the public exports of one entry module, including local re-exports. It reads source or declaration files with the TypeScript compiler API; it doesn't import, execute, or emit documented code. Install `typescript@5.9.3` explicitly in the project that supplies the compiler configuration. The adapter supports TypeScript 5.9.x and rejects other compiler versions.
+
+From that project, run:
+
+```sh
+node node_modules/@shoalrun/cli/adapters/typescript/shoalrun-reference.mjs \
+  --project tsconfig.json --entry src/index.ts --module example.sdk \
+  --out reference.json
+shoalrun references check reference.json
+```
+
+`--entry` resolves relative to the compiler configuration. `--root` defaults to its directory and bounds emitted declarations and relative provenance paths; an entry or exported declaration outside that root fails. The configuration may be outside an explicitly supplied root. `--out` resolves relative to the current working directory. Extraction reports TypeScript errors rather than publishing an incomplete entry point. It doesn't install dependencies, run project plugins, or fetch remote declarations.
+
+Functions, overloads, classes, interfaces, type aliases, enums, and constants retain signatures. Object/interface fields and methods become child symbols. JSDoc descriptions, `@param`, `@returns`, and `@example` supply prose. Private/protected members and `@internal`/`@private` symbols are omitted. Local type references link eligible exports. Inherited members aren't expanded; union alternatives remain in their full alias declaration. Namespace exports and other unsupported declarations fail explicitly. See [the adapter guide](adapters/typescript/README.md) for limits.
+
+Normal site builds still read the saved JSON and don't need TypeScript. Refresh explicitly after changing the public source or JSDoc, then validate and review the generated reference. Type extraction doesn't prove runtime behavior.
+
 ## Configure a catalog
 
 ```yaml

package/README.md

@@ -9,7 +9,7 @@ This package provides the `shoalrun` CLI, starter projects, agent skills, and of
 From the project where you want to keep your documentation:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@1.0.0
+npm install --save-dev --save-exact @shoalrun/cli@1.1.0
 ```
 
 ## Create and preview a site
@@ -39,8 +39,9 @@ The [features overview](https://www.shoalrun.com/features) describes the complet
 | A documentation site | Pages, navigation, local preview, themes, palettes, fonts, and project CSS. |
 | Reusable procedures | Recipes, shared ingredients, and cookbooks that help readers choose a complete task. |
 | HTTP API references | OpenAPI operation pages, code examples, focused contracts, and an explicit source-review gate. |
-| Code API references | [Python docstrings and converter-supplied symbols](CODE-REFERENCES.md), rendered as native reference pages. |
+| Code API references | [Python docstrings, TypeScript declarations, and converter-supplied symbols](CODE-REFERENCES.md), rendered as native reference pages. |
 | Several product releases | Independent product versions and defaults, publication routes, and a header publication selector. |
+| Build selection | Select pages and `<ForFacet>` sections with configured facets and choices, without customer profiles. |
 | Customer editions | External profiles, SKU revisions, feature grants, and conditional pages or sections. |
 | Application help | HTML and Markdown exports, stable page/section/snippet references, static and REST clients, and instance-safe mounting. |
 | Agent discovery | Markdown twins, compact linked indexes, read-only MCP tools, bundled skills, and offline references. |
@@ -48,6 +49,14 @@ The [features overview](https://www.shoalrun.com/features) describes the complet
 
 Local builds and keyword search need no provider credentials. Semantic retrieval and generated answers use separately configured services; credentials stay server-side. Reader filters are browsing controls, not authorization. Customer profiles select output during compilation; private-edition hosting remains your responsibility.
 
+## Select pages and sections for a build
+
+Declare choices under `readerFilters.facets` and set `site.contentFilter`, for example `{ audience: [customer] }`. Mark shared pages with `audiences: [customer, internal]`, then wrap additional internal instructions in `<ForFacet audience="internal">` blocks. The customer build omits those blocks from HTML, Markdown, search, discovery, and expanded resources. An unfiltered build includes them.
+
+Unmarked sections remain included; pages without a mark for a selected facet are excluded. Every facet attribute must match, with whitespace-separated alternative choices inside each attribute. This is additive information in selected builds, not replacement text. `<ReaderSection>` remains a browser visibility control and its content ships.
+
+Portable export targets need their own `contentFilter`; PDF exports inherit the site's filter unless overridden. Selection reports stay in `.shoalrun/content-selection.json`, outside public output. See the [runnable audience example](example-configs/facet-sections/README.md) and [authoring selection guidance](skills/shoalrun-author/references/facet-selection.md).
+
 ## Match your brand
 
 Use `site.logo`, `site.favicon`, and header settings for site identity. Choose a theme preset and configure `theme.palette`, `theme.mode`, and `theme.fonts`. Use `site.customCss` for changes beyond those settings. Customer profiles can supply deployment-owned branding without storing customer records in the shared source.
@@ -131,7 +140,7 @@ npx --no-install shoalrun skills list
 npx --no-install shoalrun skills read shoalrun-setup
 ```
 
-Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent.
+Ask your agent to read the skill for the task. `skills list` returns names, descriptions, and local instruction-file paths. These commands read the skills; installing the npm package does not automatically install them into your agent. Expose complete folders through your agent's discovery directory. Copy complete folders into the skill directory supported by your agent, preserving existing skills and reviewing copied versions when upgrading. Give the project's agent instructions an exact path to load before editing, with direct file reading as a fallback. See [skill setup](https://www.shoalrun.com/contribute/agent-skills).
 
 The editing workflow is to capture a baseline, edit source files, validate the changes, then review a local preview. From your documentation project directory:
 
@@ -349,7 +358,7 @@ with a Hero replaces the standard page header and does not display its dates.
 If you previously used the private GitHub Packages alpha, check `npm config get @shoalrun:registry`. Remove or replace any `@shoalrun:registry=https://npm.pkg.github.com` entry in your project or user `.npmrc`. You can explicitly select the public registry for the upgrade:
 
 ```sh
-npm install --save-dev --save-exact @shoalrun/cli@1.0.0 --@shoalrun:registry=https://registry.npmjs.org
+npm install --save-dev --save-exact @shoalrun/cli@1.1.0 --@shoalrun:registry=https://registry.npmjs.org
 ```
 
 Commit the updated package manifest and lockfile together. Check that the lockfile resolves `@shoalrun/cli` from `registry.npmjs.org`. Keep any credentials needed by other private dependencies; Shoalrun itself no longer needs a package token.

package/adapters/typescript/README.md

@@ -0,0 +1,27 @@
+# TypeScript code-reference adapter
+
+This optional adapter uses the project's installed TypeScript 5.9.x compiler API to extract one public entry point into Shoalrun's version 1 snapshot format. The maintained dependency is `typescript@5.9.3`. TypeScript 6/7 compiler APIs aren't covered by this adapter.
+
+Install the dependency explicitly, then run from your documentation or library project:
+
+```sh
+npm install --save-dev --save-exact typescript@5.9.3
+node node_modules/@shoalrun/cli/adapters/typescript/shoalrun-reference.mjs \
+  --project tsconfig.json \
+  --entry src/index.ts \
+  --module example.sdk \
+  --out reference.json
+npx --no-install shoalrun references check reference.json
+```
+
+Set `--root DIRECTORY` to bound declarations and provenance to a narrower source tree. Entry paths resolve relative to the project's compiler configuration. The output path resolves relative to the current directory. The module ID is a stable logical prefix for exported symbol IDs; use the same value when refreshing the snapshot.
+
+Public local re-exports are followed. Functions and overloads, classes, interfaces, aliases, enums, constants, declared members, and static members are represented. Private/protected declarations and `@internal` or `@private` symbols are skipped. A structural alias or inferred structural type containing an excluded member stops extraction instead of printing private details in a parent signature; expose a separate public type. Copied initializers and parameter defaults containing excluded declarations also stop extraction rather than publishing those values. Inherited members aren't expanded. Anonymous call/index signatures are retained in interface declarations, and union alternatives remain in their alias declaration. Unsupported declarations, unresolved imports, and exported declarations outside the declared source root stop extraction.
+
+JSDoc descriptions, parameter descriptions, return descriptions, and examples are retained. Other JSDoc tags aren't converted into runtime constraints. Source initializers used as defaults are copied as expressions, never evaluated. Some conditional type expansions stop extraction when their visibility cannot be verified. Type references link known public targets; built-ins and unavailable types remain text. Source locations refer to the actual input, including `.d.ts` files when those are used.
+
+The adapter calls `createProgram` without emitting files. It doesn't execute the documented module or run project transformers/plugins, install dependencies, or fetch remote inputs. The TypeScript compiler package and local configuration remain trusted development inputs. Use a reviewed project and inspect the JSON before publication.
+
+The source digest covers effective compiler options and all compiler source files, including external type dependencies. Graph accounting limits include those dependencies; they are checked after TypeScript loads the graph and are not execution or memory isolation. Run extraction only on trusted local projects. The output cannot overwrite a compiler input, including through symlinks, and is replaced atomically after validation.
+
+A site build needs only the saved JSON. Configure it through `codeReferences` as described in [CODE-REFERENCES.md](../../CODE-REFERENCES.md). This keeps extraction separate from rendering, publication selection, and content delivery.

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

@@ -30,13 +30,15 @@ Full-page token counts use cl100k_base. Navigation section ID: project-updates.
 
 - [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; 1547 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.
 

package/agent-docs/SNAPSHOT.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "sourceRepository": "https://github.com/shoalrun/docs",
-  "sourceCommit": "0af50d753fc59c1e332d5e710999e3219c3e2443",
-  "siteBuildId": "6b51e1bac3826424f2ec68156866ec40c1761f7765901fc6dfc2f2d4f24a8596",
-  "manifestDigest": "2cb3bc1d411d08d4156fb139c6257dd4e56ea79ea1aed38c85eb32986b2a1743",
-  "indexDigest": "a6c8b514805bfd808949c3d22a01deee1ae9c35b4c6e54009ae3866b21df2c6e",
-  "packageIntegrity": "sha512-TVNgFm5dtSyO7c+njfPC2fta5IWnIVALrTD0CYktEUeuFbKv0pdKg8C7ihBiQ3svOhXNnyjZSDF96N23lVl/Tw=="
+  "sourceCommit": "6198b4fcbc880b56999926ea74c69cd3d122a86a",
+  "siteBuildId": "ead78e4f9fa835d4189aade2c8d34a51b43400308304d415029ae2320db07da4",
+  "manifestDigest": "16d07fdeb5b061d6838131d603e76c475f85fcde040d5625d65516fdc19be7f8",
+  "indexDigest": "d23c76564004ef45e9523730cea63c4ed0e96d6889c2b17a49d207b1063bbb3e",
+  "packageIntegrity": "sha512-oZG3QJeXiQYa/b0Vf6j13lFj/grebtzaeLsRkL+QbLqxGjcmnR/Gs5q/nQDai358sJcDh0XUUAcMFarbPLooHQ=="
 }

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

@@ -17,11 +17,11 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## Converter snapshot
 

package/agent-docs/api-docs/code-reference-settings.sections/descriptions-type-links-and-source-links.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## Descriptions, type links, and source links
 

package/agent-docs/api-docs/code-reference-settings.sections/html-markdown-and-agents.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## HTML, Markdown, and agents
 

package/agent-docs/api-docs/code-reference-settings.sections/metadata-and-selection.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## Metadata and selection
 

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

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## Publication sources
 

package/agent-docs/api-docs/code-reference-settings.sections/python-adapter-limits.md

@@ -17,7 +17,7 @@ Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigat
 
 Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Document an API > Code API reference settings
 
-**Updated: 2026-11-06.**
+**Updated: 2026-11-07.**
 
 **Available since: 1.0.0.**
 
@@ -29,7 +29,7 @@ Parent page: [Full Markdown page](/api-docs/code-reference-settings.md)
 
 - [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. This setting is separate from `apis`, which registers OpenAPI sources.
+`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.
 
 ## Python adapter limits