infra(domain): switch production domain to docs.internetcomputer.org (#161)

## Summary

- Replace all `beta-docs.internetcomputer.org` references with
`docs.internetcomputer.org`
- `astro.config.mjs`: site URL, og/twitter image URLs, schema.org
WebSite and Organization IDs (8 refs)
- `public/.well-known/ic-domains`: IC boundary node custom domain
authorization
- `public/robots.txt`: sitemap URL + LLM discovery comments
- `public/og-image.svg`: footer text (baked into `og-image.png` at build
time)
- `README.md`: deployment URL; Background section rewritten to say the
portal has been replaced
- `AGENTS.md`: "Never" rule updated (`internetcomputer.org/docs` is
retired; `docs.internetcomputer.org` is now this site, use relative
paths); Portal tracking section updated
- `scripts/validate.js`: error messages updated to match the new reality
- `.docs-plan/decisions.md`: decision entry added for the cutover

## Notes

`docs/languages/motoko/` still contains ~30 links to
`internetcomputer.org/docs/...` but those are auto-synced from
`caffeinelabs/motoko` and need to be fixed upstream — tracked
separately.

## Sync recommendation

hand-written

Author: marc0olo

.docs-plan/decisions.md

@@ -275,3 +275,10 @@ Record decisions that constrain future work — things an agent needs to know th
 **Rationale:** Dynamic SVG generation in the build plugin adds ~30 lines of complexity for a one-time change. Static is simpler and good enough.
 **Alternatives considered:** Generate SVG dynamically in `plugins/astro-agent-docs.mjs` using `siteUrl` from Astro config (more robust, but over-engineered for a single domain change)
 
+
+## 2026-04-28: Production domain cutover to docs.internetcomputer.org
+
+**Context:** The site was previously served from `beta-docs.internetcomputer.org` as a staging domain during the transition from `dfinity/portal`. The portal has now been retired and this site is the canonical ICP developer docs.
+**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)

AGENTS.md

@@ -141,7 +141,7 @@ git checkout main
 - Write code snippets from memory — find and adapt from actual upstream code in `.sources/`
 - Modify the rationale or context of existing decisions in `.docs-plan/decisions.md` — you may remove entries that are fully reflected in the current codebase but never alter reasoning behind active decisions
 - Add `Co-Authored-By` or any AI attribution to commits or PR descriptions
-- Link to `internetcomputer.org/docs/` or `docs.internetcomputer.org` — those URLs will break. Link to pages in this site (relative paths), Learn Hub, or explain inline.
+- Link to `internetcomputer.org/docs/` — that site is retired. For internal pages use relative paths, not absolute `docs.internetcomputer.org/...` URLs. Link to Learn Hub or explain inline for external content.
 - 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
@@ -369,10 +369,7 @@ sidebar:
 
 ## Portal tracking
 
-The old portal (`dfinity/portal`) is still live during the transition period.
-- **Ignore:** dfx-only changes, JSX/component changes, release notes, NNS dapp guides
-- **Flag for rewrite:** Content updates to topics we cover
-- **Evaluate:** New content — does it belong in the new docs?
+The old portal (`dfinity/portal`) has been replaced by this site. The `.sources/portal` submodule is kept as a read-only reference for spec content (see `ic.did` sync checklist above) but no longer needs active monitoring for content changes.
 
 ## Commands
 

README.md

@@ -1,16 +1,14 @@
 # ICP Developer Docs
 
