Troubleshooting

Start with the smallest command that matches the problem.

VitePress Build Fails

npm run docs:check
npm run docs:build

Common fixes:

• Add new pages to the VitePress sidebar in docs/.vitepress/config.mts.
• Use root asset paths like /brand/favicon-32x32.png for static files under docs/public/.
• Add title and description frontmatter to every docs page.
• Correct broken repository-relative links.

Index Configuration Fails

npm run validate:index
npm run test:index

Check that index.json matches schemas/index.schema.json, all configured roots remain inside the repository, referenced registry files exist, and secret values have not been copied into the contract.

MCP TypeScript Build Fails

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

Check that mcp/tsconfig.json includes the current source and test directories, resource names match the implementation, and repos/index.yaml remains parseable.

Slack Requests Are Denied

npm run slack:policy:check
npm run mcp:test

Check the exact workspace and channel IDs in slack/access-policy.json, allowed path prefixes and visibilities, request-signing secrets, and SLACK_ALLOWED_TEAM_ID when it is set. An empty or invalid policy denies access.

Workspace Validation Fails

npm run validate:workspaces
npm run test:workspaces

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