Developer documentation site

VitePress site published at developers.theneuralledger.com (alias devs.tnl.st).

Local development

cd developers
npm install
npm run dev      # http://localhost:5173

How the API reference stays accurate

api/*.md is generated — do not edit those files by hand. They are produced from openapi.snapshot.json, a committed copy of the published schema.

npm run refresh:openapi   # pull the live schema into the snapshot
npm run generate:api      # regenerate api/*.md from the snapshot

npm run build runs generate:api first, so a build always reflects the snapshot.

The generator fails the build if the spec contains an endpoint that no page covers. That guard is deliberate: when someone adds an endpoint to the API, the docs build breaks until it is grouped in scripts/generate-api-reference.mjs. Keeping it means the reference cannot silently fall behind the API.

Hand-written pages (guides/, mcp/, reference/) are not generated. When MCP tool schemas change in server/mcp/schemas.ts, update mcp/tools.md to match.

Deploying

The site is static. Build, then publish .vitepress/dist:

npm run build
rsync -a --delete .vitepress/dist/ wodo@wodomini:/srv/theneuralledger/developers-next/
ssh wodo@wodomini 'ln -sfn /srv/theneuralledger/developers-next /srv/theneuralledger/developers-current'

First-time server setup

Requires root on wodomini and DNS pointing at the host. Both are one-time steps:

1. Create DNS A/AAAA records for developers.theneuralledger.com and devs.tnl.st pointing at the wodomini public address.

2. Install the vhost and certificate:

   sudo cp deploy/nginx-developers.conf /etc/nginx/sites-available/developers.conf
   sudo ln -s /etc/nginx/sites-available/developers.conf /etc/nginx/sites-enabled/
   sudo certbot --nginx -d developers.theneuralledger.com -d devs.tnl.st
   sudo nginx -t && sudo systemctl reload nginx

The vhost serves /srv/theneuralledger/developers-current, so create that symlink before the first reload.

Keep both hostnames DNS-only (grey cloud). They currently resolve straight to the wodomini origin, which is why AI clients can read the docs. Proxying either one through Cloudflare would subject it to the zone's AI-crawler blocking and Managed robots.txt, and the docs would start returning 403 to exactly the clients they are written for. If you ever need the proxy, pair it with a Configuration Rule scoped to the hostname that disables both features, and set SSL to Full (strict).