v0.2.3: setup wizard adds service install, Claude Code registration, PATH check

  - cortex setup now handles full onboarding: init, embeddings, password,
    LLM test, background service install, Claude Code registration, PATH symlink
  - Homebrew formula fixed: installs from wheel, includes virtualenv mixin

Author: grayisnotacolor

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] — 2026-04-12
+
+### Changed
+
+- **Setup wizard enhanced** — `cortex setup` now installs the background service (LaunchAgent/systemd), registers with Claude Code, and offers to add `cortex` to PATH. Two commands is all a new user needs: `brew install` + `cortex setup`.
+- **Homebrew formula fixed** — installs from PyPI wheel instead of building from source (avoids Rust toolchain requirement). Added `include Language::Python::Virtualenv` and `ensurepip` bootstrap.
+
 ## [0.2.2] — 2026-04-11
 
 ### Fixed
@@ -538,6 +545,7 @@ If you're upgrading from a pre-2026-04-07 install:
 > (MCP, dashboard, REST API) plus the CLI now route through the
 > canonical MCP HTTP server.
 
-[Unreleased]: https://github.com/abbacusgroup/Cortex/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/abbacusgroup/Cortex/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/abbacusgroup/Cortex/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/abbacusgroup/Cortex/compare/v0.2.0...v0.2.2
 [0.2.0]: https://github.com/abbacusgroup/Cortex/releases/tag/v0.2.0

Dockerfile

@@ -11,15 +11,15 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 
 # Copy project files
-COPY pyproject.toml uv.lock* ./
+COPY pyproject.toml uv.lock* README.md LICENSE ./
 COPY src/ src/
 COPY ontology/ ontology/
 COPY llms.txt ./
 
 # Install dependencies
 RUN uv sync --no-dev --frozen 2>/dev/null || uv sync --no-dev
 
-# Create data directory
+# Create data directory and initialize
 RUN mkdir -p /data
 
 ENV CORTEX_DATA_DIR=/data
@@ -28,9 +28,9 @@ ENV CORTEX_PORT=1314
 
 EXPOSE 1314
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
-    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:1314/health')" || exit 1
+# Health check — JSON-RPC ping to MCP endpoint
+HEALTHCHECK --interval=30s --timeout=5s --start-period=30s \
+    CMD python -c "import urllib.request,json; r=urllib.request.Request('http://localhost:1314/mcp',data=json.dumps({'jsonrpc':'2.0','id':1,'method':'ping'}).encode(),headers={'Content-Type':'application/json','Accept':'application/json, text/event-stream'},method='POST'); urllib.request.urlopen(r)" || exit 1
 
-# Default: run HTTP API server
-CMD ["uv", "run", "cortex", "serve", "--transport", "http", "--host", "0.0.0.0", "--port", "1314"]
+# Init data dir if empty (handles mounted volumes), then start server
+CMD ["sh", "-c", "uv run cortex init 2>/dev/null; uv run cortex serve --transport mcp-http --host 0.0.0.0 --port 1314"]

homebrew/Formula/abbacus-cortex.rb

@@ -1,15 +1,22 @@
 class AbbacusCortex < Formula
+  include Language::Python::Virtualenv
+
   desc "AI knowledge pipeline -- capture, search, and reason over your knowledge"
   homepage "https://github.com/abbacusgroup/Cortex"
-  url "https://files.pythonhosted.org/packages/source/a/abbacus-cortex/abbacus_cortex-0.2.1.tar.gz"
-  sha256 "0cebbd3846b7e8d90cb3c4ecc4f44805f05616c066371f09810fb71217c53f47"
+  url "https://files.pythonhosted.org/packages/source/a/abbacus-cortex/abbacus_cortex-0.2.2.tar.gz"
+  sha256 "88f3ce14c64e3c5826fa2ee3ee273f2b6216b737835a99d3d53146106444dc5a"
   license "BUSL-1.1"
 
   depends_on "python@3.12"
 
   def install
