Cerefox installer + interactive bootstrap (cfcf-style UX)

[fstamatelopoulos]

Summary

Proposal to make Cerefox installable as a global cerefox command via a one-line installer (à la cfcf, uv, ruff), with an interactive cerefox init first-run flow, a cerefox doctor diagnostic, and cerefox self-update. Models the UX on cfcf, adapted for Cerefox's Python codebase (no full TS rewrite).

Design doc: docs/research/installer-design.md
Branch: research/installer-design
Status: Research / proposal — iterate on the doc in the branch before scheduling implementation.

What problem this solves

Today's install (clone repo → uv sync → edit .env → db_deploy.py → npm build → always uv run cerefox from the repo root) is fine for developers but a barrier for end users. Three structural awkwardnesses:

• Working-directory dependence — Settings reads .env from CWD, so cerefox only works from the repo root.
• No global install path — every invocation needs uv run. Claude Desktop / Path C agents need the absolute repo path spelled out.
• No interactive bootstrap — first successful search takes ~15 minutes of doc-reading and manual config.

What the proposal delivers (target UX)

# One-line install
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh

# Interactive bootstrap — Supabase + OpenAI + schema deploy + MCP wiring
cerefox init

# Day-to-day from any directory
cerefox search "OAuth design"
cerefox ingest ~/notes/meeting.md --author "fotis" --author-type "user"
cerefox doctor
cerefox self-update

Claude Desktop MCP config collapses from uv --directory /Users/fotis/src/cerefox run cerefox mcp to cerefox mcp. Path C agent guidance no longer needs to spell out the cerefox checkout path.

Phased plan

Phase	Scope	Effort	Goal
Phase 0	Prerequisite refactors (config-dir resolution, importlib.resources for SQL files, hatch-vcs for version, wheel-includes for frontend/dist)	Small	Unblocks Phase 1. Backward-compatible — dev install path is unchanged.
Phase 1	PyPI publish, install.sh, cerefox init / doctor / self-update / configure-mcp. Doc rewrite for end-user vs dev install split.	Medium	90% of the UX win.
Phase 2	PyInstaller standalone binaries via GitHub Releases, Homebrew tap. macOS notarization decision.	Medium	Removes "must have Python" friction. Independent of Phase 1 — can defer indefinitely.
Phase 3	npm-native distribution. Not recommended without a real TS rewrite.	High, low value	Explicitly deferred.

Phase 0 + Phase 1 each become their own iteration / GitHub issue when this is scheduled.

Decision points needing your input before this becomes an iteration

Listed in §13 of the doc:

1. Phase 1 only, or Phase 1 + Phase 2 together? Phase 1 alone is the bigger UX win for less effort.
2. PyPI name: is cerefox available? Fallbacks: cerefox-cli, cerefox-knowledge.
3. ~/.cerefox/ vs XDG-strict ~/.config/cerefox/ — recommend ~/.cerefox/ for consistency with Claude Code (~/.claude/), Codex (~/.codex/), cfcf (~/.cfcf/).
4. macOS notarization budget ($99/year) — only matters for Phase 2.
5. cerefox init prompt defaults — "deploy schema?" / "wire up Claude Desktop?" default Yes or No?

Out of scope (called out explicitly in §12)

• Not a full Python-to-TypeScript rewrite. The existing Iteration 18 plan (narrow TS port of just mcp_server.py for shared-code reasons — see docs/plan.md line 1626) remains a separate, independent decision and is not blocked by or blocking this proposal.
• Not a hosted-Cerefox SaaS — users still bring their own Supabase project.
• Not a change to agent protocols (MCP / Edge Functions / GPT Actions all continue working unchanged).
• Not a replacement for the dev install path — contributors keep cloning and using uv sync.

Open questions

§10 of the doc lists 10 — most need investigation during implementation, not blocking discussion now.

How to pick this up later

1. Read the doc end-to-end. Edit on the research/installer-design branch. Push back on anything that doesn't fit how you'd want this to work.
2. Resolve the §13 decision points. Those shape the implementation tickets.
3. When the doc is locked, split into two new GitHub issues — "Phase 0: installer prerequisites" and "Phase 1: Cerefox installer + bootstrap UX" — and schedule as new iterations in plan.md. Close this issue at that point.

Related work

• PR CLI parity with MCP/API: tickets #28-31 + flag-name parity + delete-doc safety #35 / v0.1.18 — the CLI parity work just shipped (Add --author, --author-type, --requestor flags to CLI for caller-identity parity #28-31). This proposal builds on the now-complete CLI surface to make it installable.
• cerefox#26 — the only other open ticket. Independent — doesn't block or unblock this work.
• Iteration 18 (TS port of mcp_server.py) — also independent. If it lands first, this proposal just changes the implementation of cerefox mcp from a Python process to a Node.js process; the installer story is unchanged.

[fstamatelopoulos]

Closing — design phase complete. Scope expanded significantly from the original Phase 0/1 proposal into the broader Polish & Distribution arc (v0.2.0 → v1.0.0), which absorbs the installer story plus the strategic shift from Python to TypeScript/Bun via a strangler-fig migration.

Design-of-record: docs/research/polish-and-distribution-design.md — 19 sections, includes script-language policy (§12f), SemVer commitment (§11), and the v0.2.0 → v1.0.0 phased plan (§13).

Implementation roadmap: docs/plan.md Iterations 19–27. Iteration 19 (v0.2.0 — "Real Release") has the full 18-task breakdown ready to execute.

All five decision points in the original issue body got answered — TL;DR: npm under `@cerefox/memory` (not PyPI), broader TS migration scope, `~/.cerefox/` as user state root, Bun-first runtime, Apple notarization deferred until binaries ship.