docs: sync reference specs 1:1 from portal and internet-identity

.docs-plan/decisions.md

@@ -218,6 +218,13 @@ Record decisions that constrain future work — things an agent needs to know th
 **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.

.gitmodules

@@ -52,3 +52,6 @@
 [submodule ".sources/ic-pub-key"]
 	path = .sources/ic-pub-key
 	url = git@github.com:dfinity/ic-pub-key.git
+[submodule ".sources/internetidentity"]
+	path = .sources/internetidentity
+	url = https://github.com/dfinity/internet-identity.git

AGENTS.md

@@ -210,6 +210,7 @@ For current release hashes, see `.sources/VERSIONS`.
 | `.sources/papi` | `dfinity/papi` | latest release | PAPI (payment API) — cycle payment interface used by the Chain Fusion Signer |
 | `.sources/ic-pub-key` | `dfinity/ic-pub-key` | latest release | `@dfinity/ic-pub-key` CLI tool for deriving public keys via the Chain Fusion Signer |
 | `.sources/dotskills` | `vincentkoc/dotskills` | `main` | Technical documentation skill (AGPL-3.0 — kept as submodule to avoid license mixing) |
+| `.sources/internetidentity` | `dfinity/internet-identity` | `main` | Internet Identity spec (`docs/ii-spec.mdx`), Candid interface (`src/internet_identity/internet_identity.did`) |
 
 ### Submodule initialization
 
@@ -284,6 +285,7 @@ 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 |
 | `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 |

astro.config.mjs

@@ -5,6 +5,7 @@ import rehypeRewriteLinks from "./plugins/rehype-rewrite-links.mjs";
 import rehypeExternalLinks from "./plugins/rehype-external-links.mjs";
 import remarkIcpCliVersion from "./plugins/remark-icp-cli-version.mjs";
 import remarkSnippet from "./plugins/remark-snippet.mjs";
+import remarkHeadingId from "./plugins/remark-heading-id.mjs";
 import agentDocs from "./plugins/astro-agent-docs.mjs";
 import { sidebar } from "./sidebar.mjs";
 
@@ -15,7 +16,7 @@ export default defineConfig({
     // Rehype plugins work with Starlight (remark plugins don't — Starlight overrides them).
     // See: https://github.com/dfinity/icp-cli/issues/423
     rehypePlugins: [rehypeRewriteLinks, rehypeExternalLinks],
-    remarkPlugins: [remarkSnippet, remarkIcpCliVersion],
+    remarkPlugins: [remarkHeadingId, remarkSnippet, remarkIcpCliVersion],
   },
   integrations: [
     starlight({

docs/reference/application-canisters.md

@@ -2,7 +2,7 @@
 title: "Application Canisters"
 description: "Reference for the asset canister, SNS canisters, LLM canister, and other application-layer canisters with their interfaces and canister IDs"
 sidebar:
-  order: 4
+  order: 8
 ---
 
 Application canisters are well-known canisters at the application layer of the Internet Computer that developers commonly integrate into their projects. Unlike [system canisters](system-canisters.md) (which govern the network) or [protocol canisters](protocol-canisters.md) (which provide platform infrastructure), application canisters implement higher-level functionality: hosting web frontends, governing dapps via DAO, and running AI inference.