chore: remove stale Upstream comments from content pages

[marc0olo]

Background

<!-- Upstream: --> comments were introduced during the portal migration to track which upstream repo each page was derived from. Now that the migration is complete and the validator check has been removed (PR #255), these comments are no longer enforced and many are stale.

What needs to be done

Remove <!-- Upstream: --> comments from all content pages where they are noise rather than signal. Specifically:

• Remove entirely: any comment containing only hand-written, only dfinity/portal, or Learn Hub references — these are stale or zero-information
• Edit to strip portal parts: comments that reference both dfinity/portal and an active submodule — keep the active submodule reference, remove the portal part
• Keep as-is: comments referencing only active submodules with a specific file path (e.g. informed by dfinity/internet-identity — docs/vc-spec.md) — these still provide useful traceability

Scope

108 content files have <!-- Upstream: --> comments (excluding synced Motoko docs):

• 73 reference dfinity/portal (stale — remove or edit)
• 1 is hand-written only (remove)
• remainder reference active submodules (keep or edit)

How to find them

# All files with Upstream comments (excluding synced motoko)
grep -rl "<!--\s*Upstream:" docs/ --include="*.md" --include="*.mdx" | grep -v "languages/motoko"

# Portal references specifically
grep -rl "dfinity/portal" docs/ --include="*.md" --include="*.mdx"

# hand-written only
grep -rl "<!--\s*Upstream:\s*hand-written" docs/ --include="*.md" --include="*.mdx"

Notes

• The validator (scripts/validate.js) no longer checks for these comments — no CI impact
• Branch: infra/remove-upstream-comments
• Run npm run build before pushing

---

Update 2026-08-26: two things this issue is missing

1. AGENTS.md still mandates the comment

Line 25:

For pages that closely track a specific upstream file, add at the bottom: <!-- Upstream: informed by <repo> <path> -->. Skip for pages that draw from multiple sources or are fully original.

Deleting 108 comments while that rule stands means the next content PR adds a 109th. The AGENTS.md rule has to change in the same PR, otherwise this is a cleanup that undoes itself.

2. The "keep as-is" bucket depends on #355

Measured breakdown of the 108 comment lines:

Bucket	Count
Mentions dfinity/portal	73
Mentions Learn Hub	27
Mentions portal or Learn Hub (both retired)	96
Mentions only active sources (the "keep" bucket)	15
hand-written only	1
Mentions portal and an active source (the "edit" bucket)	37

So the keep bucket is 15 comments, not "the remainder" of 34. Repos referenced across those 15:

dfinity/icskills (4), dfinity/examples (4), dfinity/icp-cli (3), dfinity/internet-identity (2), dfinity/icp-js-sdk-docs (2), dfinity/ic-pub-key (2), dfinity/cdk-rs (2), dfinity/papi (1), dfinity/icp-cli-templates (1), dfinity/icp-cli-recipes (1), dfinity/chain-fusion-signer (1)

The keep criterion is "references an active submodule with a specific file path". #355 proposes reducing .sources/ to five submodules, which means 8 of the 11 repos above stop being submodules (icp-cli, icp-js-sdk-docs, ic-pub-key, cdk-rs, papi, icp-cli-templates, icp-cli-recipes, chain-fusion-signer). Only icskills, examples, and internet-identity survive. Executing this issue against today's criterion would therefore preserve comments that the very next change invalidates.

Suggested sequence

#355 first, then this issue.

#355 has to answer "when an upstream release lands, which pages does it affect?", because that is the whole point of replacing submodules with release watches. That is the same question these comments were half-answering. Settling it there produces the criterion this issue needs, and turns this into a single mechanical pass instead of two:

• if infra: reduce .sources/ submodules to what the site actually needs, watch releases for the rest #355 concludes the mapping lives in sync-generated frontmatter (source_repo / source_ref) or a central manifest, then all 108 comments go, and this issue is one clean sweep;
• if infra: reduce .sources/ submodules to what the site actually needs, watch releases for the rest #355 concludes we keep per-page provenance for hand-written pages, then this issue converts the 15 keepers into that form and deletes the other 93.

Either way it is one pass over ~108 files rather than two, and the AGENTS.md rule is rewritten once with the answer known.

Related

• infra: reduce .sources/ submodules to what the site actually needs, watch releases for the rest #355 (.sources/ strategy, and the AGENTS.md changes it forces)
• infra: clear outstanding validate --all violations at their source #356 (validate --all fails on main; what synced trees are exempt from)