Contributing and docs access

This repository

This checkout contains the Nuxt documentation website. The platform codebase is a proposed separate monorepo. Running this site does not run the intrnl control plane or customer workloads.

Local setup

Use Node.js 24 LTS and pnpm@12.5.1, as pinned in package.json. With Corepack available:

corepack pnpm install --frozen-lockfile
corepack pnpm dev

The normal development address is http://localhost:3000. The site uses Nuxt UI and Nuxt Content with the native SQLite connector. Set NUXT_PUBLIC_SITE_URL at build time when deploying somewhere other than the configured https://docs.intrnl.cloud default. The default URL is a configuration choice, not evidence of a live deployment.

Authoring

Pages live under content/ and require frontmatter title and description. Numeric filename prefixes order navigation (use zero padding for sections with ten or more pages); they are not part of public URLs. Section titles and icons live in .navigation.yml. The landing page is content/index.md.

Use root-relative public routes for internal links. Add useful cross-links between architecture, delivery requirements, and operations. Tables and code fences should describe the plan accurately; examples with ellipses are illustrative, not runnable samples. Keep placeholders and proposed contracts clearly labeled.

Maintain the 31-section coverage index and the decision register. Record implementation evidence before changing a phase from planned to accepted. Preserve all definition-of-done requirements.

Validation

corepack pnpm lint
corepack pnpm typecheck
corepack pnpm build

The production build prerenders linked pages. Check the changed routes, search, table of contents, raw Markdown, and mobile navigation. Every new category must be included in the LLM sections in nuxt.config.ts.

Machine-readable documentation

• /llms.txt is the categorized documentation index.
• /llms-full.txt contains the full documentation.
• /raw/architecture.md is the architecture page as Markdown; other docs use the same /raw/<page-path>.md pattern.
• The documentation MCP endpoint is /mcp, with read-only list-pages and get-page tools. Discover a page path with list-pages, then supply it to get-page.

These endpoints read the content served by this site. They do not grant application access, mutate source, build applications, or request deployment. The organization-aware platform tools at mcp.intrnl.cloud are a separate planned service.

Connect with Codex

Add the public documentation server using the Codex CLI:

codex mcp add intrnl-docs --url https://docs.intrnl.cloud/mcp

No login, API key, or bearer token is required. Start a new Codex session, then use /mcp to check that intrnl-docs is connected. You can also run codex mcp list in your terminal to check the saved configuration.

Try this prompt:

Use intrnl-docs to explain our runtime contract and cite the relevant documentation.

Codex can use list-pages to find relevant pages, then get-page with a discovered path such as /development/runtime-contract to read their full Markdown.

For manual configuration, add this entry to ~/.codex/config.toml instead of running the add command:

[mcp_servers.intrnl-docs]
url = "https://docs.intrnl.cloud/mcp"

If the server is missing from /mcp, check the saved configuration and restart your Codex session or IDE extension. See OpenAI's MCP configuration guide for client setup details.

Publication boundary

The pages use generic organization examples and describe detailed architecture. Keep deployment access aligned with the intended documentation audience. No remote deployment or publication is performed merely by editing this repository.