# Phase 1: installer-and-setup-architecture-simplification - Context

**Gathered:** 2026-04-14
**Status:** Ready for planning

<domain>
## Phase Boundary

Replace the current multi-entrypoint installer/setup stack with a single uv-based install/runtime model, a single `reddit-mcp setup` orchestrator, explicit failure semantics, and automatic AI-client registration that results in a usable `reddit-mcp serve` integration. Legacy migration work is out of scope for this phase.

</domain>

<decisions>
## Implementation Decisions

### Runtime model
- **D-01:** The only supported install path is `uv tool install 5mghost-rover`.
- **D-02:** The only supported runtime command for docs, registration, verification, and manual recovery is `reddit-mcp serve`.
- **D-03:** The product should not require users to preinstall Python; the preferred model is to let `uv` manage Python/runtime needs where possible.
- **D-04:** `pip` global scripts, `uvx` direct execution, and `launcher.py` are no longer parallel long-term runtime models.

### Setup orchestration
- **D-05:** `reddit-mcp setup` is the single orchestration entrypoint after installation.
- **D-06:** `setup` is internally split into explicit phases: `install`, `auth`, `cookies`, `register`, and `verify`.
- **D-07:** Each required phase must have its own success/failure result and non-zero exit behavior; no required failure may be swallowed.
- **D-08:** Installer scripts may automatically invoke `reddit-mcp setup` after package installation, but they must only pass through `setup` results and must not reinterpret failures or add fallback success logic.

### Installer boundary
- **D-09:** Installer scripts remain responsible for install-time prerequisites only: ensuring `uv` is available and package installation can succeed.
- **D-10:** Installer scripts must not own auth/cookie state machines or interactive recovery logic.
- **D-11:** The main supported flow is non-interactive-first. Platform branching stays at Windows/macOS, but interactive vs non-interactive installer logic is not a first-class architecture axis anymore.

### Registration and bundled skill
- **D-12:** AI client auto-detection and auto-registration remain part of the product contract.
- **D-13:** If no supported AI client is detected, `register` fails and the overall `setup` fails.
- **D-14:** If a detected AI client cannot be registered successfully, `register` fails and the overall `setup` fails.
- **D-15:** Registration failures must emit AI-actionable remediation output, including exact config targets and the canonical command to register.
- **D-16:** Bundled skill installation is part of the `register` phase, not an independent post-install side effect.

### Legacy patch-layer cleanup
- **D-17:** `bootstrap` is not part of the target architecture; its remaining useful behavior should be absorbed into `setup` and/or `register`.
- **D-18:** `launcher.py` is not part of the target architecture; it should exit the supported runtime path instead of remaining the command that clients launch.

### Phase exclusions
- **D-19:** Legacy migration from old `pip` / `launcher.py` / `uvx` installs is explicitly deferred because the product is not yet broadly externalized.

### the agent's Discretion
- Exact subcommand naming beyond the locked `setup` and `serve` entrypoints
- Whether `install` remains a visible subcommand or an internal phase helper
- Exact machine-readable error format for AI remediation messages

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase contract
- `.planning/PROJECT.md` — Product intent, constraints, and active simplification goals for installer/setup
- `.planning/REQUIREMENTS.md` — Formal requirements for install/runtime/setup/register/verify behavior
- `.planning/ROADMAP.md` — Phase 1 goal and success criteria
- `.planning/STATE.md` — Current milestone state and already-locked decisions

### Current reddit-mcp runtime/setup implementation
- `src/reddit_mcp/cli.py` — Current command surface, setup/bootstrap flow, manual config output, and update path
- `src/reddit_mcp/server.py` — Current setup-required guidance emitted to MCP clients and current `uvx` assumptions
- `src/reddit_mcp/config.py` — Current launcher/config path assumptions and legacy config carry-forward
- `src/reddit_mcp/cookie_manager.py` — Cookie setup behavior and current interactive browser requirements

### Cross-project installer/registration dependencies
- `../auth_gateway_for_mcp/templates/reddit-mcp.ps1.tpl` — Current Windows installer logic and false-success fallback behavior
- `../auth_gateway_for_mcp/templates/reddit-mcp.sh.tpl` — Current shell installer logic and false-success fallback behavior
- `../auth_gateway_for_mcp/src/installers.ts` — Installer rendering/publishing path
- `../shared-client-python/src/fivemghost_shared_client/registration/cli_registry.py` — Current multi-client registration behavior and runtime/launcher assumptions
- `../shared-client-python/src/fivemghost_shared_client/launcher.py` — Current launcher generation behavior that the new architecture is de-emphasizing

### Current verification coverage
- `tests/test_release_readiness.py` — Existing release/install assertions, including current runtime assumptions
- `../auth_gateway_for_mcp/tests/installer-endpoints.test.mjs` — Existing installer endpoint coverage
- `../auth_gateway_for_mcp/tests/installers-renderer.test.mjs` — Existing installer render coverage
- `../shared-client-python/tests/test_registration_configs.py` — Existing registration serialization coverage

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `src/reddit_mcp/cli.py`: already contains the current top-level command dispatcher and is the natural place to host the new `setup` orchestration contract.
- `src/reddit_mcp/cookie_manager.py`: already encapsulates the Reddit cookie acquisition/validation logic and should stay the owner of cookie-specific behavior.
- `../shared-client-python/src/fivemghost_shared_client/registration/cli_registry.py`: already centralizes multi-client registration attempts and is the natural place to simplify registration semantics.

### Established Patterns
- Current architecture mixes installer templates, CLI commands, launcher generation, and shared registration helpers into one install story.
- Current CLI help, server guidance tools, and manual config snippets still assume `uvx`, `python3`, and launcher indirection; these assumptions must be collapsed to one command truth.
- Cookie handling is already separated from auth token handling in code, which supports explicit phase separation inside `setup`.

### Integration Points
- Hosted installers in `auth_gateway_for_mcp` invoke local reddit-mcp commands and therefore must be updated in lockstep with the CLI contract.
- Shared registration helpers in `shared-client-python` define how Claude/Codex/Gemini/OpenClaw/OpenCode receive the MCP command and therefore must align with the new canonical runtime.
- MCP guidance tools in `src/reddit_mcp/server.py` must emit the same install/setup contract that the installer and CLI actually implement.

</code_context>

<specifics>
## Specific Ideas

- Keep the external experience close to one-click by allowing installer scripts to trigger `reddit-mcp setup`, but move all success/failure ownership into `setup`.
- Optimize for AI-driven remediation: when registration fails, the output should tell the AI exactly which config file and canonical command to write instead of giving vague human-only instructions.
- Prefer deletion of historical patch layers over preserving every old path. The goal is less branching, not smarter fallback.

</specifics>

<deferred>
## Deferred Ideas

- Legacy migration support for historical `pip` / `launcher.py` / `uvx` installs
- Any broader packaging redesign beyond the uv-based CLI distribution path

</deferred>

---

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