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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-data-ark
-Version: 2.0.5
+Version: 2.0.7
 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,25 +124,27 @@ 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
 
 ```bash
 pip install code-data-ark
-cda setup
+python3 -m cda setup   # use this if `cda` isn't on PATH yet
 ```
 
-That's it. `cda setup` runs four steps in sequence:
+After the first run, `cda setup` patches `~/.zprofile` so `cda` is on PATH in every new terminal.
+
+`cda setup` runs four steps in sequence:
 
 | 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` |
+| **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 |
 
-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.
+All data lives in `~/Library/goCosmix/apps/code-data-ark/`. After setup, everything is managed by the **PMF kernel** — no terminal interaction required.
 
 ### Options
 

{code_data_ark-2.0.5 → code_data_ark-2.0.7}/cda/__init__.py

@@ -1,3 +1,3 @@
 """Code Data Ark — local observability and intelligence platform for VS Code + Copilot Chat sessions."""
 
-__version__ = "2.0.2"
+__version__ = "2.0.7"

code_data_ark-2.0.7/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.5 → code_data_ark-2.0.7}/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.5 → code_data_ark-2.0.7}/cda/kernel/pmf_kernel.py

@@ -421,6 +421,14 @@ class PMFKernel:
                         pass
                 time.sleep(0.25)
                 wait_seconds += 0.25
+            # Process didn't write its own pid file — write it now using the
+            # spawned process's PID so status checks work correctly.
+            if self._is_process_alive(proc.pid):
+                try:
+                    spec.pid_file.write_text(str(proc.pid))
+                    state["pid"] = proc.pid
+                except Exception:
+                    pass
 
         if spec.service_type == "daemon":
             state["status"] = "running"

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

@@ -28,7 +28,7 @@ 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)
@@ -2671,13 +2671,14 @@ 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`:
+    Run this once after `pip install code-data-ark`.
+    If `cda` isn't on PATH yet, use the fallback:
 
-        cda setup
+        python3 -m cda setup
 
     \b
     What each step does:
-      1. Init    — create ~/.cda/ directory tree, validate VS Code data path
+      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
@@ -2685,11 +2686,13 @@ def setup(skip_sync, no_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,
     )
-    import os as _os
 
     W = 52
     BAR = "═" * W
@@ -2715,14 +2718,28 @@ def setup(skip_sync, no_browser):
     click.echo(bold(bar))
     click.echo()
 
