feat(docs): improve discoverability of API reference docs

docs/docs-operate/operators/sequencer-management/governance-participation.md

@@ -98,7 +98,7 @@ The governance process follows these stages:
 #else
 3. **Voting Delay** (3 days): A mandatory waiting period before voting opens (allows time for community review).
 4. **Voting Period** (7 days): Users who hold stake in the network vote on the proposal using their staked tokens. A proposal passes if it receives at least 20% quorum, 2/3 of votes are "yea", and a minimum of 500 validators' worth of voting power is cast.
-5. **Execution Delay** (7 days): After passing the vote, another mandatory delay before execution (allows time for node upgrades).
+5. **Execution Delay** (30 days): After passing the vote, another mandatory delay before execution (allows time for node upgrades).
 6. **Execution**: Anyone can execute the proposal, which applies the changes. There is a 7-day grace period after the execution delay during which the proposal can still be executed.
 #endif
 

docs/docs-participate/token/staking.md

@@ -74,7 +74,7 @@ If your tokens are deposited in the Governance Staking Escrow (GSE) for voting,
 To unstake your tokens, use the [Aztec Staking Dashboard](https://stake.aztec.network/). The dashboard guides you through the unstaking process:
 
 1. **Initiate withdrawal**: Select your validator and begin the exit process
-2. **Wait for the exit delay**: Your tokens remain locked during this period
+2. **Wait for the exit delay**: Your tokens remain locked during this period (if your tokens are also in the Governance Staking Escrow, the longer governance withdrawal delay applies)
 3. **Finalize withdrawal**: After the delay, complete the withdrawal to receive your tokens
 
 If you've delegated stake, contact your operator or use the delegation interface to request unstaking.

docs/docs-participate/token/voting.md

@@ -47,7 +47,7 @@ If you want governance participation without staking, you can lock tokens direct
 
 To lock tokens for voting, visit the [Governance section of the Staking Dashboard](https://stake.aztec.network/governance). Connect your wallet, choose the amount to lock, and confirm the transaction. After depositing, your voting power will be active for any proposals that enter the voting phase after your deposit.
 
-Note that locked governance tokens do not earn staking rewards and are subject to a withdrawal delay (~1.6 days on testnet, ~14.6 days on mainnet).
+Note that locked governance tokens do not earn staking rewards and are subject to a withdrawal delay (~1.6 days on testnet, ~38 days on mainnet).
 
 ## How Voting Works
 
@@ -57,7 +57,7 @@ Your voting power is determined by the amount of tokens you have locked in the G
 
 - **Locking Required**: You must lock tokens in the Governance contract to activate voting power
 - **No Slashing on Votes**: Locked voting tokens are not subject to slashing (unlike staked tokens)
-- **Withdrawal Delay**: After voting, there's a delay before you can withdraw tokens to prevent governance attacks (approximately 1.6 days on testnet, 14.6 days on mainnet)
+- **Withdrawal Delay**: After voting, there's a delay before you can withdraw tokens to prevent governance attacks (approximately 1.6 days on testnet, ~38 days on mainnet)
 
 ### Voting Timeline
 

docs/docs/networks.md

@@ -76,7 +76,7 @@ The developer SDK/aztec-nr version (used for writing and compiling contracts) ma
 | **Proposer Quorum** | 600/1000 | 60/100 |
 | **Voting Delay** | 3 days | 12 hours |
 | **Voting Duration** | 7 days | 24 hours |
-| **Execution Delay** | 7 days | 12 hours |
+| **Execution Delay** | 30 days | 12 hours |
 | **Slashing Quorum** | 65% | 33% |
 | **Slashing Round Size** | 128 epochs | 64 epochs |
 

docs/network_versioned_docs/version-v4.1.3/operators/sequencer-management/governance-participation.md

@@ -90,7 +90,7 @@ The governance process follows these stages:
 2. **Proposal Creation**: After reaching quorum, anyone can submit the payload as an official proposal.
 3. **Voting Delay** (3 days): A mandatory waiting period before voting opens (allows time for community review).
 4. **Voting Period** (7 days): Users who hold stake in the network vote on the proposal using their staked tokens. A proposal passes if it receives at least 20% quorum, 2/3 of votes are "yea", and a minimum of 500 validators' worth of voting power is cast.
-5. **Execution Delay** (7 days): After passing the vote, another mandatory delay before execution (allows time for node upgrades).
+5. **Execution Delay** (30 days): After passing the vote, another mandatory delay before execution (allows time for node upgrades).
 6. **Execution**: Anyone can execute the proposal, which applies the changes. There is a 7-day grace period after the execution delay during which the proposal can still be executed.
 
 ## Signaling Support for a Payload

docs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "build": "yarn clean && yarn preprocess && yarn spellcheck && yarn preprocess:move && yarn validate:redirects && yarn validate:api-ref-links && docusaurus build && node scripts/append_api_docs_to_llms.js",
+    "build": "yarn clean && yarn preprocess && yarn spellcheck && yarn preprocess:move && yarn validate:redirects && yarn validate:api-ref-links && docusaurus build && node scripts/augment_sitemap.js && node scripts/append_api_docs_to_llms.js",
     "validate:redirects": "./scripts/validate_redirect_targets.sh",
     "validate:api-ref-links": "./scripts/validate_api_ref_links.sh",
     "clean": "./scripts/clean.sh",

docs/scripts/append_api_docs_to_llms.js

@@ -38,10 +38,19 @@ if (defaultType && fs.existsSync(path.join(STATIC_DIR, `aztec-nr-api/${defaultTy
     name: "Aztec.nr API Reference",
     dir: `aztec-nr-api/${defaultType}`,
     description: `Auto-generated API documentation for Aztec.nr (${defaultVersion})`,
+    format: "html",
   });
 } else if (!defaultType) {
   console.warn("Warning: No default version found for API docs");
 }
+if (defaultType && fs.existsSync(path.join(STATIC_DIR, `typescript-api/${defaultType}`))) {
+  API_DIRS.push({
+    name: "TypeScript API Reference",
+    dir: `typescript-api/${defaultType}`,
+    description: `Auto-generated TypeScript API documentation for Aztec packages (${defaultVersion})`,
+    format: "markdown",
+  });
+}
 
 /**
  * Extract text content from HTML, stripping tags and normalizing whitespace.
@@ -94,9 +103,9 @@ function htmlToText(html) {
 }
 
 /**
- * Recursively find all HTML files in a directory.
+ * Recursively find all files with a given extension in a directory.
  */
-function findHtmlFiles(dir, files = []) {
+function findFiles(dir, ext, files = []) {
   if (!fs.existsSync(dir)) {
     return files;
   }
@@ -106,15 +115,29 @@ function findHtmlFiles(dir, files = []) {
   for (const entry of entries) {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      findHtmlFiles(fullPath, files);
-    } else if (entry.name.endsWith(".html")) {
+      findFiles(fullPath, ext, files);
+    } else if (entry.name.endsWith(ext)) {
       files.push(fullPath);
     }
   }
 
   return files;
 }
 
+/**
+ * Recursively find all HTML files in a directory.
+ */
+function findHtmlFiles(dir) {
+  return findFiles(dir, ".html");
+}
+
+/**
+ * Find all markdown files in a directory (non-recursive, excludes llm-summary.txt).
+ */
+function findMarkdownFiles(dir) {
+  return findFiles(dir, ".md");
+}
+
 /**
  * Get the relative URL path for a file.
  */
@@ -182,10 +205,14 @@ function main() {
       continue;
     }
 
-    const htmlFiles = sortByImportance(findHtmlFiles(dirPath));
-    console.log(`Found ${htmlFiles.length} HTML files in ${apiDir.dir}`);
+    const isMarkdown = apiDir.format === "markdown";
+    const files = isMarkdown
+      ? findMarkdownFiles(dirPath)
+      : sortByImportance(findHtmlFiles(dirPath));
+    const ext = isMarkdown ? ".md" : ".html";
+    console.log(`Found ${files.length} ${isMarkdown ? "markdown" : "HTML"} files in ${apiDir.dir}`);
 
-    if (htmlFiles.length === 0) {
+    if (files.length === 0) {
       continue;
     }
 
@@ -195,30 +222,43 @@ function main() {
     fullContentSection += `## ${apiDir.name}\n\n`;
     fullContentSection += `${apiDir.description}\n\n`;
 
-    // Process only index files for links to avoid overwhelming the llms.txt
-    const indexFiles = htmlFiles.filter(
-      (f) => f.endsWith("index.html") || f.includes("/fn.") || f.includes("/struct.") || f.includes("/trait.")
-    );
-
-    // Add links for key files
-    for (const file of indexFiles.slice(0, 100)) {
-      // Limit to 100 links per section
-      const urlPath = getUrlPath(file, STATIC_DIR);
-      const fileName = path.basename(file, ".html");
-      linksSection += `- [${fileName}](${urlPath})\n`;
-    }
+    if (isMarkdown) {
+      // For markdown API docs, add a link per file and include llm-summary.txt if present
+      const summaryPath = path.join(dirPath, "llm-summary.txt");
+      if (fs.existsSync(summaryPath)) {
+        linksSection += fs.readFileSync(summaryPath, "utf-8") + "\n\n";
+      }
+      for (const file of files) {
+        const urlPath = getUrlPath(file, STATIC_DIR);
+        const fileName = path.basename(file, ext);
+        linksSection += `- [${fileName}](${urlPath})\n`;
+      }
+    } else {
+      // For HTML API docs, process only index files for links
+      const indexFiles = files.filter(
+        (f) => f.endsWith("index.html") || f.includes("/fn.") || f.includes("/struct.") || f.includes("/trait.")
+      );
+
+      // Add links for key files
+      for (const file of indexFiles.slice(0, 100)) {
+        // Limit to 100 links per section
+        const urlPath = getUrlPath(file, STATIC_DIR);
+        const fileName = path.basename(file, ext);
+        linksSection += `- [${fileName}](${urlPath})\n`;
+      }
 
-    if (indexFiles.length > 100) {
-      linksSection += `- ... and ${indexFiles.length - 100} more files\n`;
+      if (indexFiles.length > 100) {
+        linksSection += `- ... and ${indexFiles.length - 100} more files\n`;
+      }
     }
 
     linksSection += "\n";
 
     // Add full content for all files
-    for (const file of htmlFiles) {
+    for (const file of files) {
       try {
-        const html = fs.readFileSync(file, "utf-8");
-        const text = htmlToText(html);
+        const raw = fs.readFileSync(file, "utf-8");
+        const text = isMarkdown ? raw.trim() : htmlToText(raw);
 
         if (text.length > 100) {
           // Only include if there's meaningful content

docs/scripts/augment_sitemap.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Post-build script to add static API documentation URLs to the sitemap.
+ *
+ * Docusaurus only includes its managed routes in sitemap.xml. This script
+ * appends entries for the auto-generated API docs in static/ that are
+ * copied to build/ but not indexed by the sitemap plugin.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const BUILD_DIR = path.join(__dirname, "..", "build");
+const SITE_URL = "https://docs.aztec.network";
+
+// Load version config to determine which version subdirectory to index.
+let developerVersionConfig;
+try {
+  developerVersionConfig = require("../developer_version_config.json");
+} catch {
+  developerVersionConfig = null;
+}
+
+const defaultType = developerVersionConfig?.mainnet
+  ? "mainnet"
+  : developerVersionConfig?.testnet
+    ? "testnet"
+    : null;
+
+if (!defaultType) {
+  console.warn("Warning: No default version found — skipping sitemap augmentation");
+  process.exit(0);
+}
+
+/**
+ * Recursively find all files with a given extension.
+ */
+function findFiles(dir, ext) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findFiles(fullPath, ext));
+    } else if (entry.name.endsWith(ext)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function main() {
+  const sitemapPath = path.join(BUILD_DIR, "sitemap.xml");
+
+  if (!fs.existsSync(sitemapPath)) {
+    console.error("Error: build/sitemap.xml not found. Run the build first.");
+    process.exit(1);
+  }
+
+  let sitemap = fs.readFileSync(sitemapPath, "utf-8");
+
+  // Aztec.nr API HTML files (skip raw markdown — those aren't browsable pages)
+  const nrApiDir = path.join(BUILD_DIR, `aztec-nr-api/${defaultType}`);
+  const htmlFiles = findFiles(nrApiDir, ".html");
+
+  if (htmlFiles.length === 0) {
+    console.log("No static API docs found to add to sitemap");
+    return;
+  }
+
+  // Build XML entries
+  const entries = htmlFiles
+    .map((file) => {
+      const relativePath = path.relative(BUILD_DIR, file).replace(/\\/g, "/");
+      return `<url><loc>${SITE_URL}/${relativePath}</loc><changefreq>monthly</changefreq><priority>0.3</priority></url>`;
+    })
+    .join("");
+
+  // Insert before closing </urlset>
+  sitemap = sitemap.replace("</urlset>", entries + "</urlset>");
+
+  fs.writeFileSync(sitemapPath, sitemap);
+  console.log(`Added ${htmlFiles.length} Aztec.nr API doc URLs to sitemap.xml`);
+}
+
+main();

docs/typesense.config.json

@@ -1,26 +1,43 @@
 {
   "index_name": "aztec-docs",
   "start_urls": [
-      "https://docs.aztec.network/"
+      "https://docs.aztec.network/",
+      {
+        "url": "https://docs.aztec.network/aztec-nr-api/mainnet/",
+        "selectors_key": "api-nr"
+      }
     ],
     "sitemap_urls": [
       "https://docs.aztec.network/sitemap.xml"
     ],
   "sitemap_alternate_links": true,
   "selectors": {
-    "lvl0": {
-      "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
-      "type": "xpath",
-      "global": true,
-      "default_value": "Documentation"
+    "default": {
+      "lvl0": {
+        "selector": "(//ul[contains(@class,'menu__list')]//a[contains(@class, 'menu__link menu__link--sublist menu__link--active')]/text() | //nav[contains(@class, 'navbar')]//a[contains(@class, 'navbar__link--active')]/text())[last()]",
+        "type": "xpath",
+        "global": true,
+        "default_value": "Documentation"
+      },
+      "lvl1": "header h1",
+      "lvl2": "header h2",
+      "lvl3": "header h3",
+      "lvl4": "header h4",
+      "lvl5": "header h5",
+      "lvl6": "header h6",
+      "text": "article p, article li, article td:last-child"
     },
-    "lvl1": "header h1",
-    "lvl2": "header h2",
-    "lvl3": "header h3",
-    "lvl4": "header h4",
-    "lvl5": "header h5",
-    "lvl6": "header h6",
-    "text": "article p, article li, article td:last-child"
+    "api-nr": {
+      "lvl0": {
+        "selector": "nav.sidebar h1 a",
+        "default_value": "Aztec.nr API Reference"
+      },
+      "lvl1": "main h1",
+      "lvl2": "main h2",
+      "lvl3": "main h3",
+      "lvl4": "main h4",
+      "text": "main .comments p, main .item-description, main li, main pre code"
+    }
   },
   "strip_chars": " .,;:#",
   "custom_settings": {