code-data-ark 2.0.4__tar.gz → 2.0.6__tar.gz

{code_data_ark-2.0.4 → code_data_ark-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-data-ark
-Version: 2.0.4
+Version: 2.0.6
 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
@@ -95,10 +95,17 @@ The runtime is managed by an embedded process kernel (PMF) that supervises the w
 pip install code-data-ark
 ```
 
+> **macOS / system Python note**: pip installs the `cda` binary to `~/Library/Python/3.x/bin/` which is not on `PATH` by default. Use the fallback below — `cda setup` will fix PATH for you automatically:
+>
+> ```bash
+> python3 -m cda setup
+> ```
+
 ### Install with pipx
 
 ```bash
 pipx install code-data-ark
+# pipx automatically manages PATH — `cda setup` works immediately
 ```
 
 ### Install from source
@@ -117,52 +124,73 @@ pip install -e ".[dev]"
 make install-dev
 ```
 
-> The `cda` console command is installed into your active Python environment's `bin` directory. Activate your virtual environment before running `cda`.
+> The `cda` console command is installed into your Python environment's `bin` directory. If it isn't on PATH yet, use `python3 -m cda setup` — setup patches `~/.zprofile` automatically.
 
 ## ⚡ Quick Start
 
-1. **Install**
-
 ```bash
 pip install code-data-ark
+python3 -m cda setup   # use this if `cda` isn't on PATH yet
 ```
 
-2. **Initialize — create `~/.cda/` and validate your VS Code data path**
+After the first run, `cda setup` patches `~/.zprofile` so `cda` is on PATH in every new terminal.
 
-```bash
-cda init
-```
+`cda setup` runs four steps in sequence:
+
+| Step | What it does |
+|------|-------------|
+| **1. Init** | Creates `~/Library/goCosmix/apps/code-data-ark/` — all app data in one organized namespace. Also patches `~/.zprofile` if `cda` isn't on PATH yet. |
+| **2. PMF install** | Registers a macOS LaunchAgent — CDA starts automatically on every login via `cda pmf up` |
+| **3. Sync** | Ingests all VS Code + Copilot session data into `cda.db` |
+| **4. Up** | Starts the watcher daemon and web UI via the PMF kernel, opens browser |
 
-3. **Ingest all VS Code session data**
+All data lives in `~/Library/goCosmix/apps/code-data-ark/`. After setup, everything is managed by the **PMF kernel** — no terminal interaction required.
+
+### 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.6/cda/__main__.py

@@ -0,0 +1,10 @@
+"""
+Allows `python3 -m cda <command>` as a fallback when the `cda` binary
+is not yet on PATH (e.g. immediately after `pip install code-data-ark`).
+
+    python3 -m cda setup
+"""
+from cda.ui.cli import main
+
+if __name__ == "__main__":
+    main()

{code_data_ark-2.0.4 → code_data_ark-2.0.6}/cda/kernel/paths.py

@@ -5,10 +5,16 @@ CDA_HOME is the single root for all runtime state (DB, PID files, logs,
 queue, PMF runtime).  It is resolved exactly once at import time via:
 
   1. CDA_HOME environment variable (absolute path)
-  2. ~/.cda/  (default — survives pip install, editable install, CI)
+  2. ~/Library/goCosmix/apps/code-data-ark/  (macOS default)
+  3. ~/.gocosmix/apps/code-data-ark/          (fallback on non-macOS)
 
-Pipeline stages and the CLI all import from here so every module agrees
-on the same paths regardless of where the package is installed.
+All goCosmix apps share the ~/Library/goCosmix/ namespace:
+
+  ~/Library/goCosmix/
+  ├── apps/
+  │   ├── code-data-ark/   ← CDA_HOME
+  │   └── ...              ← future goCosmix apps
+  └── system/              ← shared goCosmix infrastructure
 """
 
 import os
@@ -17,17 +23,40 @@ from pathlib import Path
 # ── home resolution ──────────────────────────────────────────────────────────
 
 
+def _default_cda_home() -> Path:
+    """Platform-appropriate default for CDA_HOME."""
+    library = Path.home() / "Library"
+    if library.exists():  # macOS
+        return library / "goCosmix" / "apps" / "code-data-ark"
+    return Path.home() / ".gocosmix" / "apps" / "code-data-ark"
+
+
 def get_cda_home() -> Path:
     """Return the CDA home directory, creating it if it doesn't exist."""
     env = os.environ.get("CDA_HOME")
     if env:
         home = Path(env).expanduser().resolve()
     else:
-        home = Path.home() / ".cda"
+        home = _default_cda_home()
     home.mkdir(parents=True, exist_ok=True)
     return home
 
 
+# ── goCosmix namespace (shared across all goCosmix apps) ────────────────────
+
+def get_gocosmix_home() -> Path:
+    """Return ~/Library/goCosmix (macOS) or ~/.gocosmix (other)."""
+    library = Path.home() / "Library"
+    if library.exists():
+        return library / "goCosmix"
+    return Path.home() / ".gocosmix"
+
+
+GOCOSMIX_HOME = get_gocosmix_home()
+GOCOSMIX_APPS = GOCOSMIX_HOME / "apps"
+GOCOSMIX_SYSTEM = GOCOSMIX_HOME / "system"
+
+
 # ── canonical paths (module-level constants, computed once) ─────────────────
 
 CDA_HOME   = get_cda_home()
@@ -49,6 +78,7 @@ RUNTIME_FILE   = PMF_DIR / "runtime.json"
 
 
 def ensure_dirs() -> None:
-    """Create all runtime directories. Safe to call multiple times."""
-    for d in (DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR, PMF_DIR, PMF_LOG_DIR, CONFIG_DIR):
+    """Create all runtime directories (including goCosmix namespace). Safe to call multiple times."""
+    for d in (GOCOSMIX_HOME, GOCOSMIX_APPS, GOCOSMIX_SYSTEM,
+              DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR, PMF_DIR, PMF_LOG_DIR, CONFIG_DIR):
         d.mkdir(parents=True, exist_ok=True)

{code_data_ark-2.0.4 → code_data_ark-2.0.6}/cda/ui/cli.py

@@ -28,7 +28,8 @@ Commands:
   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 init                   First-run setup — create ~/Library/goCosmix/ 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
@@ -80,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()
 
 
@@ -408,7 +417,8 @@ def _ui_is_running():
 @click.option("--port", default=10001, show_default=True, help="Local port for the web UI")
 @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."""
+    """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})
         url = f"http://{host}:{port}"