-    venv = virtualenv_create(libexec, "python3.12")
-    venv.pip_install_and_link buildpath
+    python3 = "python3.12"
+    venv = virtualenv_create(libexec, python3)
+    # Install from PyPI wheel (avoids building from source)
+    system libexec/"bin/python", "-m", "ensurepip", "--default-pip"
+    system libexec/"bin/python", "-m", "pip", "install", "--upgrade", "pip"
+    system libexec/"bin/python", "-m", "pip", "install", "abbacus-cortex==#{version}"
+    bin.install_symlink libexec/"bin/cortex"
   end
 
   def post_install

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "abbacus-cortex"
-version = "0.2.2"
+version = "0.2.3"
 description = "Cognitive knowledge system with formal ontology, reasoning, and intelligence serving"
 readme = "README.md"
 authors = [
@@ -74,7 +74,7 @@ dev = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.10.12,<0.11.0"]
+requires = ["uv_build>=0.10.12,<1.0.0"]
 build-backend = "uv_build"
 
 [tool.uv]

src/cortex/__init__.py

@@ -1,3 +1,3 @@
 """Cortex — Cognitive knowledge system."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"

src/cortex/cli/main.py

@@ -1101,9 +1101,78 @@ def setup(
     else:
         typer.echo("  LLM: not configured (set CORTEX_LLM_MODEL and CORTEX_LLM_API_KEY)")
 
-    typer.echo(f"\nCortex ready at {config.data_dir}")
-    typer.echo("  Run `cortex status` to verify.")
-    typer.echo("  Run `cortex serve` to start the server.")
+    # 5. Install background service
+    if not auto:
+        install_svc = typer.confirm(
+            "\n  Install as background service? (auto-starts on login)", default=True
+        )
+    else:
+        install_svc = True
+
+    if install_svc:
+        try:
+            from cortex.cli.install import do_install
+
+            do_install(config=config, service="mcp")
+        except Exception as e:
+            typer.echo(f"  Service install failed: {e}")
+            typer.echo("  You can start manually: cortex serve --transport mcp-http")
+    else:
+        typer.echo("  Skipped. Start manually: cortex serve --transport mcp-http")
+
+    # 6. Register with Claude Code
+    register_cc = typer.confirm("  Register with Claude Code?", default=True) if not auto else True
+
+    if register_cc:
+        try:
+            import json
+
+            settings_path = Path.home() / ".claude" / "settings.json"
+            settings: dict[str, Any] = {}
+            if settings_path.exists():
+                settings = json.loads(settings_path.read_text())
+            mcp_servers = settings.setdefault("mcpServers", {})
+            mcp_servers["cortex"] = {
+                "type": "http",
+                "url": config.mcp_server_url,
+            }
+            settings_path.parent.mkdir(parents=True, exist_ok=True)
+            settings_path.write_text(json.dumps(settings, indent=2) + "\n")
+            typer.echo(f"  Registered with Claude Code ({config.mcp_server_url})")
+        except Exception as e:
+            typer.echo(f"  Registration failed: {e}")
+            typer.echo("  You can register later: cortex register")
+
+    # 7. PATH check
+    import shutil
+
+    if not shutil.which("cortex"):
+        cortex_bin = Path(sys.executable).parent / "cortex"
+        if cortex_bin.exists():
+            link_path = Path("/usr/local/bin/cortex")
+            if not auto:
+                add_path = typer.confirm(
+                    "  Add `cortex` to your PATH? (creates symlink in /usr/local/bin)",
+                    default=True,
+                )
+            else:
+                add_path = True
+
+            if add_path:
+                try:
+                    link_path.symlink_to(cortex_bin)
+                    typer.echo(f"  Linked: {link_path} -> {cortex_bin}")
+                except PermissionError:
+                    typer.echo(f"  Needs sudo. Run: sudo ln -sf {cortex_bin} {link_path}")
+                except FileExistsError:
+                    typer.echo(f"  {link_path} already exists — skipping")
+            else:
+                typer.echo(f"  Skipped. Run: sudo ln -sf {cortex_bin} /usr/local/bin/cortex")
+
+    typer.echo("\nCortex is ready!")
+    typer.echo(f"  Data:   {config.data_dir}")
+    typer.echo(f"  Server: http://{config.host}:{config.port}/mcp")
+    typer.echo('\n  Try: cortex capture "My first note" --type idea --content "Hello Cortex!"')
 
     global _store
     _store = store