-    dirs = [DATA_DIR, RUN_DIR, LOG_DIR, QUEUE_DIR, PMF_DIR, PMF_LOG_DIR, CONFIG_DIR]
+    # 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)
-        click.echo(f"    {green('✓')}  {d}")
+        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",
@@ -2737,25 +2754,54 @@ def setup(skip_sync, no_browser):
     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` which starts the watcher daemon and"))
-    click.echo(dim("  web UI via the PMF kernel — no terminal required."))
+    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 will start automatically on every login")
+        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("         Ensure `cda` is on PATH, then run `cda pmf install` to retry."))
+        click.echo(yellow("         Fix PATH then run `cda pmf install` to retry."))
     click.echo()
 
     # ── Step 3: Sync ─────────────────────────────────────────────
@@ -2769,7 +2815,7 @@ def setup(skip_sync, no_browser):
         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(dim("  First run may take a few minutes depending on session history."))
         click.echo()
 
         sync_failed = False
@@ -2833,15 +2879,15 @@ def setup(skip_sync, no_browser):
     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("  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 auto-start LaunchAgent registration"))
+    click.echo(dim("    cda pmf uninstall  — remove the auto-start LaunchAgent"))
     click.echo()
 
 
@@ -2851,7 +2897,7 @@ def setup(skip_sync, no_browser):
 
 @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.5 → code_data_ark-2.0.7}/cda/ui/web.py

@@ -1008,7 +1008,7 @@ def get_overview():
                 {("(SELECT AVG(heat_score) FROM session_analysis WHERE heat_score IS NOT NULL)" if has_analysis else "0")} as avg_heat,
                 {("(SELECT COUNT(*) FROM session_analysis WHERE heat_score >= 50)" if has_analysis else "0")} as critical_sessions,
                 {("(SELECT COUNT(*) FROM anomaly_alerts)" if has_alerts else "0")} as alert_count,
-                (SELECT COUNT(DISTINCT workspace_id) FROM sessions) as workspace_count,
+                (SELECT COUNT(*) FROM workspaces) as workspace_count,
                 (SELECT MAX(created_at) FROM sessions) as last_session
         """)
 
@@ -1041,10 +1041,11 @@ def get_overview():
             LIMIT 15
         """)) if has_signals else []
 
+        exchange_count_expr = "(SELECT COUNT(*) FROM exchanges WHERE exchanges.session_id = s.session_id)" if has_exchanges else "0"
         if has_analysis:
-            recent = safe_rows(query_rows("""
+            recent = safe_rows(query_rows(f"""
                 SELECT s.session_id as id, s.title, sa.heat_score,
-                       {("(SELECT COUNT(*) FROM exchanges WHERE exchanges.session_id = s.session_id)" if has_exchanges else "0")} as exchange_count,
+                       {exchange_count_expr} as exchange_count,
                        s.created_at
                 FROM sessions s
                 LEFT JOIN session_analysis sa ON sa.session_id = s.session_id
@@ -1052,9 +1053,9 @@ def get_overview():
                 LIMIT 10
             """))
         else:
-            recent = safe_rows(query_rows("""
+            recent = safe_rows(query_rows(f"""
                 SELECT s.session_id as id, s.title, NULL as heat_score,
-                       {("(SELECT COUNT(*) FROM exchanges WHERE exchanges.session_id = s.session_id)" if has_exchanges else "0")} as exchange_count,
+                       {exchange_count_expr} as exchange_count,
                        s.created_at
                 FROM sessions s
                 ORDER BY s.created_at DESC
@@ -1161,7 +1162,7 @@ def get_session_detail(session_id):
         signals = safe_rows(query_rows("""
             SELECT * FROM exchange_signals
             WHERE session_id = ?
-            ORDER BY created_at DESC
+            ORDER BY ts DESC
         """, (session_id,))) if has_signals else []
 
         signal_summary = safe_rows(query_rows("""
@@ -1195,18 +1196,20 @@ def get_search_results(query, limit=50):
     """Full-text search across exchanges."""
     try:
         results = query_rows("""
-            SELECT DISTINCT
-                s.id as session_id,
+            SELECT
+                e.session_id,
                 s.title,
-                s.heat_score,
+                sa.heat_score,
                 e.id as exchange_id,
-                e.user_input,
-                e.assistant_response,
-                RANK() OVER (ORDER BY rank) as relevance
-            FROM sessions s
-            JOIN exchanges e ON s.id = e.session_id
-            JOIN full_text_search fts ON e.id = fts.exchange_id
-            WHERE fts.full_text_search MATCH ?
+                e.exchange_index,
+                e.user_message,
+                e.response_text,
+                e.user_ts
+            FROM fts_exchanges fts
+            JOIN exchanges e ON fts.rowid = e.id
+            JOIN sessions s ON e.session_id = s.session_id
+            LEFT JOIN session_analysis sa ON sa.session_id = e.session_id
+            WHERE fts_exchanges MATCH ?
             ORDER BY rank
             LIMIT ?
         """, (query, limit))
@@ -1219,13 +1222,11 @@ def get_workspaces():
     """List all workspaces with session counts."""
     try:
         workspaces = query_rows("""
-            SELECT DISTINCT workspace_id,
-                   COUNT(*) as session_count,
-                   MAX(created_at) as last_session
-            FROM sessions
-            WHERE workspace_id IS NOT NULL
-            GROUP BY workspace_id
-            ORDER BY session_count DESC
+            SELECT w.workspace_id, w.uri, w.name, w.type, w.session_count,
+                   (SELECT MAX(s.created_at) FROM sessions s
+                    WHERE s.workspace_id = w.workspace_id) as last_session
+            FROM workspaces w
+            ORDER BY w.session_count DESC
         """)
         return {"workspaces": workspaces}
     except Exception as e:
@@ -1253,9 +1254,9 @@ def get_memory():
     """Get all memory files."""
     try:
         memory = query_rows("""
-            SELECT id, name, size, created_at, updated_at
+            SELECT id, scope, workspace_id, session_id, filename, size_bytes, ingested_at
             FROM memory_files
-            ORDER BY updated_at DESC
+            ORDER BY ingested_at DESC
         """)
         return {"memory": memory}
     except Exception as e:
@@ -1267,21 +1268,25 @@ def get_tool_calls(query_str=None, limit=50):
     try:
         if query_str:
             results = query_rows("""
-                SELECT tc.*, e.session_id, s.title as session_title
+                SELECT tc.id, tc.session_id, tc.exchange_index, tc.request_id,
+                       tc.tool_call_id, tc.tool_name, tc.file_path,
+                       tc.arguments_json, tc.has_output, tc.ingested_at,
+                       s.title as session_title
                 FROM tool_calls tc
-                JOIN exchanges e ON tc.exchange_id = e.id
-                JOIN sessions s ON e.session_id = s.id
-                WHERE tc.tool_name LIKE ? OR tc.arguments LIKE ?
-                ORDER BY tc.created_at DESC
+                JOIN sessions s ON tc.session_id = s.session_id
+                WHERE tc.tool_name LIKE ? OR tc.arguments_json LIKE ?
+                ORDER BY tc.ingested_at DESC
                 LIMIT ?
             """, (f"%{query_str}%", f"%{query_str}%", limit))
         else:
             results = query_rows("""
-                SELECT tc.*, e.session_id, s.title as session_title
+                SELECT tc.id, tc.session_id, tc.exchange_index, tc.request_id,
+                       tc.tool_call_id, tc.tool_name, tc.file_path,
+                       tc.arguments_json, tc.has_output, tc.ingested_at,
+                       s.title as session_title
                 FROM tool_calls tc
-                JOIN exchanges e ON tc.exchange_id = e.id
-                JOIN sessions s ON e.session_id = s.id
-                ORDER BY tc.created_at DESC
+                JOIN sessions s ON tc.session_id = s.session_id
+                ORDER BY tc.ingested_at DESC
                 LIMIT ?
             """, (limit,))
         return {"tool_calls": results, "query": query_str, "count": len(results)}
@@ -1293,10 +1298,11 @@ def get_vfs(session_id):
     """List VFS files for a session."""
     try:
         vfs = query_rows("""
-            SELECT id, session_id, path, size, created_at
+            SELECT id, session_id, source_type, source_path, filename,
+                   content_type, size_bytes, sha256, ingested_at
             FROM vfs
             WHERE session_id = ?
-            ORDER BY path
+            ORDER BY filename
         """, (session_id,))
         return {"vfs": vfs, "session_id": session_id}
     except Exception as e:
@@ -1354,17 +1360,26 @@ def get_tokens(session_id=None):
         if session_id:
             tokens = query_rows("""
                 SELECT
-                    SUM(CAST(json_extract(metadata, '$.token_count') AS INTEGER)) as total_tokens,
-                    COUNT(*) as exchange_count
-                FROM exchanges
+                    SUM(prompt_tokens) as total_prompt,
+                    SUM(completion_tokens) as total_completion,
+                    SUM(cached_tokens) as total_cached,
+                    SUM(prompt_tokens + completion_tokens) as total_tokens,
+                    COUNT(*) as turn_count,
+                    GROUP_CONCAT(DISTINCT model_id) as models
+                FROM token_usage
                 WHERE session_id = ?
             """, (session_id,))
         else:
             tokens = query_rows("""
                 SELECT
-                    SUM(CAST(json_extract(metadata, '$.token_count') AS INTEGER)) as total_tokens,
-                    COUNT(*) as exchange_count
-                FROM exchanges
+                    SUM(prompt_tokens) as total_prompt,
+                    SUM(completion_tokens) as total_completion,
+                    SUM(cached_tokens) as total_cached,
+                    SUM(prompt_tokens + completion_tokens) as total_tokens,
+                    COUNT(*) as turn_count,
+                    COUNT(DISTINCT session_id) as session_count,
+                    GROUP_CONCAT(DISTINCT model_id) as models
+                FROM token_usage
             """)
         return {"tokens": tokens}
     except Exception as e:
@@ -1726,11 +1741,10 @@ def render_tokens():
     return """
     <div class="page-header">
         <div class="page-title">Token Usage</div>
-        <div class="page-subtitle">Token consumption analysis by session.</div>
-    </div>
-    <div class="card">
-        <p>Token usage analysis coming soon.</p>
+        <div class="page-subtitle">Token consumption across all sessions.</div>
     </div>
+    <div id="tokens-summary" class="loading"><div class="spinner"></div>Loading...</div>
+    <div id="tokens-table" style="margin-top:16px"></div>
     """
 
 
@@ -1910,6 +1924,9 @@ function initializePage(page) {
         case 'alerts':
             initAlerts();
             break;
+        case 'tokens':
+            initTokens();
+            break;
         case 'pipeline':
             initPipeline();
             break;
@@ -2358,6 +2375,46 @@ function initKeywords() {
     });
 }
 
+function initTokens() {
+    const summary = document.getElementById('tokens-summary');
+    const table = document.getElementById('tokens-table');
+    if (!summary) return;
+    summary.innerHTML = '<div class="spinner"></div> Loading...';
+    fetch('/api/tokens').then(r => r.json()).then(data => {
+        const t = (data.tokens || [])[0] || {};
+        const fmt = n => (n || 0).toLocaleString();
+        summary.innerHTML = `
+            <div class="grid-4">
+                <div class="card"><div class="card-header">Total Tokens</div><div class="card-value">${fmt(t.total_tokens)}</div></div>
+                <div class="card"><div class="card-header">Prompt</div><div class="card-value">${fmt(t.total_prompt)}</div></div>
+                <div class="card"><div class="card-header">Completion</div><div class="card-value">${fmt(t.total_completion)}</div></div>
+                <div class="card"><div class="card-header">Cached</div><div class="card-value">${fmt(t.total_cached)}</div></div>
+                <div class="card"><div class="card-header">Sessions</div><div class="card-value">${fmt(t.session_count)}</div></div>
+                <div class="card"><div class="card-header">Turns</div><div class="card-value">${fmt(t.turn_count)}</div></div>
+            </div>
+            <div class="card" style="margin-top:12px"><b>Models:</b> ${t.models || 'n/a'}</div>
+        `;
+    }).catch(() => {
+        summary.innerHTML = '<div class="alert alert-danger">Failed to load token data.</div>';
+    });
+    if (table) {
+        table.innerHTML = '<div class="spinner"></div> Loading sessions...';
+        const sql = 'SELECT s.title, tu.session_id, SUM(tu.prompt_tokens) as prompt, SUM(tu.completion_tokens) as completion, SUM(tu.cached_tokens) as cached, SUM(tu.prompt_tokens + tu.completion_tokens) as total, COUNT(*) as turns, GROUP_CONCAT(DISTINCT tu.model_id) as models FROM token_usage tu JOIN sessions s ON tu.session_id = s.session_id GROUP BY tu.session_id ORDER BY total DESC LIMIT 50';
+        fetch('/api/query', {method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({sql: sql})})
+            .then(r => r.json()).then(data => {
+                const rows = data.rows || [];
+                if (!rows.length) { table.innerHTML = '<p>No per-session data.</p>'; return; }
+                const fmt = n => (n || 0).toLocaleString();
+                let html = '<div class="card"><div class="card-header">Top Sessions by Token Usage</div><table class="table"><thead><tr><th>Session</th><th>Total</th><th>Prompt</th><th>Completion</th><th>Cached</th><th>Turns</th><th>Models</th></tr></thead><tbody>';
+                rows.forEach(r => {
+                    html += '<tr><td class="truncate">' + (r.title || r.session_id) + '</td><td>' + fmt(r.total) + '</td><td>' + fmt(r.prompt) + '</td><td>' + fmt(r.completion) + '</td><td>' + fmt(r.cached) + '</td><td>' + r.turns + '</td><td class="truncate">' + (r.models || '') + '</td></tr>';
+                });
+                html += '</tbody></table></div>';
+                table.innerHTML = html;
+            }).catch(() => { table.innerHTML = '<p>Failed to load session breakdown.</p>'; });
+    }
+}
+
 function initWorkspaces() {
     const container = document.getElementById('workspaces-content');
     if (!container) return;
@@ -2737,6 +2794,13 @@ def application(environ, start_response):
             start_response('200 OK', [('Content-Type', 'application/json')])
             return [response]
 
+        elif path == '/api/tokens':
+            session_id = query.get('session_id', [None])[0]
+            data = get_tokens(session_id)
+            response = json.dumps(data).encode('utf-8')
+            start_response('200 OK', [('Content-Type', 'application/json')])
+            return [response]
+
         elif path == '/api/alerts':
             data = get_alerts()
             response = json.dumps(data).encode('utf-8')

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

@@ -5,6 +5,21 @@ 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-data-ark"
-version = "2.0.5"
+version = "2.0.7"
 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.5 → code_data_ark-2.0.7}/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,25 +81,27 @@ 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
 
 ```bash
 pip install code-data-ark
-cda setup
+python3 -m cda setup   # use this if `cda` isn't on PATH yet
 ```
 
-That's it. `cda setup` runs four steps in sequence:
+After the first run, `cda setup` patches `~/.zprofile` so `cda` is on PATH in every new terminal.
+
+`cda setup` runs four steps in sequence:
 
 | 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` |
+| **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 |
 
-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.
+All data lives in `~/Library/goCosmix/apps/code-data-ark/`. After setup, everything is managed by the **PMF kernel** — no terminal interaction required.
 
 ### Options
 

code_data_ark-2.0.7/version

@@ -0,0 +1 @@
+2.0.7

code_data_ark-2.0.5/version

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