@@ -788,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}"))
 
@@ -2646,13 +2657,247 @@ 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`.
+    If `cda` isn't on PATH yet, use the fallback:
+
+        python3 -m cda setup
+
+    \b
+    What each step does:
+      1. Init    — create ~/Library/goCosmix/apps/code-data-ark/, patch 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.
+    """
+    import shutil as _shutil
+    import os as _os
+    from cda.kernel.paths import (
+        CDA_HOME, DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR,
+        PMF_DIR, PMF_LOG_DIR, CONFIG_DIR, POLICY_FILE,
+        GOCOSMIX_HOME, GOCOSMIX_APPS, GOCOSMIX_SYSTEM,
+    )
+
+    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()
+
+    # Create full goCosmix namespace + app dirs
+    dirs = [GOCOSMIX_HOME, GOCOSMIX_APPS, GOCOSMIX_SYSTEM,
+            DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR, PMF_DIR, PMF_LOG_DIR, CONFIG_DIR]
+    for d in dirs:
+        existed = d.exists()
+        d.mkdir(parents=True, exist_ok=True)
+        if not existed:
+            click.echo(f"    {green('+')}  {d}")
+        else:
+            click.echo(f"    {green('✓')}  {d}")
+
+    if not POLICY_FILE.exists():
+        POLICY_FILE.write_text("# CDA access policy\n# ALLOW <pattern>\n# DENY  <pattern>\n")
+
+    # Offer migration from legacy ~/.cda/
+    legacy = Path.home() / ".cda"
+    if legacy.exists() and legacy != CDA_HOME:
+        click.echo()
+        click.echo(yellow(f"    ⚠  Legacy data found at {legacy}"))
+        click.echo(yellow("       Run `cda migrate-home` after setup to move it to the new location."))
+
+    # VS Code data dir check
+    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()
+
+    # ── PATH patch ───────────────────────────────────────────────
+    # Detect where pip placed the `cda` binary and ensure it's on PATH.
+    # Works whether invoked as `cda setup` or `python3 -m cda setup`.
+    cda_bin_dir = None
+    cda_bin = _shutil.which("cda")
+    if cda_bin:
+        cda_bin_dir = str(Path(cda_bin).parent)
+    else:
+        # pip install --user puts scripts next to python executable
+        py_bin_dir = Path(sys.executable).parent
+        candidate = py_bin_dir / "cda"
+        if candidate.exists():
+            cda_bin_dir = str(py_bin_dir)
+
+    if cda_bin_dir and cda_bin_dir not in _os.environ.get("PATH", "").split(":"):
+        export_line = f'export PATH="{cda_bin_dir}:$PATH"'
+        zprofile = Path.home() / ".zprofile"
+        existing = zprofile.read_text() if zprofile.exists() else ""
+        if export_line not in existing:
+            with open(zprofile, "a") as f:
+                f.write(f"\n# goCosmix — added by cda setup\n{export_line}\n")
+            click.echo(f"    {green('+')}  PATH updated in ~/.zprofile")
+            click.echo(yellow("         Run `source ~/.zprofile` or open a new terminal to activate."))
+        click.echo(f"    {green('✓')}  cda binary: {cda_bin_dir}/cda")
+    elif cda_bin:
+        click.echo(f"    {green('✓')}  cda binary on PATH: {cda_bin}")
+
+    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` — starts watcher + web UI via PMF kernel."))
+    click.echo(dim("  No terminal required after this."))
+    click.echo()
+
+    pmf_ok = False
+    try:
+        target = install_launchd(CDA_HOME)
+        click.echo(f"    {green('✓')}  LaunchAgent: {target}")
+        click.echo(f"    {green('✓')}  Loaded — CDA starts automatically on every login")
+        pmf_ok = True
+    except PMFKernelError as exc:
+        click.echo(f"    {yellow('⚠')}  LaunchAgent registration failed: {exc}")
+        click.echo(yellow("         Fix 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 a few 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 starts automatically on every login via launchd."))
+    click.echo(dim("  The watcher daemon keeps your session data in sync automatically."))
+    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 the auto-start LaunchAgent"))
+    click.echo()
+
+
 # ─────────────────────────────────────────────
 # INIT
 # ─────────────────────────────────────────────
 
 @cli.command("init")
 def init():
