diff --git a/.docs-plan/README.md b/.docs-plan/README.md index f290d7d..6117c23 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 347ea49..788b70a 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 2b53162..0000000 --- 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 9a8c688..0000000 --- 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 9785b7a..0000000 --- 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 7a799d3..0000000 --- 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 92926e5..0000000 --- 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 a547219..0000000 --- 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 19d8c90..80a9aed 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`.