-Developer documentation for the [Internet Computer](https://internetcomputer.org) — built with [Astro](https://astro.build) + [Starlight](https://starlight.astro.build), deployed at [beta-docs.internetcomputer.org](https://beta-docs.internetcomputer.org).
+Developer documentation for the [Internet Computer](https://internetcomputer.org) — built with [Astro](https://astro.build) + [Starlight](https://starlight.astro.build), deployed at [docs.internetcomputer.org](https://docs.internetcomputer.org).
 
 ## Background
 
-The existing ICP docs live at [internetcomputer.org/docs](https://internetcomputer.org/docs), sourced from [dfinity/portal](https://github.com/dfinity/portal) (Docusaurus). That site accumulated content over years without a consistent information architecture, making it hard to navigate and harder to keep accurate.
-
-This repo is a ground-up rewrite: a flat Diataxis structure (Getting Started, Guides, Concepts, Languages, Reference), content verified against pinned upstream repos, and a workflow built for both human contributors and AI coding agents from day one.
+This repo is a ground-up rewrite of the ICP developer docs: a flat Diataxis structure (Getting Started, Guides, Concepts, Languages, Reference), content verified against pinned upstream repos, and a workflow built for both human contributors and AI coding agents from day one. It replaces the previous [dfinity/portal](https://github.com/dfinity/portal) (Docusaurus) site.
 
 ## Current state
 
-Most pages are content-complete. A small number of pages remain as stubs (vetkeys, encryption). The existing production docs remain live during the transition.
+Most pages are content-complete. A small number of pages remain as stubs (vetkeys, encryption).
 
 ## Content areas
 

astro.config.mjs

@@ -13,7 +13,7 @@ import { TITLE, DESCRIPTION, PUBLISHER, OG_ALT } from "./src/branding.mjs";
 
 // https://astro.build/config
 export default defineConfig({
-  site: "https://beta-docs.internetcomputer.org",
+  site: "https://docs.internetcomputer.org",
   markdown: {
     // Rehype plugins work with Starlight (remark plugins don't — Starlight overrides them).
     // See: https://github.com/dfinity/icp-cli/issues/423
@@ -61,15 +61,15 @@ export default defineConfig({
         },
         {
           tag: "meta",
-          attrs: { property: "og:image", content: "https://beta-docs.internetcomputer.org/og-image.png" },
+          attrs: { property: "og:image", content: "https://docs.internetcomputer.org/og-image.png" },
         },
         {
           tag: "meta",
           attrs: { property: "og:image:alt", content: OG_ALT },
         },
         {
           tag: "meta",
-          attrs: { name: "twitter:image", content: "https://beta-docs.internetcomputer.org/og-image.png" },
+          attrs: { name: "twitter:image", content: "https://docs.internetcomputer.org/og-image.png" },
         },
         {
           tag: "script",
@@ -79,15 +79,15 @@ export default defineConfig({
             "@graph": [
               {
                 "@type": "WebSite",
-                "@id": "https://beta-docs.internetcomputer.org/#website",
+                "@id": "https://docs.internetcomputer.org/#website",
                 "name": TITLE,
                 "description": DESCRIPTION,
-                "url": "https://beta-docs.internetcomputer.org",
-                "publisher": { "@id": "https://beta-docs.internetcomputer.org/#organization" },
+                "url": "https://docs.internetcomputer.org",
+                "publisher": { "@id": "https://docs.internetcomputer.org/#organization" },
               },
               {
                 "@type": "Organization",
-                "@id": "https://beta-docs.internetcomputer.org/#organization",
+                "@id": "https://docs.internetcomputer.org/#organization",
                 "name": PUBLISHER,
                 "url": "https://dfinity.org",
               },

public/.well-known/ic-domains

@@ -1 +1,2 @@
+docs.internetcomputer.org
 beta-docs.internetcomputer.org

public/og-image.svg

@@ -1,8 +1,8 @@
 User-agent: *
 Allow: /
 
-Sitemap: https://beta-docs.internetcomputer.org/sitemap-index.xml
+Sitemap: https://docs.internetcomputer.org/sitemap-index.xml
 
 # LLM and AI agent discovery (llmstxt.org)
-# https://beta-docs.internetcomputer.org/llms.txt
-# https://beta-docs.internetcomputer.org/llms-full.txt
+# https://docs.internetcomputer.org/llms.txt
+# https://docs.internetcomputer.org/llms-full.txt

public/robots.txt

@@ -44,8 +44,8 @@ function checkFrontmatter(file, content) {
 
 const FORBIDDEN = [
   { re: /mo:base/, msg: '"mo:base" is banned — use "mo:core" instead' },
-  { re: /internetcomputer\.org\/docs/, msg: 'internetcomputer.org/docs URLs will break — link internally or inline' },
-  { re: /docs\.internetcomputer\.org/, msg: 'docs.internetcomputer.org URLs will break — link internally or inline' },
+  { re: /internetcomputer\.org\/docs/, msg: 'internetcomputer.org/docs is retired — link internally or inline' },
+  { re: /docs\.internetcomputer\.org/, msg: 'docs.internetcomputer.org is this site — use relative paths for internal links' },
 ];
 
 function checkEmdash(file, content) {