-    """First-run setup — create ~/.cda/ directory structure and validate environment."""
+    """First-run setup — create ~/Library/goCosmix/apps/code-data-ark/ directory structure and validate environment."""
     from cda.kernel.paths import (
         CDA_HOME, DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR,
         PMF_DIR, PMF_LOG_DIR, CONFIG_DIR, POLICY_FILE,

{code_data_ark-2.0.4 → code_data_ark-2.0.6}/changelog.md

@@ -5,6 +5,32 @@ 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.6] - 2026-05-11
+
+### Added
+- **`~/Library/goCosmix/` home namespace** — all goCosmix apps share a unified `~/Library/goCosmix/` directory (macOS) or `~/.gocosmix/` (other). CDA now installs to `~/Library/goCosmix/apps/code-data-ark/` instead of `~/.cda/`. Provides a clean, organized home for all future goCosmix systems.
+- **`GOCOSMIX_HOME`, `GOCOSMIX_APPS`, `GOCOSMIX_SYSTEM`** constants in `cda.kernel.paths` — shared namespace anchors for future goCosmix apps.
+- **Auto PATH patching in `cda setup`** — detects where pip placed the `cda` binary and patches `~/.zprofile` if the bin dir is missing from PATH. Solves the macOS system Python `command not found` blocker.
+- **`python3 -m cda` entry point** (`cda/__main__.py`) — bootstrapping fallback so users can run `python3 -m cda setup` before PATH is configured.
+- **Legacy migration notice** — `cda setup` detects an existing `~/.cda/` and advises running `cda migrate-home`.
+
+### Changed
+- `cda.kernel.paths.get_cda_home()` default changed from `~/.cda` to `~/Library/goCosmix/apps/code-data-ark` (macOS) / `~/.gocosmix/apps/code-data-ark` (other). `CDA_HOME` env var still overrides.
+- `ensure_dirs()` now creates the full goCosmix namespace tree in addition to app-level dirs.
+- README quickstart updated: install command is `python3 -m cda setup` as the safe default.
+- `cda setup` Step 1 shows `+` for new dirs and `✓` for existing ones.
+
+## [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

