Troubleshooting

Start with the smallest command that matches the problem. Most docs failures fall into generation drift, missing navigation, stale dependencies, or a broken local link.

VitePress Build Fails

Run:

npm run docs:check
npm run docs:build

Common fixes:

• Run npm run docs:generate when docs/reference/cli.md or docs/reference/profiles.md is stale.
• Add new pages to the VitePress sidebar in docs/.vitepress/config.mts.
• Use root public asset paths like /brand/favicon-32x32.png for files under docs/public/.
• Add title and description frontmatter to every docs page.

Cloudflare Deployment Fails

Run:

npm run docs:build
npx wrangler pages deploy docs/.vitepress/dist --project-name=bakerstreet-index --branch=main

Check:

• CLOUDFLARE_ACCOUNT_ID is set in CI or the local shell.
• CLOUDFLARE_API_TOKEN has permission to deploy to the Pages project.
• wrangler.toml still points to docs/.vitepress/dist.
• the Pages project name is bakerstreet-index.

Custom Domain Does Not Resolve

Check Cloudflare DNS for bakerstreet.tech:

• index.bakerstreet.tech should exist as a proxied record.
• the Pages project should list index.bakerstreet.tech as a custom domain.
• the deployed site should serve from https://index.bakerstreet.tech/.

MCP TypeScript Build Fails

Run:

npm run mcp:check
npm run mcp:test
npm run mcp:smoke

Check:

• mcp/tsconfig.json includes the current source and test directories.
• resource names in docs match the server implementation.
• repos/index.yaml remains parseable.

Workspace Validation Fails

Run:

npm run validate:workspaces
npm run test:workspaces

Check:

• date values use YYYY-MM-DD.
• people records and references point to existing files.
• enums match schemas/workspace.schema.json.
• secret-like keys are not accidentally committed as workspace metadata.

Generator Output Looks Wrong

Run:

npm run test:create-index
node generator/create-index.mjs --help
node generator/create-index.mjs --name "Dry Run" --output ./tmp-dry-run --profile public-template --dry-run

Check:

• profile names match files in generator/profiles/.
• feature names match the schema enum.
• flags override config file values intentionally.