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

.github/workflows/nightly-docs-release.yml

@@ -154,6 +154,13 @@ jobs:
           ./bootstrap.sh
           echo "AZTEC_CLI_PATH=$(pwd)/aztec/dest/bin" >> $GITHUB_ENV
 
+      - name: Generate TypeScript API documentation
+        working-directory: ./docs
+        run: |
+          # Generate TypeScript API docs for this version (requires yarn-project to be built)
+          ./scripts/typescript_api_generation/generate_ts_api_docs.sh ${{ env.NIGHTLY_TAG }}
+          echo "Generated TypeScript API docs for: ${{ env.NIGHTLY_TAG }}"
+
       - name: Generate CLI documentation
         working-directory: ./docs
         continue-on-error: true

.github/workflows/release-please.yml

@@ -202,6 +202,13 @@ jobs:
           ./bootstrap.sh
           echo "AZTEC_CLI_PATH=$(pwd)/aztec/dest/bin" >> $GITHUB_ENV
 
+      - name: Generate TypeScript API documentation
+        working-directory: ./docs
+        run: |
+          # Generate TypeScript API docs for this version (requires yarn-project to be built)
+          ./scripts/typescript_api_generation/generate_ts_api_docs.sh ${{ steps.version.outputs.semver }}
+          echo "Generated TypeScript API docs for: ${{ steps.version.outputs.semver }}"
+
       - name: Generate Aztec CLI documentation
         id: aztec-cli-docs
         working-directory: ./docs

cspell.json

@@ -187,6 +187,7 @@
     "leveljs",
     "libp",
     "linkability",
+    "llms",
     "lmdb",
     "macroified",
     "maddiaa",

docs/CLAUDE.md

@@ -21,6 +21,13 @@ This project uses Yarn 4.5.2 as specified in the `packageManager` field of packa
 - `yarn spellcheck` - Run spell checking with cspell on markdown files
 - `yarn clean` - Clean build artifacts and processed docs
 
+### API Documentation Generation
+
+- `yarn generate:aztec-nr-api` - Generate Aztec.nr API docs (requires `nargo`)
+- `yarn generate:aztec-nr-api v1.0.0` - Generate for a specific version
+- `yarn generate:typescript-api` - Generate TypeScript API docs (requires yarn-project to be built)
+- `yarn generate:typescript-api v3.0.0-devnet.6` - Generate for a specific version
+
 ### Development Workflow
 
 The documentation uses a **preprocessing system** that:
@@ -98,7 +105,10 @@ Default content
 - `src/preprocess/` - Preprocessing scripts and macro handlers
 - `src/components/` - React components for documentation
 - `static/img/` - Static images and assets
+- `static/aztec-nr-api/` - Auto-generated Aztec.nr API documentation (HTML)
+- `static/typescript-api/` - Auto-generated TypeScript API documentation (markdown)
 - `scripts/` - Build and utility scripts
+- `scripts/typescript_api_generation/` - TypeScript API doc generation scripts and config
 
 ### Content Structure
 
@@ -107,6 +117,17 @@ This site uses **Docusaurus multi-instance docs** with independent versioning:
 - **Developer Guides** (`/developers/`) - Getting started, tutorials, references (devnet + nightly versions)
 - **Network Guides** (`/network/`) - Node operation and network participation (testnet + ignition versions)
 
+### Auto-Generated API Documentation
+
+Two API reference systems generate documentation from source code:
+
+- **Aztec.nr API** (`static/aztec-nr-api/`) - Generated from `noir-projects/aztec-nr/` using `nargo doc`
+- **TypeScript API** (`static/typescript-api/`) - Generated from `yarn-project/` packages using TypeDoc
+
+The TypeScript API generation is configured in `scripts/typescript_api_generation/config.json` and documents:
+- Client SDKs: `aztec.js`, `accounts`, `pxe`, `wallet-sdk`, `test-wallet`, `entrypoints`
+- Core Libraries: `stdlib`, `foundation`, `constants`
+
 ### Versioning System
 
 Uses Docusaurus multi-instance versioning with separate version tracks:
@@ -304,5 +325,5 @@ Approved external documentation sources:
 - Suggest improvements even if they go beyond pure editing
 - When making changes to documentation processes or tooling, remember to check and update READMEs, project documentation (like this file), and code comments
 
-Last updated: 2026-01-09
-Version: 1.3
+Last updated: 2026-02-04
+Version: 1.4

docs/README.md