{code_data_ark-2.0.4 → code_data_ark-2.0.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-data-ark"
-version = "2.0.4"
+version = "2.0.6"
 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.4 → code_data_ark-2.0.6}/readme.md

@@ -52,10 +52,17 @@ The runtime is managed by an embedded process kernel (PMF) that supervises the w
 pip install code-data-ark
 ```
 
+> **macOS / system Python note**: pip installs the `cda` binary to `~/Library/Python/3.x/bin/` which is not on `PATH` by default. Use the fallback below — `cda setup` will fix PATH for you automatically:
+>
+> ```bash
+> python3 -m cda setup
+> ```
+
 ### Install with pipx
 
 ```bash
 pipx install code-data-ark
+# pipx automatically manages PATH — `cda setup` works immediately
 ```
 
 ### Install from source
@@ -74,52 +81,73 @@ pip install -e ".[dev]"
 make install-dev
 ```
 
-> The `cda` console command is installed into your active Python environment's `bin` directory. Activate your virtual environment before running `cda`.
+> The `cda` console command is installed into your Python environment's `bin` directory. If it isn't on PATH yet, use `python3 -m cda setup` — setup patches `~/.zprofile` automatically.
 
 ## ⚡ Quick Start
 
-1. **Install**
-
 ```bash
 pip install code-data-ark
+python3 -m cda setup   # use this if `cda` isn't on PATH yet
 ```
 
-2. **Initialize — create `~/.cda/` and validate your VS Code data path**
+After the first run, `cda setup` patches `~/.zprofile` so `cda` is on PATH in every new terminal.
 
-```bash
-cda init
-```
+`cda setup` runs four steps in sequence:
+
+| Step | What it does |
+|------|-------------|
+| **1. Init** | Creates `~/Library/goCosmix/apps/code-data-ark/` — all app data in one organized namespace. Also patches `~/.zprofile` if `cda` isn't on PATH yet. |
+| **2. PMF install** | Registers a macOS LaunchAgent — CDA starts automatically on every login via `cda pmf up` |
+| **3. Sync** | Ingests all VS Code + Copilot session data into `cda.db` |
+| **4. Up** | Starts the watcher daemon and web UI via the PMF kernel, opens browser |
 
-3. **Ingest all VS Code session data**
+All data lives in `~/Library/goCosmix/apps/code-data-ark/`. After setup, everything is managed by the **PMF kernel** — no terminal interaction required.
+
+### 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.6/version

@@ -0,0 +1 @@
+2.0.6

code_data_ark-2.0.4/version

@@ -1 +0,0 @@
-2.0.4