Skip to content

docs: management canister API reference #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marc0olo merged 3 commits into from
Mar 19, 2026
Merged

docs: management canister API reference #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cbe018a
docs: management canister API reference
marc0olo Mar 19, 2026
3455de2
docs: address review feedback for management canister reference
marc0olo Mar 19, 2026
a998a09
docs: add ic.did Candid interface and submodule bump checklist
marc0olo Mar 19, 2026
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
7 changes: 7 additions & 0 deletions .docs-plan/decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,13 @@ Record decisions that constrain future work — things an agent needs to know th
**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 `docs/reference/_attachments/ic.did`. 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-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.
Expand Down
15 changes: 15 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -487,6 +487,21 @@ Only the project maintainer bumps submodule refs. When bumped:
2. Review if any existing docs pages are affected by the upstream changes
3. Update affected pages and note the bump in the PR description

### Synced files from submodules

Some files are copied from `.sources/` into the docs repo because they need to be served or referenced directly. When bumping the source submodule, these files must be diffed and re-copied if changed.

| Local file | Source | Affects |
|-----------|--------|---------|
| `docs/reference/_attachments/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/reference/management-canister.md` and any guides that reference affected methods |

**Portal bump checklist for `ic.did`:**
1. Diff: `diff docs/reference/_attachments/ic.did .sources/portal/docs/references/_attachments/ic.did`
2. If changed, copy: `cp .sources/portal/docs/references/_attachments/ic.did docs/reference/_attachments/ic.did`
3. Review the diff for new methods, changed signatures, or removed methods
4. Update `docs/reference/management-canister.md` to reflect any interface changes
5. Check guides that reference affected methods (chain-fusion, canister-management, backends)

## Planning artifacts (`.docs-plan/`)

Check these every session:
Expand Down
Loading
Loading