[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.

[kriszyp]

Heads-up: the v5 reference and the 5.4 release notes now live in the code repos (documentation#788, harper#3944, harper-pro#1237). reference/ and release-notes/v5-lincoln/5.4.md no longer exist on main here, so this PR's changes to them need to move. Thanks for your patience with the shuffle!

• Reference pages go to docs/reference/ at the same relative path, in HarperFast/harper (in HarperFast/harper-pro for replication/, web-application-firewall/, and the Pro sections of core pages, which are _pro-*.md partials there).
• 5.4 release notes become one fragment file per change in docs/release-notes/v5-lincoln/5.4/ of the repo the change ships in. The fragment format is in harper's docs/README.md.
• If the code change this documents is still in an open PR, the docs can go in that same PR now; no companion PR needed.
• Changes to other files here (learn/, fabric/, the v4 reference) stay in this repo.

— Claude Opus 5.5

[kylebernhardy]

This work now lives with its implementation in Fix scoped MCP reconnects and concurrent subscribe failures. Following main's documentation ownership change, the v5 reference edits are under Harper's docs/reference/mcp/, and the upgrade/feature notes use separate fragments under docs/release-notes/v5-lincoln/5.4/. The reviewed guidance and feedback fixes were carried over; the documentation repo assembles these sources at build time.

Closing this companion PR as superseded so it cannot reintroduce edits to generated content paths. The current site build against the migrated source passed (426 documents), and the MCP suite passed all 620 tests.

Comment generated by kAIle (GPT-6)

[github-actions]

🧹 Preview Cleanup

The preview deployment for this PR has been removed.