feat(docs): add TypeScript API documentation generation for LLMs #20114

critesjosh · 2026-02-02T22:06:18Z

Summary

Add automated TypeScript API documentation generation optimized for LLM consumption, integrated with Docusaurus versioning.

Features

Generate LLM-friendly markdown from TypeDoc for 9 client-facing packages
Version-aware documentation that integrates with Docusaurus multi-instance docs
Interactive reference page with copy-to-clipboard functionality for easy LLM context inclusion
Auto-generated llm-summary.txt with package metadata overview
Integrated into CI release workflows (nightly-docs-release, release-please)

Generated Documentation

Package	Size	Description
stdlib.md	167 KB	Protocol-level types and domain interfaces
aztec.js.md	90 KB	Main SDK for building Aztec applications
foundation.md	70 KB	Low-level utilities (crypto, serialization)
constants.md	50 KB	Protocol constants shared with Noir circuits
pxe.md	29 KB	Private eXecution Environment client
wallet-sdk.md	27 KB	Wallet SDK for browser/extension integrations
test-wallet.md	14 KB	Test wallet for development and e2e testing
accounts.md	8 KB	Account contract implementations (ECDSA, Schnorr)
entrypoints.md	7 KB	Transaction entrypoint implementations
Total	~470 KB	9 packages

Why Markdown?

More token-efficient than JSON (no syntax overhead)
LLMs are trained on markdown documentation
Can be directly included in prompts without parsing
Easy to copy via one-click buttons in the docs UI

Integration

Version-aware: Docs folder maps to Docusaurus version (devnet → /typescript-api/devnet/)
Reference page: New typescript_api_reference.mdx provides browsable API overview with copy icons
LLM entry points:
- /llms.txt - Full site documentation for LLM context
- /typescript-api/{version}/llm-summary.txt - Package overview summary

Sample Output

# @aztec/stdlib

## Classes

### AztecAddress

AztecAddress represents a 32-byte address in the Aztec Protocol...

