code-data-ark 2.0.3__tar.gz → 2.0.5__tar.gz

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-data-ark
-Version: 2.0.3
+Version: 2.0.5
 Summary: Code Data Ark — local observability and intelligence platform for VS Code + Copilot Chat sessions
 Project-URL: Homepage, https://github.com/goCosmix/cda
 Project-URL: Repository, https://github.com/goCosmix/cda.git
@@ -121,48 +121,67 @@ make install-dev
 
 ## ⚡ Quick Start
 
-1. **Install**
-
 ```bash
 pip install code-data-ark
+cda setup
 ```
 
-2. **Initialize — create `~/.cda/` and validate your VS Code data path**
+That's it. `cda setup` runs four steps in sequence:
 
-```bash
-cda init
-```
+| Step | What it does |
+|------|-------------|
+| **1. Init** | Creates `~/.cda/` directory tree, validates your VS Code data path |
+| **2. PMF install** | Registers a macOS LaunchAgent — CDA starts automatically on every login |
+| **3. Sync** | Ingests all VS Code + Copilot session data into `~/.cda/data/cda.db` |
+| **4. Up** | Starts the watcher daemon and web UI via the PMF kernel, opens browser |
+
+After setup, everything is managed by the **PMF kernel**. On every login, `launchd` calls `cda pmf up` which starts the watcher and web UI. No terminal interaction required.
 
-3. **Ingest all VS Code session data**
+### Options
 
 ```bash
-cda sync
+cda setup --skip-sync     # Skip initial ingest (run `cda sync` manually later)
+cda setup --no-browser    # Don't open browser when the UI starts
 ```
 
-4. **Start the live watcher daemon**
+### After setup
 
 ```bash
-cda watch start
+cda check           # Full system health diagnostic
+cda sync            # Re-ingest after significant new session activity
+cda pmf services    # View all running services and their status
+cda pmf uninstall   # Remove the auto-start LaunchAgent registration
 ```
 
-5. **Open the web dashboard**
+## 🔧 Process Management (PMF)
 
-```bash
-cda serve   # → http://127.0.0.1:10001
+All background processes run through the embedded PMF kernel. The LaunchAgent is the entry point — nothing starts directly on the host outside of PMF.
+
+```
+launchd (login)
+  └─ cda pmf up
+       ├─ PMF kernel → watcher daemon   (cda.pipeline.watcher)
+       └─ PMF kernel → web UI server    (cda.ui.web)
 ```
 
-6. **Build semantic intelligence** (optional, requires `sentence-transformers`)
+### PMF commands
 
 ```bash
-cda embed build
+cda pmf services           # List all services with status and PID
+cda pmf start <service>    # Start a service (watcher, ui, sync, reconstruct, embed-build)
+cda pmf stop <service>     # Stop a service
+cda pmf restart <service>  # Restart a service
+cda pmf logs <service>     # Tail the service log
+cda pmf up                 # Start watcher + UI (opens browser) — same as launchd trigger
+cda pmf install            # Register LaunchAgent (done automatically by cda setup)
+cda pmf uninstall          # Remove LaunchAgent
 ```
 
 ## 🌐 Web UI
 
-- **Background service**: `cda ui start`
-- **Stop service**: `cda ui stop`
-- **Service status**: `cda ui status`
-- **Foreground mode**: `cda serve`
+- **Background service** (default after setup): managed by PMF, starts on login
+- **Foreground mode**: `cda serve` — runs in the terminal, opens browser, Ctrl+C to stop
+- **Access**: `http://127.0.0.1:10001`
 
 The web UI includes:
 

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/cda/kernel/pmf_kernel.py

@@ -1,9 +1,13 @@
 import json
 import os
+import shutil
 import signal
+import socket
 import subprocess
 import sys
+import threading
 import time
