---
phase: 01-installer-and-setup-architecture-simplification
plan: 01
subsystem: cli-setup-contract
tags: [python, cli, setup, runtime, installer-contract]
requires: []
provides:
  - Canonical `reddit-mcp setup` orchestration surface
  - Canonical `reddit-mcp serve` user-facing runtime contract
  - Removal of launcher/bootstrap/python3/uvx guidance from release-readiness surfaces
affects: [reddit-mcp, auth_gateway_for_mcp, shared-client-python]
tech-stack:
  added: []
  patterns: [explicit-setup-phases, canonical-runtime-guidance, legacy-surface-retirement]
key-files:
  created: []
  modified:
    - reddit-mcp/src/reddit_mcp/cli.py
    - reddit-mcp/src/reddit_mcp/server.py
    - reddit-mcp/src/reddit_mcp/config.py
    - reddit-mcp/src/reddit_mcp/uninstall.py
    - reddit-mcp/tests/test_release_readiness.py
key-decisions:
  - "`reddit-mcp setup` now names and owns install/auth/cookies/register/verify phases at the CLI surface."
  - "User-facing runtime and recovery guidance now points to `reddit-mcp serve` instead of `uvx`, `python3`, or launcher snippets."
  - "Launcher paths are no longer exported from config state even though registration still uses a temporary compatibility bridge internally until Plan 02."
patterns-established:
  - "Release-readiness tests gate user-visible contract text, not just internal call wiring."
  - "Legacy runtime compatibility can remain behind a private bridge while the public contract is simplified first."
requirements-completed: [INST-02, INST-03, SETUP-01, SETUP-02, SETUP-03]
duration: 35min
completed: 2026-04-14
---

# Phase 1: Installer And Setup Architecture Simplification - Plan 01 Summary

**reddit-mcp now exposes a single setup/runtime contract at the CLI and MCP guidance layer, instead of advertising launcher, `python3`, `uvx`, or `bootstrap` as supported user paths.**

## Performance

- **Duration:** 35 min
- **Tasks:** 2
- **Files modified:** 5

## Accomplishments

- Refactored the CLI surface so `setup` is described and reported as explicit `install/auth/cookies/register/verify` phases.
- Removed `bootstrap` from the supported help surface and switched quick-start/manual config guidance to `reddit-mcp serve`.
- Updated MCP setup-required guidance to stop telling clients to use `uvx`.
- Removed launcher path exports from config and replaced uninstall recovery text with uv-based guidance.
- Rewrote release-readiness tests to enforce the new contract.

## Task Commits

Execution for this plan was completed in one local pass and verified before summary creation. The branch commit after this summary captures the delivered state.

## Files Created/Modified

- `reddit-mcp/src/reddit_mcp/cli.py` - Setup phase orchestration surface, canonical help text, and uv-based recovery text.
- `reddit-mcp/src/reddit_mcp/server.py` - Canonical MCP guidance for auth/cookie setup.
- `reddit-mcp/src/reddit_mcp/config.py` - Removed exported launcher path constants from config state.
- `reddit-mcp/src/reddit_mcp/uninstall.py` - Switched uninstall guidance from pip to uv.
- `reddit-mcp/tests/test_release_readiness.py` - Regression coverage for the new CLI/server contract.

## Decisions Made

- Kept the legacy launcher bridge private for now so Plan 02 can refactor shared registration without breaking this wave.
- Treated release-readiness as a user-contract test suite instead of a shared-registration implementation snapshot.

## Deviations from Plan

- The internal registration bridge still uses `write_uvx_launcher` and the old shared registration API for compatibility. That was intentional and deferred to Plan 02 rather than mixed into this wave.

## Issues Encountered

- The first pytest run was loading the installed package from the main workspace instead of the worktree. Reinstalling the worktree with `py -3 -m pip install -e .` corrected the module source and the contract tests then validated the real local changes.

## User Setup Required

None for this wave. External registration behavior still changes in Plan 02.

## Next Phase Readiness

- Plan 02 can now change shared-client registration against a stable public CLI/runtime contract.
- Installer template changes in Plan 03 can target `reddit-mcp setup` without guessing the intended user-facing semantics.

---
*Phase: 01-installer-and-setup-architecture-simplification*
*Completed: 2026-04-14*