**Constructor**
\`\`\`typescript
new AztecAddress(buffer: Fr | Buffer)
\`\`\`

**Methods**
- \`static fromString(buf: string) => AztecAddress\`
- \`toField() => Fr\`
- \`equals(other: AztecAddress) => boolean\`

Test plan

Run ./docs/scripts/typescript_api_generation/generate_ts_api_docs.sh
Verify markdown files contain expected classes/methods/types
Verify version-aware links work in Docusaurus
Test copy-to-clipboard functionality
Test nightly release workflow integration

🤖 Generated with Claude Code

Add automated TypeDoc JSON generation for 8 client-facing packages: - Client SDKs: aztec.js, accounts, pxe, entrypoints, wallet-sdk - Core Libraries: stdlib, foundation, constants Key changes: - Upgrade TypeDoc from 0.24.8 to 0.28.16 (TypeScript 5.8 support) - Add typedocOptions to package.json for each documented package - Create generation script at docs/scripts/typescript_api_generation/ - Add --excludeExternals flag to avoid including viem types (150MB+) - Generate LLM-optimized summary files and types index - Integrate with docusaurus-plugin-llms Excluded internal packages: builder, cli, kv-store, ethereum, simulator Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ludamad · 2026-02-03T09:39:46Z

Hmm curious how an AI would work with such big generated files?

…kages in TypeScript API summary

critesjosh · 2026-02-03T15:21:18Z

my hope is that it can use the llm-summary.txt file to find the relevant source files, then search the relevant files. although, looking more closely at the generated json, I think most of it can be stripped out. I'll look into make them smaller

…e reduction) Add transformer that converts TypeDoc JSON to compact LLM-optimized format: - Flatten comment structures to plain strings - Simplify source references to file:line format - Remove symbolIdMap, groups, and empty fields - Generate readable method signatures Size reduction: 15MB -> 740KB (95% reduction) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Generate both JSON and Markdown formats for each package: - JSON for programmatic access and tooling - Markdown for direct LLM context inclusion Markdown format is more token-efficient and natural for LLMs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Markdown is more token-efficient and natural for LLMs. JSON output removed to simplify the pipeline. Total size: 512KB (markdown only) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Security & reliability fixes: - Fix command injection vulnerability by using array expansion for entry points - Add rm -rf safety checks to prevent accidental deletion of dangerous paths - Use mktemp for atomic temp directory creation - Add proper JSON input validation in transformer - Fix unsafe type casting in typeToString() - Add try-catch for file operations with clear error messages - Replace grep with proper JSON parsing for typedocOptions check Output quality improvements: - Filter out verbose Zod schema types - Strip TODO/FIXME comments from descriptions - Add Quick Import Reference section to each package - Add Cross-Package References section showing type dependencies - Refactor large functions into smaller, focused helpers Configuration improvements: - Load package lists from config.json instead of hardcoding - Add npx verification before using as typedoc fallback - Remove redundant index.json and types-index.json manifests Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Replace hardcoded llm-summary.txt template with auto-generated summary: - Add metadata output (.meta.json) during TypeDoc transformation - Generate summary from metadata with accurate export counts - Apply heuristics to identify key types (Fr, AztecAddress, etc.) - Include package dependencies and categorized type reference - Write metadata to temp dir (cleaned up after summary generation) - Add detailed feature descriptions to config.json Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add TypeScript API docs generation step to nightly-docs-release.yml - Add TypeScript API docs generation step to release-please.yml - Remove redundant typescript-api from llms plugin docsDir (covered by versioned docs) - Remove typescript-api generation from docs build/start scripts (now done in workflows) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

socket-security · 2026-02-03T19:31:30Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/typedoc@0.24.8 ⏵ 0.28.16

View full report

socket-security · 2026-02-03T19:31:33Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

npm/markdown-it@14.1.0

View full report

- Remove undocumented packages (ethereum, simulator, kv-store, builder, cli) - Remove non-existent files from listing (index.json, types-index.json) - Add brief descriptions for each generated markdown file Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…lay name TypeDoc display names can contain spaces (e.g., "Wallet SDK") which produced invalid npm package identifiers like "@aztec/wallet sdk". This broke import examples in generated markdown and caused summary generation to miss packages whose metadata couldn't be matched to config. Now uses the input file path basename which matches the actual npm package name. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Convert typescript-api/index.md to MDX and add version-aware link components using Docusaurus's useActiveVersion hook. Links now automatically point to the correct API version folder (next, nightly, or devnet) based on which docs version the user is viewing. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

critesjosh · 2026-02-03T20:42:14Z

@SocketSecurity ignore npm/markdown-it@14.1.0

Add auto-generated TypeScript API markdown files for devnet version. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The next version docs are auto-generated during CI and should not be committed to the repository. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Copy the version-aware TypeScript API index page to the devnet versioned docs so it's available in the v3.0.0-devnet.6-patch.1 docs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The TypeScript API documentation generation uses TypeDoc which needs dependencies installed to resolve cross-package type references. Move the generation step to after yarn-project bootstrap in both release workflows. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Move the TypeScript API reference page from standalone typescript-api folder into aztec-js as typescript_api_reference.mdx for better organization alongside other aztec.js documentation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add inline copy icons next to LLM-optimized documentation file links, allowing readers to easily copy file contents to clipboard for use with AI assistants. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…-wallet Add noir-contracts.js (compiled Noir contract bindings) and test-wallet packages to the documented SDK packages. Move foundation and constants to excluded list since their types are re-exported through aztec.js subpaths. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

…-contracts.js - Fix test-wallet typedocOptions to use correct entry point (server.ts) - Remove noir-contracts.js from TS API docs (auto-generated, not useful) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

chore(docs): remove outdated references to Ethereum and simulator pac…

929683b

…kages in TypeScript API summary

critesjosh and others added 6 commits February 3, 2026 11:19

refactor(docs): remove JSON output, keep only markdown

94ae484

Markdown is more token-efficient and natural for LLMs. JSON output removed to simplify the pipeline. Total size: 512KB (markdown only) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

critesjosh and others added 3 commits February 3, 2026 14:33

critesjosh and others added 9 commits February 3, 2026 15:44

docs: add devnet TypeScript API documentation

f8863b9

Add auto-generated TypeScript API markdown files for devnet version. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: remove next version TypeScript API documentation

befe25d

The next version docs are auto-generated during CI and should not be committed to the repository. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: add TypeScript API reference to devnet versioned docs

48bfee2

Copy the version-aware TypeScript API index page to the devnet versioned docs so it's available in the v3.0.0-devnet.6-patch.1 docs. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: add copy-to-clipboard icons for TypeScript API reference files

f01a404

Add inline copy icons next to LLM-optimized documentation file links, allowing readers to easily copy file contents to clipboard for use with AI assistants. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: add foundation and constants to TypeScript API reference

c244171

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(docs): add TypeScript API documentation generation for LLMs #20114

feat(docs): add TypeScript API documentation generation for LLMs #20114

Uh oh!

critesjosh commented Feb 2, 2026 •

edited

Loading

Uh oh!

ludamad commented Feb 3, 2026

Uh oh!

critesjosh commented Feb 3, 2026

Uh oh!

socket-security bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

socket-security bot commented Feb 3, 2026 •

edited

Loading

Uh oh!

critesjosh commented Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat(docs): add TypeScript API documentation generation for LLMs #20114

Are you sure you want to change the base?

feat(docs): add TypeScript API documentation generation for LLMs #20114

Uh oh!

Conversation

critesjosh commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Generated Documentation

Why Markdown?

Integration

Sample Output

Test plan

Uh oh!

ludamad commented Feb 3, 2026

Uh oh!

critesjosh commented Feb 3, 2026

Uh oh!

socket-security bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

critesjosh commented Feb 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

critesjosh commented Feb 2, 2026 •

edited

Loading

socket-security bot commented Feb 3, 2026 •

edited

Loading

socket-security bot commented Feb 3, 2026 •

edited

Loading