docs(custom-domains): name the ordering trap in the II pitfall

[yhabib]

Motivation

Pitfall 9 described the symptom — II principals depend on the origin, so a custom domain changes them — and pointed at internet-identity for the fix. It left out the part that decides whether the fix is still available: it has to happen before the domain collects sign-ins. Once accounts exist under the new domain, repointing it orphans them. That ordering is what the engine console now warns about on the add-domain form (dfinity/control-panel#3394).

Changes

• Rewrote Pitfall 9 to lead with the case that makes it expensive, an app that already has users.
• Named the canister address as the origin to pin, so the reader does not have to pick.
• Added the ordering constraint and that it cannot be undone.
• Dropped the "switching from a canister URL to a custom domain" framing — nothing is switched, the canister address stays reachable, which is why it is the right derivation origin.
• Added one eval case.

Eval 9 — Adversarial: custom domain on an app that already has II users (WITH 4/4 | WITHOUT 2/4)

━━━ Adversarial: custom domain on an app that already has II users ━━━

  WITH skill: 4/4 passed
    ✅ Warns that II principals are per-origin, so existing users would get brand-new accounts at the custom domain
    ✅ Says to pin the canister address as the derivation origin and list the custom domain in .well-known/ii-alternative-origins BEFORE the domain goes live
    ✅ Notes that a domain which has already collected sign-ins cannot be repointed without orphaning those accounts
    ✅ Does NOT present the custom domain switch as principal-neutral or a pure DNS change

  WITHOUT skill: 2/4 passed
    ✅ Warns that II principals are per-origin, so existing users would get brand-new accounts at the custom domain
    ❌ Says to pin the canister address as the derivation origin and list the custom domain in .well-known/ii-alternative-origins BEFORE the domain goes live
       → The output mentions setting up ii-alternative-origins before switching but never mentions configuring derivationOrigin in the app's login call to pin the canister address, which is the other required half of the mechanism.
    ❌ Notes that a domain which has already collected sign-ins cannot be repointed without orphaning those accounts
       → The output only advises keeping the old canister URL live alongside the new domain; it never states the general principle that a domain with existing sign-ins can't be repointed elsewhere without orphaning those accounts.
    ✅ Does NOT present the custom domain switch as principal-neutral or a pure DNS change

The baseline knows principals are per-origin but gives half the fix — ii-alternative-origins without derivationOrigin — which on its own does nothing.

---

Prev. #339

[github-actions]

Skill Validation Report

Validating skill: /home/runner/work/icskills/icskills/skills/custom-domains

Structure

• Pass: SKILL.md found

Frontmatter

• Pass: name: "custom-domains" (valid)
• Pass: description: (652 chars)
• Pass: license: "Apache-2.0"
• Pass: compatibility: (45 chars)
• Pass: metadata: (2 entries)

Markdown

• Pass: no unclosed code fences found

Tokens

File	Tokens
SKILL.md body	2,684
Total	2,684

Content Analysis

Metric	Value
Word count	1,511
Code block ratio	0.19
Imperative ratio	0.15
Information density	0.17
Instruction specificity	0.81
Sections	15
List items	23
Code blocks	13

Contamination Analysis

Metric	Value
Contamination level	low
Contamination score	0.20
Primary language category	shell
Scope breadth	4

• Warning: Language mismatch: config, javascript (2 categories differ from primary)

Result: passed

Project Checks

✓ Project checks passed for 1 skills (0 warnings)