+import webbrowser
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional
@@ -17,6 +21,132 @@ from cda.kernel.paths import (
 DEFAULT_HOST = "127.0.0.1"
 DEFAULT_PORT = 10001
 
+# ── launchd integration ──────────────────────────────────────────────────────
+
+PLIST_LABEL = "com.gocosmix.cda"
+
+
+def plist_path() -> Path:
+    return Path.home() / "Library" / "LaunchAgents" / f"{PLIST_LABEL}.plist"
+
+
+def generate_plist(cda_bin: str, cda_home: Path) -> str:
+    log = cda_home / "logs" / "launchd.log"
+    return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>{PLIST_LABEL}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{cda_bin}</string>
+        <string>pmf</string>
+        <string>up</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <false/>
+    <key>StandardOutPath</key>
+    <string>{log}</string>
+    <key>StandardErrorPath</key>
+    <string>{log}</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>CDA_HOME</key>
+        <string>{cda_home}</string>
+        <key>PATH</key>
+        <string>{os.path.dirname(cda_bin)}:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>
+"""
+
+
+def install_launchd(cda_home: Path) -> Path:
+    """Write the LaunchAgent plist and load it with launchctl."""
+    cda_bin = shutil.which("cda")
+    if not cda_bin:
+        raise PMFKernelError("cda binary not found on PATH — cannot generate plist")
+
+    target = plist_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(generate_plist(cda_bin, cda_home))
+
+    # Unload any stale registration first
+    subprocess.run(["launchctl", "unload", str(target)], capture_output=True)
+
+    result = subprocess.run(
+        ["launchctl", "load", str(target)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise PMFKernelError(f"launchctl load failed: {result.stderr.strip()}")
+
+    return target
+
+
+def uninstall_launchd() -> None:
+    """Unload and remove the LaunchAgent plist."""
+    target = plist_path()
+    if target.exists():
+        subprocess.run(["launchctl", "unload", str(target)], capture_output=True)
+        target.unlink(missing_ok=True)
+
+
+def open_browser_when_ready(
+    url: str,
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    timeout: float = 12.0,
+) -> threading.Thread:
+    """
+    Spawn a daemon thread that polls host:port and opens a browser when ready.
+    For foreground (serve) use: the thread outlives the caller because serve blocks.
+    For background (pmf up / ui start): call wait_for_port() instead so we poll
+    synchronously before the process exits.
+    """
+    def _wait_and_open():
+        elapsed = 0.0
+        while elapsed < timeout:
+            try:
+                with socket.create_connection((host, port), timeout=0.5):
+                    webbrowser.open(url)
+                    return
+            except OSError:
+                time.sleep(0.25)
+                elapsed += 0.25
+
+    t = threading.Thread(target=_wait_and_open, daemon=True)
+    t.start()
+    return t
+
+
+def wait_for_port_and_open_browser(
+    url: str,
+    host: str = DEFAULT_HOST,
+    port: int = DEFAULT_PORT,
+    timeout: float = 8.0,
+) -> bool:
+    """
+    Block until host:port accepts connections (or timeout), then open browser.
+    Use this when the caller process will exit after starting a background service.
+    Returns True if port came up, False on timeout.
+    """
+    elapsed = 0.0
+    while elapsed < timeout:
+        try:
+            with socket.create_connection((host, port), timeout=0.5):
+                webbrowser.open(url)
+                return True
+        except OSError:
+            time.sleep(0.25)
+            elapsed += 0.25
+    return False
+
+
 ensure_dirs()
 
 

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/cda/ui/cli.py

@@ -24,8 +24,12 @@ Commands:
   cda pmf stop <service>     Stop a service
   cda pmf restart <service>  Restart a service
   cda pmf logs <service>     Tail service logs
+  cda pmf up                 Start watcher + web UI (opens browser when ready)
+  cda pmf install            Register as macOS LaunchAgent (auto-start on login)
+  cda pmf uninstall          Remove the LaunchAgent registration
   cda check                  Run a full self-diagnostic. The system checks itself.
   cda init                   First-run setup — create ~/.cda/ and validate environment
+  cda setup                  Full onboarding: init → pmf install → sync → up (browser opens)
   cda serve                  Start the local web UI on port 10001
   cda sync                   Full re-ingest from disk (rebuilds entire DB)
   cda reconstruct            Re-run reconstruction and FTS rebuild only
@@ -62,7 +66,11 @@ import textwrap
 import datetime
 from pathlib import Path
 from cda.pipeline.reconstruct import decompress_vfs
-from cda.kernel.pmf_kernel import PMFKernel, PMFKernelError
+from cda.kernel.pmf_kernel import (
+    PMFKernel, PMFKernelError,
+    install_launchd, uninstall_launchd, plist_path,
+    open_browser_when_ready, wait_for_port_and_open_browser,
+)
 from cda.kernel.paths import (
     DB_PATH, PID_FILE, UI_PID_FILE, UI_LOG_FILE,
     QUEUE_DIR, POLICY_FILE, ensure_dirs,
@@ -73,6 +81,14 @@ import click
 # Ensure runtime dirs exist on every CLI invocation
 ensure_dirs()
 
+
+def _pmf_warn_if_not_installed():
+    """Emit a one-time advisory if the LaunchAgent is not registered."""
+    if not plist_path().exists():
+        click.echo(yellow("  Note: LaunchAgent not installed — services won't auto-start on login."))
+        click.echo(yellow("        Run `cda setup` to register, or `cda pmf install` to add just the plist."))
+
+
 kernel = PMFKernel()
 
 
@@ -361,10 +377,11 @@ def status():
 @cli.command("serve")
 @click.option("--host", default="127.0.0.1", show_default=True, help="Local host to bind the web UI")
 @click.option("--port", default=10001, show_default=True, help="Local port for the web UI")
-def serve(host, port):
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser automatically")
+def serve(host, port, no_browser):
     """Start the local web UI for Code Data Ark in the foreground."""
-    click.echo(yellow(f"  Starting local web UI at http://{host}:{port}"))
-    click.echo(yellow("  Use `cda ui start` to launch it as a background service."))
+    url = f"http://{host}:{port}"
+    click.echo(yellow(f"  Starting local web UI at {url}"))
     try:
         import importlib
         import cda.ui.web as web
@@ -373,6 +390,8 @@ def serve(host, port):
         click.echo(red("  Failed to start web UI. Ensure the package is installed and importable."))
         click.echo(red(f"  Details: {exc}"))
         return
+    if not no_browser:
+        open_browser_when_ready(url, host, port)
     web.start_server(host=host, port=port)
 
 
@@ -396,12 +415,18 @@ def _ui_is_running():
 @ui.command("start")
 @click.option("--host", default="127.0.0.1", show_default=True, help="Local host to bind the web UI")
 @click.option("--port", default=10001, show_default=True, help="Local port for the web UI")
-def ui_start(host, port):
-    """Start the web UI as a background service."""
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser automatically")
+def ui_start(host, port, no_browser):
+    """Start the web UI as a background service (via PMF kernel)."""
+    _pmf_warn_if_not_installed()
     try:
         result = kernel.start_service("ui", options={"host": host, "port": port})
-        click.echo(green(f"  Web UI started in background at http://{host}:{port} pid={result['pid']}"))
+        url = f"http://{host}:{port}"
+        click.echo(green(f"  Web UI started in background at {url} pid={result['pid']}"))
         click.echo(yellow(f"  Logs: {UI_LOG_FILE}"))
+        if not no_browser:
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
     except PMFKernelError as exc:
         click.echo(red(f"  Failed to start UI: {exc}"))
 
@@ -485,12 +510,17 @@ def pmf_status(service_id):
 @click.argument("service_id")
 @click.option("--host", default="127.0.0.1", help="Host override for UI service")
 @click.option("--port", default=10001, help="Port override for UI service")
-def pmf_start(service_id, host, port):
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser (UI service only)")
+def pmf_start(service_id, host, port, no_browser):
     """Start a PMF-managed Ark service."""
     options = {"host": host, "port": port} if service_id == "ui" else None
     try:
         result = kernel.start_service(service_id, options=options)
         click.echo(green(f"  Started {result['label']} pid={result['pid']}"))
+        if service_id == "ui" and not no_browser:
+            url = f"http://{host}:{port}"
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
     except PMFKernelError as exc:
         click.echo(red(f"  {exc}"))
 
@@ -529,6 +559,69 @@ def pmf_logs(service_id, tail):
         click.echo(red(f"  {exc}"))
 
 
+@pmf.command("up")
+@click.option("--host", default="127.0.0.1", show_default=True, help="Host for web UI")
+@click.option("--port", default=10001, show_default=True, help="Port for web UI")
+@click.option("--no-browser", "no_browser", is_flag=True, default=False, help="Don't open browser when UI is ready")
+def pmf_up(host, port, no_browser):
+    """Start all CDA services (watcher + web UI). Called automatically by launchd on login."""
+    url = f"http://{host}:{port}"
+
+    click.echo(bold("  Code Data Ark — starting services"))
+    click.echo(hr())
+
+    try:
+        result = kernel.start_service("watcher")
+        click.echo(green(f"  Watcher      started  pid={result['pid']}"))
+    except PMFKernelError as exc:
+        click.echo(yellow(f"  Watcher      {exc}"))
+
+    try:
+        result = kernel.start_service("ui", options={"host": host, "port": port})
+        click.echo(green(f"  Web UI       started  pid={result['pid']}  →  {url}"))
+        if not no_browser:
+            click.echo(dim("  Opening browser when server is ready..."))
+            wait_for_port_and_open_browser(url, host, port)
+    except PMFKernelError as exc:
+        click.echo(yellow(f"  Web UI       {exc}"))
+
+    click.echo()
+
+
+@pmf.command("install")
+def pmf_install():
+    """Install CDA as a macOS launchd LaunchAgent (auto-start on login)."""
+    from cda.kernel.paths import CDA_HOME as _cda_home
+    click.echo()
+    click.echo(bold("  Installing CDA LaunchAgent"))
+    click.echo(hr())
+    try:
+        target = install_launchd(_cda_home)
+        click.echo(green(f"  Plist:   {target}"))
+        click.echo(green("  Label:   com.gocosmix.cda"))
+        click.echo(green("  Loaded:  yes — CDA will start automatically on next login"))
+        click.echo()
+        click.echo(dim("  To start services now without logging out:"))
+        click.echo(dim("    cda pmf up"))
+        click.echo()
+    except PMFKernelError as exc:
+        click.echo(red(f"  {exc}"))
+        click.echo(yellow("  Make sure `cda` is on PATH: export PATH=\"$HOME/Library/Python/3.9/bin:$PATH\""))
+        click.echo()
+
+
+@pmf.command("uninstall")
+def pmf_uninstall():
+    """Remove the CDA launchd LaunchAgent."""
+    target = plist_path()
+    if not target.exists():
+        click.echo(yellow("  No LaunchAgent plist found — nothing to uninstall."))
+        return
+    uninstall_launchd()
+    click.echo(green(f"  Removed: {target}"))
+    click.echo(green("  CDA will no longer start automatically on login."))
+
+
 @cli.group()
 def embed():
     """Build and inspect semantic intelligence."""
@@ -705,10 +798,11 @@ def watch():
 
 @watch.command("start")
 def watch_start():
-    """Start the live sync watcher daemon."""
+    """Start the live sync watcher daemon (via PMF kernel)."""
+    _pmf_warn_if_not_installed()
     try:
         result = kernel.start_service("watcher")
-        click.echo(green(f"  Watcher started pid={result['pid']}"))
+        click.echo(green(f"  Watcher started  pid={result['pid']}  (via PMF)"))
     except PMFKernelError as exc:
         click.echo(red(f"  {exc}"))
 
@@ -2563,6 +2657,194 @@ def check(as_json, fail_fast):
     sys.exit(0 if passed_all else 1)
 
 
+# ─────────────────────────────────────────────
+# SETUP
+# ─────────────────────────────────────────────
+
+@cli.command("setup")
+@click.option("--skip-sync", "skip_sync", is_flag=True, default=False,
+              help="Skip initial data ingest (run `cda sync` manually later)")
+@click.option("--no-browser", "no_browser", is_flag=True, default=False,
+              help="Don't open browser when the web UI starts")
+def setup(skip_sync, no_browser):
+    """
+    Full onboarding in four steps: init → pmf install → sync → up.
+
+    \b
+    Run this once after `pip install code-data-ark`:
+
+        cda setup
+
+    \b
+    What each step does:
+      1. Init    — create ~/.cda/ directory tree, validate VS Code data path
+      2. Install — register a macOS LaunchAgent so CDA starts on every login
+      3. Sync    — ingest all VS Code + Copilot session data into cda.db
+      4. Up      — start the watcher daemon and web UI via PMF, open browser
+
+    All processes are managed by the PMF kernel. The LaunchAgent calls
+    `cda pmf up` on every login — no manual interaction needed after setup.
+    """
+    from cda.kernel.paths import (
+        CDA_HOME, DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR,
+        PMF_DIR, PMF_LOG_DIR, CONFIG_DIR, POLICY_FILE,
+    )
+    import os as _os
+
+    W = 52
+    BAR = "═" * W
+    bar = "─" * W
+    host, port = "127.0.0.1", 10001
+    url = f"http://{host}:{port}"
+
+    click.echo()
+    click.echo(bold(BAR))
+    click.echo(bold("  Code Data Ark — setup"))
+    click.echo(bold(BAR))
+    click.echo()
+    click.echo(dim("  Four steps to a fully operational CDA installation:"))
+    click.echo(dim(f"    1. Init    — create {CDA_HOME}"))
+    click.echo(dim("    2. Install — register macOS LaunchAgent (auto-start on login)"))
+    click.echo(dim("    3. Sync    — first-run data ingest") + (dim("  [skipped]") if skip_sync else ""))
+    click.echo(dim("    4. Up      — start watcher + web UI via PMF, open browser"))
+    click.echo()
+
+    # ── Step 1: Init ─────────────────────────────────────────────
+    click.echo(bold(bar))
+    click.echo(bold("  Step 1/4 — Init"))
+    click.echo(bold(bar))
+    click.echo()
+
+    dirs = [DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR, PMF_DIR, PMF_LOG_DIR, CONFIG_DIR]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+        click.echo(f"    {green('✓')}  {d}")
+
+    if not POLICY_FILE.exists():
+        POLICY_FILE.write_text("# CDA access policy\n# ALLOW <pattern>\n# DENY  <pattern>\n")
+
+    vscode_data = Path(_os.environ.get(
+        "VSCODE_DATA_DIR",
+        Path.home() / "Library/Application Support/Code/User",
+    ))
+    if vscode_data.exists():
+        click.echo(f"    {green('✓')}  VS Code data dir found")
+    else:
+        click.echo(f"    {yellow('⚠')}  VS Code data dir not found: {vscode_data}")
+        click.echo(yellow("         Set VSCODE_DATA_DIR if your data is elsewhere."))
+
+    click.echo()
+    click.echo(f"    {green('✓')}  CDA_HOME: {CDA_HOME}")
+    click.echo()
+
+    # ── Step 2: PMF install ──────────────────────────────────────
+    click.echo(bold(bar))
+    click.echo(bold("  Step 2/4 — PMF install"))
+    click.echo(bold(bar))
+    click.echo()
+    click.echo(dim("  The LaunchAgent registers CDA with macOS launchd. On every login,"))
+    click.echo(dim("  launchd calls `cda pmf up` which starts the watcher daemon and"))
+    click.echo(dim("  web UI via the PMF kernel — no terminal required."))
+    click.echo()
+
+    pmf_ok = False
+    try:
+        target = install_launchd(CDA_HOME)
+        click.echo(f"    {green('✓')}  LaunchAgent: {target}")
+        click.echo(f"    {green('✓')}  Loaded — CDA will start automatically on every login")
+        pmf_ok = True
+    except PMFKernelError as exc:
+        click.echo(f"    {yellow('⚠')}  LaunchAgent registration failed: {exc}")
+        click.echo(yellow("         Ensure `cda` is on PATH, then run `cda pmf install` to retry."))
+    click.echo()
+
+    # ── Step 3: Sync ─────────────────────────────────────────────
+    click.echo(bold(bar))
+    click.echo(bold("  Step 3/4 — Sync"))
+    click.echo(bold(bar))
+    click.echo()
+
+    if skip_sync:
+        click.echo(f"    {yellow('↳')}  Skipped (--skip-sync).  Run `cda sync` when ready.")
+        click.echo()
+    else:
+        click.echo(dim("  Scanning VS Code workspaceStorage and building cda.db."))
+        click.echo(dim("  First run may take several minutes depending on session history."))
+        click.echo()
+
+        sync_failed = False
+        stages = [
+            ("cda.pipeline.ingest",      "Ingest       — reading VS Code storage"),
+            ("cda.pipeline.reconstruct",  "Reconstruct  — building exchanges + FTS"),
+            ("cda.pipeline.extract",      "Extract      — behavioral signals + tokens"),
+            ("cda.pipeline.embed",        "Embed        — semantic intelligence layer"),
+        ]
+        for module, label in stages:
+            click.echo(yellow(f"    → {label}"))
+            result = subprocess.run([sys.executable, "-m", module], capture_output=False)
+            if result.returncode != 0:
+                click.echo(red("    ✗  Failed — sync incomplete"))
+                sync_failed = True
+                break
+            click.echo(green("    ✓  Done"))
+            click.echo()
+
+        if not sync_failed:
+            click.echo(green("    ✓  Sync complete"))
+            click.echo()
+
+    # ── Step 4: Up ───────────────────────────────────────────────
+    click.echo(bold(bar))
+    click.echo(bold("  Step 4/4 — Up"))
+    click.echo(bold(bar))
+    click.echo()
+    click.echo(dim("  Starting all services through the PMF kernel."))
+    click.echo(dim("  Each process is tracked, logged, and restartable via `cda pmf`."))
+    click.echo()
+
+    for svc_id, opts, label in [
+        ("watcher", None,                         "Watcher daemon"),
+        ("ui",      {"host": host, "port": port}, f"Web UI         →  {url}"),
+    ]:
+        try:
+            result = kernel.start_service(svc_id, options=opts)
+            click.echo(f"    {green('✓')}  {label}   pid={result['pid']}")
+        except PMFKernelError as exc:
+            msg = str(exc)
+            if "already running" in msg.lower():
+                click.echo(f"    {green('✓')}  {label}   (already running)")
+            else:
+                click.echo(f"    {yellow('⚠')}  {label}   {msg}")
+
+    click.echo()
+
+    if not no_browser:
+        click.echo(dim("  Waiting for web UI..."))
+        opened = wait_for_port_and_open_browser(url, host, port)
+        if opened:
+            click.echo(f"    {green('✓')}  Browser opened: {url}")
+        else:
+            click.echo(f"    {yellow('⚠')}  Server not responding yet — visit {url} manually")
+        click.echo()
+
+    # ── Done ─────────────────────────────────────────────────────
+    click.echo(bold(BAR))
+    click.echo(bold("  Setup complete."))
+    click.echo(bold(BAR))
+    click.echo()
+    if pmf_ok:
+        click.echo(dim("  CDA will start automatically on every login via launchd."))
+    click.echo(dim("  The watcher daemon stays in sync with your VS Code sessions."))
+    click.echo(dim(f"  Visit {url} any time to explore your data."))
+    click.echo()
+    click.echo(dim("  Useful commands:"))
+    click.echo(dim("    cda check          — full system health diagnostic"))
+    click.echo(dim("    cda sync           — re-ingest after significant new session activity"))
+    click.echo(dim("    cda pmf services   — view running services and their status"))
+    click.echo(dim("    cda pmf uninstall  — remove auto-start LaunchAgent registration"))
+    click.echo()
+
+
 # ─────────────────────────────────────────────
 # INIT
 # ─────────────────────────────────────────────
@@ -2606,9 +2888,10 @@ def init():
     click.echo(bold("  CDA_HOME: ") + str(CDA_HOME))
     click.echo()
     click.echo(dim("  Next steps:"))
+    click.echo(dim("    cda pmf install  — register as a macOS LaunchAgent (auto-start on login)"))
     click.echo(dim("    cda sync         — ingest all VS Code session data"))
-    click.echo(dim("    cda watch start  — start the live watcher daemon"))
-    click.echo(dim("    cda serve        — open the web dashboard on :10001"))
+    click.echo(dim("    cda pmf up       — start watcher + web UI now (opens browser)"))
+    click.echo(dim("    cda serve        — run web UI in foreground (opens browser)"))
     click.echo()
 
 

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/changelog.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.5] - 2026-05-11
+
+### Added
+- **`cda setup`** — master onboarding command: init → pmf install → sync → up. Replaces the four-step manual process with a single command. Idempotent, safe to re-run. Accepts `--skip-sync` and `--no-browser`.
+- **PMF-first architecture**: all background processes (watcher, web UI) start exclusively through the PMF kernel. `cda watch start` and `cda ui start` now display an advisory if the LaunchAgent is not installed.
+- `_pmf_warn_if_not_installed()` helper — emitted before any background service start when the LaunchAgent plist is absent.
+
+### Changed
+- README quickstart simplified to two commands: `pip install code-data-ark` + `cda setup`
+- Added PMF architecture diagram and process management reference to README
+
+## [2.0.4] - 2026-05-11
+
+### Added
+- **`cda pmf install`** — generates and loads a macOS `~/Library/LaunchAgents/com.gocosmix.cda.plist`; CDA starts automatically on login
+- **`cda pmf uninstall`** — unloads and removes the LaunchAgent plist
+- **`cda pmf up`** — starts watcher + web UI in one command; opens browser when the server is ready; called by launchd on login
+- **Browser auto-open**: `cda serve`, `cda ui start`, and `cda pmf start ui` now open a browser tab when the server is ready (`--no-browser` to disable)
+- `cda.kernel.pmf_kernel`: `install_launchd()`, `uninstall_launchd()`, `generate_plist()`, `plist_path()`, `open_browser_when_ready()`, `wait_for_port_and_open_browser()`
+
 ## [2.0.3] - 2026-05-11
 
 ### Fixed

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-data-ark"
-version = "2.0.3"
+version = "2.0.5"
 description = "Code Data Ark — local observability and intelligence platform for VS Code + Copilot Chat sessions"
 readme = "readme.md"
 license = "MIT"

{code_data_ark-2.0.3 → code_data_ark-2.0.5}/readme.md

@@ -78,48 +78,67 @@ make install-dev
 
 ## ⚡ Quick Start
 
-1. **Install**
-
 ```bash
 pip install code-data-ark
+cda setup
 ```
 
-2. **Initialize — create `~/.cda/` and validate your VS Code data path**
+That's it. `cda setup` runs four steps in sequence:
 
-```bash
-cda init
-```
+| Step | What it does |
+|------|-------------|
+| **1. Init** | Creates `~/.cda/` directory tree, validates your VS Code data path |
+| **2. PMF install** | Registers a macOS LaunchAgent — CDA starts automatically on every login |
+| **3. Sync** | Ingests all VS Code + Copilot session data into `~/.cda/data/cda.db` |
+| **4. Up** | Starts the watcher daemon and web UI via the PMF kernel, opens browser |
+
+After setup, everything is managed by the **PMF kernel**. On every login, `launchd` calls `cda pmf up` which starts the watcher and web UI. No terminal interaction required.
 
-3. **Ingest all VS Code session data**
+### Options
 
 ```bash
-cda sync
+cda setup --skip-sync     # Skip initial ingest (run `cda sync` manually later)
+cda setup --no-browser    # Don't open browser when the UI starts
 ```
 
-4. **Start the live watcher daemon**
+### After setup
 
 ```bash
-cda watch start
+cda check           # Full system health diagnostic
+cda sync            # Re-ingest after significant new session activity
+cda pmf services    # View all running services and their status
+cda pmf uninstall   # Remove the auto-start LaunchAgent registration
 ```
 
-5. **Open the web dashboard**
+## 🔧 Process Management (PMF)
 
-```bash
-cda serve   # → http://127.0.0.1:10001
+All background processes run through the embedded PMF kernel. The LaunchAgent is the entry point — nothing starts directly on the host outside of PMF.
+
+```
+launchd (login)
+  └─ cda pmf up
+       ├─ PMF kernel → watcher daemon   (cda.pipeline.watcher)
+       └─ PMF kernel → web UI server    (cda.ui.web)
 ```
 
-6. **Build semantic intelligence** (optional, requires `sentence-transformers`)
+### PMF commands
 
 ```bash
-cda embed build
+cda pmf services           # List all services with status and PID
+cda pmf start <service>    # Start a service (watcher, ui, sync, reconstruct, embed-build)
+cda pmf stop <service>     # Stop a service
+cda pmf restart <service>  # Restart a service
+cda pmf logs <service>     # Tail the service log
+cda pmf up                 # Start watcher + UI (opens browser) — same as launchd trigger
+cda pmf install            # Register LaunchAgent (done automatically by cda setup)
+cda pmf uninstall          # Remove LaunchAgent
 ```
 
 ## 🌐 Web UI
 
-- **Background service**: `cda ui start`
-- **Stop service**: `cda ui stop`
-- **Service status**: `cda ui status`
-- **Foreground mode**: `cda serve`
+- **Background service** (default after setup): managed by PMF, starts on login
+- **Foreground mode**: `cda serve` — runs in the terminal, opens browser, Ctrl+C to stop
+- **Access**: `http://127.0.0.1:10001`
 
 The web UI includes:
 

code_data_ark-2.0.5/version

@@ -0,0 +1 @@
+2.0.5

code_data_ark-2.0.3/version

@@ -1 +0,0 @@
-2.0.3