docs: getting-started quickstart page by marc0olo · Pull Request #5 · dfinity/developer-docs

marc0olo · 2026-03-13T10:05:32Z

Summary

Full quickstart walkthrough: install icp-cli, scaffold a project, deploy to local network, call canisters
Linear flow: prerequisites → install → create → deploy → call → stop
Covers Motoko + React template with Rust alternative note
Backend-only callout points to dedicated rust and motoko subfolder templates
Explains what happens under the hood (two-canister model, canister.yaml per directory, icp-cli wiring)
Links to project structure, concepts, and next steps

Sync recommendation

informed by dfinity/icp-cli — quickstart.md, tutorial.md

marc0olo · 2026-03-13T10:18:59Z

Review: getting-started/quickstart.md — Changes Requested

Good quickstart — clear flow, template variables verified. A few issues:

1. Inconsistent time claim

Frontmatter description: "in under 10 minutes"
Body opening line: "in under 5 minutes"

Pick one and make it consistent.

2. Unverifiable npm package name

npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm

This package name isn't verifiable from the source material in .sources/. If it's wrong, the entire quickstart is broken on step 1. Verify against the actual npm registry or icp-cli repo's package.json and add a source comment so future reviewers can re-verify.

✓ Verified

CLI commands icp new, icp network start -d, icp deploy, icp canister call, icp network stop all verified against .sources/icp-cli/docs/reference/cli.md
icp canister install --mode upgrade verified (valid modes: auto, install, reinstall, upgrade)
Template variables (backend_type=motoko, frontend_type=react, network_type=Default) verified against .sources/icp-cli-templates/hello-world/cargo-generate.toml
--subfolder, --define flags verified
-d (--background) flag for icp network start verified

Adds three new verification rules to the content authoring workflow: - Internal link verification: agents must confirm target files exist - External URL verification: agents must not guess/generalize crate URLs - Self-consistency check: frontmatter and body must not contradict Also expands linking rules table with ic-stable-structures and candid crate URLs, and adds a "never" rule against linking to non-existent pages. Motivated by review of PRs #2-#5 where agents linked to plausible but non-existent paths (reference/certified-variables.md, guides/backends/ stable-memory.md) and used wrong crate URLs (docs.rs/ic-cdk for ic-stable-structures).

marc0olo · 2026-03-13T10:51:16Z

Review: getting-started/quickstart.md (round 2)

Must fix

Frontmatter/body time inconsistency — Frontmatter description says "under 10 minutes", body opening says "under 5 minutes." These must match. Content brief specifies 10 minutes. (Flagged in round 1, still unfixed.)
External URL likely wrong — https://dfinity.github.io/icp-cli/guides/installation.html uses .html extension. Starlight generates clean URLs — the correct URL is almost certainly https://dfinity.github.io/icp-cli/guides/installation/. Please verify.

Suggestions

Missing Motoko-only template footnote — Content brief asks for "footnotes for Rust-only and Motoko-only templates." The page has a "Prefer Rust?" callout but no mention of standalone templates (without frontend).
Missing agentic development cross-link — The stub lists ../guides/tools/agentic-development as a recommended cross-link. Not included in "Next steps."
Candid syntax clarification — '("World")' — note that single quotes are shell quoting, not Candid syntax. Beginners may be confused.

Verified

All 4 internal links resolve: project-structure.md, what-next.md, ../concepts/canisters.md, ../reference/candid-spec.md
All CLI commands verified: icp new (with --subfolder, --define), icp network start -d, icp deploy, icp canister call, icp network stop
Template variables (backend_type=motoko, frontend_type=react, network_type=Default) verified against .sources/icp-cli-templates/hello-world/cargo-generate.toml
npm packages @icp-sdk/icp-cli and @icp-sdk/ic-wasm confirmed in .sources/icp-cli/npm/icp-cli/package.json and installation docs
icp --version and ic-wasm --version confirmed in official docs
No dfx references, no .mdx/JSX
Frontmatter complete, all code examples under 30 lines

Covers icp-cli installation, project scaffolding from hello-world template, local network setup, deployment, canister calls, and next steps. Includes Rust footnote, under-the-hood explanation of the two-canister architecture, and links to icp-cli docs for full reference. Source: icp-cli quickstart.md, tutorial.md, hello-world template

Link to reference/candid-spec.md instead of internetcomputer.org/docs/ which will be dead once the new docs site launches.

marc0olo · 2026-03-13T11:10:55Z

Feedback addressed:

