feat(setup): detect-first, agent-driven, brownfield-aware install#162
Merged
Conversation
Rework the install/onboarding flow — the #1 adoption blocker — per .planning/ONBOARDING-SPEC.md. New `memorymaster/surfaces/setup_detect.py`: read-only, timeout-bounded environment probe (docker/compose, ollama+models, qdrant, obsidian vault, gitnexus, ~/.claude, ~/.codex, mm install, existing MCP/hooks). Every probe degrades to "absent" on error; never raises. `format_plan()` renders a will-do / skip-present / can't-missing plan. `setup_hooks.py` (additive — existing functions preserved): - argparse non-interactive mode: --yes, --db, --provider, --full-stack/ --no-full-stack, --no-cron, --codex/--no-codex, --force, --verify-only, --json. ask()/ask_yn() honor a non-interactive flag. - detect-first plan + brownfield skip-if-present (don't clobber existing MCP unless --force). - full-stack orchestration: reuse healthy Qdrant/Ollama, else docker compose up + ollama pull; graceful no-Docker SQLite-only fallback that still exits 0. - verify_install(): sentinel ingest+query round-trip (isolated scope). - fix latent MCP-path bug: register memorymaster.surfaces.mcp_server, not the deprecated memorymaster.mcp_server; also register for Codex. - config safety: malformed pre-existing settings.json/.claude.json are backed up to <name>.corrupt-<ts>.bak before rewrite — never silently wiped. Docs: new docs/AGENT-INSTALL.md (paste-into-agent prompt, Claude + Codex); README 30-second quickstart; INSTALLATION.md reference + new flags; INTEGRATING de-duplicated. Tests are hermetic (patch HOME/CLAUDE_DIR/CODEX_DIR to tmp, mock subprocess/ HTTP) — the real ~/.claude is never touched. 100 setup tests pass; full suite collects clean (3027); ruff clean. Security review: config-safe, idempotent, hermetic.
Four bugs the hermetic unit tests structurally missed (they stub detection and use a populated HOME), caught by a from-zero `docker run python:3.12-slim` install: 1. append_instructions() crashed (FileNotFoundError) writing ~/.claude/CLAUDE.md when ~/.claude doesn't exist — it was ungated while hooks/MCP were gated on detected.claude_code. Now guards on CLAUDE_DIR.exists() (mirrors the Codex half). Also gate cron + obsidian-skills on claude_code. 2. db_init used wrong arg order (`init-db --db X`); `--db` is a GLOBAL arg and must precede the subcommand (`--db X init-db`), else argparse exits 2. 3. the init-db subprocess wrote to the real stdout fd, which contextlib.redirect_stdout (a sys.stdout swap) does not cover — its output corrupted the --json document. Fixed with capture_output=True. 4. --verify-only prompted for project root and crashed with EOFError on a non-tty: the short-circuit ran AFTER project-root resolution, and --verify-only didn't imply non-interactive. Moved the short-circuit to the top; --json/--verify-only now imply non-interactive. Also: honest completion summary (reflects actual skips instead of always claiming hooks/MCP configured). Added 3 from-zero regression tests. Validated end-to-end in a clean container: no-Claude degraded path, Claude-present wiring (surfaces.mcp_server), --verify-only on non-tty, and idempotent re-run all green. 103 setup tests pass; ruff clean.
wolverin0
added a commit
that referenced
this pull request
Jun 24, 2026
…+ document v4.0.0→ work) (#167) * release: v4.1.0 — local-filesystem (Everything) bridge + LLM Atlas extractor Surfaces the previously-merged-but-undocumented work since v4.0.0: - #161 local-filesystem search bridge (resolve_project, Everything ES.exe, path redaction) - #166 LLM typed-entity Atlas extractor - #162 detect-first installer; #165 steward tiers-every-cycle; #163 CI conftest; #164 IP scrub README Key features + CHANGELOG now document the Everything integration. * docs(release): frame local-search honestly — optional, Windows/Codex-focused, graceful-degrade Re-verified the Everything bridge works end-to-end (es.exe 1.1.0.27): resolve-project finds real projects with explainable scoring, memory-first cache hits on repeat, paths redacted. But the value is narrow (path-resolution for weak-file-search agents + cross- session recall), not a headline; speed is sub-second either way. Docs now say so.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Reworks install/onboarding — the #1 adoption blocker (spec:
.planning/ONBOARDING-SPEC.md).Why
Install was spread across 3 overlapping docs with no from-zero happy path, an interactive-only setup that wasn't detect-first, no verification, and a latent MCP-path bug.
What
setup_detect.py— read-only, timeout-bounded environment probe (docker/ollama/qdrant/obsidian/gitnexus/existing config); degrades to "absent" on any error.setup_hooks.py(additive, existing functions preserved): non-interactive flags (--yes/--full-stack/--json/--verify-only/--codex/--force), detect-first plan, brownfield skip-if-present, full-stack orchestration with graceful no-Docker SQLite fallback,verify_install()round-trip, and the MCP-path bug fix (surfaces.mcp_server, not the deprecated path; also registers Codex).settings.json/.claude.jsonare backed up to*.corrupt-<ts>.bakbefore rewrite — never silently wiped.docs/AGENT-INSTALL.md(paste-into-agent prompt, Claude + Codex), README 30-second quickstart, INSTALLATION reference, INTEGRATING de-dup.Verification
100 hermetic setup tests pass (real
~/.claudenever touched); full suite collects clean (3027); ruff clean. Security review: config-safe, idempotent, hermetic (the one HIGH finding — malformed-config data loss — was fixed + regression-tested before commit).