Developer documentation for the Internet Computer — built with Astro + Starlight, deployed at docs.internetcomputer.org.

This repo is a ground-up rewrite of the ICP developer docs: a flat Diataxis structure (Getting Started, Guides, Concepts, Languages, Reference), content verified against pinned upstream repos, and a workflow built for both human contributors and AI coding agents from day one. It replaces the previous dfinity/portal (Docusaurus) site.

All core documentation sections are content-complete. Open tasks and future pages are tracked as GitHub Issues.

./scripts/setup.sh    # Initialize submodules and install dependencies
npm run dev           # Dev server at localhost:4321
npm run build         # Production build

docs/                   # All documentation (.md only)
├── getting-started/    # Tutorials
├── guides/             # How-to guides
├── concepts/           # Explanations
├── languages/          # Motoko (synced) + Rust (hand-written)
└── reference/          # Specs and reference
.sources/               # Pinned upstream source repos (read-only)
├── VERSIONS            # Current pinned versions for versioned submodules
└── ...                 # icp-cli, motoko, cdk-rs, icskills, examples, ...
AGENTS.md               # Contributor and agent instructions

Documentation lives in docs/ at the project root. Astro reads it via a symlink at src/content/docs/. Pages default to .md; .mdx is used only when a page needs interactive components (for example, language-synced tabs).

Open tasks are tracked as GitHub Issues. Content pages use the documentation label; infrastructure tasks use enhancement.

AGENTS.md is the single source of truth for contributors and AI agents alike. It covers branch naming, content authoring workflow, code conventions, PR submission, and how to handle feedback. CLAUDE.md symlinks to AGENTS.md.

Key rules at a glance:

• Use icp CLI commands in all examples — never dfx
• Use mo:core for all Motoko standard library imports — never mo:base

Use squash and merge to keep main history clean.

This project treats AI coding agents as first-class contributors. Agents (Claude Code, Codex, Cursor, etc.) write pages from source material in .sources/, verify code snippets, and address PR feedback. Human developers direct the work, review the output, and make structural decisions.

.sources/ contains pinned git submodules — CLI references, API signatures, code examples, skill files — that agents use as ground truth when writing and verifying content. Agents always read from .sources/ rather than training data.

./scripts/setup.sh    # Sets up submodules and npm deps
# Then open Claude Code or your preferred agent in the repo root.
# The agent reads AGENTS.md automatically.

The site is built per the Agent-Friendly Documentation Spec:

• /llms.txt — discovery index listing all pages with descriptions
• /<path>.md — clean markdown endpoint for every page (e.g., /concepts/canisters.md)
• Agent signaling — hidden element after <body> pointing to /llms.txt, plus <link rel="llms"> in <head>

These endpoints are generated at build time and updated automatically on every deploy.

See LICENSE.