---
phase: 01-installer-and-setup-architecture-simplification
plan: 02
subsystem: shared-registration-contract
tags: [python, registration, cli, config, canonical-command]
requires: [01]
provides:
  - Canonical `reddit-mcp serve` registration contract across supported AI clients
  - Fatal registration semantics for no-client and detected-client failure cases
  - AI-actionable remediation text naming target client and config path
affects: [shared-client-python, reddit-mcp]
tech-stack:
  added: []
  patterns: [canonical-command-serialization, fail-fast-registration, ai-actionable-remediation]
key-files:
  created: []
  modified:
    - shared-client-python/src/fivemghost_shared_client/registration/cli_registry.py
    - shared-client-python/src/fivemghost_shared_client/registration/claude_internal.py
    - shared-client-python/src/fivemghost_shared_client/registration/codex_internal.py
    - shared-client-python/src/fivemghost_shared_client/registration/gemini_internal.py
    - shared-client-python/src/fivemghost_shared_client/registration/openclaw.py
    - shared-client-python/tests/test_registration_configs.py
    - reddit-mcp/src/reddit_mcp/cli.py
key-decisions:
  - "Shared registration now serializes explicit `command` + `args` instead of guessing a runtime plus launcher path."
  - "Registration is a required setup phase: zero detected clients and detected-client write failures are both fatal."
  - "Failure messages now include the target client, config path, and canonical manual command so an AI can repair the config deterministically."
patterns-established:
  - "Per-client config writers consume one canonical command contract and stop embedding runtime-specific heuristics."
  - "Regression tests cover both config serialization and fatal registration semantics."
requirements-completed: [REG-01, REG-02, REG-03, VER-01]
duration: 25min
completed: 2026-04-14
---

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

**shared-client-python now writes the same `reddit-mcp serve` contract to supported AI clients and fails hard when registration cannot produce a usable client config.**

## Performance

- **Duration:** 25 min
- **Tasks:** 2
- **Files modified:** 7

## Accomplishments

- Replaced the registration API's `runtime` + `launcher_path` contract with explicit `command` + `args`.
- Updated Claude, Codex, Gemini, and OpenClaw config writers to persist `reddit-mcp` plus `["serve"]`.
- Changed `register_all()` to fail when no supported client is detected and when any detected client write fails.
- Added remediation output with `target_client`, `config_path`, and canonical manual command text.
- Updated reddit-mcp's register phase to call the new shared registration contract directly.

## 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

- `shared-client-python/src/fivemghost_shared_client/registration/cli_registry.py` - Canonical command registration orchestration and fatal failure semantics.
- `shared-client-python/src/fivemghost_shared_client/registration/claude_internal.py` - Claude config writer now persists explicit command/args.
- `shared-client-python/src/fivemghost_shared_client/registration/codex_internal.py` - Codex TOML writer now emits direct command/args instead of launcher indirection.
- `shared-client-python/src/fivemghost_shared_client/registration/gemini_internal.py` - Gemini config writer now persists explicit command/args.
- `shared-client-python/src/fivemghost_shared_client/registration/openclaw.py` - OpenClaw JSON/CLI registration now targets the canonical command directly.
- `shared-client-python/tests/test_registration_configs.py` - Regression coverage for canonical serialization and fatal no-client / failed-client behavior.
- `reddit-mcp/src/reddit_mcp/cli.py` - Register phase now consumes the new shared registration API.

## Decisions Made

- Kept bundled-skill installation in reddit-mcp's register phase while moving command serialization and failure semantics into shared-client-python.
- Treated no detected supported client as a hard registration failure instead of a warning-only path.

## Deviations from Plan

- None.

## Issues Encountered

- The first import-path spot check briefly appeared to resolve against the main workspace. Re-checking after the editable reinstall confirmed the active module path was the current worktree before pytest verification.

## User Setup Required

None for this wave.

## Next Phase Readiness

- Installer templates can now invoke `reddit-mcp setup` without carrying runtime probing or launcher/uvx registration fallbacks.
- README and cross-repo tests can now document and enforce a single registration command contract.

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