@@ -232,6 +232,55 @@ yarn generate:aztec-nr-api v1.0.0
 
 The generated docs are stored in `static/aztec-nr-api/<version>/` and linked from the [Aztec.nr API Reference](/developers/docs/aztec-nr/api) page.
 
+### TypeScript API Documentation
+
+The TypeScript API reference is auto-generated from the `yarn-project/` packages using TypeDoc. This generates LLM-optimized markdown documentation served from `static/typescript-api/`.
+
+**Documented packages:**
+
+- **Client SDKs:** `@aztec/aztec.js`, `@aztec/accounts`, `@aztec/pxe`, `@aztec/wallet-sdk`, `@aztec/test-wallet`, `@aztec/entrypoints`
+- **Core Libraries:** `@aztec/stdlib`, `@aztec/foundation`, `@aztec/constants`
+
+**Prerequisites:** You need `yarn-project` to be built first (the bootstrap process handles this).
+
+**Generate docs for the "next" version:**
+
+```bash
+yarn generate:typescript-api
+```
+
+**Generate docs for a specific version:**
+
+```bash
+yarn generate:typescript-api v3.0.0-devnet.6
+```
+
+**How it works:**
+
+1. Reads package configuration from `scripts/typescript_api_generation/config.json`
+2. Runs TypeDoc on each package's entry points defined in their `package.json` `typedocOptions`
+3. Transforms the TypeDoc JSON output to LLM-optimized markdown via `transform_for_llm.ts`
+4. Generates `llm-summary.txt` with an overview of all packages
+
+**Output files:**
+
+- `static/typescript-api/<version>/*.md` - Per-package markdown documentation
+- `static/typescript-api/<version>/llm-summary.txt` - Human/LLM-readable summary
+
+**Version mapping:**
+
+- Versions containing "nightly" → `nightly/` folder
+- Versions containing "devnet" → `devnet/` folder
+- Other versions → version-specific folder (e.g., `v1.0.0/`)
+
+**When to regenerate:**
+
+- When TypeScript package APIs change (new exports, updated JSDoc comments, etc.)
+- The `next` version docs should be committed to the repo
+- Versioned docs are automatically generated by CI during release workflows
+
+The generated docs are linked from the [TypeScript API Reference](/developers/docs/aztec-js/typescript_api_reference) page.
+
 ## Macros
 
 As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.

docs/developer_versioned_docs/version-v3.0.0-devnet.6-patch.1/docs/aztec-js/typescript_api_reference.mdx