Fixed time inconsistency: body now says "under 10 minutes" matching frontmatter
Fixed external URL: clean URL /installation/ instead of /installation.html
Added "Backend only?" callout for frontend_type=none
Added agentic development cross-link to Next steps
Clarified Candid syntax: noted outer single quotes are shell quoting

Copilot

Pull request overview

Replaces the Getting Started quickstart stub with a complete walkthrough for installing icp-cli, scaffolding a full-stack project, running a local network, deploying, and calling a canister, plus brief architecture context and next-step links.

Changes:

Adds prerequisites and tool installation steps (icp-cli, ic-wasm, ic-mops).
Documents a linear “create → start local network → deploy → call canister → stop network” flow (Motoko + React, with a Rust alternative note).
Adds an “under the hood” section describing the backend + frontend canister model and links to follow-on pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

Per-canister config files are canister.yaml, not icp.yaml

marc0olo · 2026-03-13T16:30:59Z

Feedback addressed:

Fixed: per-canister config file is canister.yaml, not icp.yaml
Verified icp.yaml code block matches upstream template

The hello-world template only supports frontend_type=react. For backend-only projects, use --subfolder rust or --subfolder motoko which are dedicated backend-only templates.

marc0olo · 2026-03-13T17:45:33Z

Feedback addressed:

Fixed backend-only callout: replaced --define frontend_type=none (not supported by hello-world template) with --subfolder rust or --subfolder motoko which are dedicated backend-only templates

- Fix factually incorrect ckETH deposit flow: remove false minter_address function claim and unique-per-principal address claim; describe the correct flow using the deposit function on the shared helper contract with ICP principal as call data, and the minter monitoring ReceivedEth events - Change chain-key cryptography link from external Learn Hub URL to internal page (docs/concepts/chain-key-cryptography.md) per CLAUDE.md linking rules - Add ckBTC Checker canister ID (oltsj-fqaaa-aaaar-qal5q-cai) to the canister table since the page already references the checker's public audit - Add created_at_time for dedup protection in withdrawal code (Motoko and Rust) with explanatory comment per icrc-ledger skill pitfall #5 - Update Upstream comment to reference .sources/ repos instead of external URL

marc0olo added 3 commits March 13, 2026 12:08

fix: replace old docs URLs with internal relative links

5100766

Link to reference/candid-spec.md instead of internetcomputer.org/docs/ which will be dead once the new docs site launches.

fix: address PR #5 review feedback

fc3be12

marc0olo force-pushed the docs/getting-started-quickstart branch from df39e1d to fc3be12 Compare March 13, 2026 11:10

marc0olo requested a review from Copilot March 13, 2026 14:50

Copilot started reviewing on behalf of marc0olo March 13, 2026 14:50 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

Comment thread docs/getting-started/quickstart.md

Comment thread docs/getting-started/quickstart.md

Comment thread docs/getting-started/quickstart.md Outdated

docs: fix canister.yaml reference in quickstart

c80e423

Per-canister config files are canister.yaml, not icp.yaml

marc0olo commented Mar 13, 2026

View reviewed changes

Comment thread docs/getting-started/quickstart.md Outdated

fix: use language-specific templates for backend-only projects

2a50a24

The hello-world template only supports frontend_type=react. For backend-only projects, use --subfolder rust or --subfolder motoko which are dedicated backend-only templates.

marc0olo merged commit 2ac4435 into main Mar 13, 2026

marc0olo deleted the docs/getting-started-quickstart branch March 13, 2026 17:46

marc0olo mentioned this pull request Mar 20, 2026

Skills gaps causing repeated failures in Motoko blog app generation (follow-up to #35) #37

Closed

marc0olo mentioned this pull request Apr 16, 2026

docs: chain-key tokens guide #76

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: getting-started quickstart page#5

docs: getting-started quickstart page#5
marc0olo merged 5 commits into
mainfrom
docs/getting-started-quickstart

marc0olo commented Mar 13, 2026 •

edited

Loading

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

marc0olo commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Sync recommendation

Uh oh!

marc0olo commented Mar 13, 2026

Review: getting-started/quickstart.md — Changes Requested

1. Inconsistent time claim

2. Unverifiable npm package name

✓ Verified

Uh oh!

marc0olo commented Mar 13, 2026

Review: getting-started/quickstart.md (round 2)

Must fix

Suggestions

Verified

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Uh oh!

marc0olo commented Mar 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marc0olo commented Mar 13, 2026 •

edited

Loading