Improve public API docs SEO and Mintlify metadata

[claudfuen]

Summary

• Broadened the public Comp AI API docs from questionnaire-only metadata to a full compliance automation API surface: evidence, tasks, policies, knowledge base, Trust Access, Trust Center, frameworks, controls, integrations, cloud checks, devices, people, training, vendors, risks, findings, SOA, and pentests.
• Added a durable OpenAPI metadata layer in apps/api/src/openapi/* for Mintlify titles, descriptions, tags, content, code samples, production server URLs, SEO-safe fallbacks, and route/schema pruning.
• Centralized the public-docs quality gate so generation and tests enforce the same rules for missing summaries, Mintlify metadata, SEO length, duplicate/sensitive surfaces, and private schema details.
• Regenerated packages/docs/openapi.json from the NestJS source so Mintlify gets production https://api.trycomp.ai, complete x-mint.metadata, and no localhost examples.
• Kept legitimate API-key/product APIs documented, including Trust Access request/grant management and public Trust Center data, while excluding app token/session plumbing such as questionnaire token upload and Trust Access reviewer-session routes.
• Removed internal/private surfaces from the public spec: platform-admin/internal/auth/framework-editor/browserbase/assistant/health/email unsubscribe/webhook paths, Secrets, Billing, background checks, pentest credits, finding templates, OAuth setup internals, cloud remediation/legacy internals, and unused sensitive schemas.
• Reworked authored docs positioning in packages/docs: API overview, introduction, Trust Access, and Security Questionnaire now point readers to API-key based automation instead of token-session implementation details.
• Added Mintlify redirects for /api, /docs/api, removed token-questionnaire docs, and excluded/stale API reference groups.

Ahrefs Legitimacy Report

• Legitimate: API docs had widespread missing/short/long metadata. The regenerated OpenAPI now has x-mint.metadata on all retained public operations with enforced title/description length bounds.
• Legitimate: generated docs used localhost server data. The public spec now always uses https://api.trycomp.ai.
• Legitimate: /docs/api and /api were broken/ambiguous docs routes. The docs config now redirects both to /api-reference/overview and avoids Mintlify reserved path behavior.
• Legitimate but sensitive: some routes should not be public SEO targets. The public OpenAPI generator now removes those paths and prunes unused sensitive component schemas instead of relying on hidden pages.
• Corrected after review: token/session endpoints are app/frontend plumbing, not the public integration contract. API-key backed product APIs remain documented broadly across Comp AI.
• Not changed here: canonical feedback appears already addressed by recent commits, so this PR keeps focus on public docs metadata, route visibility, and authored docs quality.

Verification

• bunx jest src/openapi-docs.spec.ts --runInBand
• GEN_OPENAPI=1 bunx jest src/gen-openapi.spec.ts --runInBand
• git diff --check
• Generated spec audit: 276 public paths, 32 tags, production server URL, 0 duplicate Mintlify titles, no questionnaire token upload route, no Trust Access session/NDA routes, Trust Access admin APIs retained, public Trust Center APIs retained.
• Sensitive scan of packages/docs/openapi.json: 0 hits for token upload/session routes, FedRAMP, internal finding-template details, secret disclosure enum, pipeline/test flags, localhost, or generated boilerplate fragments.

Notes

• bun run typecheck in apps/api still fails on current-main issues unrelated to this diff, including @trycompai/billing module resolution, existing better-auth access-control typing, framework manifest fixture types, integration-platform manifest/spec mismatches, and several existing test mock signatures.
• Three generated Prisma schema files are still untracked locally and intentionally not included in this PR.
• Mintlify references used: OpenAPI customization, x-mint metadata/content, code samples, page visibility, redirects, and the reserved /api path warning.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
CompAI	🟢 Ready	View Preview	May 10, 2026, 5:09 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
comp-framework-editor	Ready	Preview, Comment	May 10, 2026 9:30pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
app	Skipped		May 10, 2026 9:30pm
portal	Skipped		May 10, 2026 9:30pm

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

[cubic-dev-ai]

1 issue found across 7 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/docs/api-reference/overview.mdx">

<violation number="1" location="packages/docs/api-reference/overview.mdx:10">
P2: Narrow the auth wording here; not all API workflows use `X-API-Key`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review, or fix all with cubic.}