refactor(reference): split ic-interface-spec into 7 focused sub-pages

.docs-plan/decisions.md

@@ -15,17 +15,17 @@ Record decisions that constrain future work — things an agent needs to know th
 
 ## 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`.
+**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 `reference/signer-standards.md`, add it to the index and link from there.
+**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 (`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.
-**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/reference/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" }`.
+**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.
 
@@ -180,7 +180,7 @@ Record decisions that constrain future work — things an agent needs to know th
 ## 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. `reference/` pages use them sparingly for syntax examples only.
+**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
@@ -282,3 +282,13 @@ Record decisions that constrain future work — things an agent needs to know th
 **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.

AGENTS.md

@@ -119,7 +119,7 @@ git checkout main
 
 ## Ask first (confirm with the user before doing these)
 
-- Creating new top-level sections (getting-started, guides, concepts, languages, reference)
+- Creating new top-level sections (getting-started, guides, concepts, languages, references)
 - Adding new pages not in the migration plan
 - Removing existing pages from the structure
 - Changing a page's sync recommendation from hand-written to synced (or vice versa)
@@ -145,7 +145,7 @@ git checkout main
 - Link to internal pages that don't exist — every `[text](path.md)` must resolve to an actual file. Run `ls <target>` before linking. Links to `.mdx` pages use `.md` extension (Astro resolves both).
 - Link externally when an internal page exists — check `docs/` before using an external URL
 - Offer, suggest, or perform PR reviews unless a human explicitly asks
-- Write em-dashes (`—`) or use `--` as an em-dash substitute in prose. These are banned in all content: body text, bullet descriptions, "Further reading" links, and inline comments. Use a colon, semicolon, period, comma, or parentheses instead. (`--` is only acceptable inside fenced code blocks as a code comment or CLI flag.)
+- Write em-dashes (`—`) or use `--` as an em-dash substitute in prose. These are banned in all content: body text, bullet descriptions, link label text (including "Next steps", "Further reading", and "See also" sections), and inline comments. Use a colon, semicolon, period, comma, or parentheses instead. (`--` is only acceptable inside fenced code blocks as a code comment or CLI flag.)
 - Rename Candid field names, management canister API identifiers, or example/repository names to satisfy jargon rules — these are protocol-level identifiers that must match the actual interface (e.g. `dapps`, `RegisterDappCanisters`, `encrypted-notes-dapp-vetkd`)
 - Remove domain-specific technical terms that are standard vocabulary in their context: "DeFi" and "smart contract" in DeFi/token guides, "DAO" and "decentralized autonomous organization" in governance guides, "smart contracts on other chains" in chain fusion guides. These terms must stay because the target audience uses them and alternatives would be less precise.
 
@@ -182,7 +182,7 @@ docs/                       # All documentation (.md only) — src/content/docs/
 │   └── tools/              # Developer tools
 ├── concepts/               # Explanations
 ├── languages/              # Language-specific (Motoko synced, Rust hand-written)
-└── reference/              # Specifications and reference
+└── references/             # Specifications and reference
 ```
 
 ## Source material repos (`.sources/`)
@@ -290,41 +290,75 @@ EOF
 | `candid` | Check for spec changes affecting the Candid reference or type-mapping examples |
 | `response-verification` | Check for API changes affecting certified variables patterns |
 | `dotskills` | Check if the `technical-documentation` skill changed in ways that affect review criteria |
-| `internetidentity` | Check for spec changes in `docs/ii-spec.mdx`; re-sync `internet-identity-spec.md`. Re-copy Candid interface from `src/internet_identity/internet_identity.did` if changed |
+| `internetidentity` | Check for spec changes in `docs/ii-spec.mdx`; re-sync `internet-identity-spec.md` (see link adaptation note below). Re-copy Candid interface from `src/internet_identity/internet_identity.did` if changed |
 | `chain-fusion-signer` | Check for changed canister IDs, API methods, or key derivation patterns |
 | `papi` | Check for changed payment interface or cycle cost model |
 | `ic-pub-key` | Check for changed CLI flags or commands |
 
+**Link adaptation for `internet-identity-spec.md`:** The upstream source (`docs/ii-spec.mdx`) uses absolute `internetcomputer.org` URLs pointing to the IC interface spec. Our file uses relative paths into the split `ic-interface-spec/` directory. After every re-sync, run:
+```bash
+grep -n "ic-interface-spec" docs/references/internet-identity-spec.md
+```
+Any link of the form `internetcomputer.org/.../ic-interface-spec#<anchor>` or `./ic-interface-spec.md#<anchor>` must be converted. Use the anchor-to-file mapping at the bottom of `docs/references/internet-identity-spec.md` as the authoritative guide. If a new anchor appears that is not in the comment, find its file with:
+```bash
+grep -r "{#<anchor>}" docs/references/ic-interface-spec/
+```
+
 ### Synced files from submodules
 
 | Local file | Source | Affects |
 |-----------|--------|---------|
-| `public/reference/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/reference/management-canister.md` |
-| `docs/reference/ic-interface-spec.md` | `.sources/portal/docs/references/ic-interface-spec.md` | Full IC interface spec — apply portal diff as a patch on every bump |
-| `docs/reference/http-gateway-spec.md` | `.sources/portal/docs/references/http-gateway-protocol-spec.md` | HTTP Gateway spec — apply portal diff as a patch on every bump |
+| `public/reference/ic.did` | `.sources/portal/docs/references/_attachments/ic.did` | Management canister reference — new/changed methods require updating `docs/references/management-canister.md` |
+| `docs/references/ic-interface-spec/` | `.sources/portal/docs/references/ic-interface-spec.md` | IC interface spec split into 7 focused pages — apply portal diffs by section (see checklist below) |
+| `docs/references/http-gateway-spec.md` | `.sources/portal/docs/references/http-gateway-protocol-spec.md` | HTTP Gateway spec — apply portal diff as a patch on every bump |
 
 **Portal bump checklist (run on every portal bump):**
 
 **Step 1 — `ic.did`:**
 1. `diff public/reference/ic.did .sources/portal/docs/references/_attachments/ic.did`
 2. If changed: `cp .sources/portal/docs/references/_attachments/ic.did public/reference/ic.did`
 3. Review diff for new/changed/removed methods
-4. Update `docs/reference/management-canister.md` and any affected guides
+4. Update `docs/references/management-canister.md` and any affected guides
 
-**Step 2 — `ic-interface-spec.md`:** For every commit in the bump range that touched `docs/references/ic-interface-spec.md`:
-1. `git -C .sources/portal show <commit> -- docs/references/ic-interface-spec.md > /tmp/patch.diff`
-2. `patch -F 5 -p1 --input=/tmp/patch.diff docs/reference/ic-interface-spec.md`
-3. Resolve any rejects manually (our file has intentional diffs: Astro frontmatter, internal link fixes)
-4. Verify new methods/fields are reflected in `docs/reference/management-canister.md` if they touch the management canister
+**Step 2 — `ic-interface-spec/`:** The spec is now split into 7 files under `docs/references/ic-interface-spec/`. Each file maps to a section of the portal source:
+
+| File | Portal section (## heading) |
+|---|---|
+| `index.md` | Introduction, Pervasive concepts, The system state tree |
+| `https-interface.md` | HTTPS Interface |
+| `canister-interface.md` | Canister module format, Canister interface (System API) |
+| `management-canister.md` | The IC management canister, The IC Bitcoin API, The IC Provisional API |
+| `certification.md` | Certification, The HTTP Gateway protocol |
+| `abstract-behavior.md` | Abstract behavior |
+| `changelog.md` | `.sources/portal/docs/references/_attachments/interface-spec-changelog.md` (NOT `ic-interface-spec.md`) |
+
+For every commit in the bump range that touched `docs/references/ic-interface-spec.md`:
+1. `git -C .sources/portal show <commit> -- docs/references/ic-interface-spec.md > /tmp/spec.diff`
+2. Inspect the diff: identify which section(s) changed
+3. Apply the relevant hunks manually to the corresponding file(s) in `docs/references/ic-interface-spec/`
+4. Update any cross-file anchor links (`(./other.md#anchor)`) if headings were added or removed
+5. Verify new methods/fields are reflected in `docs/references/management-canister.md` if they touch the management canister
+
+For every commit in the bump range that touched `docs/references/_attachments/interface-spec-changelog.md`:
+1. `git -C .sources/portal show <commit> -- docs/references/_attachments/interface-spec-changelog.md > /tmp/changelog.diff`
+2. Apply the new version entries to `docs/references/ic-interface-spec/changelog.md`
 
 **Step 3 — `http-gateway-spec.md`:** For every commit in the bump range that touched `docs/references/http-gateway-protocol-spec.md`:
 1. `git -C .sources/portal show <commit> -- docs/references/http-gateway-protocol-spec.md > /tmp/patch.diff`
-2. `patch -F 5 -p1 --input=/tmp/patch.diff docs/reference/http-gateway-spec.md`
-3. Resolve any rejects manually
+2. `patch -F 5 -p1 --input=/tmp/patch.diff docs/references/http-gateway-spec.md`
+3. Resolve any rejects manually (see note below on link adaptation)
+4. Run `grep -n "ic-interface-spec" docs/references/http-gateway-spec.md` and convert any newly introduced links
+
+**Link adaptation for `http-gateway-spec.md`:** The portal source uses absolute `/references/ic-interface-spec#anchor` URLs. Our file uses relative paths into the split `ic-interface-spec/` directory. After every sync, any link of the form `/references/ic-interface-spec#<anchor>` or `./ic-interface-spec.md#<anchor>` must be converted. Use the anchor-to-file mapping at the bottom of `docs/references/http-gateway-spec.md` as the authoritative guide. If a new anchor appears that is not in the comment, find its file with:
+```bash
+grep -r "{#<anchor>}" docs/references/ic-interface-spec/
+```
 
 **Finding which commits touched which files:**
 ```bash
 git -C .sources/portal log --oneline <old-ref>..<new-ref> -- docs/references/ic-interface-spec.md
+git -C .sources/portal show <commit> -- docs/references/ic-interface-spec.md | grep "^[+-]## " | head -20  # identify which sections changed
+git -C .sources/portal log --oneline <old-ref>..<new-ref> -- docs/references/_attachments/interface-spec-changelog.md
 git -C .sources/portal log --oneline <old-ref>..<new-ref> -- docs/references/http-gateway-protocol-spec.md
 git -C .sources/portal log --oneline <old-ref>..<new-ref> -- docs/references/_attachments/ic.did
 ```