PRD: Clean selection-context branch drift and restore release-ready documentation

[jazelly]

Problem Statement

The selection-context branch contains work that is broader than the latest session initiatives. The core implementation and playground e2e work align with the goals, but branch-wide drift introduced documentation regressions, trailing whitespace, a large playground asset, a playground port change, and dependency-version movement. These changes may be valid, but they need to be intentionally accepted, revised, or split before landing so the release story remains clear.

Solution

Run a branch hygiene pass that separates intentional feature-supporting changes from accidental drift. Restore accurate documentation for the MCP architecture and React DevTools hook behavior, fix formatting failures, and document decisions around playground assets, port usage, dependency ranges, and lockfile policy. The result should be a branch that is easy to review, release, and maintain.

User Stories

1. As a maintainer, I want the README to describe the runtime architecture accurately, so that users understand how MCP calls reach the browser.
2. As a user evaluating the package, I want documentation to name the correct React DevTools hook, so that I can trust the technical explanation.
3. As a reviewer, I want git diff --check to pass, so that formatting noise does not block landing.
4. As a reviewer, I want branch-scope drift to be explicitly classified, so that I can tell which changes are required for selection capture.
5. As a maintainer, I want playground visual assets to be intentional, so that large files do not enter the repo accidentally.
6. As a developer running the playground, I want port changes to be documented, so that local workflows remain predictable.
7. As a package maintainer, I want dependency-version changes to be intentional, so that runtime behavior does not drift unexpectedly.
8. As a contributor, I want dependency locking policy to be clear, so that e2e dependencies are reproducible in the expected way.
9. As a release manager, I want docs and implementation to describe the same tool contracts, so that support burden stays low.
10. As an MCP client user, I want README examples to reflect actual tool names and behavior, so that setup is straightforward.
11. As a future contributor, I want custom tool examples to remain relevant but not distract from selection-context work, so that examples stay maintainable.
12. As a reviewer, I want branch cleanup to avoid changing runtime behavior unless required, so that the diff stays low risk.
13. As a maintainer, I want validation commands to be listed and passing, so that the branch can be landed confidently.
14. As a user of the playground, I want the toolkit logo and UI configuration to be clearly part of the demo, so that demo-only choices are not mistaken for library defaults.
15. As a project owner, I want the final branch narrative to match the phased commits, so that later archaeology explains why each change exists.

Implementation Decisions

• Restore or rewrite the architecture section to be accurate and concise rather than replacing it with an imprecise summary.
• Correct the React DevTools hook terminology.
• Remove trailing whitespace and ensure diff-check passes.
• Decide whether the large playground asset is necessary for this branch or should be deferred.
• Decide whether the playground port change is part of the e2e test contract or should be isolated to test configuration.
• Document why the bippy dependency range changed and whether the range should be pinned or flexible.
• Clarify repository lockfile policy for workspace and playground dependencies.
• Keep this cleanup focused on release readiness and documentation accuracy rather than adding new selection features.

Testing Decisions

• Good tests for this PRD are mostly validation checks and documentation review, not implementation-level tests.
• Run diff-check to catch whitespace and patch formatting issues.
• Run the package build to prove documentation and config cleanup did not break TypeScript compilation.
• Run the playground e2e suite to prove demo and port decisions still support the selection workflow.
• Use manual README review to verify hook names, MCP endpoints, HMR flow, browser runtime names, and custom tool behavior are accurate.
• If dependency policy changes, verify install behavior according to the chosen policy.

Out of Scope

• Rewriting all project documentation.
• Changing the public MCP API.
• Adding new selection-context capabilities.
• Performing a full release automation redesign.
• Resolving every historical documentation issue unrelated to selection capture.

Further Notes

This PRD captures the review drift. It should be treated as a release-readiness pass after the hardening and test PRDs, unless the team decides to split unrelated branch-wide changes before landing.