[kylebernhardy]

📝 Summary

Document when MCP resource subscriptions expire and how clients renew them. Companion to Make MCP resource subscriptions reliable across HTTP workers, targeting core v5.4.

Merge dependency: keep this PR in draft until Fix scoped MCP reconnects and concurrent subscribe failures merges. Before marking ready, verify the fix is included in the actual release cut; retarget the version guidance if v5.4.0 ships without it. Its scoped-isolation guarantee is not in the already merged implementation.

🔧 Changes

• Subscription guide — distinguish the retained POST expiry from the current GET expiry, explain credential rotation on both requests, align restore/retry behavior, and require a matching scoped GET when restoring scoped grants.
• Resource contracts and overview — align error/lifetime guidance and distinguish persisted subscription state from worker-local replay history.
• v5.4 release notes — explain the upgrade behavior, scoped reconnect isolation, and the renewal procedure; cite both core PRs.

Overlaps Assemble the v5 reference and open release notes from harper and harper-pro; preserve this guidance if the reference assembly lands second.

✅ Verification

• Full formatting write/check and production build passed; 426 documents processed.
• Contract checked against core source and the passing distinct-worker HTTP expiry/reconnect scenario.
• Author source checks and independent Claude/Composer reviews checked the subscription contracts, retry instructions, and release wording.

🤔 Merge order

The reference describes the upcoming v5.4 behavior. Stable v5.4.0 is not tagged yet; the scoped restoration paragraph must ship with its dependent core fix.

🤔 Final review scope

Four full passes covered the four-page change. Closing checks were limited to the resulting wording fixes: cleanup advice, shared lifecycle placement, and migration responses. A further full pass would repeat the same contract review; the final change adds no API behavior.

Comment generated by kAIle (GPT-6)

Release target: main — documentation for core v5.4
Related PRs: #788 overlaps (reference assembly moves the same MCP pages)
Complexity: easy

Deferred findings

• 6a9846ae60efef4b none documentation — reference/mcp/subscriptions.md — Open PR 788 overlaps the subscription documentation — filed MCP subscription state: recovery, auditing, and teardown follow-ups harper#4008
• 414561ca18bdca0a none documentation — release-notes/v5-lincoln/5.4.md — v5.4 scoped-isolation claim depends on companion core PR 4029 — filed MCP subscription state: recovery, auditing, and teardown follow-ups harper#4008

_{Review-Coverage: authored=codex; ran=cursor-composer,claude; adjudicated=domain; declined=gemini,cursor-grok,muse; rounds=10; full=4 @ a73e21b}

_{Review-Attention: skim ~2m (decisions: earlier-credential-expiry, blocking-reconnect-restoration, scoped-restoration-isolation) @ a73e21b}

[gemini-code-assist]

Code Review

This pull request updates the MCP documentation and release notes to clarify how resource subscriptions behave across multiple HTTP workers, specifically detailing credential expiry preservation, reconnect restoration, and credential rotation. The review feedback suggests improving readability by splitting several long sentences containing semicolons into separate, distinct sentences to clearly isolate critical limitations and instructions.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[kriszyp]

_{🤖 Reviewed with Muse}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-798

This preview will update automatically when you push new commits.