@@ -0,0 +1,173 @@
+---
+title: TypeScript API Reference
+description: API reference documentation for Aztec TypeScript packages including aztec.js, accounts, PXE, and core libraries.
+---
+
+import { useActiveVersion } from "@docusaurus/plugin-content-docs/client";
+import { useState } from "react";
+
+export const useApiVersion = () => {
+  const version = useActiveVersion("developer");
+  const versionName = version?.name || "current";
+  // Map Docusaurus version to API docs folder
+  // Use stable paths for nightly/devnet, version-specific for others
+  if (versionName === "current") return "next";
+  if (versionName.includes("nightly")) return "nightly";
+  if (versionName.includes("devnet")) return "devnet";
+  return versionName;
+};
+
+export const ApiLink = ({ path, children }) => {
+  const apiVersion = useApiVersion();
+  const href = `/typescript-api/${apiVersion}/${path}`;
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer">
+      {children}
+    </a>
+  );
+};
+
+export const ApiPath = () => {
+  const apiVersion = useApiVersion();
+  return <code>/typescript-api/{apiVersion}/</code>;
+};
+
+export const CopyIcon = ({ path, absolute = false }) => {
+  const apiVersion = useApiVersion();
+  const [status, setStatus] = useState("idle");
+
+const handleCopy = async (e) => {
+e.preventDefault();
+const url = absolute ? path : `/typescript-api/${apiVersion}/${path}`;
+setStatus("loading");
+try {
+const response = await fetch(url);
+if (!response.ok) throw new Error("Failed to fetch");
+const text = await response.text();
+await navigator.clipboard.writeText(text);
+setStatus("copied");
+setTimeout(() => setStatus("idle"), 2000);
+} catch (error) {
+setStatus("error");
+setTimeout(() => setStatus("idle"), 2000);
+}
+};
+
+const buttonStyle = {
+padding: "2px",
+marginLeft: "6px",
+cursor: status === "loading" ? "wait" : "pointer",
+border: "none",
+borderRadius: "3px",
+background: "transparent",
+color: status === "copied" ? "var(--ifm-color-success)" :
+status === "error" ? "var(--ifm-color-danger)" :
+"var(--ifm-color-emphasis-600)",
+transition: "color 0.2s ease",
+verticalAlign: "middle",
+display: "inline-flex",
+alignItems: "center",
+};
+
+const iconStyle = {
+width: "14px",
+height: "14px",
+};
+
+const copyIcon = (
+<svg style={iconStyle} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+<rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+<path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+</svg>
+);
+
+const checkIcon = (
+<svg style={iconStyle} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+<polyline points="20 6 9 17 4 12"></polyline>
+</svg>
+);
+
+const errorIcon = (
+<svg style={iconStyle} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+<line x1="18" y1="6" x2="6" y2="18"></line>
+<line x1="6" y1="6" x2="18" y2="18"></line>
+</svg>
+);
+
+const icon = status === "copied" ? checkIcon : status === "error" ? errorIcon : copyIcon;
+const title = status === "copied" ? "Copied!" : status === "error" ? "Failed to copy" : "Copy contents";
+
+return (
+<button onClick={handleCopy} style={buttonStyle} disabled={status === "loading"} title={title} aria-label={title}>
+{status === "loading" ? "..." : icon}
+</button>
+);
+};
+
+export const ApiFile = ({ path, children }) => {
+  const apiVersion = useApiVersion();
+  const href = `/typescript-api/${apiVersion}/${path}`;
+  return (
+    <span style={{ whiteSpace: "nowrap" }}>
+      <a href={href} target="_blank" rel="noopener noreferrer">
+        <code>{children || path}</code>
+      </a>
+      <CopyIcon path={path} />
+    </span>
+  );
+};
+
+This section provides API reference documentation for the Aztec TypeScript packages. These packages enable developers to build applications on Aztec, from simple contract interactions to complex privacy-preserving protocols.
+
+## Package Categories
+
+### Client SDKs
+
+Packages for building Aztec applications:
+
+| Package                | Description                                                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **@aztec/aztec.js**    | Main SDK for building Aztec applications. Provides contract deployment, transaction creation, and account management. |
+| **@aztec/accounts**    | Sample account contract implementations including ECDSA and Schnorr accounts.                                         |
+| **@aztec/pxe**         | Private eXecution Environment client library for orchestrating private transaction execution and proving.             |
+| **@aztec/wallet-sdk**  | Wallet SDK for browser and extension integrations.                                                                    |
+| **@aztec/entrypoints** | Transaction entrypoint implementations for account abstraction.                                                       |
+
+### Core Libraries
+
+Foundational types and utilities used across the Aztec stack:
+
+| Package           | Description                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| **@aztec/stdlib** | Protocol-level types including transactions, blocks, proofs, and kernel circuit types. |
+
+:::note
+Common types like `Fr`, `AztecAddress`, and `EthAddress` are re-exported through `@aztec/aztec.js` subpaths (e.g., `@aztec/aztec.js/fields`, `@aztec/aztec.js/addresses`). Most developers won't need to import from `@aztec/stdlib` directly.
+:::
+
+## LLM-Optimized Documentation
+
+For LLM consumption, we provide machine-readable documentation in multiple formats:
+
+- **[llms.txt](pathname:///llms.txt)** <CopyIcon path="/llms.txt" absolute={true} /> - Full documentation optimized for LLM context
+- <ApiLink path="llm-summary.txt">**LLM Summary**</ApiLink>
+  <CopyIcon path="llm-summary.txt" /> - Human-readable API summary
+
+### Markdown API Files
+
+The following markdown files are available for LLM context inclusion at <ApiPath />:
+
+| File                               | Description                                     |
+| ---------------------------------- | ----------------------------------------------- |
+| <ApiFile path="llm-summary.txt" /> | Human-readable summary with package overview    |
+| <ApiFile path="aztec.js.md" />     | Main SDK - contracts, transactions, accounts    |
+| <ApiFile path="accounts.md" />     | Account implementations (ECDSA, Schnorr)        |
+| <ApiFile path="pxe.md" />          | Private execution environment client            |
+| <ApiFile path="wallet-sdk.md" />   | Browser/extension wallet integration            |
+| <ApiFile path="entrypoints.md" />  | Transaction entrypoints for account abstraction |
+| <ApiFile path="stdlib.md" />       | Protocol types (transactions, blocks, proofs)   |
+
+## Related Resources
+
+- [Aztec.js Getting Started](../tutorials/js_tutorials/aztecjs-getting-started.md)
+- [GitHub: aztec-packages](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project)