Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .docs-plan/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,24 @@ Record decisions that constrain future work — things an agent needs to know th

---

## 2026-04-27: CLI and language tabs are always separate

**Context:** Some pages were mixing CLI commands into the same `<Tabs syncKey="lang">` 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 `<Tabs syncKey="lang">` group. When a section has both a CLI command and language-specific code, the CLI block comes first (quick-check path), followed by the `<Tabs>` 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:** `reference/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. `reference/icrc-standards.md` is a lightweight index of all ICRC standards grouped by category (extensible for future standards). `reference/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 `reference/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 (`reference/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.
Expand Down
2 changes: 1 addition & 1 deletion docs/concepts/chain-fusion.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Direct integration provides the strongest trust guarantees. The only assumption

Chain-key tokens are digital twins of native assets from other blockchains (for example, ckBTC for Bitcoin and ckETH for Ethereum). Each token is backed 1:1 by the native asset, which is held in a canister-controlled address on the source chain. Minting and burning happen entirely onchain. No bridge, no custodian.

These tokens implement the [ICRC-2](../guides/digital-assets/token-ledgers.md) token standard, so they can be transferred and traded within the ICP ecosystem with the same speed and cost as any other ICP token. When a user wants to redeem the underlying asset, the minter canister signs and submits a withdrawal transaction on the source chain.
These tokens implement the [ICRC-2](../guides/digital-assets/ledgers.md) token standard, so they can be transferred and traded within the ICP ecosystem with the same speed and cost as any other ICP token. When a user wants to redeem the underlying asset, the minter canister signs and submits a withdrawal transaction on the source chain.

For details on integrating with chain-key tokens, see the [Chain-key tokens guide](../guides/digital-assets/chain-key-tokens.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/getting-started/choose-your-path.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ Chain fusion lets your canister hold native assets, sign transactions, and inter

ICP has a standard token framework (ICRC) and chain-key tokens that represent assets from other chains. These guides cover the ledger APIs and token patterns for building payment flows, issuing digital assets, and integrating with exchanges.

**Start with:** [Token ledgers](../guides/digital-assets/token-ledgers.md): understand ICRC token standards and interact with ledger canisters.
**Start with:** [Ledgers](../guides/digital-assets/ledgers.md): understand ICRC token standards and interact with ledger canisters.

**Then explore:**

Expand Down
Loading
Loading