infra: content lifecycle strategy

[marc0olo]

Context

Define how docs stay fresh as upstream sources evolve. This covers change detection, sync automation, and freshness ownership.

Current state

Automated:

• Motoko pages: sync-motoko.yml — weekly, detects new caffeinelabs/motoko releases and opens a PR with synced content already committed
• Motoko + Candid grammars (Shiki): update-syntax-grammars.yml — weekly, tracks dfinity/vscode-motoko releases and opens a PR with updated TextMate grammars

Established conventions:

• Every content page carries an <!-- Upstream: hand-written | sync from | informed by --> comment (decision: 2026-03-12)
• Every submodule bump PR must follow the checklist in CLAUDE.md (per-submodule diff review, affected page updates, bump notice comments on open PRs)
• .sources/VERSIONS tracks current pinned versions for release-pinned submodules

Not yet in place:

• No automated change detection for the remaining 13+ submodules (icp-cli, cdk-rs, motoko-core, icskills, examples, icp-js-sdk-docs, candid, response-verification, chain-fusion-signer, papi, ic-pub-key, internetidentity, icp-cli-recipes, icp-cli-templates)
• No CODEOWNERS file — no defined ownership per section
• No documented review cadence or staleness policy

Remaining questions

1. Submodule change detection: Build a workflow similar to sync-motoko.yml for release-pinned submodules — check latest tag against .sources/VERSIONS, open a bump PR or issue when behind. Main/master-pinned submodules are harder (no release signal); a weekly diff summary issue may be more practical.
2. CODEOWNERS: Define section-level ownership (e.g. chain-fusion guides → chain-fusion team, Rust CDK pages → SDK team).
3. Review cadence: Document a spot-check schedule for hand-written pages that are informed by upstream sources.

Output

• Automated bump detection workflow(s) for release-pinned submodules
• CODEOWNERS file
• Staleness / review cadence documented in .docs-plan/decisions.md or CONTRIBUTING.md