From 44042eba86e9ea60218dc38910216ca608095fee Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 13 May 2026 17:43:39 +0200 Subject: [PATCH 1/9] =?UTF-8?q?chore:=20post-migration=20cleanup=20?= =?UTF-8?q?=E2=80=94=20drop=20planning=20artifacts=20and=20move=20to=20mai?= =?UTF-8?q?ntenance=20mode?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Migration is complete. All Learn Hub articles migrated; portal submodule removed; all content PRs merged. This commit closes issue #224 and brings AGENTS.md into maintenance mode. Changes: - Remove .docs-plan/decisions.md (decisions are baked into the codebase; new structural choices go in PR descriptions per issue #224 guidance) - Remove .docs-plan/migration-plan.md, synthesis.md, developer-journey.md, icp-cli-examples-inventory.md, jssdk-skills-mapping.md (migration-phase artifacts with no ongoing value; each was >170 lines loaded on every relevant task, burning context tokens for nothing) - Update AGENTS.md: remove decisions.md/migration-plan references, simplify Quick Orientation (7 steps → 4), replace "record in decisions.md" with "document in PR description", replace "not in migration plan" guard with "needs a GitHub Issue", remove stale "Previous work" section - Update .docs-plan/README.md: strip migration-era table; keep only the two evergreen workflow files (content-authoring.md, review-guidelines.md) - Update .docs-plan/content-authoring.md: remove decisions.md pointer and dead "Beads status" submit step Closes #224 --- .docs-plan/README.md | 37 +- .docs-plan/content-authoring.md | 4 +- .docs-plan/decisions.md | 322 -------------- .docs-plan/developer-journey.md | 526 ----------------------- .docs-plan/icp-cli-examples-inventory.md | 372 ---------------- .docs-plan/jssdk-skills-mapping.md | 173 -------- .docs-plan/migration-plan.md | 419 ------------------ .docs-plan/synthesis.md | 223 ---------- AGENTS.md | 23 +- 9 files changed, 11 insertions(+), 2088 deletions(-) delete mode 100644 .docs-plan/decisions.md delete mode 100644 .docs-plan/developer-journey.md delete mode 100644 .docs-plan/icp-cli-examples-inventory.md delete mode 100644 .docs-plan/jssdk-skills-mapping.md delete mode 100644 .docs-plan/migration-plan.md delete mode 100644 .docs-plan/synthesis.md diff --git a/.docs-plan/README.md b/.docs-plan/README.md index f290d7d9..6117c23d 100644 --- a/.docs-plan/README.md +++ b/.docs-plan/README.md @@ -1,49 +1,20 @@ # ICP Developer Docs — Planning Artifacts -This directory contains analysis, design decisions, and workflow references for the ICP developer documentation. +This directory contains workflow references for the ICP developer documentation. ## I'm an agent. What do I do? 1. **Read `AGENTS.md`** (project root) — rules, boundaries, content guidelines -2. **Read `decisions.md`** — understand past structural decisions before proposing new ones -3. **Find your next task** in [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` -4. **Get execution details** — read the stub file itself (has content brief, source material, cross-links in HTML comments), then check `migration-plan.md` for dependencies, effort estimate, and skills needed -5. **Do the work** following `AGENTS.md` rules -6. **Record decisions in `decisions.md`** if you made any structural choices +2. **Find your next task** in [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` +3. **Do the work** following `AGENTS.md` rules ## Files -### Living documents (check these every session) - -| File | What it answers | -|------|-----------------| -| `decisions.md` | "Has this been decided already?" — append-only decision log | -| `migration-plan.md` | "How do I execute this task?" — dependencies, source material, effort, skills per page | - -### Agent workflow references - | File | What it answers | |------|-----------------| | `content-authoring.md` | "How do I write a page?" — full content workflow, content rules, linking rules, external docs | -| `review-guidelines.md` | "How do I review a PR?" — mechanical checks, content quality checks, post format | - -### Context files (read when writing specific pages) - -| File | What it answers | -|------|-----------------| -| `synthesis.md` | "Why is the structure this way?" — full structure proposal with rationale | -| `jssdk-skills-mapping.md` | "Which icskills and JS SDK docs are relevant?" — 17 skills + 5 SDK projects | -| `icp-cli-examples-inventory.md` | "Which CLI docs, recipes, templates, examples to reference?" — full ecosystem | -| `developer-journey.md` | "How does this page fit the developer journey?" — Zero-to-Production stages | +| `review-guidelines.md` | "How do I review a PR?" — full review checklist | ## Source repos All source repos are pinned as git submodules under `.sources/` — see `AGENTS.md` → "Source material repos" for the full mapping and rules. - -## Previous work - -Branch `restructuring-attempt-1` contains the previous restructuring attempt with: -- Full Astro+Starlight infrastructure -- 124 docs pages (52 Motoko synced + 70 hand-written) -- CI workflows, sync scripts, validation scripts -- `DOCS_RESTRUCTURING_PROPOSAL.md` (v3.1) diff --git a/.docs-plan/content-authoring.md b/.docs-plan/content-authoring.md index 347ea49b..788b70ac 100644 --- a/.docs-plan/content-authoring.md +++ b/.docs-plan/content-authoring.md @@ -19,7 +19,7 @@ When drafting a new docs page: - **Verify all internal links** — every `[text](path.md)` must point to a file that exists. Run `ls ` before submitting. If the target page doesn't exist, either link to an existing page that covers the topic, or file a page proposal issue and note the missing link in your PR description. Never link to a path that doesn't exist. - **Verify all external URLs** — use the linking rules table in AGENTS.md for known resources. For any URL not in the table (crate docs, npm packages, GitHub repos), verify it is correct. Do not guess or generalize from similar URLs (e.g., `docs.rs/ic-cdk` is NOT the same as `docs.rs/ic-stable-structures`). - **Self-consistency check** — before submitting, re-read your frontmatter description and body opening paragraph. They must not contradict each other (e.g., different time estimates, different scope claims). - - Use `.md` by default. Use `.mdx` only when the page needs interactive components like `` (see `.docs-plan/decisions.md`). In `.mdx` files, use `{/* */}` for comments instead of ``. + - Use `.md` by default. Use `.mdx` only when the page needs interactive components like ``. In `.mdx` files, use `{/* */}` for comments instead of ``. - **Stub → `.mdx` rename:** All stubs are `.md` files. If your page needs tabs (e.g., Motoko/Rust examples in the same section), rename the stub from `.md` to `.mdx`, delete the old `.md` file, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert any `` comments to `{/* */}`. Internal links pointing to `.md` do not need updating — Astro resolves both extensions. - Ensure complete frontmatter (see CONTRIBUTING.md) - **Code examples — check for snippet pipeline first:** Before writing inline code, check whether the example exists in `.sources/examples` with `#region` markers: @@ -57,7 +57,7 @@ When drafting a new docs page: Consider syncing when the upstream content is comprehensive, well-maintained, and a close fit. Prefer hand-writing when the page synthesizes multiple sources or serves a different audience than the upstream. **This must appear in two places:** (1) as a comment in the page file, and (2) as a "Sync recommendation" section in the PR body (see the PR template in "Submitting" in AGENTS.md). Both are required. 6. **Propose missing pages:** If source material reveals topics that aren't covered by any existing page in the plan (e.g., a canister migration guide in icp-cli with no corresponding docs page), create a GitHub Issue with the `page-proposal` label. Include: what the page would cover, where it would live in the structure, and which upstream source it would draw from. Reference the issue in your PR description. Do not create the page — just flag it for human discussion. -7. Submit: push branch, create PR, update Beads status to `draft` (see "Multi-agent workflow" in AGENTS.md) +7. Submit: push branch, create PR (see "Submitting" in AGENTS.md) 8. Review by the relevant team (see `.github/CODEOWNERS` and CONTRIBUTING.md review ownership table) ## Content rules diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md deleted file mode 100644 index 2b531621..00000000 --- a/.docs-plan/decisions.md +++ /dev/null @@ -1,322 +0,0 @@ -# Design Decisions Log - -Record decisions that constrain future work — things an agent needs to know that aren't obvious from the code. Remove entries that are fully reflected in the current codebase (renames, file moves, cleanup). - ---- - -## 2026-05-06: Learn Hub migration — structure, staging, and sequencing - -**Context:** `learn.internetcomputer.org` (a Zendesk Help Center with ~86 articles) is being retired. Developer-relevant content must move into this docs site before the site goes down. Issues #187 and #190 document the full gap analysis. About 27 articles are end-user content (NNS dapp UI, wallet flows, network stats, vision/history) and are explicitly out of scope for developer docs. - -**Decision:** - -1. **`concepts/` subdirectory structure.** The flat 14-file layout cannot absorb ~20 additional pages cleanly. Add two subdirectories: - - `docs/concepts/protocol/` — six protocol-layer pages (consensus, P2P, message routing, execution, state sync, overview) - - `docs/concepts/chain-fusion/` — per-chain architecture pages; the existing `concepts/chain-fusion.md` moves to `concepts/chain-fusion/index.md` - - All other new pages stay flat under `docs/concepts/` (node-infrastructure, edge-infrastructure, evolution-scaling, certified-data, principals, tokenomics, token-ledgers, sns-framework) - -2. **Source staging.** All Learn Hub articles are committed as raw Markdown into `.migration/learn-hub/`, preserving the original category/section folder structure, before any content PRs are opened. Each batch PR reads from the staging files, writes proper docs pages, and deletes the staging files in the same commit. When `.migration/learn-hub/` is empty, the directory is removed and the migration is done. Each migrated page uses `` — no ongoing sync relationship. PR sync recommendation: `hand-written`. - -3. **End-user articles are out of scope.** All articles under "What is ICP?" (marketing/vision), "How can I use ICP? / Governance" (NNS dapp UI flows), "How can I use ICP? / Tokens & wallets" (quill/wallet how-tos), and "How can I use ICP? / Network stats" are not migrated into developer docs. Their disposition (NNS dapp help, IC dashboard help, marketing site) is handled outside this repo. - -4. **Batched PRs.** One `infra/learn-hub-migration-prep` PR does structural setup (staging files, decisions, navigation map, sidebar config, CLAUDE.md rule updates). Then 9 content PRs (`docs/`) migrate topic batches. See `.docs-plan/learn-hub-navigation.md` for the full batch-to-file mapping. - -5. **CLAUDE.md rule retirement.** Two rules reference Learn Hub and must be updated once all batch PRs are merged: - - The "never duplicate Learn Hub" line in the "Never" section must drop the Learn Hub reference. - - The "link to Learn Hub or explain inline" line in the "Never link to old docs" decision (2026-03-13 below) must be replaced with an instruction to link internally. - After the final batch PR merges, open a follow-up `infra/` PR to make these two edits. - -**Rationale:** Staging files in `.migration/learn-hub/` give every agent a stable, repo-local source to read before writing — consistent with the `.sources/` discipline for all other upstream content. Deleting staging files in the same PR as the content write makes progress unambiguous and prevents the staging directory from drifting out of sync. Subdirectories in `concepts/` are needed for the sidebar to remain navigable; two subdirs (not five) keeps the nesting shallow. - -**When to revisit:** Once `.migration/learn-hub/` is deleted in the final content PR, update this entry to "fully reflected in codebase" and remove it. - ---- - -## 2026-04-27: CLI and language tabs are always separate - -**Context:** Some pages were mixing CLI commands into the same `` group as Motoko and Rust code. Other pages (e.g. `cycles-management.mdx`, `lifecycle.mdx`) kept CLI as standalone blocks with language tabs appearing separately. The mixed approach creates an awkward tab for users who just want a quick CLI command. -**Decision:** CLI commands always appear as standalone code blocks, never inside a `` group. When a section has both a CLI command and language-specific code, the CLI block comes first (quick-check path), followed by the `` group (integration path). Tab order within language tabs remains Motoko → Rust → others per CLAUDE.md. -**Rationale:** CLI and code serve different audiences and mental models. CLI is for quick ad-hoc use; language code is for building integrations. Mixing them forces one audience to click past irrelevant tabs. Placing CLI first gives the faster answer to the more common case. -**When to revisit:** If a section has no meaningful CLI equivalent, omit it — don't add a CLI block just for consistency. - ---- - -## 2026-04-27: ICRC standards reference restructured into index + detail pages - -**Context:** `references/token-standards.md` mixed two unrelated standard families (digital asset standards ICRC-1/2/3/7/37 and wallet signer standards ICRC-21/25/27/29/49) under a title that didn't fit either category cleanly. The page also used "token" as a primary descriptor, conflicting with the brand voice push toward "digital assets." -**Decision:** Split into two pages. `references/icrc-standards.md` is a lightweight index of all ICRC standards grouped by category (extensible for future standards). `references/digital-asset-standards.md` (renamed from `token-standards.md`) is the deep reference for ICRC-1/2/3/7/37 only. Wallet signer standard detail stays in the wallet integration guide; the index page links to it. `guides/digital-assets/token-ledgers.mdx` renamed to `guides/digital-assets/ledgers.mdx`. -**Rationale:** "Token Standards" as a page title was inaccurate (covered signers too) and jargon-heavy. "ICRC Standards" as a single page title would be too broad (implies ALL ICRC work). Separating the index from the detail page gives a clean extensible home for future ICRC standards without forcing unrelated content together. -**When to revisit:** If wallet signer content grows enough to warrant its own `references/signer-standards.md`, add it to the index and link from there. - ---- - -## 2026-04-24: Developer Tools is a top-level sidebar item, not a section - -**Context:** The tools overview page (`references/developer-tools.md`) is a toolchain catalog — not a how-to guide, concept explanation, or specification. It doesn't fit cleanly in any Diataxis quadrant. It was previously under `guides/tools/` and then considered for Reference. -**Decision:** Expose it as a single flat top-level sidebar link between Concepts and Languages. The sidebar order is: Getting Started → Guides → Concepts → Developer Tools → Languages → Reference. The file lives at `docs/references/developer-tools.md` with `sidebar: hidden: true` to suppress it from the Reference autogenerate; `sidebar.mjs` references it explicitly via `{ slug: "reference/developer-tools", label: "Developer Tools" }`. -**Rationale:** A catalog page warrants top-level visibility. Placing it between Concepts and Languages follows the natural developer flow: understand the platform, know the tools, then go deep on your language. Single flat link (no collapsible) is correct while it remains one page. -**When to revisit:** If the tools section grows to multiple pages (dedicated icp-cli reference, JS SDK getting-started, PocketIC advanced guide), convert to a collapsible group with `autogenerate` from a new `docs/tools/` directory and update this decision. - ---- - -## 2026-04-23: icp-brand-guidelines skill lives directly in the repo - -**Context:** The `icp-brand-guidelines` skill was added to support design/brand work on the docs (CSS tokens, typography, voice). No upstream repo exists for it yet. -**Decision:** Committed directly under `.agents/skills/icp-brand-guidelines/` (real directory, not a submodule). Symlinked from `.claude/skills/icp-brand-guidelines`. If the skill is later published to a DFINITY repo, migrate to a submodule then. -**Rationale:** No upstream repo to pin. All other skills are submodule-backed; this is the only exception. The skill contains `SKILL.md` and `assets/tokens.css`. - ---- - -## 2026-04-23: ICP brand guidelines applied to docs design - -**Context:** New `icp-brand-guidelines` skill defines the visual and verbal system for all DFINITY/ICP surfaces. -**Decision:** Switched docs theme from dark-first/purple to light-default/terracotta. Newsreader serif added for headings. Custom `ThemeProvider` overrides Starlight's default to prevent auto-switching on `prefers-color-scheme`. -**Rationale:** Brand skill spec: "Light mode is the default. Dark mode is opt-in. Never use `prefers-color-scheme` to auto-switch." - ---- - -## 2026-04-17: Added chain-fusion-signer, papi, ic-pub-key submodules -**Context:** Page proposal #24 (chain-fusion signer guide) required source material not yet in `.sources/` -**Decision:** Added three new release-pinned submodules: `chain-fusion-signer` (v0.3.0), `papi` (v0.1.1), `ic-pub-key` (v1.0.1) -**Rationale:** All three are needed to write accurate code examples — signer API, ICRC-2 payment setup, and CLI usage respectively. All follow "track latest release" strategy. - -## 2026-03-11: Diataxis framework with 5 top-level sections -**Context:** Need a clear information architecture for the new developer docs -**Decision:** Use Diataxis with 5 sections: Getting Started (tutorials), Guides (how-to), Concepts (explanations), Languages (synced + hand-written), Reference (information) -**Rationale:** Diataxis is proven, maps cleanly to developer intent ("how do I" vs "what is" vs "exact params"). Languages gets its own section due to volume (52+ synced Motoko pages). -**Alternatives considered:** 10-section structure (too many groups), single guides section (too flat), capabilities as top-level (not a Diataxis quadrant) - -## 2026-03-11: No separate capabilities section -**Context:** IC capabilities (chain-key, VetKeys, HTTPS outcalls, timers, randomness) are the platform's biggest differentiators -**Decision:** Keep capabilities in concepts/ (explanation) with companion how-to guides in guides/backends/ (task-oriented) -**Rationale:** A "capabilities" section is marketing-oriented, not Diataxis-aligned. Developers find content by intent: "what is chain-key" → concepts/, "how to make HTTPS outcalls" → guides/backends/ -**Alternatives considered:** Top-level capabilities section (violates Diataxis), capabilities under guides only (loses explanatory depth) - -## 2026-03-11: Code examples — inline vs link to examples repo -**Context:** Need a consistent strategy for code in docs -**Decision:** Inline code for snippets under ~30 lines. Link to dfinity/examples repo for anything larger. Prefer linking when possible — examples repo has CI, tests, and versioning. Only inline when the `technical-documentation` skill determines it's essential for the page. -**Rationale:** Short snippets aid reading flow. Long examples are better maintained in a dedicated repo with tests. Inline code rots. -**Alternatives considered:** Always inline (maintenance burden), always link (poor reading experience) - -## 2026-03-11: icp-cli content — link, don't duplicate -**Context:** icp-cli has its own comprehensive docs at cli.internetcomputer.org/ -**Decision:** Link to icp-cli docs. Inline icp-cli commands in guides where they aid reading flow. Don't duplicate guides. -**Rationale:** Single source of truth. The migration guide is the only exception (synced). -**Alternatives considered:** Sync more content (maintenance burden), duplicate quickstart (violates single-source principle) - -## 2026-03-11: docs/ is the canonical content directory -**Context:** Astro/Starlight expects content at `src/content/docs/`, but `docs/` at root is the natural location for documentation -**Decision:** Real files live in `docs/` (project root). `src/content/docs/` is a symlink pointing to `../../docs`. All agent instructions and documentation reference `docs/` as the canonical path. -**Rationale:** `docs/` is shorter, more discoverable, and the standard convention. Astro follows the symlink transparently — builds work unchanged. -**Alternatives considered:** Keep files in `src/content/docs/` (forces long paths), no symlink (agents navigate three levels deep) - -## 2026-03-11: Motoko sidebar pre-configured, no stubs for synced content -**Context:** Motoko docs (~60 files across fundamentals/, icp-features/, reference/) are synced from `caffeinelabs/motoko` via a sync script on `restructuring-attempt-1` -**Decision:** Keep the sidebar config with `autogenerate` directives for the three Motoko subdirectories. Do not create stub files — they would be overwritten by the sync. Only the hand-written `index.md` (overview) exists as a stub. -**Rationale:** `autogenerate` picks up files automatically once the sync runs. Creating 60 stubs adds no value and creates merge noise. -**Alternatives considered:** Create stubs for all 60 pages (would be overwritten), wait to configure sidebar until sync is restored (risks forgetting the structure) - -## 2026-03-11: Image/asset strategy — `src/assets/images/` with section-based organization -**Context:** Portal has hand-drawn diagrams worth carrying over. No image strategy existed for the new docs. -**Decision:** Images live in `src/assets/images/`, organized by docs section (concepts/, guides/canister-management/, etc.). Carry over portal images case-by-case during content writing — not bulk-imported upfront. Keep the existing hand-drawn visual style. Use descriptive kebab-case filenames. -**Rationale:** `src/assets/` enables Astro image optimization (Sharp). Section-based organization mirrors the docs structure. -**Alternatives considered:** `public/images/` (no optimization), co-located images next to .md files (clutters docs/), bulk import all portal images (wasteful) - -## 2026-03-11: Use relative paths with `.md` extension for internal links -**Context:** Absolute paths like `/getting-started/quickstart/` broke on GitHub -**Decision:** All internal links must use relative paths with `.md` extension (e.g., `[Quickstart](getting-started/quickstart.md)`). A remark plugin (`plugins/remark-strip-md-extension.mjs`) strips `.md` at build time. -**Rationale:** Works on GitHub natively and on the Astro site after the plugin strips extensions. -**Alternatives considered:** Absolute paths (break on GitHub), paths without extension (break on GitHub) - -## 2026-03-11: Motoko core library is the standard; base is legacy -**Context:** The Motoko `core` library (`mops.one/core`) supersedes `base` -**Decision:** Always recommend `core` over `base` in all docs. Link to `mops.one/core/docs` as the standard library reference. The base→core migration guide is synced from `caffeinelabs/motoko` — do not edit directly. -**Rationale:** `core` is actively developed with AI-friendly design, consistent naming, and stable memory support. `base` is legacy. -**Alternatives considered:** List both as equal options (confusing, encourages legacy use) - -## 2026-03-11: Use "onchain" and "offchain" — no hyphens -**Context:** Inconsistent usage across docs (on-chain vs onchain, off-chain vs offchain) -**Decision:** Always use "onchain" and "offchain" (no hyphens) in all docs content. Never "on-chain", "off-chain", "on chain", or "off chain". -**Rationale:** "Onchain" is the prevailing convention in ICP ecosystem. "Offchain" follows the same pattern for consistency. - -## 2026-03-13: Use "icp-cli" not "`icp` CLI" in prose -**Context:** Inconsistent references to the CLI tool — some pages say "the `icp` CLI", others say "icp-cli" -**Decision:** Always use "icp-cli" when referring to the tool/project in prose. Use `icp` (code-formatted) only when showing the literal command the user types (e.g., `icp deploy`). Never write "the `icp` CLI" or "the icp command-line tool". -**Rationale:** "icp-cli" is the official project name and is consistent with how the tool is referenced in its own docs and repo. Using the project name avoids ambiguity. - -## 2026-03-11: Content writing pacing — batch per sprint -**Context:** Need a review strategy for content pages -**Decision:** Write all pages in a sprint as a batch, then review together. After each sprint, do a cross-reference verification pass. -**Rationale:** Batching allows cross-referencing between pages in the same sprint. Post-sprint verification catches broken links early. -**Alternatives considered:** One page at a time with review (too slow), no verification pass (broken links accumulate) - -## 2026-03-11: Content writing before infrastructure restoration -**Context:** P0 infrastructure tasks (validation scripts, sync scripts) are pending alongside P0 content. -**Decision:** Start content writing before restoring validation/sync scripts. Infra is not blocking content work. -**Rationale:** Validation scripts catch issues but don't prevent writing. Content is the primary deliverable. -**Alternatives considered:** Infra first (delays content), in parallel (splits focus) - -## 2026-03-11: CI deployment to IC asset canister -**Context:** Docs needed automated deployment to the Internet Computer for live preview. -**Decision:** Deploy to asset canister `2akpg-uqaaa-aaaal-qv5ha-cai` on every push to `main` via GitHub Actions + icp-cli. Custom domain: `beta-docs.internetcomputer.org`. Asset canister configured with `.ic-assets.json5` (no raw access, standard security headers, immutable caching for hashed `_astro/` assets). Canister ID stored in `.icp/data/mappings/ic.ids.json` (committed). Deployer identity imported from `DFX_IDENTITY_DESIGN_TEAM` secret in `IC mainnet` GitHub environment. -**Rationale:** Matches the pattern used by icskills repo. icp-cli is the standard deployment tool. Raw access disabled for security. -**Alternatives considered:** Deploy via dfx (deprecated), manual deployment (error-prone) - -## 2026-03-12: Corrected dependency layers and execution order for content writing -**Context:** Analysis of stub page cross-links revealed dependency errors in the original sprint ordering. -**Decision:** (1) Reordered Sprint 1 to write Layer 0 concept pages before getting-started pages. (2) Swapped candid before onchain-calls in Sprint 2. (3) Added `orthogonal-persistence` as explicit dependency for `data-persistence`. (4) Moved `what-next.md` to end of Sprint 1. (5) Added Layer column and "Dependency Layers" section to `migration-plan.md`. -**Rationale:** Correcting the dependency order ensures agents don't start pages before their prerequisites exist. The critical path is 6 layers deep. -**Alternatives considered:** Keep original ordering with "soft" dependencies (risks broken cross-links) - -## 2026-03-12: Adopt Beads for multi-agent task coordination -**Context:** Multiple developers will run agents in parallel. `progress.md` on `main` can't reflect in-flight work on unmerged branches. -**Decision:** Use [Beads](https://github.com/steveyegge/beads) (`bd`) as the coordination layer for all migration work. Key design choices: - -- **Scope:** All tasks in `migration-plan.md` — content pages, infrastructure, and any future tasks. -- **Task states:** `open` → `in_progress` (claimed) → `draft` (PR opened) → `closed` (PR merged) -- **Soft dependencies:** A task is "unblocked" when all its dependencies are at least `draft`. -- **Stale claim timeout:** 1 hour. -- **Agent priority order:** (A) Fix "changes requested" PRs → (B) Rebase approved PRs with merge conflicts → (C) Pick new work via `bd ready` -- **Branch naming:** `docs/` for content, `infra/` for infrastructure tasks -- **PR-based review:** Any agent can pick up "changes requested" PRs, not just the original author. -- **Merge conflict policy:** Always rebase before pushing. Don't rebase PRs under review. Do rebase approved PRs blocked by conflicts. -- **`progress.md` deletion:** Once all tasks are imported into Beads, delete `progress.md`. Do not initialize Beads tasks until the migration plan is finalized. - -**Rationale:** Beads uses Dolt (version-controlled SQL) that syncs via `refs/dolt/data` — independent of content branches. Solves the branch-isolation problem. -**Alternatives considered:** GitHub Issues (no dependency graph), `progress.md` with merge-to-main cadence (agents blocked on merges), Linear/Jira (external dependency) - -## 2026-03-12: Per-page sync recommendations and content lifecycle preparation -**Context:** 80 pages will be written by agents, but we don't know upfront which should be synced from upstream repos vs. hand-written. -**Decision:** Three changes: -1. **Sync recommendation per page:** Every content PR must include an `` HTML comment classifying the page as `hand-written`, `sync from `, or `informed by `. -2. **Page proposals via GitHub Issues:** When agents discover uncovered topics, create a GitHub Issue with `page-proposal` label. Reference the issue in the PR. -3. **Content lifecycle strategy deferred to P2:** After Sprint 3-4, review sync recommendations, design upstream change detection, assign freshness ownership, and triage `page-proposal` issues. -**Rationale:** Collecting sync signals during writing is cheap and provides data for the lifecycle strategy later. GitHub Issues are the natural forum for humans to discuss page proposals. -**Alternatives considered:** Decide sync/hand-written upfront (premature), skip sync tracking (lose data) - -## 2026-03-12: Source material repos as pinned git submodules - -**Context:** Agents need to read source material from 7 upstream repos (portal, icp-cli, icp-cli-recipes, icp-cli-templates, icskills, examples, icp-js-sdk-docs). Without pinned refs, different agents could read different states of these repos, leading to inconsistent content. -**Decision:** Add all 7 source repos as shallow git submodules under `.sources/`. Pin each to a specific branch or tag: -- `portal` → `master`, `icp-cli` → `v0.2.0` (latest release tag), all others → `main`/`master` (their default branch) -- Agents must always read from `.sources/`, never from local clones, `gh api`, or training data -- Only the project maintainer bumps submodule refs -- When bumped, agents review upstream changes and update affected docs pages -**Rationale:** Submodules pin exact commits, ensuring reproducible reads across agents and sessions. Bumps are explicit and reviewable in PRs. -**Alternatives considered:** Document branch names only (agents still read different commits), local clones with documented paths (not portable), `gh api` fetches (slow, rate-limited, not reproducible) - -## 2026-03-13: Diataxis content-type rules — no CLI commands in concept pages - -**Context:** PR #2 (canisters concept page) included 6 `icp` CLI command blocks in the lifecycle section. Concept pages should explain *what* and *why*, not provide step-by-step procedures. The other concept pages (network-overview, app-architecture) correctly contained zero CLI commands, but the rule was implicit. -**Decision:** Added explicit Diataxis content-type rules to both CLAUDE.md ("Content rules") and CONTRIBUTING.md ("Content types (Diataxis)"). `concepts/` pages must not contain CLI commands or step-by-step procedures — link to the relevant guide instead. `getting-started/` and `guides/` pages may include CLI commands. `references/` pages use them sparingly for syntax examples only. -**Rationale:** Making the rule explicit prevents future agents from mixing procedural content into explanatory pages. The Diataxis framework is already a stated design choice but the per-section implications for CLI command usage were not spelled out. - -## 2026-03-13: Never link to internetcomputer.org/docs — it's being replaced - -**Context:** The quickstart page linked to `internetcomputer.org/docs/building-apps/...` for Candid concepts. These URLs come from icp-cli source material which references the old portal docs. -**Decision:** Never link to `internetcomputer.org/docs/` or `docs.internetcomputer.org` — these are the old docs being replaced by this project. Instead: (1) link to a page in this docs site using relative paths, even if it's still a stub, or (2) link to Learn Hub (`learn.internetcomputer.org`) for protocol internals, or (3) explain the concept inline if no suitable page exists yet. -**Rationale:** Old docs URLs will break once the new site replaces the old one. Linking to stubs is fine — they'll have content by the time the site launches. If a topic has no planned page, flag it as a page proposal. -**Alternatives considered:** Keep old links with a TODO to update later (easy to forget, broken links at launch) - -## 2026-03-13: Shared Claude Code permissions for parallel worktree agents - -**Context:** Background agents launched in git worktrees need Bash, Edit, Read, etc. but block waiting for interactive permission approval that never comes. Per-user settings at `~/.claude/projects//settings.json` don't apply to worktree agents because the worktree has a different filesystem path. -**Decision:** Commit `.claude/settings.json` to the repo with pre-approved tools (git, npm, bd, gh, Edit, Write, Read, Grep, Glob). Deny destructive operations (force push, rm -rf). Gitignore `.claude/settings.local.json` and `.claude/worktrees/` (local-only). -**Rationale:** Shared settings travel with the repo and apply to all agents regardless of working directory. Every developer gets the same permission baseline without manual configuration. -**Alternatives considered:** Per-user project settings (doesn't apply to worktrees), fully permissive mode (too broad), manual approval (blocks background agents) - -## 2026-03-13: No Beads git hooks — manual sync only - -**Context:** `bd doctor` recommends installing git hooks (`pre-commit`, `post-merge`, `pre-push`) that auto-sync Beads state on git operations. During Sprint 1, the Dolt journal corrupted when the parent agent ran parallel `bd` commands while worktree agents were active. -**Decision:** Do not install Beads git hooks. All `bd dolt pull`/`push` calls must be manual and serialized. Only the parent agent may run `bd` commands — worktree agents must never touch Beads. -**Rationale:** Git hooks fire automatically on git operations (push, pull, checkout). Worktree agents perform these git operations concurrently, so hooks would trigger concurrent `bd` calls against the shared Dolt server, risking journal corruption. Manual serialized calls give the parent full control over when Beads is accessed. -**Alternatives considered:** Install hooks only on the main worktree (hooks still fire on parent git ops during agent runs), install hooks with a lock file (Dolt doesn't support external locking), use `--sandbox` mode for agents (still shares the server) - -## 2026-03-13: Squash-merge only, auto-delete branches - -**Context:** Agent PRs accumulate multiple commits (draft, feedback fixes, rebases) that aren't meaningful individually. -**Decision:** Enforce squash-merge as the only merge method on GitHub. Auto-delete branches after merge. Squash commit uses PR title and PR body. -**Rationale:** Keeps `git log` on `main` clean (one commit per page/feature). PR history is always available on GitHub. Auto-delete prevents stale `docs/` branches from accumulating. -**Alternatives considered:** Merge commits (noisy history), rebase merge (preserves individual commits nobody needs) - -## 2026-03-17: Merge binding-generation page into Candid interface guide - -**Context:** The planned `guides/canister-calls/binding-generation.md` had significant overlap with the existing Candid interface guide, which already covered `.did` generation and JS binding usage. The two dedicated binding tools are `@icp-sdk/bindgen` (JS/TS) and `ic-cdk-bindgen` (Rust) — `didc bind` should not be advertised for binding generation. -**Decision:** (1) Merged all binding-generation content into `candid.md` as a "Binding generation" section. (2) Removed the `binding-generation.md` stub. (3) Updated `didc` tool table to focus on validation/encoding (removed `didc bind` rows). (4) Documented both auto-generated and hand-written `.did` file paths for Motoko. (5) Updated `onchain-calls.md` canister discovery section with a cross-link to the new bindings section. (6) Removed Beads task and updated migration plan dependencies. -**Rationale:** The developer flow is linear: define interface → generate `.did` → generate bindings → use them. Splitting bindings into a separate page creates an artificial seam. The Candid guide is the natural home for the full flow. -**Alternatives considered:** Keep separate page (creates overlap and navigation friction), move all `.did` generation to the bindings page (splits related content) - -## 2026-03-19: Use .mdx with Starlight Tabs for multi-language pages, strip to clean markdown for agents - -**Context:** Guide pages showing both Motoko and Rust examples had no language toggle — readers scrolled past the other language's content. Starlight's `` component with `syncKey="lang"` syncs all tab groups on the page and persists the selection to `localStorage` across pages. -**Decision:** Pages with parallel Motoko/Rust examples use `.mdx` with Starlight's `` and `` / ``. The agent-docs plugin strips MDX artifacts from `.mdx` sources to produce clean `.md` endpoints: `` becomes a `### X` heading (level derived from parent), ESM imports are removed (only outside code fences — Motoko `import` statements are preserved), JSX wrapper tags and comments are stripped. A validation pass on every build checks generated `.md` for leftover JSX, missing language tags, heading hierarchy violations, and other artifacts. -**Rules:** (1) `.md` remains the default — only use `.mdx` when a page needs interactive components like synced tabs. (2) `syncKey="lang"` for all language tabs — ensures global persistence. (3) **Tab order follows "source → derived":** for implementation/code tabs, list Motoko first, then Rust, then other languages (JavaScript). For type-mapping tabs where Candid is the canonical definition (e.g., Records, Variants), list Candid first, then Motoko, then Rust — Candid defines the interface, the languages are projections of it. (4) The `` comment uses MDX syntax `{/* Upstream: ... */}` in `.mdx` files. (5) All content inside `` must be valid markdown (no nested JSX beyond what Starlight provides). (6) **No markdown headings inside `` blocks** — Starlight generates the "On this page" TOC at build time from all headings regardless of active tab, so headings inside tabs always appear in the TOC even when hidden. Use bold text (`**Title**`) for sub-labels inside tabs instead. -**Rationale:** Starlight's built-in Tabs handle accessibility, keyboard nav, and persistence out of the box — no custom plugin needed. The `.mdx` approach optimizes human reading experience while the stripping logic produces well-structured agent markdown with language-labeled headings. The remark-directive alternative was rejected because it requires building/maintaining a custom plugin to replicate what Starlight already provides. -**Alternatives considered:** (1) Remark-directive plugin with plain `.md` (custom infrastructure to maintain, reimplements Starlight features), (2) Keep `.md`-only with `## Motoko:` / `## Rust:` headings (no interactive tabs, poor human UX), (3) Separate pages per language (breaks the "one guide, pick your language" pattern) - -## 2026-03-19: Worktree agents must initialize submodules before starting work - -**Context:** Skills and source material are accessed via a symlink chain: `.claude/skills/` → `.agents/skills/` → `.sources//skills/`. All `.sources/` entries are git submodules. When `git worktree add` creates a new worktree, submodules are NOT initialized — `.sources/` contains only empty directories, breaking all skill symlinks and making source material inaccessible. -**Decision:** Every worktree agent must run `git submodule update --init --depth 1` as its very first command. The parent agent must include this instruction in every worktree agent's prompt. This costs ~336MB disk and ~30 seconds per worktree; both are reclaimed when the worktree is removed. -**Rationale:** Alternatives were evaluated and rejected: (1) Symlinking `.sources/` to the main repo's copy — works for file access but causes 13 spurious deletion entries in `git status` that could confuse agents into staging them; symlinking individual submodule dirs causes a hard `git status` error (exit 128). (2) `submodule.recurse=true` git config — does not auto-init submodules on `git worktree add`. (3) Vendoring skills into the repo — loses automatic sync with upstream skill repos. The submodule init approach is the only one with zero git side effects (clean status, no surprises), which is critical for agents operating autonomously. -**Alternatives considered:** Shared `.sources/` symlink (dirty git status confuses agents), `submodule.recurse` config (doesn't work for worktree creation), vendored skills (manual sync burden) - -## 2026-03-19: Sync ic.did from portal and check on submodule bumps - -**Context:** The management canister Candid interface (`ic.did`) is the machine-readable type definition for all management canister methods. It lives in the portal repo at `docs/references/_attachments/ic.did` and is embedded in the IC interface spec page. The IC repo (`dfinity/ic`) also has a copy in `packages/ic-management-canister-types/tests/ic.did`, but it may include unreleased changes. The portal version represents the released spec. -**Decision:** Copy `ic.did` from `.sources/portal/` into `public/reference/ic.did` (static asset, not content). Reference it from the management canister page. On portal submodule bumps, diff `ic.did` — if it changed, re-copy and update `management-canister.md` plus any guides referencing affected methods. Added "Synced files from submodules" section to AGENTS.md with a bump checklist. -**Rationale:** Developers need the Candid interface for binding generation and type checking. Copying rather than symlinking ensures the file is served by the docs site. The portal version is the released source of truth; the IC repo version may be ahead with unreleased changes. -**Alternatives considered:** Symlink to `.sources/` (not served by Astro build), link to GitHub raw URL (breaks offline, no version control), add IC repo as submodule (too large) - -## 2026-03-19: Drop icskills frontmatter field — advertise via skills registry instead - -**Context:** Every docs page had an optional `icskills: [ckbtc, evm-rpc]` frontmatter field tagging related IC skills for AI agent discovery. However, `cleanMarkdown()` in the agent-docs plugin strips all frontmatter, so agents consuming `.md` endpoints or `llms.txt` never see it. The only consumers were agents reading raw repo files. -**Decision:** Remove the `icskills` field from the frontmatter schema, Zod validation, all stub pages, and documentation. Instead, advertise the skills registry endpoint (`https://skills.internetcomputer.org/.well-known/skills/index.json`) in `llms.txt`. icskills remain a source material repo — agents still read from `.sources/icskills/` and list them in `` comments when used as source. -**Rationale:** The skills registry solves agent discovery at the site level. Per-page skill tags add maintenance overhead with no current consumer. If per-page hints are needed later, they can be added to the `.md` endpoints or `llms.txt` entries. -**Alternatives considered:** Emit skill tags in clean markdown output (adds complexity for narrow use case), keep frontmatter for future use (maintenance burden with no consumer) - -## 2026-03-18: Move wallet-integration from authentication to DeFi section - -**Context:** The wallet-integration page covers ICRC signer standards (ICRC-21/25/27/29/49) for transaction approval, not authentication. The wallet-integration icskill itself distinguishes wallet signers (transaction approval) from Internet Identity (authentication/login). Under `guides/authentication/`, the page was grouped with II and verifiable credentials — a different concern. -**Decision:** Move `guides/authentication/wallet-integration.md` → `guides/defi/wallet-integration.md`. Update cross-links in `what-next.md`, `internet-identity.md`, and `token-standards.md`. Update Beads task title. No sidebar config change needed (both directories use `autogenerate`). -**Rationale:** Transaction signing is closer to the DeFi/token workflow than to authentication. Developers looking for wallet transaction approval would look in DeFi, not Authentication. Discussed in PR #23 and filed as GitHub issue #25. -**Alternatives considered:** Keep in authentication (misleading grouping), create a new "Wallets" subsection (over-engineering for one page) - -## 2026-04-15: Tightened sandbox permissions and autonomous worktree agent workflow - -**Context:** The original `.claude/settings.json` had `"Bash"` as a blanket allow, which pre-approved all bash commands including `dangerouslyDisableSandbox: true` bypasses — meaning the sandbox could be silently bypassed without user visibility. Additionally, `~/.config/gh` in `denyRead` blocked `gh` commands from working inside the sandbox, and there was no technical guard against direct git manipulation of `refs/dolt/data`. Several commands that legitimately need sandbox bypass (submodule init, Dolt server start) were undocumented. -**Decision:** (1) Removed blanket `"Bash"` from `permissions.allow` — `autoAllowBashIfSandboxed: true` handles sandboxed commands automatically; only explicit `dangerouslyDisableSandbox` commands now need pre-approval. (2) Removed `~/.config/gh` from `filesystem.denyRead` — `gh` now works within the sandbox without bypass. (3) Added targeted pre-approvals for commands that legitimately need sandbox bypass: `git submodule update*` (`.git/` is hardcoded-protected by Claude Code), `bd dolt start*`, `bd dolt pull*`, `bd dolt push*`. (4) Added deny rules for direct git manipulation of `refs/dolt/data`: `git push * refs/dolt*`, `git push * --delete refs/dolt*`, `git push * :refs/dolt*`. (5) Added worktree agent prompt structure guidelines to AGENTS.md — parent passes only task ID + page path + skill instructions; worktrees do their own full research from `.sources/` and skills. (6) Changed review workflow: review worktree agents post `gh pr comment` directly (fully autonomous); parent no longer presents findings to user before posting. -**Rationale:** The blanket `"Bash"` allow was false security — it looked like bash was controlled but actually everything was pre-approved. The new model: sandboxed commands run silently (low risk, OS-isolated), pre-approved bypass commands cover the specific cases that need it (submodule init, Dolt), and `bd init --force` still prompts (it destroys local DB state). Pre-gathering source material in the parent before launching worktrees was producing lower-quality content because it bypassed the skill research workflow; worktrees reading primary sources directly produces better output. -**Alternatives considered:** Keep blanket `"Bash"` (no user visibility into bypasses), require user approval for `bd dolt push` (too noisy — fires on every status update), have parent collect review findings and present to user before posting (intentional pause, now removed for full autonomy) - -## 2026-04-21: Reference pages synced 1:1 from portal — ic-interface-spec, glossary, candid-spec - -**Context:** An audit revealed three reference pages had significant content gaps vs. the portal: `ic-interface-spec.md` (was a 355-line overview vs. 9,197-line portal spec), `glossary.md` (~39% of portal terms), and `candid-spec.md` (~57% of portal content). Since this site replaces the portal, missing content was a blocker. -**Decision:** Replace all three pages with 1:1 content from the portal (dfinity/portal master branch), stripping only MDX/Docusaurus artifacts (import lines, JSX components). Banned `internetcomputer.org/docs` URLs updated to internal links or `developer-docs.icp.xyz`. The `dfx` mention in candid-ref replaced with `icp`. The ic-interface-spec changelog (previously a separate MDX import) is inlined at the end of the spec. These pages should be re-synced whenever the portal is bumped. -**Rationale:** Portal is the current upstream for these specs; maintaining divergent summaries risks shipping incomplete/wrong reference docs to developers who were previously served by the portal. Full 1:1 sync is the only safe approach until an automated workflow is added. -**Alternatives considered:** Automated portal sync workflow (deferred — manual sync is sufficient for now), keep overview pages and link out (insufficient — this site is the portal replacement) - -## 2026-04-17: og-image.svg has a hardcoded domain - -**Context:** `public/og-image.svg` contains the site URL in its footer text (`DFINITY Foundation · beta-docs.internetcomputer.org`). The build plugin converts the SVG to `og-image.png` at build time, so the hardcoded URL ends up baked into the PNG served as the social share preview. -**Decision:** Keep the SVG as a static file (the domain changes at most once). When the site moves to its final domain, update the URL in `public/og-image.svg` alongside `astro.config.mjs` (`site`) and the og:image/twitter:image meta tags. -**Rationale:** Dynamic SVG generation in the build plugin adds ~30 lines of complexity for a one-time change. Static is simpler and good enough. -**Alternatives considered:** Generate SVG dynamically in `plugins/astro-agent-docs.mjs` using `siteUrl` from Astro config (more robust, but over-engineered for a single domain change) - - -## 2026-04-28: Production domain cutover to docs.internetcomputer.org - -**Context:** The site was previously served from `beta-docs.internetcomputer.org` as a staging domain during the transition from `dfinity/portal`. The portal has now been retired and this site is the canonical ICP developer docs. -**Decision:** Switch all domain references from `beta-docs.internetcomputer.org` to `docs.internetcomputer.org`. Updated files: `astro.config.mjs` (site URL + og/twitter/schema.org meta), `public/robots.txt` (sitemap), `public/og-image.svg` (footer text), `README.md`, `AGENTS.md` (never-link rule + portal tracking section), `scripts/validate.js` (error messages). The `docs.internetcomputer.org` lint rule in validate.js is kept — it still enforces relative paths for internal links. -**Rationale:** The beta domain was always a temporary staging address. With the portal retired, `docs.internetcomputer.org` is the permanent home. -**Alternatives considered:** Keep beta domain as a redirect origin (handled at DNS/CDN level, not in code) - ---- - -## 2026-05-04: ic-interface-spec split into 7 focused sub-pages - -**Context:** `docs/references/ic-interface-spec.md` was a 483K monolith covering 13 distinct sections serving very different audiences (agent builders, CDK developers, canister developers, protocol implementors). The `afdocs` checker flagged it for both `page-size-markdown` (482K chars, limit 480K) and `page-size-html` (524K converted, 79% boilerplate). The Abstract behavior section alone was 5,747 lines (formal state machine notation) accounting for 64% of the file. -**Decision:** Split into `docs/references/ic-interface-spec/` with 7 pages: `index.md` (intro, pervasive concepts, system state tree), `https-interface.md`, `canister-interface.md` (module format + System API), `management-canister.md` (management + Bitcoin + provisional APIs), `certification.md` (certification + HTTP Gateway), `abstract-behavior.md`, `changelog.md`. All 204 heading anchors were remapped; cross-file `(#anchor)` references updated to `(./target.md#anchor)`. The Abstract behavior page carries a note directing application developers to the practical sections. CLAUDE.md sync rules updated with a section-to-file mapping table for portal bump workflow. -**Rationale:** Each section serves a distinct audience and use case. Splitting enables independent navigation, brings all pages under the 480K size limit, and gives the agent-friendly docs checker clean per-section `.md` endpoints. The technical-documentation skill confirmed the split is correct Diataxis structure for a reference spec of this scope. -**Sync:** Portal bump workflow changed from patch-on-single-file to inspect-diff-and-apply-by-section. See CLAUDE.md "Step 2 — ic-interface-spec/" checklist. -**When to revisit:** If the portal is fully retired as source, remove the portal sync checklist from CLAUDE.md and mark these files as hand-maintained. diff --git a/.docs-plan/developer-journey.md b/.docs-plan/developer-journey.md deleted file mode 100644 index 9a8c6887..00000000 --- a/.docs-plan/developer-journey.md +++ /dev/null @@ -1,526 +0,0 @@ -# Developer Journey: Zero to Production - -## Journey Map - -### Stage 1: Discovery — "What is ICP? Why should I build here?" - -**Developer mindset:** Evaluating the platform. Wants to understand differentiators quickly. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Platform overview | concepts/network-overview.md | [Learn Hub](https://learn.internetcomputer.org) | — | -| Architecture model | concepts/app-architecture.md | Learn Hub | — | -| What are canisters? | concepts/canisters.md | Learn Hub | — | -| Unique capabilities at a glance | concepts/chain-key-cryptography.md, concepts/orthogonal-persistence.md, concepts/reverse-gas-model.md | Learn Hub | — | -| Cross-chain story | concepts/chain-fusion.md | Learn Hub | — | - -**Key insight:** A developer in discovery mode reads 1-3 concept pages and decides whether to try the quickstart. The concepts/ section must have strong opening paragraphs that answer "why should I care?" within 30 seconds. - ---- - -### Stage 2: Setup — Install tools, scaffold first project - -**Developer mindset:** Committed to trying ICP. Wants to go from zero to running code in < 10 minutes. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Install icp-cli, scaffold project | getting-started/quickstart.md | [icp-cli docs](https://cli.internetcomputer.org/) | — | -| Understand project files | getting-started/project-structure.md | icp-cli docs (project structure) | — | -| AI-assisted development | guides/tools/agentic-development.md | [icskills](https://skills.internetcomputer.org) | All 17 skills | -| Choose next steps | getting-started/what-next.md | — | — | - -**Templates used:** `hello-world` (default), potentially `bitcoin-starter` for chain-fusion interest. - -**Recipes relevant:** Rust recipe, Motoko recipe (depending on language choice). - -**Key insight:** The quickstart must use a single icp-cli template and get the developer to a deployed local canister with a working frontend. No forks, no decisions. The "what-next" page is the critical routing page that sends developers into guides/ based on their goal. - ---- - -### Stage 3: Backend Development — Write canister code - -**Developer mindset:** Building their first real feature. Needs patterns, not concepts. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Data storage patterns | guides/backends/data-persistence.md | — | `icp-canister-data-storage` | -| HTTP requests from canisters | guides/backends/https-outcalls.md | — | `icp-https-outcalls` | -| Scheduled tasks | guides/backends/timers.md | — | `icp-timers` | -| Randomness | guides/backends/randomness.md | — | `icp-randomness` | -| Certified responses | guides/backends/certified-variables.md | — | `icp-certified-variables` | -| Calling other canisters | guides/canister-calls/onchain-calls.md, guides/canister-calls/candid.md | — | `icp-inter-canister-calls` | -| Language reference | languages/motoko/ or languages/rust/ | [Motoko core](https://mops.one/core/docs), [Rust CDK](https://docs.rs/ic-cdk/latest/ic_cdk/) | — | - -**Key insight:** This is where developers spend 80% of their time. Every guide must have copy-pasteable code for both Rust and Motoko. Link to the relevant icskill at the top of each guide so AI agents can assist. - ---- - -### Stage 4: Frontend Development — Build UI, connect to canister - -**Developer mindset:** Has a working backend, wants to wire up a UI. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Calling canisters from apps | guides/canister-calls/offchain-calls.md | [JS SDK](https://js.icp.build), [Rust agent](https://docs.rs/ic-agent) | — | -| Asset canister setup | guides/frontends/asset-canister.md | icp-cli docs | `icp-asset-canister` | -| Framework integration | guides/frontends/frameworks.md | [JS SDK](https://js.icp.build) | — | -| Custom domains | guides/frontends/custom-domains.md | — | — | -| User login | guides/authentication/internet-identity.md | — | `icp-internet-identity` | -| Wallet connection | guides/defi/wallet-integration.md | — | — | -| Response verification | guides/frontends/certification.md | — | — | - -**Templates used:** `react-starter`, `vanilla-js-starter`. - -**Key insight:** Not all developers need this stage (backend-only developers skip it). The asset canister page is the entry point; it should link clearly to authentication as the natural next step after "I have a UI." - ---- - -### Stage 5: Testing — Validate before deployment - -**Developer mindset:** Code works locally, wants confidence before spending cycles on mainnet. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Testing approaches | guides/testing/strategies.md | — | — | -| PocketIC integration tests | guides/testing/pocket-ic.md | — | `icp-pocket-ic-testing` | -| Canister logs (debugging) | guides/canister-management/logs.md | icp-cli docs | — | - -**Key insight:** Testing is often skipped by developers in a rush. The strategies page should make a strong case for why testing matters on ICP (upgrades are irreversible, cycles cost money). PocketIC is the primary testing tool and needs thorough coverage. - ---- - -### Stage 6: Deployment — Ship to mainnet - -**Developer mindset:** Ready to go live. Needs to understand cycles, subnets, and the deployment command. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Cycles acquisition + management | guides/canister-management/cycles-management.md | icp-cli docs | `icp-cycles-management` | -| Subnet selection | guides/canister-management/subnet-selection.md | — | — | -| Canister settings for prod | guides/canister-management/settings.md | icp-cli docs | — | -| Reproducible builds | guides/canister-management/reproducible-builds.md | — | — | -| Canister lifecycle (install, upgrade) | guides/canister-management/lifecycle.md | icp-cli docs | `icp-canister-lifecycle` | - -**Key insight:** This is the highest-anxiety stage. Developers worry about costs, irreversible mistakes, and configuration errors. The cycles-management page is the single most important page here -- it must answer "how much will this cost me?" directly. - ---- - -### Stage 7: Production — Monitor, manage, secure - -**Developer mindset:** Live on mainnet. Needs operational guides. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Security hardening | guides/security/ (all 5 pages) | — | `icp-canister-security` | -| Wasm optimization | guides/canister-management/optimization.md | — | — | -| Canister snapshots / backup | guides/canister-management/snapshots.md | — | — | -| Monitoring via logs | guides/canister-management/logs.md | icp-cli docs | — | - -**Key insight:** Security guides should be written as checklists, not essays. A developer going to production wants "did I forget anything?" not "here is the theory of access control." - ---- - -### Stage 8: Advanced — Chain fusion, DeFi, governance - -**Developer mindset:** Experienced ICP developer exploring platform-specific capabilities. - -| Need | Docs page(s) | External docs | icskills | -|------|-------------|---------------|----------| -| Bitcoin integration | guides/chain-fusion/bitcoin.md | — | `icp-bitcoin-integration` | -| Ethereum integration | guides/chain-fusion/ethereum.md | — | `icp-evm-rpc` | -| Solana integration | guides/chain-fusion/solana.md | — | — | -| Token ledgers | guides/defi/token-ledgers.md | — | `icp-icrc-ledger` | -| Chain-key tokens | guides/defi/chain-key-tokens.md | — | — | -| SNS governance | guides/governance/ (all 3 pages) | — | `icp-sns-governance` | - -**Key insight:** These are destination sections, not sequential. A DeFi developer may jump straight here after Stage 3. The "what-next" page and sidebar must make these discoverable without forcing a linear path. - ---- - -## Sidebar Order Recommendation - -The guides/ sub-groups should follow the natural development sequence. A developer scrolling the sidebar should see the order they would actually build things in. - -### Recommended sidebar order for guides/: - -``` -guides/ - backends/ # 1. Write your canister logic - canister-calls/ # 2. Call other canisters - frontends/ # 3. Build a UI - authentication/ # 4. Add user login - testing/ # 5. Test before deploying - canister-management/ # 6. Configure and manage canisters - production/ # 7. Deploy and operate on mainnet - security/ # 8. Harden for production - chain-fusion/ # 9. Integrate with other chains - defi/ # 10. Build financial applications - governance/ # 11. Decentralize with SNS - tools/ # 12. Tooling reference (always last) -``` - -**Rationale:** -- Groups 1-4 follow the build sequence (backend -> cross-canister -> frontend -> auth) -- Groups 5-8 follow the ship sequence (test -> configure -> deploy -> secure) -- Groups 9-11 are advanced/domain-specific (no assumed order) -- Group 12 is reference-like (tools overview, migration guide) and belongs at the end - -### Recommended top-level sidebar order: - -``` -Getting Started # Always first -Guides # Bulk of content, follows journey -Concepts # Deeper understanding (read when needed) -Languages # Language-specific reference -Reference # Specs, costs, errors (lookup when needed) -``` - ---- - -## Structure Alternatives - -### Variant A: Current Proposal (Diataxis Pure) - -``` -getting-started/ (4 tutorials) -guides/ - backends/ (7 how-to) - canister-management/ (6 how-to) - frontends/ (4 how-to) - authentication/ (2 how-to) - canister-calls/(3 how-to) - testing/ (2 how-to) - production/ (3 how-to) - chain-fusion/ (4 how-to) - defi/ (3 how-to) - governance/ (3 how-to) - security/ (5 how-to) - tools/ (2 how-to) -concepts/ (13 explanations) -languages/ (Motoko synced + Rust) -reference/ (13 reference pages) -``` - -**Pros:** -- Clean Diataxis alignment (each section = one quadrant) -- Flat top-level (5 sections) is easy to scan -- Guides sub-groups can be reordered without structural changes -- AI agents can reliably predict where content lives based on type (how-to vs. concept vs. reference) -- 12 sub-groups in guides/ keeps each group small (2-7 pages) - -**Cons:** -- 12 sub-groups in guides/ is a lot to scan in the sidebar -- Concept/guide pairs are separated (e.g., concepts/chain-fusion.md vs guides/chain-fusion/bitcoin.md) -- developer must navigate between sections -- "backends/" may not be immediately clear to ICP newcomers - -**Journey fit:** Good for stages 2-7 (linear journey). Weaker for stage 1 (discovery) and stage 8 (advanced) where developers browse by topic rather than task sequence. - ---- - -### Variant B: Journey-Oriented (Build, Ship, Scale) - -``` -getting-started/ (4 tutorials) -build/ - backends/ (7 how-to) - canister-calls/(3 how-to) - frontends/ (4 how-to) - authentication/ (2 how-to) - testing/ (2 how-to) -ship/ - canister-management/ (6 how-to) - production/ (3 how-to) - security/ (5 how-to) -scale/ - chain-fusion/ (4 how-to) - defi/ (3 how-to) - governance/ (3 how-to) -concepts/ (13 explanations) -languages/ (Motoko synced + Rust) -reference/ (13 reference pages) -tools/ (2 pages, promoted to top-level) -``` - -**Pros:** -- Maps directly to the developer journey (build -> ship -> scale) -- Each top-level section tells you where you are in the journey -- Fewer sub-groups per section (5 under build, 3 under ship, 3 under scale) -- "Tools" as top-level makes it easy to find migration guide and tooling overview - -**Cons:** -- 8 top-level sections is more than the recommended 5-7 for sidebar scannability -- Breaks Diataxis purity (build/ship/scale are journey stages, not information types) -- Developers who know what they want (e.g., "HTTPS outcalls guide") must first figure out which journey stage it belongs to -- "Scale" is a misnomer -- chain fusion and DeFi are not about scaling, they are domain capabilities -- AI agents have a harder time predicting content location (is security in "ship" or "build"?) - -**Journey fit:** Excellent for the linear first-time journey (stages 2-7). Poor for experienced developers who return to docs for specific tasks, and for AI agents that need predictable paths. - ---- - -### Variant C: Hybrid (Guides + Capabilities) - -``` -getting-started/ (4 tutorials) -guides/ - backends/ (7 how-to) - canister-calls/(3 how-to) - frontends/ (4 how-to) - authentication/ (2 how-to) - testing/ (2 how-to) - canister-management/ (6 how-to) - production/ (3 how-to) - security/ (5 how-to) -capabilities/ - chain-fusion/ (4 how-to + concepts merged) - defi/ (3 how-to + concepts merged) - governance/ (3 how-to + concepts merged) -concepts/ (10 explanations, minus the 3 moved to capabilities) -languages/ (Motoko synced + Rust) -reference/ (13 reference pages) -``` - -**Pros:** -- Separates "core development guides" from "platform capability deep-dives" -- Chain fusion, DeFi, and governance get their own home with concept + how-to co-located -- Reduces guides/ sub-group count from 12 to 8 -- Capabilities section is a natural landing zone for Ethereum migrants and DeFi developers - -**Cons:** -- Breaks Diataxis by mixing concepts and how-to in capabilities/ -- Creates ambiguity: is "HTTPS outcalls" a capability or a backend guide? (It could be either) -- Where does a new capability go? The decision boundary between guides/ and capabilities/ is fuzzy -- 6 top-level sections, borderline for sidebar scannability -- Concept/how-to co-location means some concept pages live in concepts/ and others in capabilities/ -- inconsistent - -**Journey fit:** Good for discovery (capabilities section is browsable by topic) and for advanced stages (8). Weaker for the linear journey because the developer must understand the guides/capabilities split. - ---- - -## Recommended Structure - -**Recommendation: Variant A (Current Proposal / Diataxis Pure) with sidebar ordering improvements.** - -### Rationale - -1. **Diataxis consistency is the strongest signal for both humans and AI agents.** When every how-to is under guides/, every concept is under concepts/, and every spec is under reference/, there is zero ambiguity about where to find or place content. This matters enormously for a docs site that will be maintained by multiple agents and human contributors. - -2. **The 12 sub-groups concern is manageable.** With the recommended sidebar ordering (above), the guides/ section reads as a natural journey. Starlight supports collapsible sidebar groups, so developers can collapse sections they have moved past. - -3. **Variant B's journey framing is better solved by the "what-next" page.** Rather than encoding the journey into the URL structure (which creates friction for returning developers), the getting-started/what-next.md page can route developers to the right guides/ sub-group based on their goal. This preserves the journey without sacrificing findability. - -4. **Variant C's capabilities separation creates more problems than it solves.** The decision already recorded in decisions.md (2026-03-11: "No separate capabilities section") is correct. Capabilities are best expressed as concept + guide pairs linked to each other, not co-located. - -5. **AI agent ergonomics favor Variant A.** An agent given a task like "help the user make HTTPS outcalls" can predictably look for guides/backends/https-outcalls.md. With Variant B, the agent must reason about journey stages. With Variant C, the agent must reason about the guides/capabilities boundary. - -### Adjustments to Variant A - -Two refinements to the current proposal: - -1. **Rename `guides/canister-management/` to `guides/canister-management/`** to disambiguate from "canister development" (which is what backends/ covers). This makes the distinction clear: backends/ = writing canister code, canister-management/ = configuring, upgrading, and operating canisters. - -2. **Add a `guides/tools/` entry for `dev-environments.md`** (or similar) to cover Gitpod, GitHub Codespaces, and local dev setup beyond the quickstart. This fills a gap for developers who want to set up CI or team environments. - -### Final structure - -``` -getting-started/ - quickstart.md - project-structure.md - what-next.md - -guides/ - backends/ # Write canister logic - data-persistence.md - https-outcalls.md - timers.md - randomness.md - certified-variables.md - canister-calls/ # Call other canisters - onchain-calls.md - candid.md - binding-generation.md - parallel-calls.md - frontends/ # Build a UI - asset-canister.md - custom-domains.md - certification.md - frameworks.md - authentication/ # Add user login - internet-identity.md - wallet-integration.md (moved to guides/defi/) - testing/ # Test before deploying - strategies.md - pocket-ic.md - canister-management/ # Configure and manage (renamed) - lifecycle.md - settings.md - logs.md - optimization.md - large-wasm.md - snapshots.md - reproducible-builds.md - production/ # Deploy and operate - subnet-selection.md - cycles-management.md - canister-discovery.md - security/ # Harden for production - access-management.md - canister-upgrades.md - data-integrity.md - dos-prevention.md - inter-canister-calls.md - chain-fusion/ # Integrate with other chains - bitcoin.md - ethereum.md - solana.md - dogecoin.md - defi/ # Build financial applications - token-ledgers.md - chain-key-tokens.md - rosetta.md - governance/ # Decentralize with SNS - launching.md - managing.md - testing.md - tools/ # Tooling - overview.md - migrating-from-dfx.md - -concepts/ - network-overview.md - app-architecture.md - canisters.md - chain-key-cryptography.md - vetkeys.md - https-outcalls.md - onchain-randomness.md - timers.md - reverse-gas-model.md - orthogonal-persistence.md - chain-fusion.md - governance.md - security.md - -languages/ - motoko/ # Synced from caffeinelabs/motoko - rust/ - index.md - stable-structures.md - testing.md - -reference/ - management-canister.md - system-canisters.md - protocol-canisters.md - application-canisters.md - token-standards.md - cycles-costs.md - subnet-selection.md - execution-errors.md - ic-interface-spec.md - http-gateway-spec.md - candid-spec.md - internet-identity-spec.md - glossary.md -``` - ---- - -## Edge Case Analysis - -### 1. Backend-only developer (no frontend) - -**Journey:** Discovery -> Setup -> Backend Development -> Testing -> Deployment -> Production - -**Navigation path:** -- getting-started/quickstart.md (uses hello-world template, ignores frontend) -- getting-started/what-next.md -> routes to guides/backends/ -- Works through relevant backend guides -- Skips frontends/ and authentication/ entirely -- Goes to guides/testing/ -> guides/canister-management/ -> guides/canister-management/ - -**Does the structure work?** Yes. Frontends and authentication are clearly separate sub-groups that backend-only developers can skip without confusion. The sidebar ordering places backends/ first, so the developer sees their content immediately. - -**Gap to address:** The quickstart should note that the frontend is optional and can be removed from the project template, or offer a backend-only template variant. - -### 2. Developer migrating from Ethereum - -**Journey:** Discovery (focused on differences) -> Setup -> Chain Fusion + Backend -> Deployment - -**Navigation path:** -- concepts/app-architecture.md (ICP vs Ethereum architecture) -- concepts/reverse-gas-model.md (biggest paradigm shift) -- concepts/chain-fusion.md (how ICP connects to Ethereum) -- getting-started/quickstart.md -- guides/chain-fusion/ethereum.md (their primary interest) -- guides/backends/ (ICP-specific patterns) -- guides/canister-management/cycles-management.md (cycles vs gas) - -**Does the structure work?** Mostly. The concepts section handles the "what's different" question well. The chain-fusion section is discoverable in the sidebar. - -**Gap to address:** Consider a "Coming from Ethereum" callout or section in concepts/app-architecture.md that maps Ethereum concepts to ICP equivalents (contract = canister, gas = cycles, Solidity = Motoko/Rust, etc.). This is a paragraph, not a whole page -- keep it in the concept page. - -### 3. AI agent looking for implementation guidance - -**Journey:** Direct lookup by task -> Read guide -> Read icskill -> Generate code - -**Navigation path:** -- Agent receives task like "add HTTPS outcalls to my canister" -- Looks up guides/backends/https-outcalls.md (predictable path) -- Reads linked icskill `icp-https-outcalls` for code patterns -- References languages/rust/ or languages/motoko/ for syntax details -- Checks reference/ for API specifics if needed - -**Does the structure work?** Yes, and this is Variant A's strongest advantage. The path from task description to docs page is deterministic: "how to X" -> guides/{category}/X.md. AI agents do not benefit from journey-oriented structures (Variant B) because they do not follow linear journeys. - -**Gap to address:** Every guide page should have a machine-readable frontmatter field linking to the relevant icskill(s) and examples repo path. This enables agents to discover related resources programmatically. - -### 4. DeFi developer - -**Journey:** Discovery -> Setup -> Backend + DeFi + Chain Fusion -> Testing -> Deployment - -**Navigation path:** -- concepts/network-overview.md (quick platform overview) -- getting-started/quickstart.md -- guides/defi/token-ledgers.md (core of their work) -- guides/defi/chain-key-tokens.md -- guides/chain-fusion/bitcoin.md or ethereum.md (for cross-chain tokens) -- guides/canister-calls/onchain-calls.md (ledger interaction is inter-canister) -- guides/security/ (financial applications need all security guides) -- guides/canister-management/cycles-management.md - -**Does the structure work?** Yes. The DeFi developer has a clear home in guides/defi/ and naturally branches into chain-fusion/ and security/. The separation of these three sub-groups works well because DeFi developers need all three but in different proportions depending on their specific project. - -**Gap to address:** The guides/defi/ section should have an index page or the token-ledgers.md page should open with a "building DeFi on ICP" overview that maps common DeFi patterns (DEX, lending, staking) to the relevant guide pages across sections. - -### 5. Developer deploying to production for the first time - -**Journey:** Has working local project -> Deployment -> Production -> Security - -**Navigation path:** -- guides/canister-management/cycles-management.md (first question: "how much does this cost?") -- guides/canister-management/subnet-selection.md (where to deploy) -- guides/canister-management/settings.md (production settings: controllers, memory limits) -- guides/canister-management/reproducible-builds.md (verify your build) -- guides/canister-management/lifecycle.md (install vs upgrade) -- guides/security/ (pre-launch security checklist) -- reference/cycles-costs.md (exact cost lookup) - -**Does the structure work?** Yes, but the path crosses three sub-groups (production/, canister-management/, security/). This is acceptable because each sub-group has a distinct concern, and the pages should cross-link. - -**Gap to address:** Consider a "Production checklist" callout in guides/canister-management/cycles-management.md (the likely entry point) that links to the 5-6 pages a first-time deployer must read. This acts as a mini-journey within the guides section without requiring a separate "deployment tutorial" (which would overlap with the how-to guides). - ---- - -## Cross-Cutting Recommendations - -1. **Concept-Guide linking:** Every concept page should end with a "Hands-on" section linking to the corresponding guide(s). Every guide page should have a "Background" link to the relevant concept. This bridges the Diataxis quadrants without co-locating content. - -2. **icskill links in frontmatter:** Add an `icskills` frontmatter field (array of skill IDs) to every guide page. This enables agents to discover skills programmatically and enables a future "Try with AI" button on each page. - -3. **The "what-next" page is critical routing infrastructure.** It should present 3-4 paths (backend focus, full-stack, chain fusion, DeFi) with 2-3 sentences each and direct links. This is the single page that makes the linear journey work within a non-linear structure. - -4. **Sidebar annotations:** Use Starlight's badge feature to mark sub-groups as "Core" (backends, frontends, testing, canister-management, production) vs "Advanced" (chain-fusion, defi, governance). This helps new developers focus and experienced developers browse. - -5. **examples repo mapping:** Each guide page should link to 1-2 relevant examples from the 97 in the examples repo. This provides the "full working project" complement to the guide's focused snippets. diff --git a/.docs-plan/icp-cli-examples-inventory.md b/.docs-plan/icp-cli-examples-inventory.md deleted file mode 100644 index 9785b7ad..00000000 --- a/.docs-plan/icp-cli-examples-inventory.md +++ /dev/null @@ -1,372 +0,0 @@ -# icp-cli Ecosystem + Examples Inventory - -Compiled 2026-03-11. Sources: icp-cli/docs (33 files), icp-cli-recipes (4 recipes), icp-cli-templates (6 templates), dfinity/examples (~97 examples). - ---- - -## icp-cli Docs → Developer Docs - -| icp-cli Page | Developer Docs Page | Relationship | -|---|---|---| -| `index.md` (landing) | guides/tools/overview | link — landing page for icp-cli site | -| `quickstart.md` | getting-started/quickstart | sync — our quickstart should mirror icp-cli's quickstart closely | -| `tutorial.md` | getting-started/quickstart, getting-started/project-structure | link — tutorial is the detailed version of quickstart | -| `telemetry.md` | (none) | link only — reference from tools/overview | -| **Concepts** | | | -| `concepts/project-model.md` | getting-started/project-structure | sync candidate — icp.yaml structure, .icp/ directory, canister discovery | -| `concepts/build-deploy-sync.md` | guides/canister-management/lifecycle | link — deploy lifecycle is core canister lifecycle content | -| `concepts/environments.md` | guides/canister-management/cycles-management, guides/canister-management/settings | link — environments are key for multi-env deployments | -| `concepts/recipes.md` | getting-started/project-structure, guides/tools/overview | link — recipes are a core icp-cli concept | -| `concepts/canister-discovery.md` | guides/canister-calls/onchain-calls, guides/frontends/asset-canister | sync candidate — canister env vars, frontend-to-backend wiring | -| `concepts/binding-generation.md` | guides/canister-calls/binding-generation | sync candidate — this is exactly the binding generation topic | -| **Guides** | | | -| `guides/installation.md` | getting-started/quickstart | sync candidate — install steps must be in our quickstart | -| `guides/local-development.md` | getting-started/quickstart, guides/frontends/asset-canister | link — dev workflow, frontend dev server setup | -| `guides/deploying-to-mainnet.md` | guides/canister-management/cycles-management | sync candidate — identity, ICP, cycles, deploy workflow | -| `guides/deploying-to-specific-subnets.md` | guides/canister-management/subnet-selection | sync candidate — subnet selection, colocation | -| `guides/canister-snapshots.md` | guides/canister-management/snapshots | sync candidate — this IS the snapshots guide | -| `guides/canister-migration.md` | guides/canister-management/lifecycle | link — advanced canister migration | -| `guides/managing-environments.md` | guides/canister-management/cycles-management | link — multi-env setup | -| `guides/managing-identities.md` | guides/defi/wallet-integration | link — identity management reference | -| `guides/tokens-and-cycles.md` | guides/canister-management/cycles-management, guides/defi/token-ledgers | link — ICP/cycles/ICRC-1 token commands | -| `guides/containerized-networks.md` | guides/testing/strategies | link — Docker-based test networks | -| `guides/using-recipes.md` | getting-started/project-structure | link — how to configure build recipes | -| `guides/creating-recipes.md` | (none) | link only — advanced topic for recipe authors | -| `guides/creating-templates.md` | (none) | link only — advanced topic for template authors | -| **Reference** | | | -| `reference/cli.md` | guides/tools/overview | link — always link to https://cli.internetcomputer.org/ | -| `reference/configuration.md` | getting-started/project-structure | link — icp.yaml schema reference | -| `reference/canister-settings.md` | guides/canister-management/settings | link — all canister settings | -| `reference/environment-variables.md` | guides/canister-calls/onchain-calls, guides/frontends/asset-canister | link — env vars for build and runtime | -| **Migration** | | | -| `migration/from-dfx.md` | guides/tools/migrating-from-dfx | sync — already auto-synced from icp-cli repo | - ---- - -## Recipes → Developer Docs - -| Recipe | Latest Version | Developer Docs Pages | What to Show | -|---|---|---|---| -| `@dfinity/rust` | v3.1.0 | getting-started/quickstart, getting-started/project-structure | Inline icp.yaml snippet showing recipe config; link to recipe README for params | -| `@dfinity/motoko` | v4.0.0 | getting-started/quickstart, getting-started/project-structure | Inline icp.yaml snippet showing recipe config; link to recipe README for params | -| `@dfinity/asset-canister` | v2.1.0 | guides/frontends/asset-canister, getting-started/project-structure | Inline icp.yaml snippet; explain build/dir/version params; link to recipe README | -| `@dfinity/prebuilt` | v2.0.0 | guides/canister-management/lifecycle, guides/canister-management/reproducible-builds | Inline icp.yaml snippet for deploying pre-built WASM; mention sha256 verification | - -### Recipe icp.yaml Snippets to Inline - -**Rust recipe** (~8 lines): -```yaml -canisters: - - name: backend - recipe: - type: "@dfinity/rust@v3.1.0" - configuration: - package: backend - shrink: true -``` - -**Motoko recipe** (~7 lines): -```yaml -canisters: - - name: backend - recipe: - type: "@dfinity/motoko@v4.0.0" - configuration: - main: src/main.mo -``` - -**Asset canister recipe** (~9 lines): -```yaml -canisters: - - name: frontend - recipe: - type: "@dfinity/asset-canister@v2.1.0" - configuration: - build: - - npm install - - npm run build - dir: dist -``` - -**Prebuilt recipe** (~8 lines): -```yaml -canisters: - - name: my-canister - recipe: - type: "@dfinity/prebuilt@v2.0.0" - configuration: - path: ./my-canister.wasm - sha256: -``` - ---- - -## Templates → Developer Docs - -| Template | Subfolder | Developer Docs Pages | Context | -|---|---|---|---| -| hello-world | `hello-world` | getting-started/quickstart, guides/frontends/asset-canister, guides/canister-calls/binding-generation | Default template for `icp new`. Full-stack: Motoko/Rust backend + React frontend. Shows canister discovery via ic_env cookie, @icp-sdk/bindgen Vite plugin. | -| motoko | `motoko` | getting-started/quickstart | Backend-only Motoko template. Simplest starting point for Motoko developers. | -| rust | `rust` | getting-started/quickstart | Backend-only Rust template. Shows Rust recipe with shrink, custom candid, metadata. | -| bitcoin-starter | `bitcoin-starter` | guides/chain-fusion/bitcoin | Bitcoin integration template. Shows bitcoind-addr network config, environment-specific BITCOIN_NETWORK env var, multi-environment setup (local/staging/production). | -| proxy | `proxy` | guides/testing/strategies, guides/canister-management/cycles-management | Proxy canister for forwarding calls with cycles on connected networks. Useful for testing cycle-dependent methods on mainnet. | -| static-website | `static-website` | guides/frontends/asset-canister, guides/frontends/frameworks | Pure frontend: Vite + asset-canister recipe. No backend. Good example for hosting-only use case. | - -### Template Mentions - -- **getting-started/quickstart**: Show `icp new my-project --subfolder hello-world` (already covered in icp-cli quickstart) -- **getting-started/project-structure**: Explain hello-world template output: icp.yaml, backend/, frontend/, .icp/ -- **guides/chain-fusion/bitcoin**: Reference `icp new my-project --subfolder bitcoin-starter` with the multi-environment icp.yaml -- **guides/frontends/asset-canister**: Reference static-website template as simplest frontend-only example - ---- - -## Examples → Developer Docs - -### Chain Fusion Examples - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/basic_bitcoin | Motoko | Bitcoin send/receive via ECDSA+Schnorr APIs | guides/chain-fusion/bitcoin | Link | -| rust/basic_bitcoin | Rust | Bitcoin send/receive via ECDSA+Schnorr APIs | guides/chain-fusion/bitcoin | Link | -| rust/basic_ethereum | Rust | Ethereum send/receive ETH via tECDSA + HTTPS outcalls | guides/chain-fusion/ethereum | Link | -| rust/basic_solana | Rust | Solana integration (redirects to sol-rpc-canister repo) | guides/chain-fusion/solana | Link | -| rust/basic_dogecoin | Rust | Dogecoin integration (redirects to dogecoin-canister repo) | guides/chain-fusion/dogecoin | Link | -| motoko/evm_block_explorer | Motoko | EVM block explorer via HTTPS outcalls | guides/chain-fusion/ethereum | Link | -| rust/evm_block_explorer | Rust | EVM block explorer via HTTPS outcalls | guides/chain-fusion/ethereum | Link | - -### Cryptography / Threshold Signatures - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/threshold-ecdsa | Motoko | Threshold ECDSA signing | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum | Link | -| rust/threshold-ecdsa | Rust | Threshold ECDSA signing | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum | Link | -| motoko/threshold-schnorr | Motoko | Threshold Schnorr signing | guides/chain-fusion/bitcoin | Link | -| rust/threshold-schnorr | Rust | Threshold Schnorr signing | guides/chain-fusion/bitcoin | Link | -| motoko/vetkd | Motoko | VetKD (Verifiable Encrypted Threshold Key Derivation) | guides/security/data-integrity | Link | -| rust/vetkd | Rust | VetKD | guides/security/data-integrity | Link | -| motoko/vetkeys | Motoko | VetKeys encryption | guides/security/data-integrity | Link | -| rust/vetkeys | Rust | VetKeys encryption | guides/security/data-integrity | Link | - -### Token & DeFi Examples - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/icp_transfer | Motoko | ICP ledger transfer | guides/defi/token-ledgers | Link | -| rust/icp_transfer | Rust | ICP ledger transfer | guides/defi/token-ledgers | Link | -| motoko/token_transfer | Motoko | ICRC-1 token transfer | guides/defi/token-ledgers, guides/defi/chain-key-tokens | Link | -| rust/token_transfer | Rust | ICRC-1 token transfer | guides/defi/token-ledgers, guides/defi/chain-key-tokens | Link | -| motoko/token_transfer_from | Motoko | ICRC-2 transfer_from (approve+transfer) | guides/defi/token-ledgers | Link | -| rust/token_transfer_from | Rust | ICRC-2 transfer_from | guides/defi/token-ledgers | Link | -| motoko/icrc2-swap | Motoko | ICRC-2 token swap | guides/defi/token-ledgers | Link | -| rust/receiving-icp | Rust | Receiving ICP in a canister | guides/defi/token-ledgers | Link | -| motoko/tokenmania | Motoko | Token game (full app) | guides/defi/token-ledgers | Link | -| rust/tokenmania | Rust | Token game (full app) | guides/defi/token-ledgers | Link | - -### HTTPS Outcalls - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/send_http_get | Motoko | HTTPS outcall GET | guides/backends/https-outcalls | Inline (core code ~20 lines) | -| rust/send_http_get | Rust | HTTPS outcall GET | guides/backends/https-outcalls | Inline (core code ~25 lines) | -| motoko/send_http_post | Motoko | HTTPS outcall POST | guides/backends/https-outcalls | Link | -| rust/send_http_post | Rust | HTTPS outcall POST | guides/backends/https-outcalls | Link | -| rust/exchange-rates | Rust | HTTPS outcalls to fetch exchange rates | guides/backends/https-outcalls | Link | - -### Backend Features - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/parallel_calls | Motoko | Parallel inter-canister calls | guides/canister-calls/parallel-calls | Link (good walkthrough) | -| rust/parallel_calls | Rust | Parallel inter-canister calls | guides/canister-calls/parallel-calls | Link | -| rust/inter-canister-calls | Rust | Basic inter-canister calls | guides/canister-calls/onchain-calls | Link | -| motoko/cert-var | Motoko | Certified variables | guides/backends/certified-variables | Link | -| motoko/hello_cycles | Motoko | Sending/receiving cycles | guides/canister-management/cycles-management | Link | -| rust/periodic_tasks | Rust | Timers / periodic tasks | guides/backends/timers | Link | -| motoko/random_maze | Motoko | Onchain randomness | guides/backends/randomness | Link | -| motoko/pub-sub | Motoko | Pub/sub pattern | guides/canister-calls/onchain-calls | Link | -| motoko/composite_query | Motoko | Composite queries | guides/canister-calls/onchain-calls | Link | -| rust/composite_query | Rust | Composite queries | guides/canister-calls/onchain-calls | Link | -| motoko/query_stats | Motoko | Query statistics | guides/canister-management/logs | Link | -| rust/query_stats | Rust | Query statistics | guides/canister-management/logs | Link | -| motoko/canister_logs | Motoko | Canister logging | guides/canister-management/logs | Link | -| rust/canister_logs | Rust | Canister logging | guides/canister-management/logs | Link | -| motoko/low_wasm_memory | Motoko | Low WASM memory handling | guides/canister-management/optimization | Link | -| rust/low_wasm_memory | Rust | Low WASM memory handling | guides/canister-management/optimization | Link | -| motoko/classes | Motoko | Motoko classes / canister factory | guides/canister-management/lifecycle | Link | -| motoko/canister_factory | Motoko | Programmatic canister creation | guides/canister-management/lifecycle | Link | -| rust/performance_counters | Rust | Performance counters | guides/canister-management/optimization | Link | -| rust/guards | Rust | Access control guards | guides/security/access-management | Link | -| rust/simd | Rust | SIMD operations in WASM | guides/canister-management/optimization | Link | -| rust/backend_wasm64 | Rust | Wasm64 backend | guides/canister-management/optimization, guides/canister-management/large-wasm | Link | -| rust/x509 | Rust | X.509 certificate handling | guides/security/data-integrity | Link | -| rust/candid_type_generation | Rust | Candid type generation | guides/canister-calls/candid | Link | -| rust/canister-info | Rust | Canister info API | guides/canister-management/lifecycle | Link | -| rust/canister-snapshots | Rust | Programmatic snapshots | guides/canister-management/snapshots | Link | -| rust/canister-snapshot-download | Rust | Snapshot download | guides/canister-management/snapshots | Link | -| rust/unit_testable_rust_canister | Rust | Unit testing patterns | guides/testing/strategies | Link | -| rust/stake_neuron_from_cli | Rust | NNS neuron staking | guides/governance/managing | Link | -| rust/sns-adaptor | Rust | SNS adaptor canister | guides/governance/launching | Link | - -### Authentication / Identity - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/internet_identity_integration | Motoko | Internet Identity login | guides/authentication/internet-identity | Link | -| motoko/encrypted-notes-dapp-vetkd | Motoko | Encrypted notes with II + VetKD | guides/authentication/internet-identity, guides/security/data-integrity | Link | -| rust/encrypted-notes-dapp-vetkd | Rust | Encrypted notes with II + VetKD | guides/authentication/internet-identity, guides/security/data-integrity | Link | -| motoko/who_am_i | Motoko | Caller principal identification | guides/security/access-management | Inline (~10 lines) | -| rust/who_am_i | Rust | Caller principal identification | guides/security/access-management | Inline (~10 lines) | - -### Frontend / Hosting - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| hosting/static-website | HTML/CSS | Basic static website hosting | guides/frontends/asset-canister | Link | -| hosting/photo-storage | JS | Photo storage with asset canister | guides/frontends/asset-canister | Link | -| hosting/react | React | React app hosting | guides/frontends/frameworks | Link | -| hosting/godot-html5-template | Godot | Godot game hosting | guides/frontends/frameworks | Link | -| hosting/unity-webgl-template | Unity | Unity WebGL hosting | guides/frontends/frameworks | Link | -| hosting/my_crypto_blog | JS | Blog with crypto features | guides/frontends/asset-canister | Link | -| hosting/oisy-signer-demo | JS | OISY wallet signer demo | guides/defi/wallet-integration | Link | -| svelte/svelte-motoko-starter | Svelte+Motoko | Svelte + Motoko starter | guides/frontends/frameworks | Link | -| svelte/sveltekit-starter | SvelteKit | SvelteKit starter | guides/frontends/frameworks | Link | - -### Native Apps - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| native-apps/unity_ii_applink | Unity/C# | Unity + Internet Identity (App Link) | guides/authentication/internet-identity | Link | -| native-apps/unity_ii_deeplink | Unity/C# | Unity + Internet Identity (Deep Link) | guides/authentication/internet-identity | Link | -| native-apps/unity_ii_universallink | Unity/C# | Unity + Internet Identity (Universal Link) | guides/authentication/internet-identity | Link | - -### Other - -| Example | Language | Feature | Developer Docs Page | Inline or Link | -|---|---|---|---|---| -| motoko/hello_world | Motoko | Hello world | getting-started/quickstart | Link | -| rust/hello_world | Rust | Hello world | getting-started/quickstart | Link | -| motoko/backend_only | Motoko | Backend-only canister | getting-started/project-structure | Link | -| rust/backend_only | Rust | Backend-only canister | getting-started/project-structure | Link | -| motoko/daily_planner | Motoko | Full CRUD app | guides/backends/data-persistence | Link | -| rust/daily_planner | Rust | Full CRUD app | guides/backends/data-persistence | Link | -| motoko/superheroes | Motoko | CRUD with relationships | guides/backends/data-persistence | Link | -| motoko/flying_ninja | Motoko | Game example | (none — showcase only) | Link from getting-started/what-next | -| rust/flying_ninja | Rust | Game example | (none — showcase only) | Link from getting-started/what-next | -| motoko/llm_chatbot | Motoko | LLM chatbot | guides/backends/onchain-ai | Link | -| rust/llm_chatbot | Rust | LLM chatbot | guides/backends/onchain-ai | Link | -| motoko/ic-pos | Motoko | Point-of-sale app | guides/defi/token-ledgers | Link | -| motoko/nft-creator | Motoko | NFT creation | guides/defi/token-ledgers | Link | -| motoko/filevault | Motoko | Encrypted file storage | guides/security/data-integrity | Link | -| rust/photo_gallery | Rust | Photo gallery with storage | guides/backends/data-persistence | Link | -| rust/qrcode | Rust | QR code generation | guides/backends/https-outcalls | Link | -| rust/face-recognition | Rust | Face recognition (WASM ML) | guides/canister-management/optimization | Link | -| rust/image-classification | Rust | Image classification (WASM ML) | guides/canister-management/optimization | Link | -| wasm/counter | WASM | Raw WASM counter | (none — advanced showcase) | — | - ---- - -## Sync Candidates - -These icp-cli docs pages are strong candidates for syncing content into developer-docs (either via automated sync or manual rewrite that stays in close alignment): - -1. **`migration/from-dfx.md`** → `guides/tools/migrating-from-dfx` — Already synced from icp-cli repo. Keep as-is. - -2. **`guides/installation.md`** → `getting-started/quickstart` — Installation steps MUST match between the two. Consider syncing the install section or extracting a shared snippet. - -3. **`quickstart.md`** → `getting-started/quickstart` — Our quickstart should use identical commands. Sync the command sequence (icp new, network start, deploy, canister call). - -4. **`concepts/canister-discovery.md`** → `guides/canister-calls/onchain-calls` and `guides/frontends/asset-canister` — Canister environment variables and the ic_env cookie mechanism are critical for both frontend-to-backend and backend-to-backend communication. This content should be rewritten for our docs with links back to the icp-cli version. - -5. **`concepts/binding-generation.md`** → `guides/canister-calls/binding-generation` — Short enough to adapt into our page, linking to @icp-sdk/bindgen, candid crate, and didc. - -6. **`guides/canister-snapshots.md`** → `guides/canister-management/snapshots` — This is the definitive guide; rewrite with links back. - -7. **`guides/deploying-to-specific-subnets.md`** → `guides/canister-management/subnet-selection` — Subnet selection is production-critical; rewrite with links back. - -8. **`guides/deploying-to-mainnet.md`** → `guides/canister-management/cycles-management` — Identity setup, ICP acquisition, cycles minting, and deployment workflow. Rewrite the cycles/deployment portion. - -Pages that should be **link-only** (not synced): -- `reference/cli.md` — Always link to https://cli.internetcomputer.org/ -- `reference/configuration.md` — Link to icp-cli site -- `reference/canister-settings.md` — Link to icp-cli site -- `reference/environment-variables.md` — Link to icp-cli site -- `guides/creating-recipes.md` — Advanced; link only -- `guides/creating-templates.md` — Advanced; link only -- `guides/containerized-networks.md` — Link only (mention Docker option in testing page) -- `telemetry.md` — Link only - ---- - -## Recommendations - -### 1. Recipe Snippets Are the Primary Configuration Examples - -Every developer-docs page that shows "how to set up a canister" should use recipe-based icp.yaml snippets. The four official recipes cover 95%+ of use cases: -- **Rust backend**: `@dfinity/rust` -- **Motoko backend**: `@dfinity/motoko` -- **Frontend/static**: `@dfinity/asset-canister` -- **Pre-built WASM**: `@dfinity/prebuilt` - -Do NOT show raw build steps (cargo build, moc, etc.) as the primary approach. Show recipes first, then mention custom build steps as an escape hatch. - -### 2. Templates as Starting Points in Quickstart - -The getting-started/quickstart page should prominently feature: -- `icp new my-project --subfolder hello-world` as the default path -- `icp new my-project --subfolder rust` for Rust-only projects -- `icp new my-project --subfolder motoko` for Motoko-only projects -- `icp new my-project --subfolder bitcoin-starter` in the Bitcoin guide - -### 3. Examples Repo Needs icp-cli Migration - -The examples repo (`dfinity/examples`) still uses dfx commands throughout. All README files reference `dfx start`, `dfx deploy`, etc. Before linking heavily from developer-docs, the examples should be updated to use icp-cli. Priority examples for migration: -- hello_world (both languages) — linked from quickstart -- send_http_get/post (both) — linked from HTTPS outcalls guide -- basic_bitcoin (both) — linked from Bitcoin guide -- icp_transfer / token_transfer (both) — linked from token ledgers guide -- internet_identity_integration — linked from II guide -- parallel_calls (both) — linked from parallel calls guide - -### 4. Inline vs. Link Decision Framework - -**Inline** (copy code into docs page) when: -- Code is <30 lines and illustrates a single concept -- The pattern is stable and unlikely to change -- Examples: who_am_i (~10 lines), basic HTTP GET handler (~20 lines), recipe icp.yaml snippets - -**Link** (point to examples repo) when: -- Example is a full project with multiple files -- Code changes frequently -- Example has its own README with deployment instructions -- Examples: basic_bitcoin, encrypted-notes-dapp, tokenmania - -### 5. icp.yaml Environment Patterns to Highlight - -The bitcoin-starter template shows an excellent pattern for multi-environment config with environment-specific canister env vars. This pattern should be referenced in: -- `guides/canister-management/cycles-management` — staging vs production -- `guides/chain-fusion/bitcoin` — regtest vs testnet vs mainnet -- `guides/canister-management/settings` — environment-specific settings - -### 6. Canister Discovery is Cross-Cutting - -The canister discovery mechanism (PUBLIC_CANISTER_ID env vars + ic_env cookie) appears in: -- icp-cli concepts/canister-discovery.md -- icp-cli guides/local-development.md (frontend dev server section) -- hello-world template README -- icp-cli concepts/binding-generation.md - -This should be a single, well-explained section in `guides/canister-calls/onchain-calls` with cross-references from `guides/frontends/asset-canister` and `getting-started/project-structure`. - -### 7. Missing Example Coverage - -Some developer-docs pages have no corresponding examples: -- **guides/backends/data-persistence** — daily_planner and superheroes exist but are basic. Consider linking photo_gallery (Rust) for a more complete example. -- **guides/canister-management/reproducible-builds** — No dedicated example. Reference `@dfinity/prebuilt` recipe with sha256 verification. -- **guides/security/dos-prevention** — No example. This is a conceptual guide. -- **guides/security/inter-canister-calls** — guards example (Rust) covers access control but not call safety patterns. -- **guides/testing/pocket-ic** — containerized-networks guide covers Docker-based PocketIC, but no standalone PocketIC example exists in the examples repo. - -### 8. Template-to-Recipe Version Alignment - -Templates pin specific recipe versions (e.g., `@dfinity/rust@v3.1.0` in the rust template). Developer-docs should use unversioned recipe references or a placeholder like `@dfinity/rust@` so they don't go stale. Note the icp-cli docs already use this pattern (e.g., `@dfinity/rust@v3.0.0` — one version behind the template). A remark plugin could inject current versions at build time, similar to how CLI link versions are injected. diff --git a/.docs-plan/jssdk-skills-mapping.md b/.docs-plan/jssdk-skills-mapping.md deleted file mode 100644 index 7a799d31..00000000 --- a/.docs-plan/jssdk-skills-mapping.md +++ /dev/null @@ -1,173 +0,0 @@ -# JS SDK + icskills Mapping - -## icskills Inventory - -17 published skills (16 unique source skills + `wallet` alias of `cycles-management` in dist): - -| # | Skill | Category | Summary | -|---|-------|----------|---------| -| 1 | `asset-canister` | Frontend | Deploy frontend assets, certified assets, SPA routing, custom domains, programmatic uploads | -| 2 | `canister-security` | Security | Access control, anonymous principal rejection, reentrancy (CallerGuard), async safety (saga), callback traps, cycle drain protection, upgrade safety | -| 3 | `certified-variables` | Security | Merkle trees, certified data API, witness generation, frontend certificate validation | -| 4 | `ckbtc` | DeFi | BTC deposit/withdrawal via minter, ckBTC transfers, subaccount derivation, UTXO management | -| 5 | `cycles-management` | Infrastructure | Cycle balances, top-ups, freezing thresholds, canister creation, ICP-to-cycles via CMC | -| 6 | `evm-rpc` | Integration | JSON-RPC calls to Ethereum/EVM chains, multi-provider consensus, ERC-20 reads, signed tx submission | -| 7 | `https-outcalls` | Integration | HTTP requests from canisters, transform functions, cycle costs, response limits, idempotency | -| 8 | `ic-dashboard` | Integration | REST APIs for dashboard.internetcomputer.org (canister metadata, ICRC ledger, SNS, ICP ledger, metrics) | -| 9 | `icp-cli` | Infrastructure | Project config (icp.yaml), recipes, environments, canister lifecycle, identity management | -| 10 | `icrc-ledger` | Tokens | ICRC-1/ICRC-2 token standard, transfers, balances, approve/transferFrom, fee handling, local test ledger | -| 11 | `internet-identity` | Auth | Passkey and OpenID login, delegation handling, principal-per-app isolation | -| 12 | `multi-canister` | Architecture | Inter-canister calls, canister factory, async messaging, bounded/unbounded wait, 2MB limits | -| 13 | `sns-launch` | Governance | Token economics, governance params, testflight, NNS proposal, decentralization swap | -| 14 | `stable-memory` | Architecture | StableBTreeMap (Rust), persistent actor (Motoko), MemoryManager, upgrade hooks | -| 15 | `vetkd` | Security | Onchain encryption, IBE, transport keys, key derivation, access control for secrets | -| 16 | `wallet-integration` | Wallet | ICRC signer standards (21/25/27/29/49), popup wallet model, consent messages, OISY signer | -| 17 | `wallet` (alias) | Infrastructure | Published alias of `cycles-management` in dist | - -## JS SDK Inventory - -5 projects at https://js.icp.build: - -| # | Project | Package | Type | Summary | -|---|---------|---------|------|---------| -| 1 | Core | `@icp-sdk/core` | Library | Base library: agent, identity, principal, HttpAgent, certificate verification | -| 2 | Auth | `@icp-sdk/auth` | Library | Authentication: AuthClient, Internet Identity integration, delegation identity | -| 3 | Canisters | `@icp-sdk/canisters` | Library | Canister interaction: asset manager, ledger/governance actor factories | -| 4 | Pic JS | `pic-js` | Tool | Canister testing framework for JS/TS (PocketIC-based) | -| 5 | Bindgen | `@icp-sdk/bindgen` | Tool | Generate JS/TS bindings from Candid | - ---- - -## icskills to Docs Pages Mapping - -| Skill | Docs Pages (add `icskills` frontmatter) | Notes | -|-------|----------------------------------------|-------| -| `asset-canister` | `guides/frontends/asset-canister`, `guides/frontends/custom-domains`, `guides/frontends/certification`, `guides/frontends/frameworks` | Primary target is asset-canister page; custom-domains and certification are also covered by this skill | -| `canister-security` | `guides/security/access-management`, `guides/security/canister-upgrades`, `guides/security/data-integrity`, `guides/security/dos-prevention`, `guides/security/inter-canister-calls`, `concepts/security` | Broad skill; map to all security guide pages plus concepts/security | -| `certified-variables` | `guides/backends/certified-variables`, `guides/frontends/certification`, `concepts/security` | Primary is backends/certified-variables; also relevant for frontend cert verification | -| `ckbtc` | `guides/chain-fusion/bitcoin`, `guides/defi/chain-key-tokens`, `guides/defi/token-ledgers` | Primary is bitcoin chain-fusion; also relevant for chain-key tokens overview | -| `cycles-management` | `guides/canister-management/cycles-management`, `guides/canister-management/lifecycle`, `guides/canister-management/settings`, `concepts/reverse-gas-model` | Primary is cycles-management; lifecycle and settings pages reference cycle operations | -| `evm-rpc` | `guides/chain-fusion/ethereum`, `concepts/chain-fusion` | Primary is ethereum chain-fusion page | -| `https-outcalls` | `guides/backends/https-outcalls`, `concepts/https-outcalls` | Both the guide and concept page | -| `ic-dashboard` | `guides/canister-management/canister-discovery`, `reference/system-canisters` | Dashboard APIs are for off-chain discovery; reference for system canister metadata | -| `icp-cli` | `getting-started/quickstart`, `getting-started/project-structure`, `guides/tools/overview`, `guides/tools/migrating-from-dfx` | Foundational skill; referenced from getting-started and tools sections | -| `icrc-ledger` | `guides/defi/token-ledgers`, `reference/token-standards`, `guides/defi/chain-key-tokens` | Primary is token-ledgers; also token-standards reference | -| `internet-identity` | `guides/authentication/internet-identity`, `reference/internet-identity-spec` | Primary is the II guide page | -| `multi-canister` | `guides/canister-calls/onchain-calls`, `guides/canister-calls/candid`, `guides/canister-calls/parallel-calls`, `concepts/app-architecture` | Primary is canister-calls/onchain-calls; also relevant for parallel calls and app architecture | -| `sns-launch` | `guides/governance/launching`, `guides/governance/managing`, `guides/governance/testing`, `concepts/governance` | Maps to all three governance guide pages | -| `stable-memory` | `guides/backends/data-persistence`, `guides/canister-management/lifecycle`, `concepts/orthogonal-persistence` | Primary is data-persistence; lifecycle covers upgrade patterns | -| `vetkd` | `concepts/vetkeys`, `guides/security/data-integrity` | Primary is concepts/vetkeys; security/data-integrity for encryption use cases | -| `wallet-integration` | `guides/defi/wallet-integration` | Direct 1:1 mapping | -| `wallet` (alias) | (same as `cycles-management`) | Not a separate mapping needed | - -## JS SDK to Docs Pages Mapping - -| JS SDK Project | Docs Pages (should link to js.icp.build) | Where in page | -|---------------|----------------------------------------|---------------| -| **Core** (`@icp-sdk/core`) | `getting-started/quickstart` | "Install dependencies" section; link to https://js.icp.build/core | -| | `guides/tools/agentic-development` | Agent setup section; link to Core docs for HttpAgent | -| | `guides/frontends/frameworks` | JS framework integration; Core is the base dependency | -| | `guides/frontends/certification` | Client-side certificate verification uses Core | -| | `guides/canister-calls/candid` | Agent/actor creation from JS side | -| | `concepts/app-architecture` | Frontend-to-canister communication overview | -| **Auth** (`@icp-sdk/auth`) | `guides/authentication/internet-identity` | "Frontend integration" section; link to https://js.icp.build/auth | -| | `guides/defi/wallet-integration` | Auth prerequisites section | -| | `guides/frontends/frameworks` | Auth setup in React/Svelte/Vue apps | -| **Canisters** (`@icp-sdk/canisters`) | `guides/frontends/asset-canister` | "Programmatic uploads" section; link to https://js.icp.build/canisters | -| | `guides/defi/token-ledgers` | JS ledger actor usage examples | -| | `guides/defi/chain-key-tokens` | JS interaction with ckBTC/ckETH ledgers | -| | `guides/governance/managing` | JS governance actor for SNS management | -| **Pic JS** | `guides/testing/strategies` | "JavaScript testing" section; link to https://js.icp.build/pic-js | -| | `guides/testing/pocket-ic` | Pic JS is the JS wrapper for PocketIC | -| | `guides/governance/testing` | SNS testflight with Pic JS | -| **Bindgen** (`@icp-sdk/bindgen`) | `guides/canister-calls/binding-generation` | Primary page; link to https://js.icp.build/bindgen | -| | `guides/canister-calls/candid` | "Generating JS bindings" subsection | -| | `getting-started/project-structure` | Mention bindgen in project scaffolding | - -## Gaps - -### Skills with no direct docs page - -| Skill | Gap | Recommendation | -|-------|-----|----------------| -| `ic-dashboard` | No dedicated docs page for dashboard APIs | Map to `guides/canister-management/canister-discovery` and mention in `reference/system-canisters`. Consider a short "Dashboard APIs" section in canister-discovery page. | -| `canister-security` | Covers many topics spread across 5+ pages | No single landing page. Consider linking from a `guides/security/` index or overview callout. | - -### Docs pages with no skill coverage - -| Docs Page | Missing Skill | Recommendation | -|-----------|--------------|----------------| -| `guides/backends/timers` | No `timers` skill | Create a `timers` skill or fold into existing skill. Covered in `concepts/timers` but no agent skill exists. | -| `guides/backends/randomness` | No `randomness` skill | Create a `randomness` skill. Covered in `concepts/onchain-randomness` but no agent skill exists. | -| `guides/canister-management/large-wasm` | No skill | Niche topic; may not need a skill. Document icp-cli `--wasm-chunk-store` flag. | -| `guides/canister-management/logs` | No skill | Could be a section in `icp-cli` skill or a new `canister-observability` skill. | -| `guides/canister-management/optimization` | No skill | Covered partially by `icp-cli` (ic-wasm). Consider adding optimization guidance to `icp-cli` skill. | -| `guides/canister-management/snapshots` | No skill | New IC feature; consider a `canister-snapshots` skill when stable. | -| `guides/canister-management/reproducible-builds` | No skill | Could be a section in `icp-cli` skill. | -| `guides/chain-fusion/solana` | No skill | No Solana integration skill exists. Create when Solana support is ready. | -| `guides/chain-fusion/dogecoin` | No skill | No Dogecoin skill. The `ckbtc` skill covers Bitcoin; Dogecoin may need its own. | -| `guides/defi/rosetta` | No skill | Rosetta API is specialized; consider a `rosetta` skill for exchange integration. | -| `guides/canister-management/subnet-selection` | No skill | Reference/informational page; may not need a skill. | -| `reference/*` (most pages) | No skills | Reference pages are lookups, not how-to guides. Skills are not expected here. | -| `concepts/*` (most pages) | No skills | Concept pages explain architecture; link to skills where relevant but concepts pages themselves do not need `icskills` frontmatter. | - -### JS SDK gaps - -| JS SDK Project | Gap | -|---------------|-----| -| Core | No dedicated "JS Agent" docs page in developer-docs. Core concepts (HttpAgent, identity, principal) are foundational but have no single page. | -| Auth | Well-covered by `guides/authentication/internet-identity`. No gap. | -| Canisters | No dedicated "JS canister interaction" page. Usage is spread across multiple guides. | -| Pic JS | Well-covered by `guides/testing/` pages. No gap. | -| Bindgen | Well-covered by `guides/canister-calls/binding-generation`. No gap. | - -## Recommendations - -### 1. Surfacing skills in docs pages - -Add an `icskills` field to frontmatter of relevant docs pages: - -```yaml ---- -title: "Asset Canister" -icskills: - - asset-canister ---- -``` - -This enables: -- A "Related agent skills" callout box on each page linking to https://skills.internetcomputer.org/asset-canister -- Automated validation that skill references are valid -- AI agents to discover which skill to load for a given docs topic - -### 2. JS SDK link placement - -For each docs page that references JS SDK, add links in context: -- **Inline in code examples**: When showing JS code, link to the relevant js.icp.build project docs -- **"JS SDK" callout box**: For pages with significant JS content, add a callout linking to the specific project -- **Prerequisites section**: List the npm package and link to js.icp.build for API details - -Standard link format per CLAUDE.md rules (link to https://js.icp.build, not versioned): -- `[Core library](https://js.icp.build/core)` -- `[Auth library](https://js.icp.build/auth)` -- `[Canisters library](https://js.icp.build/canisters)` -- `[Pic JS](https://js.icp.build/pic-js)` -- `[Bindgen](https://js.icp.build/bindgen)` - -### 3. Priority new skills to create - -1. **`timers`** -- Covers periodic and one-shot timers (concepts/timers, guides/backends/timers). High value since timers are common in production canisters. -2. **`randomness`** -- Covers onchain randomness via management canister (concepts/onchain-randomness, guides/backends/randomness). Important for games, lotteries, fair selection. -3. **`rosetta`** -- Covers Rosetta API for exchange integration (guides/defi/rosetta). Specialized but important for DeFi ecosystem. - -### 4. Cross-reference pattern - -For maximum developer utility, each guides/ page should have: -- `icskills` frontmatter listing relevant skills (for agent discovery) -- Inline links to js.icp.build where JS examples appear (for human developers) -- Links to external docs per CLAUDE.md rules (Rust CDK, Motoko core, icp-cli) - -This creates a three-layer reference system: -1. **Agent skills** (icskills) -- for AI-assisted development -2. **JS SDK docs** (js.icp.build) -- for frontend/JS developers -3. **Language CDK docs** (docs.rs, mops.one) -- for backend developers diff --git a/.docs-plan/migration-plan.md b/.docs-plan/migration-plan.md deleted file mode 100644 index 92926e5b..00000000 --- a/.docs-plan/migration-plan.md +++ /dev/null @@ -1,419 +0,0 @@ -# Migration Plan - -> This file is the **execution playbook** — it tells you _how_ to do each task (dependencies, source material, effort, skills). For _what to do next_, check [GitHub Issues](https://github.com/dfinity/developer-docs/issues). - -Covers all 80 content pages + infrastructure tasks (excluding synced Motoko pages, section index pages, and the landing page). - -## How to use this file - -1. Pick a task from [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` -2. Check the **Dependency Layers** section below to understand what's unblocked -3. Look up that task's details in the sprint tables: dependencies, source material, effort estimate -4. Do the work following `AGENTS.md` rules -5. Submit PR with a `## Sync recommendation` section in the description - -## Effort key - -- **S** (< 2 hours), **M** (2-4 hours), **L** (4-8 hours), **XL** (8+ hours) -- **Skills**: `rewrite` (rewrite portal content), `original` (write from scratch), `sync` (adapt from icp-cli), `reference` (compile reference data) - ---- - -## Infrastructure Tasks - -These are non-content tasks needed to make the docs production-ready. All scripts/workflows are preserved on `restructuring-attempt-1` and need to be adapted to the new structure. - -| Priority | Task | Effort | Details | -|----------|------|--------|---------| -| P0 | Restore validation scripts | M | `scripts/validate-frontmatter.mjs`, `scripts/validate-no-dfx.sh`, `scripts/validate-no-mdx.sh` — update paths for new structure, add to `package.json` | -| P0 | Restore sync scripts | M | See details below | - -**Restore sync scripts — details:** - -Scripts to copy from `restructuring-attempt-1` branch: -- `scripts/sync-motoko.sh` — pulls Motoko docs from `caffeinelabs/motoko`, flattens into `docs/languages/motoko/{fundamentals,icp-features,reference}/` -- `scripts/postprocess-motoko.mjs` — injects frontmatter, rewrites internal links, strips JSX components -- `scripts/sync-icp-cli-version.mjs` — syncs `docs/guides/tools/migrating-from-dfx.md` from `dfinity/icp-cli` - -Restoration checklist: -1. Copy scripts from `restructuring-attempt-1` -2. Update all target paths from `src/content/docs/` to `docs/` -3. Update frontmatter injection to match current schema (no `features` or `last_verified` fields) -4. Run sync and verify output files have correct frontmatter -5. Run `npm run build` to confirm Astro picks up synced files -6. Add sync commands to `package.json` scripts -| P1 | Set up CI workflows | M | `.github/workflows/` — restore from attempt-1, update for new structure | -| P1 | Restore build generators | M | `scripts/generate-llms-txt.mjs`, `scripts/generate-manifest.mjs` — update for new page paths | -| P1 | Custom styling / theming | L | Design TBD — currently using Starlight defaults | -| P1 | Content gap analysis | L | Systematic comparison of all upstream sources against written docs. Depends on Sprint 4 completion (all P0 content). See details below. | -| P2 | Configure CODEOWNERS and branch protection | S | Set up CODEOWNERS with team-specific reviewers (security, defi, languages, etc.) and require CODEOWNERS approval on PRs. Depends on content being written (need to know final review ownership per section). | -| P2 | Content lifecycle strategy | M | Define upstream change detection, sync automation, and freshness ownership. Depends on gap analysis + sync recommendations from content PRs. See details below. | - -**Content gap analysis — details:** - -Run after Sprint 4 (all P0 pages written). Systematic comparison of upstream sources against our docs to catch what individual agents missed: -1. **Portal full diff** — Compare all portal content (`dfinity/portal`) against our 81 pages. Identify uncovered topics, outdated information carried over, and content that exists in portal but was intentionally excluded (document why). -2. **icp-cli docs coverage** — Check all guides and reference pages in `dfinity/icp-cli/docs/` for content we don't reference or cover. Flag guides that should be synced or linked. -3. **Examples repo coverage** — Check `dfinity/examples` for examples with no corresponding docs page or cross-link. -4. **icskills coverage** — Verify every icskill topic has a corresponding guide or concept page that references it. -5. **Page proposal triage** — Review all open GitHub Issues with `page-proposal` label alongside the gap analysis. Prioritize and add approved pages to the plan. -6. **Output** — Prioritized list of: gaps to fill (new pages or sections), content improvements (existing pages missing key information), and upstream sources to add to the sync/monitoring list. - -**Content lifecycle strategy — details:** - -Deferred until after the gap analysis. Design must answer: -1. **Sync vs. hand-written vs. upstream-informed** — Review `` comments from content PRs. Decide which pages to auto-sync and which to monitor manually. -2. **Upstream change detection** — How to detect when upstream repos (icp-cli, examples, icskills, portal) ship changes that affect our docs. Options: GitHub Action that diffs upstream weekly, Dependabot-style alerts, or manual review cadence. -3. **Freshness ownership** — Who reviews upstream changes per section. Maps to CODEOWNERS but for content accuracy, not just code review. -4. **New page proposals** — Review remaining open GitHub Issues with `page-proposal` label. Decide which to add to the plan. - ---- - -## Dependency Layers (P0 pages) - -Pages are organized into layers based on what they depend on. **All pages within the same layer can be written in parallel.** A page can only start once all its dependencies (in prior layers) are at least in `draft` status. - -``` -Layer 0 — No dependencies (start immediately, 3 parallel agents) - ├── concepts/canisters.md ← hub page, most pages depend on this - ├── concepts/network-overview.md - └── concepts/chain-key-cryptography.md - -Layer 1 — Depends on Layer 0 (up to 6 parallel agents) - ├── concepts/app-architecture.md (needs: canisters, network-overview) - ├── concepts/reverse-gas-model.md (needs: canisters) - ├── concepts/orthogonal-persistence.md (needs: canisters) - ├── concepts/https-outcalls.md (needs: canisters) - ├── concepts/security.md (needs: canisters) - ├── concepts/chain-fusion.md (needs: chain-key-cryptography) - ├── getting-started/quickstart.md (needs: canisters) - ├── guides/backends/https-outcalls.md (needs: canisters) - ├── guides/backends/timers.md (needs: canisters) - ├── guides/canister-calls/candid.md (needs: canisters) - └── guides/security/access-management.md (needs: canisters) - -Layer 2 — Depends on Layer 1 (up to 5 parallel agents) - ├── getting-started/project-structure.md (needs: quickstart) - ├── guides/backends/data-persistence.md (needs: canisters, orthogonal-persistence) - ├── guides/canister-calls/onchain-calls.md (needs: candid) - ├── guides/frontends/asset-canister.md (needs: project-structure) - ├── guides/chain-fusion/bitcoin.md (needs: chain-key-cryptography, chain-fusion) - └── guides/chain-fusion/ethereum.md (needs: chain-key-cryptography, chain-fusion) - -Layer 3 — Depends on Layer 2 (up to 4 parallel agents) - ├── getting-started/what-next.md (needs: quickstart, project-structure) - ├── guides/canister-management/lifecycle.md (needs: canisters, data-persistence) - ├── guides/authentication/internet-identity.md (needs: asset-canister) - └── guides/defi/token-ledgers.md (needs: onchain-calls) - -Layer 4 — Depends on Layer 3 (up to 4 parallel agents) - ├── guides/canister-management/settings.md (needs: lifecycle) - ├── guides/canister-management/reproducible-builds.md (needs: lifecycle) - ├── guides/testing/strategies.md (needs: lifecycle) - ├── guides/security/canister-upgrades.md (needs: lifecycle, data-persistence) - └── guides/canister-management/cycles-management.md (needs: lifecycle, settings) - -Layer 5 — Depends on Layer 4 - └── guides/testing/pocket-ic.md (needs: strategies) -``` - -**Critical path** (longest chain): canisters → orthogonal-persistence → data-persistence → lifecycle → settings → cycles-management (6 layers deep). - -**No-dependency pages** (can be written at any time): `migrating-from-dfx.md`, `motoko/index.md`, `reference/token-standards.md`, `reference/cycles-costs.md`. - ---- - -## Phase 1: P0 Pages (38 pages) -- Highest Developer Impact - -These pages form the critical path for any developer building on ICP. Ship these first. - -### Sprint 1: Foundation (7 pages) - -The absolute minimum for a functional docs site. A developer can go from zero to deployed canister. - -**Parallelism:** 3 agents can work simultaneously on Layer 0, then transition to Layer 1 pages. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 1 | — | `index.md` | M | None | Portal home.mdx | original | -| 2 | 0 | `concepts/canisters.md` | M | None | Portal essentials/canisters.mdx, message-execution.mdx | rewrite | -| 3 | 0 | `concepts/network-overview.md` | M | None | Portal essentials/network-overview.mdx | rewrite | -| 4 | 1 | `concepts/app-architecture.md` | M | canisters, network-overview | Portal app-architecture.mdx, application-architectures.mdx | rewrite | -| 5 | 1 | `getting-started/quickstart.md` | L | canisters | Portal quickstart, icp-cli quickstart, installation guide, hello-world template | sync, rewrite | -| 6 | 2 | `getting-started/project-structure.md` | M | quickstart | icp-cli project-model, recipes, binding-generation | sync | -| 7 | 2 | `getting-started/what-next.md` | S | quickstart, project-structure | Developer journey analysis | original | - -### Sprint 2: Core Backend Development (10 pages) - -A developer can write canister logic, handle persistence, make HTTP calls, use timers, and call other canisters. - -**Parallelism:** 4 agents can work simultaneously — concepts cluster, backends cluster, canister-calls cluster, and chain-key cluster run in parallel. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 8 | 0 | `concepts/chain-key-cryptography.md` | M | concepts/network-overview | Portal chain-key sections | rewrite | -| 9 | 1 | `concepts/orthogonal-persistence.md` | M | concepts/canisters | Portal persistence sections | rewrite | -| 10 | 1 | `concepts/https-outcalls.md` | M | concepts/canisters | Portal https-outcalls overview | rewrite | -| 11 | 1 | `concepts/reverse-gas-model.md` | M | concepts/canisters | Portal gas-cost.mdx, tokens-and-cycles.mdx | rewrite | -| 12 | 1 | `concepts/chain-fusion.md` | M | chain-key-cryptography | Portal chain-fusion/overview.mdx, supported-chains.mdx | rewrite | -| 13 | 1 | `guides/canister-calls/candid.md` | M | concepts/canisters | Portal Candid sections, generating-candid.mdx | rewrite | -| 14 | 1 | `guides/backends/https-outcalls.md` | L | concepts/canisters | Portal https-outcalls/ (5 files); icskills: https-outcalls | rewrite | -| 15 | 1 | `guides/backends/timers.md` | M | concepts/canisters | Portal periodic-tasks.mdx | rewrite | -| 16 | 2 | `guides/backends/data-persistence.md` | L | canisters, orthogonal-persistence | Portal storage.mdx, idempotency.mdx; icskills: stable-memory | rewrite | -| 17 | 2 | `guides/canister-calls/onchain-calls.md` | L | candid | Portal advanced-calls.mdx, icp-cli canister-discovery; icskills: multi-canister | rewrite, sync | - -### Sprint 3: Frontend, Auth, and Production (11 pages) - -A developer can build a full-stack app with auth and deploy to mainnet. - -**Parallelism:** 3 agents — frontend/auth track, canister-management track, security/testing track. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 18 | 1 | `concepts/security.md` | M | concepts/canisters | Portal trust-in-canisters.mdx | rewrite | -| 19 | 1 | `guides/security/access-management.md` | M | concepts/canisters | Portal general.mdx (access sections); icskills: canister-security | rewrite | -| 20 | 2 | `guides/frontends/asset-canister.md` | L | project-structure | Portal frontends/using-an-asset-canister.mdx; icskills: asset-canister | rewrite | -| 21 | 3 | `guides/authentication/internet-identity.md` | L | asset-canister | Portal authentication/ (3 files); icskills: internet-identity | rewrite | -| 22 | 3 | `guides/canister-management/lifecycle.md` | XL | concepts/canisters, data-persistence | Portal canister-management/ (8 files); icp-cli build-deploy-sync | rewrite, sync | -| 23 | 4 | `guides/canister-management/settings.md` | M | lifecycle | Portal control.mdx, settings.mdx; icp-cli canister-settings | rewrite, sync | -| 24 | 4 | `guides/canister-management/reproducible-builds.md` | M | lifecycle | Portal reproducible-builds.mdx; @dfinity/prebuilt recipe | rewrite | -| 25 | 4 | `guides/testing/strategies.md` | M | lifecycle | Portal benchmarking.mdx; icp-cli containerized-networks | rewrite | -| 26 | 4 | `guides/security/canister-upgrades.md` | M | lifecycle, data-persistence | icskills: canister-security | original | -| 27 | 5 | `guides/testing/pocket-ic.md` | M | strategies | JS SDK: pic-js docs | original | -| 28 | 5 | `guides/canister-management/cycles-management.md` | L | lifecycle, settings | Portal topping-up.mdx; icp-cli deploying-to-mainnet; icskills: cycles-management | rewrite, sync | - -### Sprint 4: Chain Fusion, DeFi, and Key Reference (9 pages) - -A developer can integrate with Bitcoin/Ethereum and work with tokens. - -**Parallelism:** 3 agents — bitcoin/ethereum track (XL, needs dedicated agents), token/defi track, reference/language track (all independent). - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 29 | 2 | `guides/chain-fusion/bitcoin.md` | XL | chain-key-cryptography, chain-fusion | Portal build-on-btc/ (14 files); icskills: ckbtc | rewrite | -| 30 | 2 | `guides/chain-fusion/ethereum.md` | XL | chain-key-cryptography, chain-fusion | Portal chain-fusion/ethereum/ (10 files); icskills: evm-rpc | rewrite | -| 31 | 3 | `guides/defi/token-ledgers.md` | L | canister-calls/onchain-calls | Portal defi/tokens/; icskills: icrc-ledger | rewrite | -| 32 | — | `guides/tools/migrating-from-dfx.md` | S | None | Auto-synced from icp-cli repo | sync | -| 33 | — | `languages/motoko/index.md` | S | None | Synced content landing page | original | -| 34 | 1 | `languages/rust/index.md` | L | concepts/canisters | Portal Rust CDK intro, limitations, upgrading | rewrite | -| 35 | 1 | `reference/management-canister.md` | L | concepts/canisters | IC interface spec (management canister section) | reference | -| 36 | — | `reference/token-standards.md` | M | None | Portal token-standards files; icskills: icrc-ledger | reference | -| 37 | — | `reference/cycles-costs.md` | M | None | Portal resource-limits.mdx, cost tables | reference | - ---- - -## Phase 2: P1 Pages (29 pages) -- Important but Non-Blocking - -These pages fill out the docs site with important secondary content. - -### Sprint 5: Backend and Canister Guides (9 pages) - -**Parallelism:** 3 agents — backends track (all need only concepts/canisters), canister-management track (all need lifecycle), frontends/auth track. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 38b | 1 | `guides/backends/onchain-ai.md` | M | concepts/canisters | Forum post (LLM canister intro), docs.rs/ic-llm, mops.one/llm; examples: llm_chatbot (Rust/Motoko) | original | -| 39 | 1 | `guides/backends/randomness.md` | M | concepts/canisters | Portal randomness.mdx | rewrite | -| 40 | 2 | `guides/backends/certified-variables.md` | M | concepts/security | Portal advanced-calls.mdx (certified vars); icskills: certified-variables | rewrite | -| 41 | 4 | `guides/canister-management/logs.md` | M | lifecycle | Portal logs.mdx, backtraces.mdx, access-logs.mdx | rewrite | -| 42 | 4 | `guides/canister-management/optimization.md` | M | lifecycle | Portal optimize/rust.mdx, motoko.mdx | rewrite | -| 43 | 4 | `guides/canister-management/snapshots.md` | M | lifecycle | Portal snapshots.mdx; icp-cli canister-snapshots | rewrite, sync | -| 44 | 3 | `guides/frontends/custom-domains.md` | M | asset-canister | Portal custom-domains/ (2 files) | rewrite | -| 45 | 3+ | `guides/frontends/certification.md` | M | asset-canister, certified-variables | Portal asset-security.mdx | rewrite | -| 46 | 4 | `guides/defi/wallet-integration.md` | M | internet-identity | Portal integrate-misc-wallets.mdx; icskills: wallet-integration | rewrite | - -### Sprint 6: Canister Calls, Production, Security, Tools (11 pages) - -**Parallelism:** 4 agents — canister-calls track, security track, tools track (independent), defi track. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| ~~47~~ | — | ~~`guides/canister-calls/binding-generation.md`~~ | — | — | Merged into `candid.md` "Binding generation" section | — | -| 47b | 3 | `guides/canister-calls/offchain-calls.md` | M | candid | JS SDK: @icp-sdk/core, @icp-sdk/canisters; icp-cli canister-discovery; hello-world template | original | -| 48 | 5+ | `guides/canister-management/subnet-selection.md` | M | cycles-management | Portal deploy-specific-subnet.mdx; icp-cli deploying-to-specific-subnets | rewrite, sync | -| 49 | 2 | `guides/security/data-integrity.md` | L | concepts/security | icskills: vetkd, certified-variables; examples: vetkeys, vetkd | rewrite | -| 50 | 2 | `guides/security/dos-prevention.md` | M | concepts/security | icskills: canister-security | original | -| 51 | 3 | `guides/security/inter-canister-calls.md` | M | canister-calls/onchain-calls | icskills: canister-security, multi-canister | original | -| 52 | 3+ | `guides/security/encryption.md` | L | concepts/vetkeys | Portal vetkeys/ (9 files); icskills: vetkd; examples: vetkd, vetkeys, encrypted-notes-dapp-vetkd, filevault | rewrite | -| 53 | 4 | `guides/authentication/verifiable-credentials.md` | M | internet-identity | Portal verifiable-credentials/ (4 files); VC spec | rewrite | -| 54 | — | `guides/tools/overview.md` | M | None | Portal dev-tools-overview.mdx, cdks/index.mdx | rewrite | -| 54b | 2 | `guides/tools/agentic-development.md` | M | quickstart | icskills README, all 17 skills | original | -| 55 | 4+ | `guides/defi/chain-key-tokens.md` | M | token-ledgers, bitcoin, ethereum | Portal chain-key-tokens files; icskills: ckbtc | rewrite | - -### Sprint 7: Governance, Concepts, Languages (8 pages) - -**Parallelism:** 3 agents — governance track (sequential: governance concept → launching → managing/testing), concepts track (all independent), rust track. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 56 | 2+ | `guides/governance/launching.md` | L | concepts/governance | Portal launching/ (4 files), tokenomics/ (4 files); icskills: sns-launch | rewrite | -| 57 | 3+ | `guides/governance/managing.md` | M | launching | Portal managing/ (4 files); icskills: sns-launch | rewrite | -| 58 | 3+ | `guides/governance/testing.md` | M | launching | Portal testing/ (3 files); icskills: sns-launch | rewrite | -| 59 | 2 | `concepts/vetkeys.md` | M | chain-key-cryptography | Portal VetKeys sections; icskills: vetkd | rewrite | -| 60 | — | `concepts/onchain-randomness.md` | S | None | Portal randomness conceptual parts | rewrite | -| 61 | — | `concepts/timers.md` | S | None | Portal periodic-tasks conceptual parts | rewrite | -| 62 | — | `concepts/governance.md` | M | None | Portal tokenomics/index.mdx | rewrite | -| 63 | 2 | `languages/rust/stable-structures.md` | M | rust/index | Portal stable-structures.mdx, canister-state.mdx | rewrite | - -### Sprint 8: Reference Pages (7 pages) - -**Parallelism:** All 7 pages can be written in parallel — no inter-dependencies. Only glossary.md benefits from having concept pages done first. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 64 | — | `reference/system-canisters.md` | M | None | Portal system-canisters references | reference | -| 65 | — | `reference/protocol-canisters.md` | M | None | Portal protocol references; icskills: ckbtc, evm-rpc | reference | -| 66 | — | `reference/subnet-types.md` | M | None | Portal deploy-specific-subnet | reference | -| 67 | — | `reference/execution-errors.md` | M | None | Portal trapping.mdx, resource-limits.mdx | reference | -| 68 | — | `reference/ic-interface-spec.md` | S | None | IC interface spec links | reference | -| 69 | — | `reference/candid-spec.md` | S | None | Candid spec links | reference | -| 70 | all | `reference/glossary.md` | L | All concept pages | Portal glossary; all concept pages | reference | - ---- - -## Phase 3: P2 Pages (11 pages) -- Nice to Have - -These pages cover niche or advanced topics. Ship after P0 and P1 are complete. - -### Sprint 9: Advanced Guides (6 pages) - -**Parallelism:** All 6 pages can run in parallel — dependencies are all from earlier sprints. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 71 | 4 | `guides/canister-management/large-wasm.md` | M | lifecycle | Portal compile.mdx (large Wasm), simd.mdx; examples: backend_wasm64 | rewrite | -| 72 | 3 | `guides/canister-calls/parallel-calls.md` | M | canister-calls/onchain-calls | Portal advanced-calls.mdx (composite queries); examples: parallel_calls | rewrite | -| 73 | 3 | `guides/frontends/frameworks.md` | L | asset-canister | Portal existing-frontend.mdx; examples: react, svelte starters | rewrite | -| 74 | 2 | `guides/chain-fusion/solana.md` | M | chain-fusion concept | Portal solana/overview.mdx | rewrite | -| 75 | 2 | `guides/chain-fusion/dogecoin.md` | M | chain-fusion concept | Portal dogecoin/overview.mdx | rewrite | -| 76 | 4 | `guides/defi/rosetta.md` | L | token-ledgers | Portal defi/rosetta/ files | rewrite | -### Sprint 10: Remaining Reference and Languages (4 pages) - -**Parallelism:** All 4 pages can run in parallel. - -| # | Layer | Page | Effort | Dependencies | Source Material | Skills | -|---|-------|------|--------|-------------|-----------------|--------| -| 78 | — | `reference/application-canisters.md` | M | None | Portal application references | reference | -| 79 | — | `reference/http-gateway-spec.md` | S | None | HTTP gateway spec links | reference | -| 80 | — | `reference/internet-identity-spec.md` | S | None | II spec links | reference | -| 81 | 5 | `languages/rust/testing.md` | M | rust/index, testing/strategies | examples: unit_testable_rust_canister | original | - ---- - -## Effort Summary - -| Phase | Pages | S | M | L | XL | Estimated Total Hours | -|-------|-------|---|---|---|----|-----------------------| -| P0 (Sprint 1-4) | 37 | 3 | 18 | 10 | 3 | ~117 hours | -| P1 (Sprint 5-8) | 33 | 3 | 22 | 4 | 0 | ~91 hours | -| P2 (Sprint 9-10) | 11 | 2 | 6 | 3 | 0 | ~30 hours | -| **Total** | **82** | **8** | **46** | **17** | **3** | **~238 hours** | - ---- - -## Dependencies Graph (Critical Path) - -Arrows show "is required by" (parent → child means child depends on parent). - -``` -concepts/canisters.md ← HUB: most pages depend on this - ├── concepts/app-architecture.md (also needs: network-overview) - ├── concepts/reverse-gas-model.md - ├── concepts/orthogonal-persistence.md - ├── concepts/https-outcalls.md - ├── concepts/security.md - │ ├── guides/backends/certified-variables.md - │ ├── guides/security/data-integrity.md - │ └── guides/security/dos-prevention.md - ├── getting-started/quickstart.md - │ ├── getting-started/project-structure.md - │ │ └── getting-started/what-next.md - │ └── guides/tools/agentic-development.md - ├── guides/canister-calls/candid.md ← NOTE: candid before onchain-calls - │ ├── guides/canister-calls/onchain-calls.md - │ │ ├── guides/defi/token-ledgers.md - │ │ │ └── guides/defi/chain-key-tokens.md - │ │ ├── guides/security/inter-canister-calls.md - │ │ └── guides/canister-calls/parallel-calls.md - │ └── guides/canister-calls/offchain-calls.md - ├── guides/backends/data-persistence.md (also needs: orthogonal-persistence) - │ └── guides/canister-management/lifecycle.md - │ ├── guides/canister-management/settings.md - │ │ └── guides/canister-management/cycles-management.md - │ │ └── guides/canister-management/subnet-selection.md - │ ├── guides/canister-management/reproducible-builds.md - │ ├── guides/canister-management/logs.md - │ ├── guides/canister-management/optimization.md - │ ├── guides/canister-management/snapshots.md - │ ├── guides/testing/strategies.md - │ │ └── guides/testing/pocket-ic.md - │ └── guides/security/canister-upgrades.md - ├── guides/backends/https-outcalls.md - ├── guides/backends/timers.md - └── guides/security/access-management.md - -concepts/network-overview.md - └── concepts/chain-key-cryptography.md - ├── concepts/chain-fusion.md - │ ├── guides/chain-fusion/bitcoin.md - │ ├── guides/chain-fusion/ethereum.md - │ ├── guides/chain-fusion/solana.md - │ └── guides/chain-fusion/dogecoin.md - └── concepts/vetkeys.md - └── guides/security/encryption.md - -getting-started/project-structure.md - └── guides/frontends/asset-canister.md - ├── guides/authentication/internet-identity.md - │ ├── guides/defi/wallet-integration.md - │ └── guides/authentication/verifiable-credentials.md - ├── guides/frontends/custom-domains.md - ├── guides/frontends/certification.md (also needs: certified-variables) - └── guides/frontends/frameworks.md - -concepts/governance.md - └── guides/governance/launching.md - ├── guides/governance/managing.md - └── guides/governance/testing.md - -languages/rust/index.md - ├── languages/rust/stable-structures.md - └── languages/rust/testing.md (also needs: testing/strategies) -``` - -**Critical path** (6 layers deep): -`canisters → orthogonal-persistence → data-persistence → lifecycle → settings → cycles-management → subnet-selection` - -**Independent pages** (no dependencies, can be written at any time): -`index.md`, `migrating-from-dfx.md`, `motoko/index.md`, `reference/token-standards.md`, `reference/cycles-costs.md`, `reference/system-canisters.md`, `reference/protocol-canisters.md`, `reference/subnet-types.md`, `reference/execution-errors.md`, `reference/ic-interface-spec.md`, `reference/candid-spec.md`, `concepts/onchain-randomness.md`, `concepts/timers.md`, `concepts/governance.md`, `guides/tools/overview.md` - ---- - -## Notes - -- `guides/tools/migrating-from-dfx.md` is auto-synced from the icp-cli repo, so it needs no manual authoring. -- Motoko language pages (~60) are synced from `caffeinelabs/motoko` and are not included in this plan. See `decisions.md` for details. -- Cross-links between concept-guide pairs should be added as content is written. -- **All icp-cli commands, flags, and installation instructions must be verified** against the icp-cli repo source (`dfinity/icp-cli`, `docs/reference/cli.md`). Never guess CLI syntax — fetch with: `gh api repos/dfinity/icp-cli/contents/docs/reference/cli.md --jq '.content' | base64 -d` -- Each stub page contains ``, ``, and `` HTML comments — read these before writing. -- After completing a page, open a PR with a `## Sync recommendation` section and link it to the corresponding GitHub Issue. - ---- - -## Learn Hub migration batches - -Nine content PRs to migrate learn.internetcomputer.org articles into `docs/`. Source staging files are in `.migration/learn-hub/`. Full article-to-file mapping and cross-link instructions: `.docs-plan/learn-hub-navigation.md`. Per-batch agent workflow: `.docs-plan/learn-hub-migration.md`. - -To claim a batch: check `git ls-remote origin docs/concepts-*` — branch exists means claimed, open PR against `infra/learn-hub-migration-prep` means in progress, branch gone (merged) means done. No GitHub Issues needed. Full workflow: `.docs-plan/learn-hub-migration.md`. - -| Batch | Branch | Target files | Effort | Status | -|---|---|---|---|---| -| 1 — Protocol stack | `docs/concepts-protocol-stack` | `concepts/protocol/index.md`, `consensus.md`, `peer-to-peer.md`, `message-routing.md`, `execution.md`, `state-synchronization.md` | Large | open | -| 2 — Node infrastructure | `docs/concepts-node-infrastructure` | `concepts/node-infrastructure.md` | Medium | open | -| 3 — Edge infrastructure | `docs/concepts-edge-infrastructure` | `concepts/edge-infrastructure.md` | Medium | open | -| 4 — Evolution & scaling | `docs/concepts-evolution-scaling` | `concepts/evolution-scaling.md` | Small–medium | open | -| 5 — Chain Fusion deep dives | `docs/concepts-chain-fusion-deep-dives` | `concepts/chain-fusion/index.md` (moved), `bitcoin.md`, `ethereum.md`, `solana.md`, `dogecoin.md`, `exchange-rate-canister.md`, `chain-key-tokens.md` | Large | open | -| 6 — Cryptography deep dives | `docs/concepts-cryptography-deep-dives` | `concepts/certified-data.md`, expand `concepts/chain-key-cryptography.md` | Medium | open | -| 7 — Governance deep dives | `docs/concepts-governance-deep-dives` | expand `concepts/governance.md`, `concepts/sns-framework.md`, `references/nns-proposal-types.md`, `references/sns-dao-settings.md` | Large | open (do batch 8 first) | -| 8 — Tokens & ledgers | `docs/concepts-tokens-ledgers` | `concepts/tokenomics.md`, `concepts/token-ledgers.md`, expand `concepts/cycles.md` | Medium | open | -| 9 — Canister concept fillers | `docs/concepts-canister-fillers` | `concepts/principals.md`, expand `concepts/canisters.md` | Medium | open | diff --git a/.docs-plan/synthesis.md b/.docs-plan/synthesis.md deleted file mode 100644 index a5472194..00000000 --- a/.docs-plan/synthesis.md +++ /dev/null @@ -1,223 +0,0 @@ -# Synthesis: Final Documentation Structure - -> Generated 2026-03-11. This is the canonical structure definition for the ICP developer docs restructuring. Every page listed here has a corresponding stub in `docs/`. - -## Design Principles - -1. **Diataxis-aligned** -- Getting Started (tutorials), Guides (how-to), Concepts (explanations), Reference (information) -2. **Developer-journey ordered** -- Sidebar follows build -> ship -> scale progression -3. **Agent-friendly** -- Predictable paths: "how to X" = `guides/{category}/X.md`, "what is X" = `concepts/X.md` -4. **No duplication** -- Link to icp-cli docs, JS SDK, Learn Hub, mops.one, docs.rs for external content -5. **icskills as source material** -- Agents read icskills from `.sources/icskills/` for accurate canister IDs and code patterns; skills are discoverable via the skills registry endpoint in `llms.txt` - ---- - -## Pages by Section - -### Landing Page (1 page) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 1 | `index.md` | ICP Developer Docs | landing | beginner | Compelling landing page highlighting the zero-to-production developer journey. Surfaces IC capabilities (chain-key, chain fusion, orthogonal persistence, reverse gas). Links to all five sections and external resources. | Portal home.mdx, DOCS_RESTRUCTURING_PROPOSAL.md | All section index pages | P0 | - -### Getting Started (4 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 2 | `getting-started/quickstart.md` | Quickstart | tutorial | beginner | Install icp-cli, scaffold a project with `icp new`, start local network, deploy, call canister, view frontend. Under 10 minutes. Single linear path, no forks. | Portal building-apps/getting-started/quickstart.mdx, icp-cli quickstart.md, icp-cli guides/installation.md, hello-world template | project-structure, what-next, concepts/canisters | P0 | -| 3 | `getting-started/project-structure.md` | Project Structure | tutorial | beginner | Explain icp.yaml, .icp/ directory, canister discovery, recipes, and binding generation. Walk through the hello-world template output. | icp-cli concepts/project-model.md, concepts/recipes.md, concepts/binding-generation.md, hello-world template | quickstart, guides/canister-calls/binding-generation, guides/frontends/asset-canister | P0 | -| 4 | `guides/tools/agentic-development.md` | Agentic Development | how-to | beginner | Set up AI-assisted ICP development. Install icskills, configure your AI agent (Claude, Cursor, Copilot), use skills for code generation. References llm_chatbot examples as demo. | icskills README, all 17 skills, llm_chatbot examples (Rust/Motoko) | quickstart, guides/tools/overview | P1 | -| 5 | `getting-started/what-next.md` | What Next? | tutorial | beginner | Critical routing page. Presents 4-5 paths based on developer goals: backend-only, full-stack, chain fusion, DeFi, governance. Each path has 2-3 sentences and direct links to the relevant guides section. | Developer journey analysis, all guides/ sections | All guides/ section entry pages | P0 | - -### Guides -- Backends (7 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 6 | `guides/backends/data-persistence.md` | Data Persistence | how-to | intermediate | Store and retrieve data in canisters. Covers stable structures (Rust), persistent actors (Motoko), MemoryManager, upgrade hooks. Idempotency patterns. | Portal building-apps/canister-management/storage.mdx, best-practices/storage.mdx, best-practices/idempotency.mdx; icskills: stable-memory; examples: daily_planner, superheroes, photo_gallery | concepts/orthogonal-persistence, guides/canister-management/lifecycle, languages/rust/stable-structures | P0 | -| 7 | `guides/backends/https-outcalls.md` | HTTPS Outcalls | how-to | intermediate | Make HTTP GET/POST requests from canisters to external APIs. Transform functions, cycle costs, response size limits, idempotency. Inline GET example (~20 lines each language). | Portal building-apps/integrations/https-outcalls/ (5 files); icskills: https-outcalls; examples: send_http_get, send_http_post, exchange-rates | concepts/https-outcalls, guides/chain-fusion/ethereum | P0 | -| 8 | `guides/backends/timers.md` | Timers | how-to | intermediate | Set up one-shot and periodic timers in canisters. Timer API for Rust and Motoko. Heartbeat migration. Common patterns: periodic cleanup, scheduled tasks. | Portal building-apps/integrations/periodic-tasks.mdx; examples: periodic_tasks (Rust) | concepts/timers, guides/canister-management/lifecycle | P0 | -| 9 | `guides/backends/randomness.md` | Onchain Randomness | how-to | intermediate | Generate unpredictable random numbers using the management canister's raw_rand API. Use cases: games, lotteries, fair selection. Security considerations. | Portal building-apps/integrations/randomness.mdx; examples: random_maze (Motoko) | concepts/onchain-randomness, guides/security/data-integrity | P1 | -| 10 | `guides/backends/certified-variables.md` | Certified Variables | how-to | advanced | Implement certified data for query responses. Merkle trees, witness generation, the certified data API. Frontend verification of certified responses. | Portal building-apps/integrations/advanced-calls.mdx (certified variables section); icskills: certified-variables; examples: cert-var (Motoko) | concepts/security, guides/frontends/certification | P1 | -| 11 | `guides/canister-management/large-wasm.md` | Large Wasm Modules | how-to | advanced | Deploy canisters exceeding the 2MB Wasm limit. Wasm chunk store, gzip compression, ic-wasm tool. Wasm64 support. | Portal building-apps/developing-canisters/compile.mdx (large Wasm section); examples: backend_wasm64 (Rust) | guides/canister-management/optimization, reference/execution-errors | P2 | -| 12 | `guides/canister-calls/parallel-calls.md` | Parallel Calls | how-to | advanced | Execute multiple inter-canister calls concurrently. Futures in Rust, async in Motoko. Error handling for partial failures. Performance benefits. | Portal building-apps/integrations/advanced-calls.mdx (composite queries section); icskills: multi-canister; examples: parallel_calls (both), composite_query (both) | guides/canister-calls/onchain-calls, guides/canister-management/optimization | P2 | - -### Guides -- Canisters (6 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 13 | `guides/canister-management/lifecycle.md` | Canister Lifecycle | how-to | intermediate | Create, install, upgrade, and delete canisters. Pre/post-upgrade hooks, state management, canister factory pattern. Migration between subnets. | Portal building-apps/canister-management/upgrade.mdx, state.mdx, developing-canisters/create.mdx, compile.mdx, install.mdx, deploy.mdx, delete.mdx, history.mdx, trapping.mdx, advanced/canister-migration.mdx; icp-cli concepts/build-deploy-sync.md; icskills: cycles-management, stable-memory; examples: canister_factory, classes, canister-info | concepts/canisters, guides/backends/data-persistence, guides/canister-management/cycles-management | P0 | -| 14 | `guides/canister-management/settings.md` | Canister Settings | how-to | intermediate | Configure controllers, memory limits, freezing threshold, compute allocation, and log visibility. Environment-specific settings. | Portal building-apps/canister-management/control.mdx, settings.mdx; icp-cli reference/canister-settings.md, concepts/environments.md; icskills: cycles-management | guides/canister-management/lifecycle, guides/canister-management/cycles-management, reference/cycles-costs | P0 | -| 15 | `guides/canister-management/logs.md` | Canister Logs | how-to | intermediate | Debug canisters using the logging API. Log levels, structured logging, query statistics. Access logs for monitoring. | Portal building-apps/canister-management/logs.mdx, backtraces.mdx, advanced/canister-access-logs.mdx; examples: canister_logs (both), query_stats (both) | guides/testing/strategies, guides/canister-management/lifecycle | P1 | -| 16 | `guides/canister-management/optimization.md` | Canister Optimization | how-to | advanced | Reduce Wasm size and improve canister performance. ic-wasm shrinking, SIMD, performance counters, memory management. Language-specific tips. | Portal building-apps/advanced/optimize/rust.mdx, motoko.mdx; examples: low_wasm_memory (both), performance_counters, simd, face-recognition, image-classification | guides/canister-management/large-wasm, reference/cycles-costs | P1 | -| 17 | `guides/canister-management/snapshots.md` | Canister Snapshots | how-to | intermediate | Create, list, restore, and delete canister snapshots for backup and recovery. Programmatic snapshots via management canister API. | Portal building-apps/canister-management/snapshots.mdx; icp-cli guides/canister-snapshots.md; examples: canister-snapshots, canister-snapshot-download (Rust) | guides/canister-management/lifecycle, guides/security/canister-upgrades | P1 | -| 18 | `guides/canister-management/reproducible-builds.md` | Reproducible Builds | how-to | advanced | Verify canister Wasm matches source code. Docker-based builds, sha256 verification, the prebuilt recipe. Trust and transparency for users. | Portal building-apps/best-practices/reproducible-builds.mdx; @dfinity/prebuilt recipe | guides/canister-management/lifecycle, concepts/security, guides/canister-management/cycles-management | P0 | - -### Guides -- Frontends (4 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 19 | `guides/frontends/asset-canister.md` | Asset Canister | how-to | intermediate | Deploy frontend assets to ICP. The @dfinity/asset-canister recipe, build configuration, SPA routing, programmatic uploads via JS SDK. | Portal building-apps/frontends/using-an-asset-canister.mdx, uploading-serving-assets.mdx; icp-cli concepts/canister-discovery.md; icskills: asset-canister; examples: static-website, photo-storage, my_crypto_blog; JS SDK: @icp-sdk/canisters; static-website template | getting-started/project-structure, guides/frontends/custom-domains, guides/frontends/certification | P0 | -| 20 | `guides/frontends/custom-domains.md` | Custom Domains | how-to | intermediate | Point a custom domain to your ICP-hosted frontend. DNS configuration, boundary node registration, SSL certificates. | Portal building-apps/frontends/custom-domains/using-custom-domains.mdx, dns-setup.mdx; icskills: asset-canister | guides/frontends/asset-canister, guides/canister-management/cycles-management | P1 | -| 21 | `guides/frontends/certification.md` | Response Certification | how-to | advanced | Verify that query responses come from the IC and have not been tampered with. Client-side certificate verification, the service worker approach. | Portal building-apps/frontends/asset-security.mdx; icskills: certified-variables; JS SDK: @icp-sdk/core (certificate verification) | guides/backends/certified-variables, concepts/security | P1 | -| 22 | `guides/frontends/frameworks.md` | Frontend Frameworks | how-to | intermediate | Integrate React, Svelte, Vue, or other frameworks with ICP. Vite plugin setup, agent configuration, framework starters. Also covers Unity, Godot for game hosting. | Portal building-apps/frontends/existing-frontend.mdx; JS SDK: @icp-sdk/core, @icp-sdk/auth; examples: hosting/react, svelte-motoko-starter, sveltekit-starter, godot-html5-template, unity-webgl-template | guides/frontends/asset-canister, guides/authentication/internet-identity | P2 | - -### Guides -- Authentication (2 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 23 | `guides/authentication/internet-identity.md` | Internet Identity | how-to | intermediate | Integrate passkey-based authentication. Frontend setup with @icp-sdk/auth, delegation handling, principal-per-app isolation, alternative origins. Unity native app integration. | Portal building-apps/authentication/overview.mdx, integrate-internet-identity.mdx, alternative-origins.mdx; icskills: internet-identity; JS SDK: @icp-sdk/auth; examples: internet_identity_integration (Motoko), encrypted-notes-dapp-vetkd (both), unity native-apps | concepts/security, guides/frontends/frameworks, reference/internet-identity-spec | P0 | -| 24 | `guides/defi/wallet-integration.md` | Wallet Integration | how-to | advanced | Connect ICRC signer-standard wallets (OISY, Plug, NFID). ICRC-21/25/27/29/49 standards, popup wallet model, consent messages. | Portal building-apps/authentication/integrate-misc-wallets.mdx; icskills: wallet-integration; examples: oisy-signer-demo; icp-cli guides/managing-identities.md | guides/authentication/internet-identity, reference/token-standards | P1 | - -### Guides -- Canister Calls (3 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 25 | `guides/canister-calls/onchain-calls.md` | Onchain Calls | how-to | intermediate | Call functions on other canisters. Canister discovery (env vars, ic_env cookie), update vs query calls, error handling, third-party canister integration. | Portal building-apps/integrations/advanced-calls.mdx, advanced/using-third-party-canisters.mdx, developer-tools/cdks/rust/intercanister.mdx; icp-cli concepts/canister-discovery.md; icskills: multi-canister; examples: inter-canister-calls (Rust), pub-sub (Motoko) | concepts/canisters, guides/canister-calls/candid, guides/canister-calls/parallel-calls | P0 | -| 26 | `guides/canister-calls/candid.md` | Candid Interface | how-to | intermediate | Define and use Candid interfaces for canister communication. Type mapping between Rust/Motoko/JS, service definitions, type generation. | Portal building-apps/developing-canisters/ (Candid sections), developer-tools/cdks/rust/generating-candid.mdx; examples: candid_type_generation (Rust); JS SDK: @icp-sdk/core | guides/canister-calls/onchain-calls, guides/canister-calls/binding-generation, reference/candid-spec | P0 | -| 27 | `guides/canister-calls/binding-generation.md` | Binding Generation | how-to | intermediate | Generate type-safe bindings from Candid files. @icp-sdk/bindgen for JS/TS, didc for Rust, icp-cli automatic generation. Vite plugin integration. | icp-cli concepts/binding-generation.md; icskills: multi-canister; JS SDK: @icp-sdk/bindgen; examples: hello-world template (shows Vite plugin) | guides/canister-calls/candid, getting-started/project-structure | P1 | -| 27b | `guides/canister-calls/offchain-calls.md` | Offchain Calls | how-to | intermediate | Call canister functions from JS/TS frontends, scripts, and agents. Agent creation, canister discovery, query vs update calls, authentication context, error handling. | JS SDK: @icp-sdk/core, @icp-sdk/canisters; icp-cli concepts/canister-discovery.md; hello-world template | guides/canister-calls/candid, guides/canister-calls/binding-generation, guides/canister-calls/onchain-calls, guides/frontends/asset-canister, guides/authentication/internet-identity | P1 | - -### Guides -- Testing (2 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 28 | `guides/testing/strategies.md` | Testing Strategies | how-to | intermediate | Overview of testing approaches: unit tests, integration tests with PocketIC, benchmarking, Docker-based test networks. Why testing matters on ICP (irreversible upgrades, cycle costs). | Portal building-apps/advanced/benchmarking.mdx; icp-cli guides/containerized-networks.md; examples: unit_testable_rust_canister; JS SDK: pic-js | guides/testing/pocket-ic, guides/canister-management/lifecycle | P0 | -| 29 | `guides/testing/pocket-ic.md` | PocketIC | how-to | intermediate | Run integration tests against a lightweight IC replica. Rust PocketIC library, Pic JS for JavaScript, multi-subnet testing, time travel. | icskills: (none yet); JS SDK: pic-js; icp-cli guides/containerized-networks.md; examples: (none standalone, linked from pic-js docs) | guides/testing/strategies, guides/governance/testing | P0 | - -### Guides -- Production (3 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 30 | `guides/canister-management/subnet-selection.md` | Subnet Selection | how-to | intermediate | Choose the right subnet for deployment. Application vs system subnets, European subnet, fiduciary subnet, colocation. Deploy to specific subnet with icp-cli. | Portal building-apps/developing-canisters/deploy-specific-subnet.mdx; icp-cli guides/deploying-to-specific-subnets.md; reference/subnet-types | concepts/network-overview, guides/canister-management/cycles-management, reference/subnet-types | P1 | -| 31 | `guides/canister-management/cycles-management.md` | Cycles Management | how-to | intermediate | Acquire cycles and manage canister budgets. ICP-to-cycles conversion via CMC, top-ups, freezing thresholds, monitoring balance, multi-environment deployment. Production checklist. | Portal building-apps/canister-management/topping-up.mdx, building-apps/getting-started/tokens-and-cycles.mdx; icp-cli guides/deploying-to-mainnet.md, guides/tokens-and-cycles.md, guides/managing-environments.md; icskills: cycles-management; examples: hello_cycles (Motoko); proxy template | concepts/reverse-gas-model, guides/canister-management/settings, reference/cycles-costs | P0 | -| 32 | `guides/canister-management/canister-discovery.md` | Canister Discovery | how-to | intermediate | Make your canister findable on the IC dashboard. Metadata, ICRC-1 compliance for token discovery, dashboard REST APIs. | icskills: ic-dashboard; reference/system-canisters | guides/canister-management/settings, reference/system-canisters | P2 | - -### Guides -- Chain Fusion (4 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 33 | `guides/chain-fusion/bitcoin.md` | Bitcoin Integration | how-to | advanced | Send and receive BTC from canisters. Address generation (ECDSA + Schnorr), transaction creation/signing/submission, UTXO management, local regtest setup. ckBTC overview. | Portal build-on-btc/ (14 files); icskills: ckbtc; examples: basic_bitcoin (both), threshold-ecdsa (both), threshold-schnorr (both); bitcoin-starter template | concepts/chain-fusion, concepts/chain-key-cryptography, guides/defi/chain-key-tokens | P0 | -| 34 | `guides/chain-fusion/ethereum.md` | Ethereum Integration | how-to | advanced | Interact with Ethereum from canisters. EVM RPC canister (7hfb6-caaaa-aaaar-qadga-cai), address generation, transaction signing/submission, ERC-20 reads. | Portal building-apps/chain-fusion/ethereum/ (10 files); icskills: evm-rpc; examples: basic_ethereum, evm_block_explorer (both), threshold-ecdsa (both) | concepts/chain-fusion, guides/backends/https-outcalls, guides/defi/chain-key-tokens | P0 | -| 35 | `guides/chain-fusion/solana.md` | Solana Integration | how-to | advanced | Interact with Solana from canisters. Sol RPC canister, transaction signing, SPL token reads. Current status and limitations. | Portal building-apps/chain-fusion/solana/overview.mdx; examples: basic_solana (redirects to sol-rpc-canister repo) | concepts/chain-fusion, guides/chain-fusion/ethereum | P2 | -| 36 | `guides/chain-fusion/dogecoin.md` | Dogecoin Integration | how-to | advanced | Send and receive DOGE from canisters. Dogecoin canister integration, address generation, transaction workflow. | Portal building-apps/chain-fusion/dogecoin/overview.mdx; examples: basic_dogecoin (redirects to dogecoin-canister repo) | concepts/chain-fusion, guides/chain-fusion/bitcoin | P2 | - -### Guides -- DeFi (3 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 37 | `guides/defi/token-ledgers.md` | Token Ledgers | how-to | intermediate | Transfer ICP and ICRC-1/ICRC-2 tokens from canisters. Ledger canister interaction, approve/transferFrom, fee handling, local test ledger setup. | Portal defi/tokens/ (multiple files); icskills: icrc-ledger; JS SDK: @icp-sdk/canisters; examples: icp_transfer, token_transfer, token_transfer_from (both), icrc2-swap, receiving-icp, ic-pos, nft-creator, tokenmania | reference/token-standards, guides/defi/chain-key-tokens, guides/canister-calls/onchain-calls | P0 | -| 38 | `guides/defi/chain-key-tokens.md` | Chain-Key Tokens | how-to | advanced | Work with ckBTC, ckETH, and other chain-key tokens. Minting, redemption, ledger interaction, subaccount derivation. | Portal defi/chain-key-tokens/ files; icskills: ckbtc; JS SDK: @icp-sdk/canisters; examples: token_transfer (both) | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum, guides/defi/token-ledgers | P1 | -| 39 | `guides/defi/rosetta.md` | Rosetta API | how-to | advanced | Integrate with the Rosetta API for exchange compatibility. Construction API, Data API, ICP-specific extensions. | Portal defi/rosetta/ files | guides/defi/token-ledgers, reference/token-standards | P2 | - -### Guides -- Governance (3 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 40 | `guides/governance/launching.md` | Launching an SNS | how-to | advanced | Decentralize your app with an SNS. Token economics configuration, governance parameters, integration checklist, NNS proposal submission. | Portal building-apps/governing-apps/launching/ (4 files), tokenomics/ (4 files); icskills: sns-launch; examples: sns-adaptor (Rust) | concepts/governance, guides/governance/testing, guides/governance/managing | P1 | -| 41 | `guides/governance/managing.md` | Managing an SNS | how-to | advanced | Operate a live SNS. Making proposals, cycles management, asset canister updates, neuron staking from CLI. | Portal building-apps/governing-apps/managing/ (4 files); icskills: sns-launch; JS SDK: @icp-sdk/canisters; examples: stake_neuron_from_cli (Rust) | guides/governance/launching, concepts/governance | P1 | -| 42 | `guides/governance/testing.md` | Testing SNS Governance | how-to | advanced | Test your SNS before mainnet launch. Local testing with PocketIC, testflight on mainnet, pre-launch verification checklist. | Portal building-apps/governing-apps/testing/ (3 files); icskills: sns-launch; JS SDK: pic-js | guides/governance/launching, guides/testing/pocket-ic | P1 | - -### Guides -- Security (5 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 43 | `guides/security/access-management.md` | Access Management | how-to | intermediate | Control who can call your canister. Controller-only functions, caller checking, anonymous principal rejection, Rust guards. | Portal building-apps/best-practices/general.mdx (access control sections); icskills: canister-security; examples: guards (Rust), who_am_i (both, inline ~10 lines) | concepts/security, guides/canister-management/settings | P0 | -| 44 | `guides/security/canister-upgrades.md` | Secure Upgrades | how-to | intermediate | Upgrade canisters safely. Pre/post-upgrade hooks, stable memory migration, rollback strategies, snapshot-based recovery. | icskills: canister-security; portal building-apps/canister-management/upgrade.mdx | guides/canister-management/lifecycle, guides/canister-management/snapshots, guides/backends/data-persistence | P0 | -| 45 | `guides/security/data-integrity.md` | Data Integrity | how-to | advanced | Protect data confidentiality and integrity. VetKeys for onchain encryption, X.509 certificates, signature verification, IBE patterns. | Portal building-apps/authentication/independently-verifying-ic-signatures.mdx; icskills: canister-security, vetkd, certified-variables; examples: vetkd, vetkeys (both), encrypted-notes-dapp-vetkd (both), x509 (Rust), filevault (Motoko) | concepts/vetkeys, concepts/security, guides/backends/certified-variables | P1 | -| 46 | `guides/security/dos-prevention.md` | DoS Prevention | how-to | intermediate | Protect canisters from denial-of-service attacks. Rate limiting, cycle drain protection, ingress message filtering, resource limits. | icskills: canister-security; portal building-apps/best-practices/general.mdx (DoS sections) | concepts/security, guides/canister-management/settings, reference/cycles-costs | P1 | -| 47 | `guides/security/inter-canister-calls.md` | Inter-Canister Call Safety | how-to | advanced | Handle the security pitfalls of async inter-canister calls. Reentrancy (CallerGuard), saga pattern, callback traps, bounded/unbounded wait. | icskills: canister-security, multi-canister | guides/canister-calls/onchain-calls, guides/canister-calls/parallel-calls, concepts/security | P1 | - -### Guides -- Tools (2 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 48 | `guides/tools/overview.md` | Developer Tools | how-to | beginner | Overview of the ICP developer toolchain. icp-cli, CDKs (Rust CDK, Motoko), icp.ninja playground, VS Code extensions, ic-wasm. Links to all external tool docs. | Portal building-apps/developer-tools/dev-tools-overview.mdx, cdks/index.mdx, icp-ninja.mdx; icskills: icp-cli | getting-started/quickstart, guides/tools/migrating-from-dfx | P1 | -| 49 | `guides/tools/migrating-from-dfx.md` | Migrating from dfx | how-to | intermediate | Synced from icp-cli repo. Command mapping, config migration, breaking changes. | icp-cli migration/from-dfx.md (auto-synced) | guides/tools/overview | P0 | - -### Concepts (13 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 50 | `concepts/network-overview.md` | Network Overview | explanation | beginner | What is the Internet Computer? Subnets, nodes, consensus, boundary nodes. Developer-focused: what does the network architecture mean for your app? | Portal building-apps/essentials/network-overview.mdx; Learn Hub: consensus, subnets | concepts/canisters, concepts/app-architecture, reference/subnet-types | P0 | -| 51 | `concepts/app-architecture.md` | Application Architecture | explanation | beginner | How ICP apps are structured. Canister as backend + frontend, inter-canister communication, frontend-to-canister flow. Comparison with traditional web apps and Ethereum. | Portal building-apps/best-practices/application-architectures.mdx, getting-started/app-architecture.mdx | concepts/canisters, guides/frontends/asset-canister, guides/canister-calls/onchain-calls | P0 | -| 52 | `concepts/canisters.md` | Canisters | explanation | beginner | What are canisters? Smart contracts that run WebAssembly, hold state, serve HTTP, and pay for their own compute. Execution model, message types, memory model. | Portal building-apps/essentials/canisters.mdx, message-execution.mdx; Learn Hub: canister execution | concepts/app-architecture, guides/canister-management/lifecycle, concepts/reverse-gas-model | P0 | -| 53 | `concepts/chain-key-cryptography.md` | Chain-Key Cryptography | explanation | intermediate | Threshold signatures that enable the IC's unique capabilities. ECDSA, Schnorr, BLS, key management, chain evolution technology. | Portal (chain-key sections scattered); Learn Hub: threshold signatures | concepts/chain-fusion, guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum | P0 | -| 54 | `concepts/vetkeys.md` | VetKeys | explanation | advanced | Verifiable encrypted threshold key derivation. Onchain encryption, identity-based encryption, transport keys. Current status and roadmap. | Portal (vetkeys sections); Learn Hub: VetKeys; icskills: vetkd | guides/security/data-integrity, concepts/chain-key-cryptography | P1 | -| 55 | `concepts/https-outcalls.md` | HTTPS Outcalls | explanation | intermediate | How canisters make HTTP requests to the outside world. Consensus on responses, transform functions, cycle pricing, limitations. | Portal building-apps/integrations/https-outcalls/ (overview files); Learn Hub: HTTPS outcalls consensus | guides/backends/https-outcalls, guides/chain-fusion/ethereum | P0 | -| 56 | `concepts/onchain-randomness.md` | Onchain Randomness | explanation | intermediate | How ICP generates unpredictable random numbers. VRF-based randomness from the management canister, security guarantees, use cases. | Portal building-apps/integrations/randomness.mdx (conceptual parts); Learn Hub: VRF | guides/backends/randomness, concepts/security | P1 | -| 57 | `concepts/timers.md` | Timers | explanation | intermediate | The global timer mechanism. How the IC schedules periodic and one-shot tasks. Comparison with heartbeats (deprecated). | Portal building-apps/integrations/periodic-tasks.mdx (conceptual parts); Learn Hub: timers | guides/backends/timers, concepts/canisters | P1 | -| 58 | `concepts/reverse-gas-model.md` | Reverse Gas Model | explanation | beginner | Why users do not pay gas on ICP. Canisters pay cycles for compute, storage, and bandwidth. ICP-to-cycles conversion. Cost predictability. | Portal building-apps/essentials/gas-cost.mdx, getting-started/tokens-and-cycles.mdx; Learn Hub: cycles economics | guides/canister-management/cycles-management, reference/cycles-costs, concepts/canisters | P0 | -| 59 | `concepts/orthogonal-persistence.md` | Orthogonal Persistence | explanation | intermediate | How canister memory survives across executions and upgrades. Stable memory, heap persistence in Motoko, stable structures in Rust. | Portal (persistence sections); Learn Hub: orthogonal persistence | guides/backends/data-persistence, languages/rust/stable-structures, guides/canister-management/lifecycle | P0 | -| 60 | `concepts/chain-fusion.md` | Chain Fusion | explanation | intermediate | How ICP connects to Bitcoin, Ethereum, Solana, and other chains. Chain-key signatures, threshold ECDSA/Schnorr, HTTP outcalls to other chains, chain-key tokens. | Portal building-apps/chain-fusion/overview.mdx, supported-chains.mdx, evm-rpc/how-it-works.mdx; Learn Hub: chain-key tokens | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum, concepts/chain-key-cryptography | P0 | -| 61 | `concepts/governance.md` | Governance | explanation | intermediate | How ICP is governed. The NNS, SNS for app governance, neuron staking, proposals, tokenomics basics. | Portal building-apps/governing-apps/tokenomics/index.mdx; Learn Hub: NNS | guides/governance/launching, guides/governance/managing | P1 | -| 62 | `concepts/security.md` | Security Model | explanation | intermediate | The IC security model. Canister isolation, trust boundaries, certified variables, the role of boundary nodes. Threat model for app developers. | Portal building-apps/best-practices/trust-in-canisters.mdx; icskills: canister-security; Learn Hub: security model | guides/security/access-management, guides/security/canister-upgrades, guides/frontends/certification | P0 | - -### Languages -- Motoko (1 page, rest synced) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 63 | `languages/motoko/index.md` | Motoko | explanation | beginner | Landing page for Motoko documentation. Overview of the language, links to synced fundamentals/ICP features/reference sections. Link to mops.one/core (standard library; supersedes base). Note the base→core migration guide (synced). | Synced from caffeinelabs/motoko; Motoko core: https://mops.one/core/docs; base→core migration guide synced from Motoko repo | getting-started/quickstart, guides/backends/data-persistence | P0 | - -### Languages -- Rust (3 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 64 | `languages/rust/index.md` | Rust CDK | explanation | intermediate | Getting started with Rust on ICP. ic-cdk overview, project setup with @dfinity/rust recipe, canister macros, message types, inter-canister calls. Limitations and workarounds. | Portal developer-tools/cdks/rust/intro-to-rust.mdx, rust-limitations.mdx, upgrading.mdx, message-inspect.mdx; Rust CDK: https://docs.rs/ic-cdk/latest/ic_cdk/ | getting-started/quickstart, guides/backends/data-persistence, languages/rust/stable-structures | P0 | -| 65 | `languages/rust/stable-structures.md` | Stable Structures | how-to | intermediate | Use StableBTreeMap, StableVec, and other stable data structures in Rust canisters. MemoryManager, upgrade patterns, when to use stable vs heap. | Portal developer-tools/cdks/rust/stable-structures.mdx, canister-state.mdx; icskills: stable-memory; Rust CDK: https://docs.rs/ic-cdk/latest/ic_cdk/ | guides/backends/data-persistence, concepts/orthogonal-persistence, guides/canister-management/lifecycle | P1 | -| 66 | `languages/rust/testing.md` | Testing Rust Canisters | how-to | intermediate | Unit and integration testing for Rust canisters. Mocking ic-cdk calls, PocketIC Rust library, test patterns. | examples: unit_testable_rust_canister; Rust CDK: https://docs.rs/ic-cdk/latest/ic_cdk/ | guides/testing/strategies, guides/testing/pocket-ic | P2 | - -### Reference (13 pages) - -| # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | -|---|------|-------|----------|-------|---------------|-----------------|-------------|----------| -| 67 | `reference/management-canister.md` | Management Canister | reference | intermediate | API reference for the IC management canister (aaaaa-aa). All methods: create_canister, install_code, raw_rand, ecdsa_public_key, sign_with_ecdsa, http_request, etc. | Portal references/ic-interface-spec (management canister section); IC interface spec | concepts/canisters, guides/canister-management/lifecycle, guides/backends/randomness | P0 | -| 68 | `reference/system-canisters.md` | System Canisters | reference | intermediate | Inventory of system-level canisters: NNS canisters (governance, ledger, registry, CMC, cycles minting), Internet Identity, ICP ledger with canister IDs. | Portal references/system-canisters; icskills: ic-dashboard | reference/management-canister, concepts/governance | P1 | -| 69 | `reference/protocol-canisters.md` | Protocol Canisters | reference | intermediate | Canisters that implement protocol-level features: Bitcoin canister, EVM RPC canister, exchange rate canister, SNS-W. Canister IDs and interfaces. | Portal references/ (scattered); icskills: ckbtc, evm-rpc | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum, reference/system-canisters | P1 | -| 70 | `reference/application-canisters.md` | Application Canisters | reference | intermediate | Notable application-layer canisters: asset canister, SNS canisters. Canister IDs, interfaces, versioning. | Portal references/ (scattered); icskills: asset-canister, sns-launch | guides/frontends/asset-canister, guides/governance/launching | P2 | -| 71 | `reference/token-standards.md` | Token Standards | reference | intermediate | ICRC-1 (fungible transfers), ICRC-2 (approve/transferFrom), ICRC-3 (transaction log), ICRC-7 (NFT). Standard interfaces, canister IDs for ledgers. | Portal defi/tokens/token-standards files; icskills: icrc-ledger, wallet-integration | guides/defi/token-ledgers, guides/defi/wallet-integration | P0 | -| 72 | `reference/cycles-costs.md` | Cycles Costs | reference | intermediate | Exact cycle costs for compute, storage, HTTPS outcalls, signing, canister creation. Cost tables, comparison with cloud pricing. Resource limits. | Portal building-apps/canister-management/resource-limits.mdx, defi cost tables; reference/subnet-types for pricing tiers | guides/canister-management/cycles-management, concepts/reverse-gas-model | P0 | -| 73 | `reference/subnet-types.md` | Subnet Types Reference | reference | intermediate | All subnet types: application, system, European, fiduciary, Bitcoin, II. Node counts, replication factors, cycle cost multipliers. | Portal building-apps/developing-canisters/deploy-specific-subnet.mdx; icp-cli guides/deploying-to-specific-subnets.md | guides/canister-management/subnet-selection, reference/cycles-costs | P1 | -| 74 | `reference/execution-errors.md` | Execution Errors | reference | intermediate | Common canister execution errors with explanations and fixes. Trap codes, out-of-cycles, instruction limit exceeded, memory limit, call context errors. | Portal building-apps/canister-management/trapping.mdx, resource-limits.mdx | guides/canister-management/lifecycle, guides/canister-management/optimization, reference/cycles-costs | P1 | -| 75 | `reference/ic-interface-spec.md` | IC Interface Specification | reference | advanced | Summary and links to the IC interface specification. System API, HTTP interface, canister lifecycle, certified data. Links to the full spec. | Portal references/ic-interface-spec.mdx | reference/management-canister, reference/candid-spec | P1 | -| 76 | `reference/http-gateway-spec.md` | HTTP Gateway Specification | reference | advanced | How boundary nodes serve canister HTTP responses. The HTTP gateway protocol, certification, service workers. | Portal references/ (HTTP gateway section); Learn Hub: boundary nodes | guides/frontends/certification, reference/ic-interface-spec | P2 | -| 77 | `reference/candid-spec.md` | Candid Specification | reference | intermediate | The Candid interface description language. Type system, encoding, subtyping rules. Links to the full specification. | Portal references/candid-spec; | guides/canister-calls/candid, reference/ic-interface-spec | P1 | -| 78 | `reference/internet-identity-spec.md` | Internet Identity Specification | reference | advanced | Internet Identity protocol details. Delegation chains, passkey management, canister signatures, alternative origins. | Portal references/ (II section); icskills: internet-identity | guides/authentication/internet-identity, reference/system-canisters | P2 | -| 79 | `reference/glossary.md` | Glossary | reference | beginner | Definitions of ICP-specific terms. Canister, cycle, principal, subnet, replica, boundary node, NNS, SNS, chain-key, etc. | Portal references/glossary; all concept pages | All concept and guide pages | P1 | - ---- - -## Page Count Summary - -| Section | Pages | P0 | P1 | P2 | -|---------|-------|----|----|-----| -| Landing | 1 | 1 | 0 | 0 | -| Getting Started | 4 | 4 | 0 | 0 | -| Guides -- Backends | 7 | 3 | 2 | 2 | -| Guides -- Canisters | 6 | 3 | 2 | 0 | (Note: lifecycle, settings, reproducible-builds are P0) -| Guides -- Frontends | 4 | 1 | 2 | 1 | -| Guides -- Authentication | 2 | 1 | 1 | 0 | -| Guides -- Canister Calls | 3 | 2 | 1 | 0 | -| Guides -- Testing | 2 | 2 | 0 | 0 | -| Guides -- Production | 3 | 1 | 1 | 1 | -| Guides -- Chain Fusion | 4 | 2 | 0 | 2 | -| Guides -- DeFi | 3 | 1 | 1 | 1 | -| Guides -- Governance | 3 | 0 | 3 | 0 | -| Guides -- Security | 5 | 2 | 3 | 0 | -| Guides -- Tools | 2 | 1 | 1 | 0 | -| Concepts | 13 | 8 | 4 | 0 | (Note: security is P0) -| Languages -- Motoko | 1 | 1 | 0 | 0 | -| Languages -- Rust | 3 | 1 | 1 | 1 | -| Reference | 13 | 3 | 7 | 3 | -| **Total** | **79** | **37** | **29** | **11** | - -Note: Motoko synced pages (~52) are not counted here. The `guides/tools/migrating-from-dfx.md` is auto-synced so it counts as P0 but requires no authoring effort. - ---- - -## icskills Source Material Summary - -17 skills used as source material for docs pages. See `.docs-plan/jssdk-skills-mapping.md` for the full mapping table. Skills are discoverable by agents via the skills registry endpoint advertised in `llms.txt`. - -## JS SDK Mapping Summary - -5 JS SDK projects mapped to docs pages. See `.docs-plan/jssdk-skills-mapping.md` for the full mapping table. diff --git a/AGENTS.md b/AGENTS.md index 19d8c90f..80a9aedb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,7 @@ # ICP Developer Docs: Agent & Contributor Instructions ICP developer documentation built with Astro + Starlight. -Content is `.md` by default. Pages that need interactive components (e.g., language-synced tabs) use `.mdx` — see `.docs-plan/decisions.md` for the policy. +Content is `.md` by default. Pages that need interactive components (e.g., language-synced tabs) use `.mdx`. Goal: get developers (human and AI) building on the IC as fast as possible. This file is the single source of truth for all agents (Claude Code, Codex, Cursor, etc.) and contributors. `CLAUDE.md` symlinks here. @@ -10,11 +10,8 @@ This file is the single source of truth for all agents (Claude Code, Codex, Curs 1. Read this file for rules and boundaries 2. Run `./scripts/setup.sh` — initializes submodules and npm deps -3. Check `.docs-plan/decisions.md` before making any structural changes -4. Pick a task from [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` -5. Look up the page in `.docs-plan/migration-plan.md` for source material and effort -6. Do the work following the rules below -7. Record any structural decisions in `.docs-plan/decisions.md` +3. Pick a task from [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` +4. Do the work following the rules below ## Branch naming @@ -118,25 +115,23 @@ git checkout main ## Always (do these without asking) -- Read `.docs-plan/decisions.md` before proposing structural changes - **Load skills before writing** — `technical-documentation` + the relevant icskill + `icp-brand-voice` + `icp-brand-design`. Run `git submodule update --init --depth 1` if skills appear as broken symlinks. - Use `icp` CLI commands in all examples — never `dfx` - Use `mo:core` for all Motoko standard library imports — never `mo:base`. See `.sources/motoko/doc/md/12-base-core-migration.md` for the full mapping. - Use `.md` by default; `.mdx` only for interactive components (e.g. ``). Tab order: Motoko → Rust → others. - Include complete frontmatter (title + description required — see schema below) -- Record structural decisions in `.docs-plan/decisions.md` immediately — new files, path changes, config changes, any choice a future agent needs to understand +- Document structural decisions in the PR description — new files, path changes, config changes, any choice a future contributor needs to understand - **Every non-stub content page must end with an `` comment** listing every `.sources/` repo used - **Every PR must include a `## Sync recommendation` section** in the description ## Ask first (confirm with the user before doing these) - Creating new top-level sections (getting-started, guides, concepts, languages, references) -- Adding new pages not in the migration plan +- Adding new pages without a corresponding GitHub Issue - Removing existing pages from the structure - Changing a page's sync recommendation from hand-written to synced (or vice versa) - Changing the frontmatter schema - Modifying the sidebar configuration in `astro.config.mjs` -- Changing decisions recorded in `.docs-plan/decisions.md` - Adding new external doc sources to the linking rules - Adding a new entry to `.sources/` (new submodule) @@ -150,7 +145,6 @@ git checkout main - Nest sidebar items more than 3 levels deep - Skip reading source material before writing a page - Write code snippets from memory — find and adapt from actual upstream code in `.sources/` -- Modify the rationale or context of existing decisions in `.docs-plan/decisions.md` — you may remove entries that are fully reflected in the current codebase but never alter reasoning behind active decisions - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions - Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Explain inline or link to `docs/concepts/` for protocol-level background; do not link to `learn.internetcomputer.org` (Learn Hub has been retired; its content is now in this site under `docs/concepts/`). - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls ` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both). @@ -360,13 +354,9 @@ grep -r "{#}" docs/references/ic-interface-spec/ | File | What it answers | |------|-----------------| -| `decisions.md` | "Has this been decided already?" — append-only decision log | -| `migration-plan.md` | "How do I execute this task?" — source material and effort per page | | `content-authoring.md` | "How do I write a page?" — full authoring workflow | | `review-guidelines.md` | "How do I review a PR?" — full review checklist | -Additional context files (less frequently needed): `synthesis.md`, `developer-journey.md`, `jssdk-skills-mapping.md`, `icp-cli-examples-inventory.md`. - ## Content authoring workflow Read `.docs-plan/content-authoring.md` before writing any page. It covers: reading stubs and source material, writing content, code snippet verification, sync recommendations, linking rules, and external docs. @@ -432,6 +422,3 @@ The site implements the [Agent-Friendly Documentation Spec](https://agentdocsspe **SECTIONS array:** The `SECTIONS` array in `plugins/astro-agent-docs.mjs` maps directory prefixes to section labels in `llms.txt`. Update it when adding or renaming sidebar sections in `astro.config.mjs`. -## Previous work - -Branch `restructuring-attempt-1` preserves the previous attempt with 124 pages, CI workflows, sync scripts, and `DOCS_RESTRUCTURING_PROPOSAL.md`. From 620074393e7f0ffe77bf771b2d66f3cc10ce9c56 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 27 May 2026 14:10:18 +0200 Subject: [PATCH 2/9] chore: fold .docs-plan into AGENTS.md, drop folder entirely - Moves content-authoring workflow and review guidelines into AGENTS.md as standalone sections, making it the single source of truth - Removes migration-phase stub workflow and per-snippet upstream verification; code examples are maintained in dfinity/examples going forward, referenced via region markers or inline - Deletes .docs-plan/ folder (README.md, content-authoring.md, review-guidelines.md) - Removes .docs-plan/** path-ignore from deploy-ic.yml - Cleans up stale .docs-plan references in README.md and CONTRIBUTING.md --- .docs-plan/README.md | 20 ----- .docs-plan/content-authoring.md | 90 ---------------------- .docs-plan/review-guidelines.md | 64 ---------------- .github/workflows/deploy-ic.yml | 1 - AGENTS.md | 130 +++++++++++++++++++++++++++++--- CONTRIBUTING.md | 4 +- README.md | 1 - 7 files changed, 122 insertions(+), 188 deletions(-) delete mode 100644 .docs-plan/README.md delete mode 100644 .docs-plan/content-authoring.md delete mode 100644 .docs-plan/review-guidelines.md diff --git a/.docs-plan/README.md b/.docs-plan/README.md deleted file mode 100644 index 6117c23d..00000000 --- a/.docs-plan/README.md +++ /dev/null @@ -1,20 +0,0 @@ -# ICP Developer Docs — Planning Artifacts - -This directory contains workflow references for the ICP developer documentation. - -## I'm an agent. What do I do? - -1. **Read `AGENTS.md`** (project root) — rules, boundaries, content guidelines -2. **Find your next task** in [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` -3. **Do the work** following `AGENTS.md` rules - -## Files - -| File | What it answers | -|------|-----------------| -| `content-authoring.md` | "How do I write a page?" — full content workflow, content rules, linking rules, external docs | -| `review-guidelines.md` | "How do I review a PR?" — full review checklist | - -## Source repos - -All source repos are pinned as git submodules under `.sources/` — see `AGENTS.md` → "Source material repos" for the full mapping and rules. diff --git a/.docs-plan/content-authoring.md b/.docs-plan/content-authoring.md deleted file mode 100644 index 788b70ac..00000000 --- a/.docs-plan/content-authoring.md +++ /dev/null @@ -1,90 +0,0 @@ -# Content authoring workflow - -> **Task coordination:** Follow the "Multi-agent workflow" section in AGENTS.md for claiming tasks, branch creation, and PR submission. The steps below cover the content writing process itself. - -When drafting a new docs page: - -1. Read the stub page — it contains content brief, source material, and cross-links -2. Read source material from `.sources/`. Resolve paths using the "Source material repos" table in AGENTS.md. - > **If source material is unavailable at the expected path:** write from the content brief + icskills + your training knowledge, and add `` so future contributors know to verify. -3. Read any related icskills skill file from `.sources/icskills/` for accurate canister IDs and code patterns. -4. Write the content: - - Follow the content brief in the stub - - Use icp-cli commands (never dfx) - - **Verify all CLI commands and flags** against `.sources/icp-cli/docs/reference/cli.md` — never guess command syntax - - **Verify all code snippets against upstream source** — never write code examples from memory. Adapt from the source material you read in step 2, or grep `.sources/` for the specific function/API you're using. Ensure return types are handled correctly (e.g., unwrap Motoko `?Text` with `switch`/`case`, wrap raw strings with `Principal::from_text` where needed). For recipe versions, check `.sources/icp-cli-recipes` tags. - - **Safe code adaptation** — when adapting code from `.sources/` into a shorter snippet, preserve all imports, error handling, and type conversions that affect correctness. If you must omit setup code, use `// ...` to indicate elided lines — never silently drop lines. Do not invent variable names or types that aren't in the source. If the source context (test harness, full app) is significantly different from a standalone snippet, note what you changed. - - **Never invent command output** — if a page shows expected CLI output or canister responses, copy from actual output in `.sources/` (READMEs, test fixtures, example logs). If no actual output exists, write `` instead of guessing. Do not fabricate canister IDs, cycle counts, error messages, or version strings. - - **Flag uncertainty** — if after checking `.sources/` you are not confident a code snippet, API behavior, or technical claim is correct, add `` as an HTML comment next to the uncertain content. This tells reviewers where to focus. It is always better to flag than to silently guess. - - **Verify all internal links** — every `[text](path.md)` must point to a file that exists. Run `ls ` before submitting. If the target page doesn't exist, either link to an existing page that covers the topic, or file a page proposal issue and note the missing link in your PR description. Never link to a path that doesn't exist. - - **Verify all external URLs** — use the linking rules table in AGENTS.md for known resources. For any URL not in the table (crate docs, npm packages, GitHub repos), verify it is correct. Do not guess or generalize from similar URLs (e.g., `docs.rs/ic-cdk` is NOT the same as `docs.rs/ic-stable-structures`). - - **Self-consistency check** — before submitting, re-read your frontmatter description and body opening paragraph. They must not contradict each other (e.g., different time estimates, different scope claims). - - Use `.md` by default. Use `.mdx` only when the page needs interactive components like ``. In `.mdx` files, use `{/* */}` for comments instead of ``. - - **Stub → `.mdx` rename:** All stubs are `.md` files. If your page needs tabs (e.g., Motoko/Rust examples in the same section), rename the stub from `.md` to `.mdx`, delete the old `.md` file, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert any `` comments to `{/* */}`. Internal links pointing to `.md` do not need updating — Astro resolves both extensions. - - Ensure complete frontmatter (see CONTRIBUTING.md) - - **Code examples — check for snippet pipeline first:** Before writing inline code, check whether the example exists in `.sources/examples` with `#region` markers: - ```bash - grep -r "#region" .sources/examples/// - ``` - - **Region markers found** → use `` (requires `.mdx`): - ```mdx - import CodeExample from '../../../src/components/CodeExample.astro'; - - - ```rust snippet="my_example/src/my_example_backend/src/lib.rs#my_region" - ``` - - ``` - Paths in `snippet=` are relative to `.sources/examples//`. A missing region is a build error — verify it exists before using it. - - **No markers found** → inline if <30 lines; link to `dfinity/examples` on GitHub if longer. Note in the PR description: "used inline code for X — no `#region` markers in `.sources/examples` yet." - - **Example exists but lacks markers for the function you need** → use inline/link as fallback, and comment on [#44](https://github.com/dfinity/developer-docs/issues/44) with the specific file and region name needed. This is the one case worth flagging on #44 — it's a concrete, actionable gap. - - Link to external docs per linking rules in `content-authoring.md` -5. **Sync recommendation:** After reading source material, decide whether this page should be: - - **Hand-written** — original content, no upstream equivalent - - **Synced** — upstream repo has authoritative content that should be auto-synced (like Motoko docs) - - **Upstream-informed** — hand-written but closely tracks an upstream source that should be monitored for changes - Record your recommendation as a comment at the bottom of the page. Use `` in `.md` files and `{/* */}` in `.mdx` files: - ```markdown - - - - ``` - In `.mdx` files, use JSX comment syntax instead: - ```mdx - {/* Upstream: hand-written */} - {/* Upstream: informed by dfinity/portal — ...; dfinity/icskills — ... */} - ``` - Consider syncing when the upstream content is comprehensive, well-maintained, and a close fit. Prefer hand-writing when the page synthesizes multiple sources or serves a different audience than the upstream. - **This must appear in two places:** (1) as a comment in the page file, and (2) as a "Sync recommendation" section in the PR body (see the PR template in "Submitting" in AGENTS.md). Both are required. -6. **Propose missing pages:** If source material reveals topics that aren't covered by any existing page in the plan (e.g., a canister migration guide in icp-cli with no corresponding docs page), create a GitHub Issue with the `page-proposal` label. Include: what the page would cover, where it would live in the structure, and which upstream source it would draw from. Reference the issue in your PR description. Do not create the page — just flag it for human discussion. -7. Submit: push branch, create PR (see "Submitting" in AGENTS.md) -8. Review by the relevant team (see `.github/CODEOWNERS` and CONTRIBUTING.md review ownership table) - -## Content rules - -- **Spelling:** "onchain" and "offchain" (no hyphens). Use "icp-cli" in prose; use `icp` only in code blocks for the literal command. -- **Always use `.md` extension in internal links**, even when linking to a `.mdx` file (e.g., `[Canister lifecycle](lifecycle.md)`). Use relative paths. Never absolute paths like `/getting-started/quickstart/` — they break on GitHub. -- Images go in `src/assets/images/` organized by section (see CONTRIBUTING.md). Carry over portal images case-by-case; keep the hand-drawn visual style. -- **No headings inside `` blocks** — they always appear in the TOC regardless of which tab is active. Use **bold text** instead of `###` for sub-labels inside tabs. -- **Motoko standard library:** Always use `core` (`mops.one/core`), never `base`. Link to the synced base→core migration guide for developers still on `base`. -- **Diataxis content types** — match content to its section: - - `concepts/` — Explanations only. Describe *what* and *why*. No CLI commands, no step-by-step procedures. - - `getting-started/` — Tutorials. Step-by-step with CLI commands. Linear, opinionated, complete. - - `guides/` — How-to guides. Task-oriented with CLI commands where relevant. - - `reference/` — Specifications and lookups. Precise, complete, no tutorials. -- **End-of-page navigation:** End every page with a `## Next steps` section. Always use "Next steps" — never "What's next" or other variants. - -## Linking rules (do not duplicate — link instead) - -| Resource | URL | Notes | -|----------|-----|-------| -| CLI commands | https://cli.internetcomputer.org/ | | -| Motoko core library | https://mops.one/core/docs | supersedes `base`; migration guide synced from Motoko repo | -| Rust CDK (`ic-cdk`) | https://docs.rs/ic-cdk/latest/ic_cdk/ | | -| Rust stable structures | https://docs.rs/ic-stable-structures/latest/ic_stable_structures/ | | -| Rust Candid | https://docs.rs/candid/latest/candid/ | | -| JS SDK | https://js.icp.build | | -| Protocol internals / Learn Hub | https://learn.internetcomputer.org | | -| Agent skill files | https://skills.internetcomputer.org | | - -> **Rust crate URLs:** Each crate has its own URL — do not substitute. For crates not in this table, use `https://docs.rs//latest//` (hyphens → underscores in the path). diff --git a/.docs-plan/review-guidelines.md b/.docs-plan/review-guidelines.md deleted file mode 100644 index 8c3f39bf..00000000 --- a/.docs-plan/review-guidelines.md +++ /dev/null @@ -1,64 +0,0 @@ -# PR review guidelines - -**Only review PRs when explicitly asked by a human.** Agents must never offer, suggest, or perform PR reviews on their own initiative. Reviews are a developer decision. The agent's focus is: (1) manage tasks, (2) create content PRs, (3) fix content based on existing reviews/comments. - -When asked to review a PR, load the `technical-documentation` skill and the relevant icskill for the page topic first. For parallel reviews using worktrees, see "Submodule initialization in worktrees" in AGENTS.md. - -## Initial review (first time reviewing a page) - -*Mechanical checks:* -1. **Internal links** — `ls` every `[text](path.md)` target. If the `.md` file doesn't exist, also check for `.mdx` — Astro resolves `.md` links to `.mdx` files. Flag as broken only if neither exists. -2. **External URLs** — verify against the linking rules table in `content-authoring.md`. Flag any guessed or wrong URLs (especially `docs.rs` crate links). -3. **CLI commands** — verify all `icp` commands and flags against `.sources/icp-cli/docs/reference/cli.md`. -4. **Frontmatter** — complete and consistent with the body (no contradictions in descriptions, time estimates, scope). -5. **Content rules compliance** — no `dfx` references, no `.mdx`/JSX, code examples <30 lines inline, relative links with `.md` extension, `core` not `base` for Motoko, Diataxis content type respected. -6. **Code snippet verification** — for every code example, verify function names, import paths, and return type handling against `.sources/`. Search efficiently: start with the most likely submodule (JS → `icp-js-sdk-docs/` or `examples/`, Rust/Motoko → `icp-cli-templates/` or `examples/`, CLI → `icp-cli/docs/`), then broaden only if the function isn't found. Flag snippets that leave the reader with an unusable intermediate value (e.g., unhandled optionals, raw strings where a `Principal` is needed). For recipe versions, check `.sources/icp-cli-recipes` tags. -7. **Verification flags** — search the page for `` and `` and `` comments. Does the page address every point in the brief? Was the source material actually consulted? Flag significant gaps or divergences. -12. **Accuracy** — cross-check technical claims (memory limits, latency numbers, API behavior) against `.sources/` material. Search across ALL relevant submodules, not just one. Flag anything that looks wrong or outdated. -13. **Developer empathy** — does the page anticipate what a developer would actually struggle with? Flag pages that explain obvious things at length while glossing over the hard parts. For concept pages: does it answer "why should I care?" For guides: does it handle the error cases a developer will actually hit? - -*Post using this format:* - -```markdown -## Review: - -### Must fix -- ****: - -### Suggestions -- ****: - -### Verified -- (e.g., "All CLI commands verified against .sources/icp-cli/docs/reference/cli.md") -``` - -Omit any section that has no items. Every initial review must include the "Verified" section to show what was actually checked. - -## Follow-up review (after feedback was addressed) - -Only run this when reviewing a PR that already had an initial review. Do NOT re-run the full checklist. - -1. Read the previous review comment(s) to understand what was requested. -2. Verify each requested change was made correctly. -3. Check that fixes didn't introduce new issues (e.g., dangling links from removed sections, broken frontmatter from removed fields). -4. Skip re-verifying items that were already signed off in the initial review, unless the fix directly touches them. - -*Post using this format:* - -```markdown -## Follow-up review: - -### Fixed -- - -### Still needs work -- -``` - -Omit "Still needs work" if everything looks good. diff --git a/.github/workflows/deploy-ic.yml b/.github/workflows/deploy-ic.yml index 2381a968..0ecb424c 100644 --- a/.github/workflows/deploy-ic.yml +++ b/.github/workflows/deploy-ic.yml @@ -6,7 +6,6 @@ on: paths-ignore: - 'AGENTS.md' - 'CLAUDE.md' - - '.docs-plan/**' - '.claude/**' - '.beads/**' workflow_dispatch: diff --git a/AGENTS.md b/AGENTS.md index 80a9aedb..db7749df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,7 +33,7 @@ Three outcomes: ## Doing the work -**Content pages:** Follow `.docs-plan/content-authoring.md` before writing. Every content page must: +**Content pages:** Follow the "Content authoring workflow" section below before writing. Every content page must: - Include an `` comment at the bottom listing every `.sources/` repo used - Load the relevant icskill before writing (see "Skills" section below) - Load `technical-documentation` skill before writing @@ -54,7 +54,7 @@ A `` top-level comment only covers feedback up to tha **Automated reviewer feedback (Copilot, bots):** Verify each claim against `.sources/` before acting. Copilot is often right on factual errors (wrong API names, incorrect behavior); often wrong on style preferences and project-convention conflicts. -**PR reviews:** Only when explicitly asked. Load `technical-documentation` skill and the relevant icskill first. See `.docs-plan/review-guidelines.md` for the full checklist. +**PR reviews:** Only when explicitly asked. Load `technical-documentation` skill and the relevant icskill first. See the "Review guidelines" section below. ## Submitting @@ -161,7 +161,6 @@ git checkout main - `docs/` — All documentation (`.md` only). `src/content/docs/` symlinks here for Astro. - `docs/languages/motoko/` — Auto-synced from `caffeinelabs/motoko` (do not edit directly). Bumps are fully automated: a weekly workflow (`.github/workflows/sync-motoko.yml`) detects new releases, runs `npm run sync:motoko`, and opens a PR with the synced content already committed. No manual sync step needed — just review and merge the PR. - `docs/guides/tools/migrating-from-dfx.md` — Synced from `dfinity/icp-cli` (do not edit directly) -- `.docs-plan/` — Planning artifacts, decisions, authoring workflow, review guidelines - `.sources/` — **Pinned submodules of upstream source repos** (see "Source material repos" below) - `.agents/skills/` — Agent skills (symlinks into `.sources/`). Run `git submodule update --init --depth 1` if broken. - `.claude/skills/` — Symlinks to `.agents/skills/` for Claude Code @@ -350,16 +349,127 @@ The following files are no longer synced from an external submodule — they are grep -r "{#}" docs/references/ic-interface-spec/ ``` -## Planning artifacts (`.docs-plan/`) +## Content authoring workflow + +When writing a new docs page: + +1. Read the GitHub Issue — it contains the content brief and scope. +2. Read relevant source material from `.sources/` for the topic (see "Source material repos" above). Use it to verify CLI commands, API signatures, and technical claims. +3. Load the relevant icskill from `.sources/icskills/` for accurate canister IDs and code patterns. +4. Write the content: + - Use icp-cli commands (never dfx) + - **Verify all CLI commands and flags** against `.sources/icp-cli/docs/reference/cli.md` — never guess command syntax + - **Never invent command output** — copy from actual output in `.sources/` (READMEs, test fixtures, example logs) or write `` instead of guessing. Do not fabricate canister IDs, cycle counts, error messages, or version strings. + - **Flag uncertainty** — if you're not confident a technical claim is correct, add `` next to the uncertain content. It is always better to flag than to silently guess. + - **Verify all internal links** — every `[text](path.md)` must point to a file that exists. Run `ls ` before submitting. If the target doesn't exist, link to the nearest existing page and note the gap in the PR description. + - **Verify all external URLs** — use the linking rules table below for known resources. For any URL not in the table (crate docs, npm packages, GitHub repos), verify it is correct. Do not guess or generalize from similar URLs (e.g., `docs.rs/ic-cdk` is NOT the same as `docs.rs/ic-stable-structures`). + - **Self-consistency check** — re-read your frontmatter description and body opening paragraph. They must not contradict each other. + - Use `.md` by default. Use `.mdx` only when the page needs interactive components like ``. In `.mdx` files, use `{/* */}` for comments instead of ``. + - **Stub → `.mdx` rename:** If your page needs tabs (e.g., Motoko/Rust examples in the same section), rename the stub from `.md` to `.mdx`, delete the old `.md` file, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert any `` comments to `{/* */}`. Internal links pointing to `.md` do not need updating — Astro resolves both extensions. + - Ensure complete frontmatter (see the "Frontmatter schema" section below) + - **Code examples:** Check `dfinity/examples` (`.sources/examples`) for existing examples with `#region` markers first. If markers exist, use the `` component (requires `.mdx`). If not, write inline if <30 lines, or link to the GitHub file if longer. Code examples are maintained in `dfinity/examples` — when that repo is updated, the docs are updated alongside it. +5. **Sync recommendation:** After reading source material, decide whether this page should be: + - **Hand-written** — original content, no upstream equivalent + - **Synced** — upstream repo has authoritative content that should be auto-synced (like Motoko docs) + - **Upstream-informed** — hand-written but closely tracks an upstream source that should be monitored for changes + Record your recommendation as a comment at the bottom of the page. Use `` in `.md` files and `{/* */}` in `.mdx` files: + ```markdown + + + + ``` + **This must appear in two places:** (1) as a comment in the page file, and (2) as a "Sync recommendation" section in the PR body (see the "Submitting" section above). Both are required. +6. Submit: push branch, create PR (see the "Submitting" section above) -| File | What it answers | -|------|-----------------| -| `content-authoring.md` | "How do I write a page?" — full authoring workflow | -| `review-guidelines.md` | "How do I review a PR?" — full review checklist | +## Content rules -## Content authoring workflow +- **Spelling:** "onchain" and "offchain" (no hyphens). Use "icp-cli" in prose; use `icp` only in code blocks for the literal command. +- **Always use `.md` extension in internal links**, even when linking to a `.mdx` file (e.g., `[Canister lifecycle](lifecycle.md)`). Use relative paths. Never absolute paths like `/getting-started/quickstart/` — they break on GitHub. +- Images go in `src/assets/images/` organized by section. Carry over portal images case-by-case; keep the hand-drawn visual style. +- **No headings inside `` blocks** — they always appear in the TOC regardless of which tab is active. Use **bold text** instead of `###` for sub-labels inside tabs. +- **Motoko standard library:** Always use `core` (`mops.one/core`), never `base`. Link to the synced base→core migration guide for developers still on `base`. +- **Diataxis content types** — match content to its section: + - `concepts/` — Explanations only. Describe *what* and *why*. No CLI commands, no step-by-step procedures. + - `getting-started/` — Tutorials. Step-by-step with CLI commands. Linear, opinionated, complete. + - `guides/` — How-to guides. Task-oriented with CLI commands where relevant. + - `references/` — Specifications and lookups. Precise, complete, no tutorials. +- **End-of-page navigation:** End every page with a `## Next steps` section. Always use "Next steps" — never "What's next" or other variants. + +## Linking rules (do not duplicate — link instead) + +| Resource | URL | Notes | +|----------|-----|-------| +| CLI commands | https://cli.internetcomputer.org/ | | +| Motoko core library | https://mops.one/core/docs | supersedes `base`; migration guide synced from Motoko repo | +| Rust CDK (`ic-cdk`) | https://docs.rs/ic-cdk/latest/ic_cdk/ | | +| Rust stable structures | https://docs.rs/ic-stable-structures/latest/ic_stable_structures/ | | +| Rust Candid | https://docs.rs/candid/latest/candid/ | | +| JS SDK | https://js.icp.build | | +| Agent skill files | https://skills.internetcomputer.org | | + +> **Rust crate URLs:** Each crate has its own URL — do not substitute. For crates not in this table, use `https://docs.rs//latest//` (hyphens → underscores in the path). + +## Review guidelines + +**Only review PRs when explicitly asked by a human.** Agents must never offer, suggest, or perform PR reviews on their own initiative. + +When asked to review a PR, load the `technical-documentation` skill and the relevant icskill for the page topic first. + +### Initial review (first time reviewing a page) + +*Mechanical checks:* +1. **Internal links** — `ls` every `[text](path.md)` target. If the `.md` file doesn't exist, also check for `.mdx` — Astro resolves `.md` links to `.mdx` files. Flag as broken only if neither exists. +2. **External URLs** — verify against the linking rules table above. Flag any guessed or wrong URLs (especially `docs.rs` crate links). +3. **CLI commands** — verify all `icp` commands and flags against `.sources/icp-cli/docs/reference/cli.md`. +4. **Frontmatter** — complete and consistent with the body (no contradictions in descriptions, time estimates, scope). +5. **Content rules compliance** — no `dfx` references, no `.mdx`/JSX, relative links with `.md` extension, `core` not `base` for Motoko, Diataxis content type respected. + +*Content quality checks:* +6. **Reader test** — read the page title, then the first two paragraphs. Does the opening deliver on the title's promise? Does it assume the reader came from a specific page or completed prior steps? (Pages must stand on their own — link to prerequisites, don't assume them.) Flag pages that open with background or history instead of what the reader came for. +7. **Funnel check** — does the page follow: orient (what is this, who is it for) → explain/instruct → what's next? Flag pages that bury the lede, put prerequisites after the main content, or end without a clear next step. +8. **Scanability** — can a developer skimming headings and bold text get the gist without reading every paragraph? Flag walls of text and important information buried mid-paragraph. +9. **Accuracy** — cross-check technical claims (memory limits, latency numbers, API behavior) against `.sources/` material. Flag anything that looks wrong or outdated. +10. **Developer empathy** — does the page anticipate what a developer would actually struggle with? For concept pages: does it answer "why should I care?" For guides: does it handle the error cases a developer will actually hit? + +*Post using this format:* + +```markdown +## Review: + +### Must fix +- ****: + +### Suggestions +- ****: + +### Verified +- (e.g., "All CLI commands verified against .sources/icp-cli/docs/reference/cli.md") +``` + +Omit any section that has no items. Every initial review must include the "Verified" section to show what was actually checked. + +### Follow-up review (after feedback was addressed) + +Only run this when reviewing a PR that already had an initial review. Do NOT re-run the full checklist. + +1. Read the previous review comment(s) to understand what was requested. +2. Verify each requested change was made correctly. +3. Check that fixes didn't introduce new issues (e.g., dangling links from removed sections, broken frontmatter from removed fields). +4. Skip re-verifying items already signed off in the initial review, unless the fix directly touches them. + +*Post using this format:* + +```markdown +## Follow-up review: + +### Fixed +- + +### Still needs work +- +``` -Read `.docs-plan/content-authoring.md` before writing any page. It covers: reading stubs and source material, writing content, code snippet verification, sync recommendations, linking rules, and external docs. +Omit "Still needs work" if everything looks good. ## Skills (required) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f377c3e..17c8fafa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ npm run build # Production build ## Content format -Documentation is Markdown (`.md`) by default. Pages that need interactive components — such as `` for multi-language sections — use `.mdx`. See `.docs-plan/decisions.md` for the full policy. +Documentation is Markdown (`.md`) by default. Pages that need interactive components — such as `` for multi-language sections — use `.mdx`. Files live in `docs/` (project root) and follow the site map defined in `astro.config.mjs`. Astro reads them via a symlink at `src/content/docs/`. @@ -168,4 +168,4 @@ Key commands: - `bd update --status draft --notes "PR #X"` — mark task as draft after PR creation - `bd list --limit 0` — see all tasks (default caps at 50) -See `.docs-plan/README.md` for analysis artifacts and `.docs-plan/migration-plan.md` for execution details. +See [AGENTS.md](AGENTS.md) for authoring workflow and content rules. diff --git a/README.md b/README.md index 8486e800..2cc7a8dd 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,6 @@ docs/ # All documentation (.md only) .sources/ # Pinned upstream source repos (read-only) ├── VERSIONS # Current pinned versions for versioned submodules └── ... # icp-cli, motoko, cdk-rs, icskills, examples, ... -.docs-plan/ # Planning artifacts and authoring workflow AGENTS.md # Contributor and agent instructions ``` From 2d4c050d974ce2887669180737a07811bd6a0836 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 27 May 2026 15:07:31 +0200 Subject: [PATCH 3/9] chore: slim AGENTS.md for maintenance mode, extract operational references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrites AGENTS.md around the 5 on-demand task types (write/update content, snippets, review PRs, address feedback, follow-up review) instead of the migration-era issue-driven workflow - Removes: GitHub issue workflow, Beads, stub references, sync recommendation as a PR requirement, three-outcomes branch startup procedure, per-snippet upstream verification requirement - Drops Learn Hub from linking rules (content now in docs/concepts/) - Upstream comment now optional — required only for pages that actively track an upstream source, not for original content - Moves submodule bump procedures → .agents/submodule-bumping.md - Moves directly-maintained spec file procedures → .agents/spec-maintenance.md - AGENTS.md: 535 lines → 327 lines - Cleans up CONTRIBUTING.md: removes Beads, draft checklist, stub references, portal image path, outdated validation note --- .agents/spec-maintenance.md | 34 ++ .agents/submodule-bumping.md | 82 +++++ AGENTS.md | 655 ++++++++++++----------------------- CONTRIBUTING.md | 37 +- 4 files changed, 345 insertions(+), 463 deletions(-) create mode 100644 .agents/spec-maintenance.md create mode 100644 .agents/submodule-bumping.md diff --git a/.agents/spec-maintenance.md b/.agents/spec-maintenance.md new file mode 100644 index 00000000..d73abd67 --- /dev/null +++ b/.agents/spec-maintenance.md @@ -0,0 +1,34 @@ +# Spec maintenance + +The following files are maintained directly in this repository. Update them manually when the IC team announces a new version of the relevant specification. + +## Directly maintained files + +| Local file | What it is | When to update | +|-----------|-----------|---------------| +| `public/references/ic.did` | Candid interface of the IC management canister | New management canister methods or changed types; update `docs/references/management-canister.md` and affected guides alongside | +| `public/references/_attachments/certificates.cddl` | Certificate CDDL schema | IC certification spec changes | +| `public/references/_attachments/requests.cddl` | Request CDDL schema | IC HTTPS interface spec changes | +| `public/references/_attachments/http-gateway.did` | HTTP Gateway Candid interface | HTTP Gateway spec changes | +| `docs/references/ic-interface-spec/` | IC Interface Spec (7 focused pages) | IC spec version bumps — apply changes to the matching file (see mapping below) | +| `docs/references/http-gateway-spec.md` | HTTP Gateway Protocol Spec | HTTP Gateway spec version bumps | + +## IC Interface Spec — section-to-file mapping + +| File | IC spec section | +|---|---| +| `index.md` | Introduction, Pervasive concepts, The system state tree | +| `https-interface.md` | HTTPS Interface | +| `canister-interface.md` | Canister module format, Canister interface (System API) | +| `management-canister.md` | The IC management canister, The IC Bitcoin API, The IC Provisional API | +| `certification.md` | Certification, The HTTP Gateway protocol | +| `abstract-behavior.md` | Abstract behavior | +| `changelog.md` | IC spec changelog | + +## Link adaptation for `http-gateway-spec.md` + +If an update introduces absolute `/references/ic-interface-spec#` links, convert them to relative paths using the anchor-to-file mapping at the bottom of `docs/references/http-gateway-spec.md`. To find which file owns a given anchor: + +```bash +grep -r "{#}" docs/references/ic-interface-spec/ +``` diff --git a/.agents/submodule-bumping.md b/.agents/submodule-bumping.md new file mode 100644 index 00000000..ccf8b254 --- /dev/null +++ b/.agents/submodule-bumping.md @@ -0,0 +1,82 @@ +# Submodule bumping + +Only the project maintainer bumps submodule refs. Reference this file when asked to bump a submodule. + +## Step 0 — Determine the new ref + +- **Release-pinned repos:** `git ls-remote --tags origin` — pin to the highest version tag's commit. +- **main/master repos:** fetch and checkout `origin/main` or `origin/master`. + +## General checklist (all submodules) + +1. Identify changes: `git -C .sources/ log --oneline ..` +2. Grep docs pages for content derived from that submodule; update affected pages +3. Check open PRs — post a bump-notice comment if the bump may affect pages under review (format below) +4. Update `.sources/VERSIONS` for release-pinned repos +5. Note the bump in the PR description + +**Bump-notice PR comment:** +```bash +gh pr comment --body "$(cat <<'EOF' + +`` was bumped to ``. The following content on this PR may be outdated: +- [specific item and why] + +Please review before merging. +EOF +)" +``` + +## Per-submodule additional checks + +| Submodule | Extra checks on bump | +|---|---| +| `motoko` | **Automated** — `.github/workflows/sync-motoko.yml` opens a PR with the bump, synced docs, and VERSIONS update already committed. Review the content diff and merge. Also grep all Motoko code blocks for changed/removed API signatures. | +| `motoko-core` | Grep all Motoko code blocks for changed/removed API signatures | +| `cdk-rs` | Check `ic-cdk`, `ic-cdk-timers`, `ic-cdk-macros` API changes — grep all Rust code blocks | +| `icp-cli` | Grep all CLI examples for changed/removed commands or flags. If the release introduces a new minor version (e.g. `v0.3.x`), update all CLI doc link slugs — see "Link adaptation for icp-cli" below. | +| `icskills` | Check for changed canister IDs or code patterns | +| `examples` | Verify linked files still exist at the same path | +| `icp-cli-recipes` | Check for renamed or removed recipes referenced in docs | +| `icp-cli-templates` | Check for renamed or restructured templates | +| `icp-js-sdk-docs` | Unzip and compare API signatures; check `versions.json` for new releases | +| `candid` | Check for spec changes affecting the Candid reference or type-mapping examples | +| `response-verification` | Check for API changes affecting certified variables patterns | +| `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria | +| `internetidentity` | Run `npm run sync:ii-spec` — syncs `ii-spec.mdx` → `docs/references/internet-identity-spec.md` and `vc-spec.md` → `docs/references/verifiable-credentials-spec.md`. If the script exits with a warning about unhandled links, add the new pattern to `linkMap` (ii-spec) or `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. Pin to the latest `release-YYYY-MM-DD` tag. The **Sync II spec** workflow (`.github/workflows/sync-ii-spec.yml`) runs automatically; trigger manually for early sync. | +| `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns | +| `papi` | Check for changed payment interface or cycle cost model | +| `ic-pub-key` | Check for changed CLI flags or commands | + +## Link adaptation for `icp-cli` + +All CLI docs links use a versioned slug (e.g. `https://cli.internetcomputer.org/0.2/...`). When bumped to a new minor version: + +1. Read the new slug: `cat .sources/icp-cli/docs-site/versions.json` — use the `"version"` marked `"latest": true`. +2. Verify all linked paths still exist in the new submodule before replacing: + ```bash + grep -roh "cli\.internetcomputer\.org/[0-9][.0-9]*/[^\"' )#]*" docs/ --include="*.md" --include="*.mdx" \ + | sed 's|cli\.internetcomputer\.org/[0-9][.0-9]*/||' | sort -u | grep -v "^$" \ + | while read p; do + [ -f ".sources/icp-cli/docs/${p}.md" ] || echo "MISSING: $p" + done + ``` + Resolve any MISSING paths manually before proceeding. +3. Replace the slug across all files: + ```bash + old=0.2; new=0.3 + find docs/ \( -name "*.md" -o -name "*.mdx" \) | xargs sed -i "s|cli.internetcomputer.org/${old}/|cli.internetcomputer.org/${new}/|g" + ``` +4. Run `npm run build` to confirm no broken links. + +## Link adaptation for `internet-identity-spec.md` and `verifiable-credentials-spec.md` + +Both are handled automatically by `npm run sync:ii-spec`. If a new unhandled link pattern appears, the script exits with a warning — add it to `linkMap` (ii-spec) or `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`, then re-run. Use `grep -r "{#}" docs/references/ic-interface-spec/` to find which file owns a given anchor. + +## Shallow clone resolution + +If a shallow clone can't resolve a pinned commit: +```bash +git -C .sources/ fetch --unshallow +git -C .sources/ checkout +``` diff --git a/AGENTS.md b/AGENTS.md index db7749df..9292d828 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,534 +1,327 @@ -# ICP Developer Docs: Agent & Contributor Instructions +# ICP Developer Docs -ICP developer documentation built with Astro + Starlight. -Content is `.md` by default. Pages that need interactive components (e.g., language-synced tabs) use `.mdx`. -Goal: get developers (human and AI) building on the IC as fast as possible. +ICP developer documentation built with Astro + Starlight. Goal: get developers building on the IC as fast as possible. `CLAUDE.md` symlinks here. -This file is the single source of truth for all agents (Claude Code, Codex, Cursor, etc.) and contributors. `CLAUDE.md` symlinks here. - -## Quick orientation +```bash +./scripts/setup.sh # initialize submodules and npm deps +npm run build # must pass before any push +``` -1. Read this file for rules and boundaries -2. Run `./scripts/setup.sh` — initializes submodules and npm deps -3. Pick a task from [GitHub Issues](https://github.com/dfinity/developer-docs/issues) — content pages use the `documentation` label; infra tasks use `enhancement` -4. Do the work following the rules below +Tasks come on-demand — no GitHub issue required unless proposing a structural change. ## Branch naming -- Content pages: `docs/` (e.g., `docs/concepts-vetkeys`, `docs/guides-security-encryption`) -- Infrastructure tasks: `infra/` (e.g., `infra/validation-scripts`, `infra/ci-workflows`) +- Content: `docs/` (e.g., `docs/guides-security-encryption`) +- Infrastructure: `infra/` (e.g., `infra/ci-workflows`) + +## Writing or updating content -## Starting a task +Load the relevant skills first (see "Skills" below). Then: + +- Read relevant source material from `.sources/` to verify CLI commands, API signatures, and technical claims (see "Source material" below for what to consult per topic). +- **CLI commands:** verify every flag against `.sources/icp-cli/docs/reference/cli.md` — never guess syntax. +- **Internal links:** run `ls ` before adding any link. Always use `.md` extension, even for `.mdx` targets. +- **External URLs:** use the "Linking rules" table below. Verify any URL not in the table — do not guess. +- **Flag uncertainty:** add `` next to any claim you can't verify from `.sources/`. Never silently guess. +- **Do not invent command output** — copy from `.sources/` READMEs or test fixtures, or write ``. +- **`.md` → `.mdx` conversion:** if a page needs multi-language tabs, rename `.md` → `.mdx`, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert `` comments to `{/* */}`. Astro resolves `.md` links to `.mdx` files — no link updates needed. +- For pages that closely track an upstream source, add at the bottom: ``. Skip for original content. +- Follow the "Content rules" section below. + +## Adding or updating code snippets + +Check `.sources/examples` for existing examples with `#region` markers first: ```bash -git fetch origin -git ls-remote origin docs/ # branch exists? -gh pr list --head docs/ # PR exists? +grep -r "#region" .sources/examples/// ``` -Three outcomes: -- **Branch + PR exist** → "changes requested" pickup. `git checkout docs/ && git pull origin docs/` -- **Branch exists, no PR** → stale. Delete remote branch, start fresh from `main` -- **Neither exists** → fresh work. `git checkout -b docs/ origin/main` +- **Markers found:** use the `` component (requires `.mdx`). Paths in `snippet=` are relative to `.sources/examples//`. A missing region is a build error — verify it exists. +- **No markers:** write inline if <30 lines; link to the GitHub file if longer. -## Doing the work +Code examples are maintained in `dfinity/examples` — when that repo is updated, docs are updated alongside it. -**Content pages:** Follow the "Content authoring workflow" section below before writing. Every content page must: -- Include an `` comment at the bottom listing every `.sources/` repo used -- Load the relevant icskill before writing (see "Skills" section below) -- Load `technical-documentation` skill before writing +## Reviewing a PR -**PR feedback:** Check all three feedback sources before fixing anything: -```bash -# 1. Review body (attached to the review decision) -gh api repos/{owner}/{repo}/pulls//reviews --jq '.[] | {user: .user.login, state: .state, body: .body}' +Only when explicitly asked. Load `technical-documentation` and the relevant icskill first. Never offer or initiate a review unprompted. -# 2. Top-level PR comments -gh pr view --json comments --jq '.comments[] | {author: .author.login, created: .createdAt, body: .body}' +### Initial review -# 3. Inline review comments (separate endpoint — do NOT skip this) -gh api repos/{owner}/{repo}/pulls//comments --jq '.[] | {user: .user.login, created_at: .created_at, path: .path, body: .body}' +*Mechanical checks:* +1. **Internal links** — `ls` every `[text](path.md)` target. Flag as broken only if neither `.md` nor `.mdx` exists. +2. **External URLs** — verify against the linking rules table below. +3. **CLI commands** — verify against `.sources/icp-cli/docs/reference/cli.md`. +4. **Frontmatter** — title and description present and consistent with body. +5. **Rules compliance** — no `dfx`, no `.mdx` without interactive components, relative `.md` links, `mo:core` not `mo:base`. + +*Quality checks:* +6. **Reader test** — does the opening deliver on the title's promise and stand alone without assumed prior context? +7. **Funnel** — orient → explain/instruct → next steps. Flag buried leads and pages that end without direction. +8. **Scanability** — can a developer get the gist from headings and bold text alone? +9. **Accuracy** — cross-check technical claims against `.sources/`. Flag anything wrong or outdated. +10. **Developer empathy** — does it address what a developer will actually struggle with? + +Post using this format: +```markdown +## Review: + +### Must fix +- ****: + +### Suggestions +- ****: + +### Verified +- ``` +Omit empty sections. Always include "Verified." -A `` top-level comment only covers feedback up to that timestamp. Check for inline comments posted after it. For each feedback item: cross-check against `.sources/` before applying. Skip items that conflict with AGENTS.md rules or source material — record why. +### Follow-up review -**Automated reviewer feedback (Copilot, bots):** Verify each claim against `.sources/` before acting. Copilot is often right on factual errors (wrong API names, incorrect behavior); often wrong on style preferences and project-convention conflicts. +Do NOT re-run the full checklist. Only check what was requested: +1. Verify each requested change was made correctly. +2. Check that fixes didn't introduce new issues (dangling links, broken frontmatter). -**PR reviews:** Only when explicitly asked. Load `technical-documentation` skill and the relevant icskill first. See the "Review guidelines" section below. +Post using this format: +```markdown +## Follow-up review: -## Submitting +### Fixed +- -**Fresh page:** -```bash -npm run build # must pass -git rebase origin/main -git push -u origin docs/ -gh pr create --title "docs: " --body "$(cat <<'EOF' -## Summary - +### Still needs work +- +``` +Omit "Still needs work" if everything looks good. -## Sync recommendation - `, or `informed by — `> -EOF -)" -git checkout main +## Addressing PR feedback + +Read all three feedback sources before making any changes: + +```bash +# Review body +gh api repos/{owner}/{repo}/pulls//reviews --jq '.[] | {user: .user.login, state: .state, body: .body}' +# Top-level comments +gh pr view --json comments --jq '.comments[] | {author: .author.login, created: .createdAt, body: .body}' +# Inline comments (do not skip) +gh api repos/{owner}/{repo}/pulls//comments --jq '.[] | {user: .user.login, created_at: .created_at, path: .path, body: .body}' ``` -**After addressing feedback:** +A `` comment covers feedback only up to its timestamp — check for inline comments posted after it. + +After fixing, run `npm run build`, then: ```bash -npm run build # must pass git push gh pr comment --body "$(cat <<'EOF' Feedback addressed: -- +- EOF )" -git checkout main ``` -**Any time commits are pushed to a PR branch** — check whether the PR description still accurately reflects the complete set of changes on the branch. If new commits introduce changes not covered by the existing summary, update the description immediately: -```bash -gh pr edit --body "$(cat <<'EOF' - -EOF -)" -``` -Do not leave a PR description that no longer matches the branch. The description is the reviewer's first read; a stale summary wastes review time and creates confusion. +**Automated reviewer feedback (Copilot, bots):** verify each claim against `.sources/` before acting. Often right on factual errors; often wrong on style preferences. -**PR body formatting rule (applies to `gh pr create`, `gh pr edit`, and `gh pr comment`)** — always pass the body through a single-quoted heredoc (`<<'EOF'`). Single-quoted heredocs suppress all shell expansion, so backticks and other special characters are passed through literally. Never manually escape backticks with `\`` inside the heredoc: the backslash will appear verbatim in the rendered output. +## Submitting -**Rebase approved PR with merge conflicts:** ```bash -git fetch origin && git checkout +npm run build git rebase origin/main -git push --force-with-lease -git checkout main +git push -u origin +gh pr create --title ": " --body "$(cat <<'EOF' +## Summary +<bullets> +EOF +)" ``` -## Merge conflict policy +**PR body rule:** always use a single-quoted heredoc (`<<'EOF'`). Backticks and special characters pass through literally — never escape them manually inside the heredoc. + +**Keep descriptions current:** if new commits change the scope of a PR, update the description immediately with `gh pr edit`. -- **Fresh PRs** — rebase on `main` before first push -- **Feedback fixes** — commit and push only. Do NOT rebase unless there are actual merge conflicts. -- **Approved PRs with conflicts** — rebase + `git push --force-with-lease`. Only case where force-push is justified. -- **Never force-push a PR under active review** +**Merge conflicts:** +- Fresh PRs: rebase before first push +- Feedback fixes: commit and push only — do not rebase +- Approved PRs with conflicts: `git rebase origin/main && git push --force-with-lease` +- Never force-push a PR under active review -## Always (do these without asking) +## Always -- **Load skills before writing** — `technical-documentation` + the relevant icskill + `icp-brand-voice` + `icp-brand-design`. Run `git submodule update --init --depth 1` if skills appear as broken symlinks. -- Use `icp` CLI commands in all examples — never `dfx` -- Use `mo:core` for all Motoko standard library imports — never `mo:base`. See `.sources/motoko/doc/md/12-base-core-migration.md` for the full mapping. -- Use `.md` by default; `.mdx` only for interactive components (e.g. `<Tabs syncKey="lang">`). Tab order: Motoko → Rust → others. -- Include complete frontmatter (title + description required — see schema below) -- Document structural decisions in the PR description — new files, path changes, config changes, any choice a future contributor needs to understand -- **Every non-stub content page must end with an `<!-- Upstream: -->` comment** listing every `.sources/` repo used -- **Every PR must include a `## Sync recommendation` section** in the description +- Load relevant skills before writing (see "Skills" below) +- Use `icp` CLI commands — never `dfx` +- Use `mo:core` for Motoko imports — never `mo:base`. See `.sources/motoko/doc/md/12-base-core-migration.md` for the full mapping. +- Default to `.md`; use `.mdx` only for interactive components. Tab order: Motoko → Rust → others. +- Complete frontmatter on every page (title + description required) +- Document structural decisions in the PR description -## Ask first (confirm with the user before doing these) +## Ask first -- Creating new top-level sections (getting-started, guides, concepts, languages, references) -- Adding new pages without a corresponding GitHub Issue -- Removing existing pages from the structure -- Changing a page's sync recommendation from hand-written to synced (or vice versa) +- Creating or removing top-level sections +- Removing existing pages - Changing the frontmatter schema -- Modifying the sidebar configuration in `astro.config.mjs` -- Adding new external doc sources to the linking rules -- Adding a new entry to `.sources/` (new submodule) +- Modifying sidebar configuration (`astro.config.mjs`) +- Adding a new `.sources/` submodule -## Never (do not do these under any circumstances) +## Never - Reference `dfx` — it is deprecated and banned -- Use `mo:base` imports in Motoko code examples — use `mo:core` instead. Critical replacements: `Buffer` → `List`, `HashMap`/`TrieMap`/`Trie`/`RBTree` → `Map`, `Deque` → `Queue`, `OrderedMap` → `pure/Map`, `OrderedSet` → `pure/Set` -- Create `.mdx` files without a clear need for interactive components — default to `.md` -- Duplicate content that lives in external docs (icp-cli, JS SDK, icskills) +- Use `mo:base` — use `mo:core` instead. Critical replacements: `Buffer` → `List`, `HashMap`/`TrieMap`/`Trie`/`RBTree` → `Map`, `Deque` → `Queue`, `OrderedMap` → `pure/Map`, `OrderedSet` → `pure/Set` +- Create `.mdx` without a clear need for interactive components +- Duplicate content that lives in external docs (icp-cli site, JS SDK docs, icskills) - Edit synced files directly (`docs/languages/motoko/`, `docs/guides/tools/migrating-from-dfx.md`) - Nest sidebar items more than 3 levels deep -- Skip reading source material before writing a page -- Write code snippets from memory — find and adapt from actual upstream code in `.sources/` - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions -- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Explain inline or link to `docs/concepts/` for protocol-level background; do not link to `learn.internetcomputer.org` (Learn Hub has been retired; its content is now in this site under `docs/concepts/`). -- Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls <target>` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both). -- Link to a page without a section anchor when the surrounding context refers to a specific topic covered by a subsection — always check the target file's headings and include `#anchor` when a more precise destination exists. Verify anchors by grepping headings: `grep "^## \|^### " <target>`. Anchor slugs: lowercase, spaces → `-`, special chars stripped. -- Link to `https://cli.internetcomputer.org/` (bare root) — all CLI doc pages are under a versioned path. Use `https://cli.internetcomputer.org/0.2/<path>` (current slug; verify with `cat .sources/icp-cli/docs-site/versions.json`) and confirm the path exists in `.sources/icp-cli/docs/<path>.md`. For command-specific links add a section anchor from `.sources/icp-cli/docs/reference/cli.md` (e.g. `#icp-canister-logs`, `#icp-canister-settings-update`, `#icp-cycles`). When bumping icp-cli to a new minor version, follow the "Link adaptation for `icp-cli`" checklist in "Bumping submodules". -- Link externally when an internal page exists — check `docs/` before using an external URL -- Offer, suggest, or perform PR reviews unless a human explicitly asks -- Write em-dashes (`—`) or use `--` as an em-dash substitute in prose. These are banned in all content: body text, bullet descriptions, link label text (including "Next steps", "Further reading", and "See also" sections), and inline comments. Use a colon, semicolon, period, comma, or parentheses instead. (`--` is only acceptable inside fenced code blocks as a code comment or CLI flag.) -- Rename Candid field names, management canister API identifiers, or example/repository names to satisfy jargon rules — these are protocol-level identifiers that must match the actual interface (e.g. `dapps`, `RegisterDappCanisters`, `encrypted-notes-dapp-vetkd`) -- Remove domain-specific technical terms that are standard vocabulary in their context: "DeFi" and "smart contract" in DeFi/token guides, "DAO" and "decentralized autonomous organization" in governance guides, "smart contracts on other chains" in chain fusion guides. These terms must stay because the target audience uses them and alternatives would be less precise. +- Link to `internetcomputer.org/docs/` (retired) or `learn.internetcomputer.org` (content is now in this repo under `docs/concepts/`) +- Link to internal pages that don't exist — run `ls <target>` before linking. Links to `.mdx` files use `.md` extension. +- Link without a section anchor when the context refers to a specific subsection — verify anchors with `grep "^## \|^### " <target>`. Slugs: lowercase, spaces → `-`, special chars stripped. +- Link to `https://cli.internetcomputer.org/` bare root — use the versioned path. Current slug: `0.2`; verify with `cat .sources/icp-cli/docs-site/versions.json`. +- Link externally when an internal page exists — check `docs/` first +- Write em-dashes (`—`) or use `--` as prose punctuation — use colon, semicolon, or parentheses instead. (`--` is fine inside code blocks as a CLI flag or comment.) +- Rename Candid field names, management canister API identifiers, or example repo names — these are protocol-level identifiers +- Remove domain-specific terms that are standard vocabulary in context: "DeFi"/"smart contract" in DeFi guides, "DAO"/"decentralized autonomous organization" in governance guides +- Offer, suggest, or perform PR reviews unless explicitly asked ## Key directories -- `docs/` — All documentation (`.md` only). `src/content/docs/` symlinks here for Astro. -- `docs/languages/motoko/` — Auto-synced from `caffeinelabs/motoko` (do not edit directly). Bumps are fully automated: a weekly workflow (`.github/workflows/sync-motoko.yml`) detects new releases, runs `npm run sync:motoko`, and opens a PR with the synced content already committed. No manual sync step needed — just review and merge the PR. +- `docs/` — All documentation (`.md` by default). `src/content/docs/` symlinks here. +- `docs/languages/motoko/` — Auto-synced from `caffeinelabs/motoko` (do not edit directly) - `docs/guides/tools/migrating-from-dfx.md` — Synced from `dfinity/icp-cli` (do not edit directly) -- `.sources/` — **Pinned submodules of upstream source repos** (see "Source material repos" below) -- `.agents/skills/` — Agent skills (symlinks into `.sources/`). Run `git submodule update --init --depth 1` if broken. -- `.claude/skills/` — Symlinks to `.agents/skills/` for Claude Code -- `plugins/` — Astro build plugins (rehype/remark transforms and the agent-docs integration) -- `icp.yaml` — icp-cli project config (asset canister recipe) -- `.icp/data/` — Canister ID mappings (committed to git) +- `.sources/` — Pinned source submodules (read-only) +- `.agents/skills/` — Agent skill files. Run `git submodule update --init --depth 1` if broken. +- `.agents/submodule-bumping.md` — Procedures for bumping source submodules (maintainer use) +- `.agents/spec-maintenance.md` — Procedures for maintaining directly-owned spec files (maintainer use) ## Project structure ``` -docs/ # All documentation (.md only) — src/content/docs/ symlinks here -├── index.mdx # Landing page +docs/ ├── getting-started/ # Tutorials -├── guides/ # How-to guides -│ ├── backends/ # Backend development patterns -│ ├── canister-calls/ # Candid interfaces, bindings, onchain and offchain calls -│ ├── frontends/ # Frontend development -│ ├── authentication/ # Auth integration -│ ├── testing/ # Testing strategies -│ ├── canister-management/ # Lifecycle, settings, cycles, optimization, deployment -│ ├── security/ # Security best practices -│ ├── chain-fusion/ # Cross-chain integration -│ ├── defi/ # Token and DeFi guides -│ ├── governance/ # SNS and DAO guides -│ └── tools/ # Developer tools +├── guides/ +│ ├── backends/ +│ ├── canister-calls/ +│ ├── frontends/ +│ ├── authentication/ +│ ├── testing/ +│ ├── canister-management/ +│ ├── security/ +│ ├── chain-fusion/ +│ ├── defi/ +│ ├── governance/ +│ └── tools/ ├── concepts/ # Explanations -├── languages/ # Language-specific (Motoko synced, Rust hand-written) +├── languages/ # Motoko (synced), Rust (hand-written) └── references/ # Specifications and reference ``` -## Source material repos (`.sources/`) - -All upstream source repos are pinned as **git submodules** under `.sources/`. This ensures every agent reads the exact same content, regardless of when they run. - -**Two pinning strategies:** -- **Track latest release** — repos where the release represents the live/deployed state. Pin to the latest release tag. Spec changes are only accurate once released. -- **Track main/master** — content repos where the default branch *is* the canonical source. - -For current release hashes, see `.sources/VERSIONS`. - -| Submodule | Repo | Pinned to | What it provides | -|-----------|------|-----------|-----------------| -| `.sources/icp-cli` | `dfinity/icp-cli` | latest release | CLI reference, command syntax verification | -| `.sources/icp-cli-recipes` | `dfinity/icp-cli-recipes` | `main` | Recipe examples for CLI guides | -| `.sources/icp-cli-templates` | `dfinity/icp-cli-templates` | `main` | Project templates for getting-started | -| `.sources/icskills` | `dfinity/icskills` | `main` | Skill files with canister IDs and code patterns | -| `.sources/examples` | `dfinity/examples` | `master` | Code examples (link to for >30 line snippets) | -| `.sources/icp-js-sdk-docs` | `dfinity/icp-js-sdk-docs` | `main` | JS SDK docs — content in zip archives: `unzip -p .sources/icp-js-sdk-docs/public/<lib>/latest.zip <file>`. Libraries: `@icp-sdk/core` (`core/`), `@icp-sdk/auth` (`auth/`), `@icp-sdk/canisters` (`canisters/`), `@icp-sdk/signer` (`signer/`), `@icp-sdk/bindgen` (`bindgen/`), `@dfinity/pic` (`pic-js/`) | -| `.sources/motoko` | `caffeinelabs/motoko` | latest release | Motoko compiler — language spec, system function names, syntax verification | -| `.sources/motoko-core` | `caffeinelabs/motoko-core` | latest release | Motoko core library (`mo:core`) — API signatures, module docs | -| `.sources/cdk-rs` | `dfinity/cdk-rs` | latest release | Rust CDK (`ic-cdk`, `ic-cdk-timers`, `ic-cdk-macros`) — API signatures | -| `.sources/candid` | `dfinity/candid` | latest release | Candid spec, type system, `didc` tool source | -| `.sources/response-verification` | `dfinity/response-verification` | latest release | Response verification, certified variables, certificate trees | -| `.sources/chain-fusion-signer` | `dfinity/chain-fusion-signer` | latest release | Chain Fusion Signer — API, key derivation, address generation, ICRC-2 payment model | -| `.sources/papi` | `dfinity/papi` | latest release | PAPI (payment API) — cycle payment interface used by the Chain Fusion Signer | -| `.sources/ic-pub-key` | `dfinity/ic-pub-key` | latest release | `@dfinity/ic-pub-key` CLI tool for deriving public keys via the Chain Fusion Signer | -| `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) | -| `.agents/skills/icp-brand-voice` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand voice: positioning, vocabulary, banned terms, voice attributes | -| `.agents/skills/icp-brand-design` | n/a — lives directly in this repo | n/a | ICP / DFINITY brand design: color tokens, typography, layout, components, accessibility | -| `.sources/internetidentity` | `dfinity/internet-identity` | latest release | Internet Identity spec (`docs/ii-spec.mdx`), VC spec (`docs/vc-spec.md`), Candid interface (`src/internet_identity/internet_identity.did`) | - -### Submodule initialization - -```bash -git submodule update --init --depth 1 # sufficient for all docs work -``` +## Source material -**Do NOT use `--recursive`** — pulls many GB of unnecessary nested submodule data. +All source repos are pinned as git submodules under `.sources/`. Always read from `.sources/` — never from local clones, `gh api`, or training data. Do not modify `.sources/` — it is read-only. -If a shallow clone can't resolve a pinned commit: ```bash -git -C .sources/<repo> fetch --unshallow -git -C .sources/<repo> checkout <commit> +git submodule update --init --depth 1 # do NOT use --recursive ``` -### Rules for agents +Consult the relevant submodule when writing or reviewing: -- **Always read source material from `.sources/`** — never from local clones, `gh api`, or training data -- **Consult relevant repos when writing or reviewing:** - - **Motoko code** → `motoko-core` (API signatures) + `motoko` (compiler: system function names, keywords) - - **Rust code** → `cdk-rs` (`ic-cdk`, `ic-cdk-timers`, management canister types) - - **Candid** → `candid` (spec, type system, `didc` behavior) - - **Certified data / query verification** → `response-verification` - - **CLI commands** → `icp-cli` (never guess flags or syntax) - - **JavaScript / TypeScript** → `icp-js-sdk-docs` (unzip archives before reading; never guess JS SDK API) - - **Code examples** → `examples` (link to for snippets >30 lines) -- **Do not modify `.sources/`** — read-only. Edits go to the upstream repos. +| Topic | Submodule | +|-------|-----------| +| CLI commands and flags | `.sources/icp-cli/` — verify against `docs/reference/cli.md` | +| Motoko APIs (`mo:core`) | `.sources/motoko-core/` | +| Motoko compiler / syntax | `.sources/motoko/` | +| Rust CDK (`ic-cdk`, `ic-cdk-timers`) | `.sources/cdk-rs/` | +| JavaScript / TypeScript SDK | `.sources/icp-js-sdk-docs/` — unzip: `unzip -p .sources/icp-js-sdk-docs/public/<lib>/latest.zip <file>` | +| Code examples | `.sources/examples/` | +| CLI recipes | `.sources/icp-cli-recipes/` | +| Project templates | `.sources/icp-cli-templates/` | +| Canister IDs and skill files | `.sources/icskills/` | +| Candid spec | `.sources/candid/` | +| Certified variables | `.sources/response-verification/` | +| Chain Fusion Signer | `.sources/chain-fusion-signer/` | +| PAPI (payment API) | `.sources/papi/` | +| `@dfinity/ic-pub-key` CLI | `.sources/ic-pub-key/` | +| Internet Identity spec | `.sources/internetidentity/` | +| Technical documentation skill | `.sources/dotskills/` (AGPL-3.0 — kept as submodule to avoid license mixing) | -### Bumping submodules +For current pinned versions, see `.sources/VERSIONS`. -Only the project maintainer bumps submodule refs. When bumped: +For submodule bump procedures, see [`.agents/submodule-bumping.md`](.agents/submodule-bumping.md). -**Step 0 — Determine the new ref:** -- **Latest release repos:** Use `git ls-remote --tags origin` to find the highest version tag. Pin to that tag's commit. -- **main/master repos:** Fetch and checkout `origin/main` or `origin/master`. +## Skills -**General checklist (all submodules):** -1. Identify changes: `git -C .sources/<repo> log --oneline <old-ref>..<new-ref>` -2. Grep docs pages for content derived from that submodule; update affected pages -3. Check open PRs — post a comment if the bump may affect pages under review (format below) -4. **For release-pinned repos:** update `.sources/VERSIONS` -5. Note the bump in the PR description +Load skills matching the task before starting any content work. Run `git submodule update --init --depth 1` if skills appear as broken symlinks. -**PR comment format:** -```bash -gh pr comment <PR#> --body "$(cat <<'EOF' -<!-- submodule-bump-notice --> -`<repo>` was bumped to `<new-ref>`. The following content on this PR may be outdated: -- [specific item and why] +Always load for content writing: +- **`technical-documentation`** — quality and structure +- **`icp-brand-voice`** — vocabulary, banned terms, voice -Please review before merging. -EOF -)" -``` +Load the icskill matching the page topic: -**Per-submodule additional checks:** - -| Submodule | Extra checks on bump | -|---|---| -| `motoko` | **Automated** — `.github/workflows/sync-motoko.yml` opens a PR with the submodule bump, synced docs, and VERSIONS update already committed. Review the content diff and merge. Also check for changed/removed API signatures — grep all Motoko code blocks in docs. | -| `motoko-core` | Check for changed/removed API signatures — grep all Motoko code blocks in docs | -| `cdk-rs` | Check `ic-cdk`, `ic-cdk-timers`, `ic-cdk-macros` API changes — grep all Rust code blocks | -| `icp-cli` | Check for changed/removed commands or flags — grep all CLI examples. If the release tag introduces a new minor version (e.g. `v0.3.x`), update all CLI doc link slugs — see "Link adaptation for `icp-cli`" below | -| `icskills` | Check for changed canister IDs or code patterns | -| `examples` | Verify linked files still exist at the same path | -| `icp-cli-recipes` | Check for renamed or removed recipes referenced in docs | -| `icp-cli-templates` | Check for renamed or restructured templates | -| `icp-js-sdk-docs` | Unzip and compare API signatures; check `versions.json` for new releases | -| `candid` | Check for spec changes affecting the Candid reference or type-mapping examples | -| `response-verification` | Check for API changes affecting certified variables patterns | -| `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria | -| `internetidentity` | Run `npm run sync:ii-spec` — the script syncs both `ii-spec.mdx` → `docs/references/internet-identity-spec.md` and `vc-spec.md` → `docs/references/verifiable-credentials-spec.md`, handling all link rewrites, Candid inlining, and frontmatter in one pass. If the script exits with a warning about unhandled links, add the new pattern to `linkMap` (ii-spec) or `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. Pin to the latest `release-YYYY-MM-DD` tag — spec changes are only live once the canister is deployed at that release. The **Sync II spec** workflow (`.github/workflows/sync-ii-spec.yml`) checks the latest release tag and only opens a PR when `docs/ii-spec.mdx`, `docs/vc-spec.md`, or `internet_identity.did` actually changed. Trigger manually for early sync. | -| `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns | -| `papi` | Check for changed payment interface or cycle cost model | -| `ic-pub-key` | Check for changed CLI flags or commands | - -**Link adaptation for `icp-cli`:** All links to the CLI docs site use a versioned path slug (e.g. `https://cli.internetcomputer.org/0.2/...`). The slug must match the current latest release. When the submodule is bumped to a new minor version: - -1. Read the new slug from the submodule: `cat .sources/icp-cli/docs-site/versions.json` — use the `"version"` value marked `"latest": true`. -2. Extract every unique path currently linked and verify each one still exists in the new submodule **before** doing any replacements: - ```bash - grep -roh "cli\.internetcomputer\.org/[0-9][.0-9]*/[^\"' )#]*" docs/ --include="*.md" --include="*.mdx" \ - | sed 's|cli\.internetcomputer\.org/[0-9][.0-9]*/||' | sort -u | grep -v "^$" \ - | while read p; do - [ -f ".sources/icp-cli/docs/${p}.md" ] || echo "MISSING: $p" - done - ``` - If any path is reported as MISSING, find its replacement in `.sources/icp-cli/docs/` and update that link manually. Do not proceed to step 3 until all paths are accounted for. -3. Replace the old slug with the new one across all files: - ```bash - old=0.2 # replace with the old slug - new=0.3 # replace with the new slug - find docs/ \( -name "*.md" -o -name "*.mdx" \) | xargs sed -i "s|cli.internetcomputer.org/${old}/|cli.internetcomputer.org/${new}/|g" - ``` -4. Run `npm run build` to confirm no broken links. - -**Link adaptation for `internet-identity-spec.md` and `verifiable-credentials-spec.md`:** Both are handled automatically by `npm run sync:ii-spec`. The script rewrites stale `internetcomputer.org` links to internal relative paths using `linkMap` (ii-spec) and `vcLinkMap` (vc-spec) in `scripts/sync-ii-spec.mjs`. If a new unhandled link pattern appears, the script exits with a warning — add it to the appropriate map with the correct relative path (use `grep -r "{#<anchor>}" docs/references/ic-interface-spec/` to find which file owns a given anchor), then re-run. Stale links in `vc-spec.md` are tracked upstream in `dfinity/internet-identity#3889`; once fixed, the rewrites become harmless no-ops (old URL simply no longer appears in the source). - -### Directly maintained spec files - -The following files are no longer synced from an external submodule — they are maintained directly in this repository. Update them manually when the IC team announces a new version of the relevant specification. - -| Local file | What it is | When to update | -|-----------|-----------|---------------| -| `public/references/ic.did` | Candid interface of the IC management canister | New management canister methods or changed types; update `docs/references/management-canister.md` and affected guides alongside | -| `public/references/_attachments/certificates.cddl` | Certificate CDDL schema (linked from `docs/references/ic-interface-spec/certification.md`) | IC certification spec changes | -| `public/references/_attachments/requests.cddl` | Request CDDL schema (linked from `docs/references/ic-interface-spec/https-interface.md`) | IC HTTPS interface spec changes | -| `public/references/_attachments/http-gateway.did` | HTTP Gateway Candid interface (linked from `docs/references/http-gateway-spec.md`) | HTTP Gateway spec changes | -| `docs/references/ic-interface-spec/` | IC Interface Spec split into 7 focused pages | IC spec version bumps — apply changes to the matching file (see section mapping below) | -| `docs/references/http-gateway-spec.md` | HTTP Gateway Protocol Spec | HTTP Gateway spec version bumps | - -**IC Interface Spec — section-to-file mapping:** - -| File | IC spec section | -|---|---| -| `index.md` | Introduction, Pervasive concepts, The system state tree | -| `https-interface.md` | HTTPS Interface | -| `canister-interface.md` | Canister module format, Canister interface (System API) | -| `management-canister.md` | The IC management canister, The IC Bitcoin API, The IC Provisional API | -| `certification.md` | Certification, The HTTP Gateway protocol | -| `abstract-behavior.md` | Abstract behavior | -| `changelog.md` | IC spec changelog | - -**Link adaptation for `http-gateway-spec.md`:** If an update introduces absolute `/references/ic-interface-spec#<anchor>` links, convert them to relative paths using the anchor-to-file mapping at the bottom of `docs/references/http-gateway-spec.md`. If a new anchor is not in that comment, find its file with: -```bash -grep -r "{#<anchor>}" docs/references/ic-interface-spec/ -``` - -## Content authoring workflow - -When writing a new docs page: - -1. Read the GitHub Issue — it contains the content brief and scope. -2. Read relevant source material from `.sources/` for the topic (see "Source material repos" above). Use it to verify CLI commands, API signatures, and technical claims. -3. Load the relevant icskill from `.sources/icskills/` for accurate canister IDs and code patterns. -4. Write the content: - - Use icp-cli commands (never dfx) - - **Verify all CLI commands and flags** against `.sources/icp-cli/docs/reference/cli.md` — never guess command syntax - - **Never invent command output** — copy from actual output in `.sources/` (READMEs, test fixtures, example logs) or write `<!-- TODO: verify output -->` instead of guessing. Do not fabricate canister IDs, cycle counts, error messages, or version strings. - - **Flag uncertainty** — if you're not confident a technical claim is correct, add `<!-- Needs human verification: [reason] -->` next to the uncertain content. It is always better to flag than to silently guess. - - **Verify all internal links** — every `[text](path.md)` must point to a file that exists. Run `ls <target-path>` before submitting. If the target doesn't exist, link to the nearest existing page and note the gap in the PR description. - - **Verify all external URLs** — use the linking rules table below for known resources. For any URL not in the table (crate docs, npm packages, GitHub repos), verify it is correct. Do not guess or generalize from similar URLs (e.g., `docs.rs/ic-cdk` is NOT the same as `docs.rs/ic-stable-structures`). - - **Self-consistency check** — re-read your frontmatter description and body opening paragraph. They must not contradict each other. - - Use `.md` by default. Use `.mdx` only when the page needs interactive components like `<Tabs syncKey="lang">`. In `.mdx` files, use `{/* */}` for comments instead of `<!-- -->`. - - **Stub → `.mdx` rename:** If your page needs tabs (e.g., Motoko/Rust examples in the same section), rename the stub from `.md` to `.mdx`, delete the old `.md` file, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert any `<!-- -->` comments to `{/* */}`. Internal links pointing to `<page>.md` do not need updating — Astro resolves both extensions. - - Ensure complete frontmatter (see the "Frontmatter schema" section below) - - **Code examples:** Check `dfinity/examples` (`.sources/examples`) for existing examples with `#region` markers first. If markers exist, use the `<CodeExample>` component (requires `.mdx`). If not, write inline if <30 lines, or link to the GitHub file if longer. Code examples are maintained in `dfinity/examples` — when that repo is updated, the docs are updated alongside it. -5. **Sync recommendation:** After reading source material, decide whether this page should be: - - **Hand-written** — original content, no upstream equivalent - - **Synced** — upstream repo has authoritative content that should be auto-synced (like Motoko docs) - - **Upstream-informed** — hand-written but closely tracks an upstream source that should be monitored for changes - Record your recommendation as a comment at the bottom of the page. Use `<!-- -->` in `.md` files and `{/* */}` in `.mdx` files: - ```markdown - <!-- Upstream: hand-written --> - <!-- Upstream: sync from dfinity/icp-cli docs/guides/canister-migration.md --> - <!-- Upstream: informed by dfinity/portal docs/building-apps/canister-management/settings.mdx --> - ``` - **This must appear in two places:** (1) as a comment in the page file, and (2) as a "Sync recommendation" section in the PR body (see the "Submitting" section above). Both are required. -6. Submit: push branch, create PR (see the "Submitting" section above) - -## Content rules - -- **Spelling:** "onchain" and "offchain" (no hyphens). Use "icp-cli" in prose; use `icp` only in code blocks for the literal command. -- **Always use `.md` extension in internal links**, even when linking to a `.mdx` file (e.g., `[Canister lifecycle](lifecycle.md)`). Use relative paths. Never absolute paths like `/getting-started/quickstart/` — they break on GitHub. -- Images go in `src/assets/images/` organized by section. Carry over portal images case-by-case; keep the hand-drawn visual style. -- **No headings inside `<TabItem>` blocks** — they always appear in the TOC regardless of which tab is active. Use **bold text** instead of `###` for sub-labels inside tabs. -- **Motoko standard library:** Always use `core` (`mops.one/core`), never `base`. Link to the synced base→core migration guide for developers still on `base`. -- **Diataxis content types** — match content to its section: - - `concepts/` — Explanations only. Describe *what* and *why*. No CLI commands, no step-by-step procedures. - - `getting-started/` — Tutorials. Step-by-step with CLI commands. Linear, opinionated, complete. - - `guides/` — How-to guides. Task-oriented with CLI commands where relevant. - - `references/` — Specifications and lookups. Precise, complete, no tutorials. -- **End-of-page navigation:** End every page with a `## Next steps` section. Always use "Next steps" — never "What's next" or other variants. - -## Linking rules (do not duplicate — link instead) - -| Resource | URL | Notes | -|----------|-----|-------| -| CLI commands | https://cli.internetcomputer.org/ | | -| Motoko core library | https://mops.one/core/docs | supersedes `base`; migration guide synced from Motoko repo | -| Rust CDK (`ic-cdk`) | https://docs.rs/ic-cdk/latest/ic_cdk/ | | -| Rust stable structures | https://docs.rs/ic-stable-structures/latest/ic_stable_structures/ | | -| Rust Candid | https://docs.rs/candid/latest/candid/ | | -| JS SDK | https://js.icp.build | | -| Agent skill files | https://skills.internetcomputer.org | | - -> **Rust crate URLs:** Each crate has its own URL — do not substitute. For crates not in this table, use `https://docs.rs/<crate-name>/latest/<crate_name>/` (hyphens → underscores in the path). - -## Review guidelines - -**Only review PRs when explicitly asked by a human.** Agents must never offer, suggest, or perform PR reviews on their own initiative. - -When asked to review a PR, load the `technical-documentation` skill and the relevant icskill for the page topic first. - -### Initial review (first time reviewing a page) - -*Mechanical checks:* -1. **Internal links** — `ls` every `[text](path.md)` target. If the `.md` file doesn't exist, also check for `.mdx` — Astro resolves `.md` links to `.mdx` files. Flag as broken only if neither exists. -2. **External URLs** — verify against the linking rules table above. Flag any guessed or wrong URLs (especially `docs.rs` crate links). -3. **CLI commands** — verify all `icp` commands and flags against `.sources/icp-cli/docs/reference/cli.md`. -4. **Frontmatter** — complete and consistent with the body (no contradictions in descriptions, time estimates, scope). -5. **Content rules compliance** — no `dfx` references, no `.mdx`/JSX, relative links with `.md` extension, `core` not `base` for Motoko, Diataxis content type respected. - -*Content quality checks:* -6. **Reader test** — read the page title, then the first two paragraphs. Does the opening deliver on the title's promise? Does it assume the reader came from a specific page or completed prior steps? (Pages must stand on their own — link to prerequisites, don't assume them.) Flag pages that open with background or history instead of what the reader came for. -7. **Funnel check** — does the page follow: orient (what is this, who is it for) → explain/instruct → what's next? Flag pages that bury the lede, put prerequisites after the main content, or end without a clear next step. -8. **Scanability** — can a developer skimming headings and bold text get the gist without reading every paragraph? Flag walls of text and important information buried mid-paragraph. -9. **Accuracy** — cross-check technical claims (memory limits, latency numbers, API behavior) against `.sources/` material. Flag anything that looks wrong or outdated. -10. **Developer empathy** — does the page anticipate what a developer would actually struggle with? For concept pages: does it answer "why should I care?" For guides: does it handle the error cases a developer will actually hit? - -*Post using this format:* - -```markdown -## Review: <page title> - -### Must fix -- **<issue>**: <description and suggested fix> - -### Suggestions -- **<issue>**: <description> - -### Verified -- <what checked out> (e.g., "All CLI commands verified against .sources/icp-cli/docs/reference/cli.md") -``` - -Omit any section that has no items. Every initial review must include the "Verified" section to show what was actually checked. - -### Follow-up review (after feedback was addressed) - -Only run this when reviewing a PR that already had an initial review. Do NOT re-run the full checklist. - -1. Read the previous review comment(s) to understand what was requested. -2. Verify each requested change was made correctly. -3. Check that fixes didn't introduce new issues (e.g., dangling links from removed sections, broken frontmatter from removed fields). -4. Skip re-verifying items already signed off in the initial review, unless the fix directly touches them. - -*Post using this format:* - -```markdown -## Follow-up review: <page title> - -### Fixed -- <what was fixed and confirmed correct> - -### Still needs work -- <what wasn't addressed or was addressed incorrectly> -``` - -Omit "Still needs work" if everything looks good. - -## Skills (required) - -Skills are a **hard prerequisite** — do not start content work, review, or any ICP-related task without them. Run `git submodule update --init --depth 1` if skills appear as broken symlinks. - -Verify at session start: -```bash -ls .agents/skills/icp-cli/SKILL.md .agents/skills/technical-documentation/SKILL.md -``` - -- **`technical-documentation`** — Load before drafting or reviewing any docs page -- **icskills** — Load the skill matching the page topic: - -| Page topic | icskill | -|---|---| +| Topic | icskill | +|-------|---------| | Bitcoin / ckBTC | `ckbtc` | -| Ethereum / EVM chains | `evm-rpc` | -| Certified variables / certified data | `certified-variables` | +| Ethereum / EVM | `evm-rpc` | +| Certified variables | `certified-variables` | | HTTPS outcalls | `https-outcalls` | | SNS / governance | `sns-launch` | -| Identity / authentication | `internet-identity` | -| Multi-canister / architecture | `multi-canister` | +| Identity / auth | `internet-identity` | +| Multi-canister | `multi-canister` | | ICRC tokens / ledger | `icrc-ledger` | | CLI / tooling | `icp-cli` | | Frontend / asset canister | `asset-canister` | | Cycles / billing | `cycles-management` | -| Stable memory / data persistence | `stable-memory` | +| Stable memory | `stable-memory` | | Security | `canister-security` | -| Wallet / DeFi integration | `wallet-integration` | +| Wallet / DeFi | `wallet-integration` | | vetKD / encryption | `vetkd` | -If no skill matches, use `technical-documentation` only. Topics with no dedicated icskill yet: on-chain AI, randomness/VRF, timers, Candid, chain-key tokens. +Topics without a dedicated icskill: on-chain AI, randomness/VRF, timers, Candid, chain-key tokens. + +For design work (CSS, UI, marketing copy), also load `icp-brand-design`. + +## Content rules -**For all content writing** — load `icp-brand-voice` alongside `technical-documentation`. It is the authoritative source for banned jargon, preferred framing, and voice rules. For design work (CSS, copy, UI components, docs styling, marketing copy), also load `icp-brand-design`. +- **Spelling:** "onchain" and "offchain" (no hyphens). "icp-cli" in prose; `icp` in code blocks only. +- **Internal links:** `.md` extension always, even for `.mdx` targets. Relative paths only — never absolute like `/getting-started/quickstart/`. +- **No headings inside `<TabItem>` blocks** — use **bold text** instead. +- **Motoko:** use `mo:core` (`mops.one/core`), never `mo:base`. +- **Diataxis content types:** + - `concepts/` — what and why; no CLI commands or step-by-step + - `getting-started/` — linear tutorials with CLI commands + - `guides/` — task-oriented how-to + - `references/` — precise lookups, no tutorials +- End every page with a `## Next steps` section. + +## Linking rules + +| Resource | URL | +|----------|-----| +| CLI docs | https://cli.internetcomputer.org/ (versioned path required — see Never section) | +| Motoko core library | https://mops.one/core/docs | +| Rust CDK (`ic-cdk`) | https://docs.rs/ic-cdk/latest/ic_cdk/ | +| Rust stable structures | https://docs.rs/ic-stable-structures/latest/ic_stable_structures/ | +| Rust Candid | https://docs.rs/candid/latest/candid/ | +| JS SDK | https://js.icp.build | +| Agent skill files | https://skills.internetcomputer.org | + +> Each Rust crate has its own URL — do not substitute. For crates not listed, use `https://docs.rs/<crate-name>/latest/<crate_name>/` (hyphens → underscores in the path). ## Frontmatter schema ```yaml --- -title: "Page Title" # Required -description: "One-line description" # Required +title: "Page Title" # Required +description: "One-liner" # Required sidebar: - order: 1 # Optional: only where reading order matters + order: 1 # Optional — only where reading order matters --- ``` ## Commands -- `npm run dev` — Local dev server -- `npm run build` — Production build -- `npm run preview` — Preview production build +- `npm run dev` — local dev server +- `npm run build` — production build (must pass before any push) +- `npm run preview` — preview production build ## Agent-friendly documentation -The site implements the [Agent-Friendly Documentation Spec](https://agentdocsspec.com). The `agentDocs()` integration (`plugins/astro-agent-docs.mjs`) generates `/llms.txt` and `.md` endpoints at build time. - -**Build output:** -- `/llms.txt` — discovery index listing all pages with links to `.md` endpoints -- `/<path>.md` — clean markdown for every page (frontmatter, HTML comments, MDX artifacts stripped) - -**SECTIONS array:** The `SECTIONS` array in `plugins/astro-agent-docs.mjs` maps directory prefixes to section labels in `llms.txt`. Update it when adding or renaming sidebar sections in `astro.config.mjs`. - +The `agentDocs()` integration (`plugins/astro-agent-docs.mjs`) generates `/llms.txt` and `.md` endpoints at build time. Update the `SECTIONS` array in that file when adding or renaming sidebar sections in `astro.config.mjs`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17c8fafa..fa9e619a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -48,7 +48,7 @@ Each top-level section has a specific purpose. Match your content accordingly: | `concepts/` | Explanation | What it is, how it works, why it matters | No — link to guides | | `getting-started/` | Tutorial | Step-by-step learning path | Yes — complete and linear | | `guides/` | How-to | Task-oriented instructions | Yes — where relevant | -| `reference/` | Reference | Lookup information | Sparingly — for syntax examples only | +| `references/` | Reference | Lookup information | Sparingly — for syntax examples only | ### Do - Write in plain, direct language @@ -91,9 +91,7 @@ src/assets/images/ - Use descriptive kebab-case filenames (e.g., `canister-internals.png`, `create-canister-flow.png`) - Always include alt text: `![Canister internals](../../assets/images/concepts/canister-internals.png)` - Prefer SVG for diagrams (scalable, smaller). Use PNG for hand-drawn illustrations and screenshots. -- When carrying over portal images, keep the existing hand-drawn visual style -- Decide case-by-case during content writing whether a portal image is worth carrying over -- Portal images are in `portal/static/img/docs/` — copy and rename to match the new structure +- Keep the hand-drawn visual style consistent with existing images ## Agent-friendly documentation @@ -104,14 +102,11 @@ The build generates `/llms.txt` and per-page `.md` endpoints from your content. ## Source material -`.sources/` contains pinned git submodules that agents use as ground truth when writing and reviewing content — CLI references, API signatures, skill files, code examples, and the old portal docs. +`.sources/` contains pinned git submodules that agents use as ground truth when writing and reviewing content — CLI references, API signatures, skill files, and code examples. **Do not edit files in `.sources/` directly.** They are read-only references; changes go to the upstream repos. -Current pinned release versions are in [`.sources/VERSIONS`](.sources/VERSIONS). Bumping a submodule is a maintainer task — follow the procedure in `AGENTS.md` "Bumping submodules". The two pinning strategies are: - -- **Release-pinned** (`icp-cli`, `motoko`, `motoko-core`, `cdk-rs`, `candid`, `response-verification`) — pinned to the latest release tag so docs reflect what users actually have installed. Never pin past the latest release. -- **main/master-tracked** (`portal`, `examples`, `icskills`, and others) — track the default branch; the branch tip is the canonical source. +Current pinned release versions are in [`.sources/VERSIONS`](.sources/VERSIONS). Bumping a submodule is a maintainer task — follow [`.agents/submodule-bumping.md`](.agents/submodule-bumping.md) for the full procedure. ## Synced content @@ -146,26 +141,4 @@ Before submitting a PR, manually verify: 3. **Valid frontmatter** — required fields present, valid values 4. **`npm run build`** — Site builds without errors -> **Note:** Validation scripts are not yet set up on this branch. They are preserved on `restructuring-attempt-1` and will be restored when the docs are ready for production. CI deployment to the IC asset canister runs on every push to `main` (see `.github/workflows/deploy-ic.yml`). - -## Draft completeness checklist - -Before setting a task to `draft` status in Beads, verify: - -1. Content brief from the stub is fully addressed -2. All code examples are tested and copy-pasteable -3. icp-cli commands verified against [CLI reference](https://cli.internetcomputer.org/) -4. Cross-links from `<!-- Cross-Links -->` converted to actual markdown links -5. Source material HTML comments removed from the final content -6. `npm run build` passes - -## Progress tracking - -All tasks are tracked in [Beads](https://github.com/steveyegge/beads) (`bd`). See `AGENTS.md` → "Multi-agent workflow" for the full coordination protocol. - -Key commands: -- `bd ready` — show tasks you can work on (no unresolved blockers) -- `bd update <id> --status draft --notes "PR #X"` — mark task as draft after PR creation -- `bd list --limit 0` — see all tasks (default caps at 50) - -See [AGENTS.md](AGENTS.md) for authoring workflow and content rules. +See [AGENTS.md](AGENTS.md) for the full authoring workflow and content rules. From 84b0a58f65fac4442d51cb10fa6e1eb61019361a Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 15:46:39 +0200 Subject: [PATCH 4/9] =?UTF-8?q?chore:=20trim=20and=20correct=20AGENTS.md?= =?UTF-8?q?=20=E2=80=94=20fix=20setup=20hint,=20project=20structure,=20sta?= =?UTF-8?q?le=20path?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9292d828..8ac1c82e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,7 @@ # ICP Developer Docs -ICP developer documentation built with Astro + Starlight. Goal: get developers building on the IC as fast as possible. `CLAUDE.md` symlinks here. - ```bash -./scripts/setup.sh # initialize submodules and npm deps -npm run build # must pass before any push +./scripts/setup.sh # run this first — initializes submodules (.sources/) and npm deps ``` Tasks come on-demand — no GitHub issue required unless proposing a structural change. @@ -149,7 +146,7 @@ EOF - Load relevant skills before writing (see "Skills" below) - Use `icp` CLI commands — never `dfx` -- Use `mo:core` for Motoko imports — never `mo:base`. See `.sources/motoko/doc/md/12-base-core-migration.md` for the full mapping. +- Use `mo:core` for Motoko imports — never `mo:base`. See `.sources/motoko/doc/md/base-core-migration.md` for the full mapping. - Default to `.md`; use `.mdx` only for interactive components. Tab order: Motoko → Rust → others. - Complete frontmatter on every page (title + description required) - Document structural decisions in the PR description @@ -199,15 +196,14 @@ docs/ ├── guides/ │ ├── backends/ │ ├── canister-calls/ -│ ├── frontends/ +│ ├── canister-management/ │ ├── authentication/ +│ ├── frontends/ │ ├── testing/ -│ ├── canister-management/ │ ├── security/ │ ├── chain-fusion/ -│ ├── defi/ -│ ├── governance/ -│ └── tools/ +│ ├── digital-assets/ +│ └── governance/ ├── concepts/ # Explanations ├── languages/ # Motoko (synced), Rust (hand-written) └── references/ # Specifications and reference @@ -240,7 +236,7 @@ Consult the relevant submodule when writing or reviewing: | PAPI (payment API) | `.sources/papi/` | | `@dfinity/ic-pub-key` CLI | `.sources/ic-pub-key/` | | Internet Identity spec | `.sources/internetidentity/` | -| Technical documentation skill | `.sources/dotskills/` (AGPL-3.0 — kept as submodule to avoid license mixing) | +| Technical documentation skill | `.sources/dotskills/` | For current pinned versions, see `.sources/VERSIONS`. @@ -318,10 +314,5 @@ sidebar: ## Commands -- `npm run dev` — local dev server - `npm run build` — production build (must pass before any push) -- `npm run preview` — preview production build - -## Agent-friendly documentation - -The `agentDocs()` integration (`plugins/astro-agent-docs.mjs`) generates `/llms.txt` and `.md` endpoints at build time. Update the `SECTIONS` array in that file when adding or renaming sidebar sections in `astro.config.mjs`. +- `npm run dev` — local dev server From e783b427b00af8e9200261de4dbf6c4460b5b159 Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 16:43:20 +0200 Subject: [PATCH 5/9] chore: remove no-op externalToInternal map and tighten post-migration docs - Drop the 70-entry externalToInternal URL rewrite map from postprocess-motoko.mjs; all old internetcomputer.org/docs/ patterns were already handled by upstream PR #6132 which rewrote them to docs.internetcomputer.org/... URLs covered by the generic handler - Narrow the link-matching regex to docs.internetcomputer.org only - Update spec-maintenance.md: correct filename to http-gateway-protocol-spec.md and remove the link adaptation section (no longer needed; this repo is now the primary source for http-gateway-protocol-spec.md) - Improve AGENTS.md anchor-linking rule: require reading the target page to find the most specific anchor, not just a heading grep --- .agents/spec-maintenance.md | 9 +--- AGENTS.md | 4 +- scripts/postprocess-motoko.mjs | 88 ++-------------------------------- 3 files changed, 6 insertions(+), 95 deletions(-) diff --git a/.agents/spec-maintenance.md b/.agents/spec-maintenance.md index d73abd67..0112ebdf 100644 --- a/.agents/spec-maintenance.md +++ b/.agents/spec-maintenance.md @@ -11,7 +11,7 @@ The following files are maintained directly in this repository. Update them manu | `public/references/_attachments/requests.cddl` | Request CDDL schema | IC HTTPS interface spec changes | | `public/references/_attachments/http-gateway.did` | HTTP Gateway Candid interface | HTTP Gateway spec changes | | `docs/references/ic-interface-spec/` | IC Interface Spec (7 focused pages) | IC spec version bumps — apply changes to the matching file (see mapping below) | -| `docs/references/http-gateway-spec.md` | HTTP Gateway Protocol Spec | HTTP Gateway spec version bumps | +| `docs/references/http-gateway-protocol-spec.md` | HTTP Gateway Protocol Spec | HTTP Gateway spec version bumps | ## IC Interface Spec — section-to-file mapping @@ -25,10 +25,3 @@ The following files are maintained directly in this repository. Update them manu | `abstract-behavior.md` | Abstract behavior | | `changelog.md` | IC spec changelog | -## Link adaptation for `http-gateway-spec.md` - -If an update introduces absolute `/references/ic-interface-spec#<anchor>` links, convert them to relative paths using the anchor-to-file mapping at the bottom of `docs/references/http-gateway-spec.md`. To find which file owns a given anchor: - -```bash -grep -r "{#<anchor>}" docs/references/ic-interface-spec/ -``` diff --git a/AGENTS.md b/AGENTS.md index 8ac1c82e..d6764dd9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ Tasks come on-demand — no GitHub issue required unless proposing a structural ## Writing or updating content -Load the relevant skills first (see "Skills" below). Then: +Load `technical-documentation`, `icp-brand-voice`, and the relevant icskill before writing (see "Skills" for the topic-to-skill mapping). Then: - Read relevant source material from `.sources/` to verify CLI commands, API signatures, and technical claims (see "Source material" below for what to consult per topic). - **CLI commands:** verify every flag against `.sources/icp-cli/docs/reference/cli.md` — never guess syntax. @@ -170,7 +170,7 @@ EOF - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions - Link to `internetcomputer.org/docs/` (retired) or `learn.internetcomputer.org` (content is now in this repo under `docs/concepts/`) - Link to internal pages that don't exist — run `ls <target>` before linking. Links to `.mdx` files use `.md` extension. -- Link without a section anchor when the context refers to a specific subsection — verify anchors with `grep "^## \|^### " <target>`. Slugs: lowercase, spaces → `-`, special chars stripped. +- Link to an internal page without checking for a relevant section anchor — read the target page to find the most specific section that fits, then derive the anchor slug from its heading (lowercase, spaces → `-`, special chars stripped). - Link to `https://cli.internetcomputer.org/` bare root — use the versioned path. Current slug: `0.2`; verify with `cat .sources/icp-cli/docs-site/versions.json`. - Link externally when an internal page exists — check `docs/` first - Write em-dashes (`—`) or use `--` as prose punctuation — use colon, semicolon, or parentheses instead. (`--` is fine inside code blocks as a CLI flag or comment.) diff --git a/scripts/postprocess-motoko.mjs b/scripts/postprocess-motoko.mjs index a433bcfd..7734c7e9 100644 --- a/scripts/postprocess-motoko.mjs +++ b/scripts/postprocess-motoko.mjs @@ -8,8 +8,7 @@ * <motokoExamples> placeholder insertion, mo:base→mo:core rewrites. * * What remains: - * 1. Rewrite external internetcomputer.org/docs links to internal paths. - * Still needed for Changelog entries and any legacy links not yet fixed upstream. + * 1. Rewrite docs.internetcomputer.org links to internal paths. * 2. Replace em-dashes (banned per ICP style guide). * Still needed for Changelog entries. * 3. Redirect remaining core/base library relative links to mops.one (safety net). @@ -22,80 +21,6 @@ import { fileURLToPath } from 'node:url'; const ROOT = resolve(fileURLToPath(import.meta.url), '..', '..'); const MOTOKO_DIR = join(ROOT, 'docs', 'languages', 'motoko'); -// --------------------------------------------------------------------------- -// External URL rewrite table: internetcomputer.org/docs/... → internal path -// --------------------------------------------------------------------------- -const externalToInternal = new Map([ - // Canister management - ['internetcomputer.org/docs/building-apps/canister-management/logs', '/guides/canister-management/logs'], - ['internetcomputer.org/docs/building-apps/canister-management/resource-limits', '/guides/canister-management/large-wasm'], - ['internetcomputer.org/docs/building-apps/canister-management/snapshots', '/guides/canister-management/snapshots'], - ['internetcomputer.org/docs/building-apps/canister-management/upgrade', '/guides/canister-management/lifecycle'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/logs', '/guides/canister-management/logs'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/upgrade', '/guides/canister-management/lifecycle'], - - // Core concepts - ['internetcomputer.org/docs/building-apps/essentials/canisters', '/concepts/canisters'], - ['internetcomputer.org/docs/building-apps/essentials/message-execution', '/references/message-execution-properties'], - ['internetcomputer.org/docs/references/async-code', '/references/message-execution-properties'], - - // Candid - ['internetcomputer.org/docs/building-apps/interact-with-canisters/candid/candid-concepts', '/guides/canister-calls/candid'], - ['internetcomputer.org/docs/building-apps/interact-with-canisters/candid/using-candid', '/guides/canister-calls/candid'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/candid', '/guides/canister-calls/candid'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/candid/candid-concepts','/guides/canister-calls/candid'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/candid/candid-howto', '/guides/canister-calls/candid'], - ['internetcomputer.org/docs/references/candid-ref', '/references/candid-spec'], - - // Calling - ['internetcomputer.org/docs/building-apps/interact-with-canisters/query-calls', '/concepts/canisters'], - ['internetcomputer.org/docs/building-apps/interact-with-canisters/update-calls', '/concepts/canisters'], - ['internetcomputer.org/docs/building-apps/interact-with-canisters/agents/overview', '/guides/canister-calls/calling-from-clients'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/call/overview', '/guides/canister-calls/calling-from-clients'], - - // Timers and randomness - ['internetcomputer.org/docs/building-apps/network-features/periodic-tasks-timers', '/guides/backends/timers'], - ['internetcomputer.org/docs/building-apps/network-features/randomness', '/guides/backends/randomness'], - ['internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks', '/guides/backends/timers'], - ['internetcomputer.org/docs/current/developer-docs/smart-contracts/advanced-features/randomness', '/guides/backends/randomness'], - - // Security - ['internetcomputer.org/docs/building-apps/security/iam/', '/guides/security/identity-and-access-management'], - ['internetcomputer.org/docs/building-apps/security/iam', '/guides/security/identity-and-access-management'], - ['internetcomputer.org/docs/current/developer-docs/security/security-best-practices/inter-canister-calls', '/guides/security/inter-canister-calls'], - - // IC interface spec (anchor-specific entries before the base URL) - ['internetcomputer.org/docs/references/ic-interface-spec#global-timer', '/references/ic-interface-spec/canister-interface#global-timer'], - ['internetcomputer.org/docs/references/ic-interface-spec#heartbeat', '/references/ic-interface-spec/canister-interface#heartbeat'], - ['internetcomputer.org/docs/references/ic-interface-spec#system-api-inspect-message', '/references/ic-interface-spec/canister-interface#system-api-inspect-message'], - ['internetcomputer.org/docs/references/ic-interface-spec#ic-raw_rand', '/references/ic-interface-spec/management-canister#ic-raw_rand'], - ['internetcomputer.org/docs/references/ic-interface-spec', '/references/ic-interface-spec/'], - ['internetcomputer.org/docs/current/references/ic-interface-spec', '/references/ic-interface-spec/'], - ['internetcomputer.org/docs/current/references/ic-interface-spec/','/references/ic-interface-spec/'], - ['internetcomputer.org/docs/references/system-canisters/management-canister', '/references/management-canister'], - - // Storage (anchor-specific entries before base URL) - ['internetcomputer.org/docs/building-apps/canister-management/storage#heap-memory', '/concepts/orthogonal-persistence#heap-wasm-linear-memory'], - ['internetcomputer.org/docs/building-apps/canister-management/storage#motoko-storage-handling', '/concepts/orthogonal-persistence#motoko-true-orthogonal-persistence'], - ['internetcomputer.org/docs/building-apps/canister-management/storage', '/concepts/orthogonal-persistence'], - - // Getting started - ['internetcomputer.org/docs/current/developer-docs/getting-started/install', '/getting-started/quickstart'], - ['internetcomputer.org/docs/current/developer-docs/setup/install', '/getting-started/quickstart'], - ['internetcomputer.org/docs/current/developer-docs/getting-started/deploy-and-manage', '/getting-started/quickstart'], - ['internetcomputer.org/docs/current/developer-docs/getting-started/development-workflow','/getting-started/quickstart'], - - // docs.motoko.org (non-existent domain) and mo-doc link - ['docs.motoko.org', '/developer-tools/#mo-doc'], - ['docs.internetcomputer.org/developer-tools/#mo-doc', '/developer-tools/#mo-doc'], - - // Motoko-internal links using old portal paths - ['internetcomputer.org/docs/motoko/language-manual', '/languages/motoko/reference/language-manual'], - ['internetcomputer.org/docs/current/motoko/main/reference/language-manual', '/languages/motoko/reference/language-manual'], - ['internetcomputer.org/docs/motoko/data-persistence', '/languages/motoko/fundamentals/actors/data-persistence'], - ['internetcomputer.org/docs/motoko/icp-features/system-functions', '/languages/motoko/icp-features/system-functions'], -]); - let unresolvedExternalCount = 0; function rewriteExternalLink(url) { @@ -111,13 +36,6 @@ function rewriteExternalLink(url) { return '/' + withoutAnchor.slice('docs.internetcomputer.org/'.length) + anchor; } - if (anchor && externalToInternal.has(normalized)) return externalToInternal.get(normalized); - if (externalToInternal.has(withoutAnchor)) return externalToInternal.get(withoutAnchor) + anchor; - for (const [key, val] of externalToInternal) { - if (withoutAnchor.startsWith(key + '/') || withoutAnchor.startsWith(key + '#')) { - return val + anchor; - } - } return null; } @@ -163,7 +81,7 @@ function processFile(filePath) { }); // Rewrite external links to internal paths. - const extDomain = '(?:(?:www\\.)?internetcomputer\\.org\\/docs\\/|docs\\.internetcomputer\\.org\\/|docs\\.motoko\\.org)'; + const extDomain = 'docs\\.internetcomputer\\.org\\/'; const extLinkRe = new RegExp( `\\((https?:\\/\\/${extDomain}[^)\\s]*)\\)|(?<!\\()(https?:\\/\\/${extDomain}[^\\s)]*)`, 'g', @@ -236,7 +154,7 @@ walkAndProcess(MOTOKO_DIR); console.log(`Post-processing complete: ${filesChanged} files updated.`); if (unresolvedExternalCount > 0) { - console.error(`\nWARNING: ${unresolvedExternalCount} UNRESOLVED-EXTERNAL link(s) — add missing entries to externalToInternal in postprocess-motoko.mjs.`); + console.error(`\nWARNING: ${unresolvedExternalCount} UNRESOLVED-EXTERNAL link(s) — add a rewrite handler to rewriteExternalLink in postprocess-motoko.mjs.`); process.exit(1); } From 9938d687f99a104740fb2fbe9a11da3e07fde46c Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 18:08:21 +0200 Subject: [PATCH 6/9] chore: drop Upstream comment validation and stale README bullets MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove checkUpstream from validate.js — the hand-written/portal comments are noise and the portal references are stale; meaningful upstream traceability is tracked in .agents/spec-maintenance.md and the AGENTS.md source material table. Follow-up cleanup in GH #279. - Update AGENTS.md: Upstream comment is now optional and only recommended where a page closely tracks a specific upstream file - Fix ambiguous CLI path in source material table - Remove two stale README bullets (Upstream comment requirement and Sync recommendation) that contradicted AGENTS.md - Remove Learn Hub from README related resources (content now in repo) --- AGENTS.md | 4 ++-- README.md | 3 --- scripts/validate.js | 9 --------- 3 files changed, 2 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d6764dd9..bcb02a96 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ Load `technical-documentation`, `icp-brand-voice`, and the relevant icskill befo - **Flag uncertainty:** add `<!-- Needs human verification: [reason] -->` next to any claim you can't verify from `.sources/`. Never silently guess. - **Do not invent command output** — copy from `.sources/` READMEs or test fixtures, or write `<!-- TODO: verify output -->`. - **`.md` → `.mdx` conversion:** if a page needs multi-language tabs, rename `.md` → `.mdx`, add `import { Tabs, TabItem } from '@astrojs/starlight/components';` after the frontmatter, and convert `<!-- -->` comments to `{/* */}`. Astro resolves `.md` links to `.mdx` files — no link updates needed. -- For pages that closely track an upstream source, add at the bottom: `<!-- Upstream: informed by <repo> <path> -->`. Skip for original content. +- For pages that closely track a specific upstream file, add at the bottom: `<!-- Upstream: informed by <repo> <path> -->`. Skip for pages that draw from multiple sources or are fully original. - Follow the "Content rules" section below. ## Adding or updating code snippets @@ -221,7 +221,7 @@ Consult the relevant submodule when writing or reviewing: | Topic | Submodule | |-------|-----------| -| CLI commands and flags | `.sources/icp-cli/` — verify against `docs/reference/cli.md` | +| CLI commands and flags | `.sources/icp-cli/` — verify against `.sources/icp-cli/docs/reference/cli.md` | | Motoko APIs (`mo:core`) | `.sources/motoko-core/` | | Motoko compiler / syntax | `.sources/motoko/` | | Rust CDK (`ic-cdk`, `ic-cdk-timers`) | `.sources/cdk-rs/` | diff --git a/README.md b/README.md index 2cc7a8dd..e0ab00e1 100644 --- a/README.md +++ b/README.md @@ -55,8 +55,6 @@ 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` -- Every content page ends with an `<!-- Upstream: -->` comment listing source repos used -- Every PR includes a `## Sync recommendation` in the description Use **squash and merge** to keep `main` history clean. @@ -97,7 +95,6 @@ These endpoints are generated at build time and updated automatically on every d | ICP CLI docs | https://cli.internetcomputer.org | | JS SDK docs | https://js.icp.build | | ICP Skills | https://skills.internetcomputer.org | -| Learn Hub | https://learn.internetcomputer.org | | Motoko core library | https://mops.one/core/docs | | Rust CDK API | https://docs.rs/ic-cdk/latest/ic_cdk | diff --git a/scripts/validate.js b/scripts/validate.js index 3a0c3fbd..5f2def34 100644 --- a/scripts/validate.js +++ b/scripts/validate.js @@ -21,14 +21,6 @@ function isStub(content) { return content.includes('TODO: Write content'); } -function checkUpstream(file, content) { - if (isSynced(file) || isStub(content) || path.basename(file) === 'index.md') return []; - if (!/<!--\s*Upstream:\s*(hand-written|sync from|informed by)/.test(content)) { - return ['missing <!-- Upstream: hand-written|sync from|informed by --> comment']; - } - return []; -} - function checkFrontmatter(file, content) { if (isSynced(file)) return []; try { @@ -107,7 +99,6 @@ function checkInternalLinks(file, content) { function validate(file) { const content = fs.readFileSync(file, 'utf8'); return [ - ...checkUpstream(file, content), ...checkFrontmatter(file, content), ...checkForbiddenPatterns(file, content), ...checkEmdash(file, content), From 65860c4c3c4d4590d0705059d162332801c544fc Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 18:21:16 +0200 Subject: [PATCH 7/9] =?UTF-8?q?chore:=20remove=20spec-maintenance.md=20?= =?UTF-8?q?=E2=80=94=20spec=20files=20are=20owned=20by=20IC=20core=20teams?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/spec-maintenance.md | 27 --------------------------- AGENTS.md | 1 - 2 files changed, 28 deletions(-) delete mode 100644 .agents/spec-maintenance.md diff --git a/.agents/spec-maintenance.md b/.agents/spec-maintenance.md deleted file mode 100644 index 0112ebdf..00000000 --- a/.agents/spec-maintenance.md +++ /dev/null @@ -1,27 +0,0 @@ -# Spec maintenance - -The following files are maintained directly in this repository. Update them manually when the IC team announces a new version of the relevant specification. - -## Directly maintained files - -| Local file | What it is | When to update | -|-----------|-----------|---------------| -| `public/references/ic.did` | Candid interface of the IC management canister | New management canister methods or changed types; update `docs/references/management-canister.md` and affected guides alongside | -| `public/references/_attachments/certificates.cddl` | Certificate CDDL schema | IC certification spec changes | -| `public/references/_attachments/requests.cddl` | Request CDDL schema | IC HTTPS interface spec changes | -| `public/references/_attachments/http-gateway.did` | HTTP Gateway Candid interface | HTTP Gateway spec changes | -| `docs/references/ic-interface-spec/` | IC Interface Spec (7 focused pages) | IC spec version bumps — apply changes to the matching file (see mapping below) | -| `docs/references/http-gateway-protocol-spec.md` | HTTP Gateway Protocol Spec | HTTP Gateway spec version bumps | - -## IC Interface Spec — section-to-file mapping - -| File | IC spec section | -|---|---| -| `index.md` | Introduction, Pervasive concepts, The system state tree | -| `https-interface.md` | HTTPS Interface | -| `canister-interface.md` | Canister module format, Canister interface (System API) | -| `management-canister.md` | The IC management canister, The IC Bitcoin API, The IC Provisional API | -| `certification.md` | Certification, The HTTP Gateway protocol | -| `abstract-behavior.md` | Abstract behavior | -| `changelog.md` | IC spec changelog | - diff --git a/AGENTS.md b/AGENTS.md index bcb02a96..ed318daa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -186,7 +186,6 @@ EOF - `.sources/` — Pinned source submodules (read-only) - `.agents/skills/` — Agent skill files. Run `git submodule update --init --depth 1` if broken. - `.agents/submodule-bumping.md` — Procedures for bumping source submodules (maintainer use) -- `.agents/spec-maintenance.md` — Procedures for maintaining directly-owned spec files (maintainer use) ## Project structure From 651f60cd0ffb6cb589b0dc1056fb0eec262e3a5d Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 18:29:33 +0200 Subject: [PATCH 8/9] chore: incorporate #206 follow-up issue pattern into submodule-bumping.md --- .agents/submodule-bumping.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/.agents/submodule-bumping.md b/.agents/submodule-bumping.md index ccf8b254..71a0de9a 100644 --- a/.agents/submodule-bumping.md +++ b/.agents/submodule-bumping.md @@ -10,10 +10,28 @@ Only the project maintainer bumps submodule refs. Reference this file when asked ## General checklist (all submodules) 1. Identify changes: `git -C .sources/<repo> log --oneline <old-ref>..<new-ref>` -2. Grep docs pages for content derived from that submodule; update affected pages +2. Apply any mechanical per-submodule steps (synced file copies, link slug updates — see table below) 3. Check open PRs — post a bump-notice comment if the bump may affect pages under review (format below) 4. Update `.sources/VERSIONS` for release-pinned repos 5. Note the bump in the PR description +6. **Always open a follow-up GitHub issue** for a dedicated docs review (label: `documentation`, title: `docs: review docs after bumping <submodule> to <new-ref>`). Include the old and new version, a summary of what changed, and the template below. + +**Follow-up issue body template:** +``` +`<submodule>` was bumped from `<old-ref>` to `<new-ref>`. + +## What changed +<paste relevant entries from git log / CHANGELOG> + +## Docs review task +Review all docs pages that reference content from this submodule (API names, CLI commands, canister IDs, code patterns, version numbers). For every affected page, check it against the new version and update as needed. Look for: +- Changed or removed APIs/commands that appear in code blocks or prose +- New APIs not yet documented +- Cross-SDK gaps (e.g. a new API landed in one language but not others) +- Version numbers that need updating + +Submodule source: `.sources/<submodule>/` +``` **Bump-notice PR comment:** ```bash From b49daaeea2254bd0564119e0672da6aab6edcdda Mon Sep 17 00:00:00 2001 From: Marco Walz <marco.walz@dfinity.org> Date: Wed, 27 May 2026 18:32:47 +0200 Subject: [PATCH 9/9] =?UTF-8?q?chore:=20revert=20follow-up=20issue=20patte?= =?UTF-8?q?rn=20=E2=80=94=20bump=20PRs=20cover=20docs=20review=20inline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agents/submodule-bumping.md | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/.agents/submodule-bumping.md b/.agents/submodule-bumping.md index 71a0de9a..ccf8b254 100644 --- a/.agents/submodule-bumping.md +++ b/.agents/submodule-bumping.md @@ -10,28 +10,10 @@ Only the project maintainer bumps submodule refs. Reference this file when asked ## General checklist (all submodules) 1. Identify changes: `git -C .sources/<repo> log --oneline <old-ref>..<new-ref>` -2. Apply any mechanical per-submodule steps (synced file copies, link slug updates — see table below) +2. Grep docs pages for content derived from that submodule; update affected pages 3. Check open PRs — post a bump-notice comment if the bump may affect pages under review (format below) 4. Update `.sources/VERSIONS` for release-pinned repos 5. Note the bump in the PR description -6. **Always open a follow-up GitHub issue** for a dedicated docs review (label: `documentation`, title: `docs: review docs after bumping <submodule> to <new-ref>`). Include the old and new version, a summary of what changed, and the template below. - -**Follow-up issue body template:** -``` -`<submodule>` was bumped from `<old-ref>` to `<new-ref>`. - -## What changed -<paste relevant entries from git log / CHANGELOG> - -## Docs review task -Review all docs pages that reference content from this submodule (API names, CLI commands, canister IDs, code patterns, version numbers). For every affected page, check it against the new version and update as needed. Look for: -- Changed or removed APIs/commands that appear in code blocks or prose -- New APIs not yet documented -- Cross-SDK gaps (e.g. a new API landed in one language but not others) -- Version numbers that need updating - -Submodule source: `.sources/<submodule>/` -``` **Bump-notice PR comment:** ```bash