arkaos 2.18.1 → 2.19.1

package/README.md

@@ -161,7 +161,7 @@ ArkaOS doesn't just execute — it **learns, dreams, and researches**.
 Every solution you implement is captured and indexed. When you need authentication in a new Laravel project, ArkaOS already knows how you did it in the last three projects — with the exact pattern, configuration, and lessons learned.
 
 - **Dual-write**: Obsidian (human-readable) + Vector DB (semantic search)
-- **Cross-project**: Knowledge from Rockport applies to ClubeFashion
+- **Cross-project**: Knowledge from ClientRetail applies to ClientFashion
 - **Confidence scoring**: Patterns validated 3+ times become "validated patterns"
 
 ### Dreaming (runs at 02:00)
@@ -185,7 +185,7 @@ Pending reflections from Dreaming:
 
 2. [technical] Sync retry — improve
    Fixed backoff can cause thundering herd. Use exponential
-   backoff with jitter (validated pattern from Rockport).
+   backoff with jitter (validated pattern from ClientRetail).
 
 Want me to elaborate?
 ```
@@ -204,11 +204,11 @@ Intelligence Briefing — 2026-04-10
 
 ACTION REQUIRED:
 - Laravel 12.1.3 security patch — SQL injection in whereHas.
-  Affects: ClubeFashion, Fovory. Fix: composer update laravel/framework.
+  Affects: ClientFashion, ClientCommerce. Fix: composer update laravel/framework.
 
 OPPORTUNITIES:
-- Shopify Winter '26 bulk product API — Fovory sync could be 10x faster.
-- Nuxt 4 RC2 migration guide published — start preparing ZugaTV.
+- Shopify Winter '26 bulk product API — ClientCommerce sync could be 10x faster.
+- Nuxt 4 RC2 migration guide published — start preparing ClientVideo.
 
 COMPETITOR WATCH:
 - CrewAI v3 launched memory layer — similar to our Cognitive Layer
@@ -233,9 +233,9 @@ arkaos scheduler logs         # View logs
 ArkaOS manages client projects as **ecosystems** — groups of related projects with dedicated squads.
 
 ```
-/rockport          → Rockport ecosystem (4 projects: API, frontend, admin, docs)
-/fovory            → Fovory ecosystem (supplier sync + Shopify theme)
-/clubefashion      → ClubeFashion (6 projects: CRM, store, API, migration...)
+/client_retail          → ClientRetail ecosystem (4 projects: API, frontend, admin, docs)
+/client_commerce            → ClientCommerce ecosystem (supplier sync + Shopify theme)
+/client_fashion      → ClientFashion (6 projects: CRM, store, API, migration...)
 /edp               → EDP (3 projects: portal, API, analytics)
 ```
 

package/VERSION

@@ -1 +1 @@
-2.18.1
+2.19.1

package/config/cognition/prompts/dreaming.md

@@ -70,7 +70,7 @@ vector = VectorWriter(os.path.expanduser("~/.arkaos/knowledge.db"))
 
 - Compare today's errors with past errors — if same error type appears > 2 times, create Anti-Pattern entry
 - Compare today's solutions with past solutions — if same pattern appears > 2 times, promote to Validated Pattern
-- Detect inconsistencies between projects ("In Rockport used X, in ClubeFashion used Y for same problem")
+- Detect inconsistencies between projects ("In ClientRetail used X, in ClientFashion used Y for same problem")
 
 ## Phase 4: Curation and Consolidation
 
@@ -123,7 +123,7 @@ quality_score: 75
 entries_created: 4
 entries_updated: 2
 insights_generated: 3
-projects_active: [fovory, rockport, clubefashion]
+projects_active: [client_commerce, client_retail, client_fashion]
 ---
 
 # Dreaming Report — YYYY-MM-DD
@@ -199,7 +199,7 @@ Write structured metrics to `~/.arkaos/logs/dreaming/YYYY-MM-DD.json`:
     "entries_updated": 2,
     "insights_generated": 3,
     "captures_processed": 15,
-    "projects_reviewed": ["fovory", "rockport"]
+    "projects_reviewed": ["client_commerce", "client_retail"]
 }
 ```
 

package/config/hooks/cwd-changed.ps1

@@ -43,7 +43,13 @@ if ([string]::IsNullOrWhiteSpace($newCwd)) { exit 0 }
 if (-not (Test-Path -LiteralPath $newCwd -PathType Container)) { exit 0 }
 
 # ─── Detect ecosystem from ecosystems.json ─────────────────────────────
-$ecosystemsFile = Join-Path $env:USERPROFILE '.claude\skills\arka\knowledge\ecosystems.json'
+# Canonical path is %USERPROFILE%\.arkaos\ecosystems.json (ADR 2026-04-17).
+# Falls back to the legacy skill-dir path until v2.21.0.
+$ecosystemsFile = Join-Path $env:USERPROFILE '.arkaos\ecosystems.json'
+if (-not (Test-Path -LiteralPath $ecosystemsFile)) {
+    $legacyEcosystems = Join-Path $env:USERPROFILE '.claude\skills\arka\knowledge\ecosystems.json'
+    if (Test-Path -LiteralPath $legacyEcosystems) { $ecosystemsFile = $legacyEcosystems }
+}
 $ecosystem = ''
 $ecosystemName = ''
 
@@ -115,15 +121,17 @@ if (Test-Path -LiteralPath $composerJson) {
 
 # ─── Check for project descriptor ─────────────────────────────────────
 $dirName = Split-Path -Leaf $newCwd.TrimEnd('\','/')
-$projectsDir   = Join-Path $env:USERPROFILE '.claude\skills\arka\projects'
-$descriptorFile = Join-Path $projectsDir "$dirName.md"
-$descriptorDir  = Join-Path (Join-Path $projectsDir $dirName) 'PROJECT.md'
+$newProjectsDir    = Join-Path $env:USERPROFILE '.arkaos\projects'
+$legacyProjectsDir = Join-Path $env:USERPROFILE '.claude\skills\arka\projects'
 
 $descriptor = ''
-if (Test-Path -LiteralPath $descriptorFile) {
-    $descriptor = $descriptorFile
-} elseif (Test-Path -LiteralPath $descriptorDir) {
-    $descriptor = $descriptorDir
+foreach ($candidate in @(
+    (Join-Path $newProjectsDir    "$dirName.md"),
+    (Join-Path (Join-Path $newProjectsDir    $dirName) 'PROJECT.md'),
+    (Join-Path $legacyProjectsDir "$dirName.md"),
+    (Join-Path (Join-Path $legacyProjectsDir $dirName) 'PROJECT.md')
+)) {
+    if (Test-Path -LiteralPath $candidate) { $descriptor = $candidate; break }
 }
 
 # ─── Build context output ─────────────────────────────────────────────

package/config/hooks/cwd-changed.sh

@@ -13,7 +13,13 @@ if [ -z "$NEW_CWD" ] || [ ! -d "$NEW_CWD" ]; then
 fi
 
 # ─── Detect ecosystem from ecosystems.json ─────────────────────────────
-ECOSYSTEMS_FILE="$HOME/.claude/skills/arka/knowledge/ecosystems.json"
+# Canonical path is ~/.arkaos/ecosystems.json (ADR 2026-04-17). During the
+# deprecation window we fall back to the legacy skill-dir path. The legacy
+# fallback is removed in v2.21.0.
+ECOSYSTEMS_FILE="$HOME/.arkaos/ecosystems.json"
+if [ ! -f "$ECOSYSTEMS_FILE" ] && [ -f "$HOME/.claude/skills/arka/knowledge/ecosystems.json" ]; then
+  ECOSYSTEMS_FILE="$HOME/.claude/skills/arka/knowledge/ecosystems.json"
+fi
 ECOSYSTEM=""
 ECOSYSTEM_NAME=""
 
@@ -75,16 +81,19 @@ elif [ -f "$NEW_CWD/pyproject.toml" ]; then
 fi
 
 # ─── Check for project descriptor ─────────────────────────────────────
+# New canonical path: ~/.arkaos/projects/. Legacy fallback remains until v2.21.0.
 DIR_NAME=$(basename "$NEW_CWD")
 DESCRIPTOR=""
-DESCRIPTOR_FILE="$HOME/.claude/skills/arka/projects/${DIR_NAME}.md"
-DESCRIPTOR_DIR="$HOME/.claude/skills/arka/projects/${DIR_NAME}/PROJECT.md"
-
-if [ -f "$DESCRIPTOR_FILE" ]; then
-  DESCRIPTOR="$DESCRIPTOR_FILE"
-elif [ -f "$DESCRIPTOR_DIR" ]; then
-  DESCRIPTOR="$DESCRIPTOR_DIR"
-fi
+for CANDIDATE in \
+  "$HOME/.arkaos/projects/${DIR_NAME}.md" \
+  "$HOME/.arkaos/projects/${DIR_NAME}/PROJECT.md" \
+  "$HOME/.claude/skills/arka/projects/${DIR_NAME}.md" \
+  "$HOME/.claude/skills/arka/projects/${DIR_NAME}/PROJECT.md"; do
+  if [ -f "$CANDIDATE" ]; then
+    DESCRIPTOR="$CANDIDATE"
+    break
+  fi
+done
 
 # ─── Build context output ─────────────────────────────────────────────
 CONTEXT=""

package/core/runtime/user_paths.py

@@ -0,0 +1,115 @@
+"""Canonical resolver for ArkaOS user-local data paths.
+
+User-mutable data lives under ~/.arkaos/. The installed skill bundle at
+~/.claude/skills/arka/ is read-only and installer-managed. Two historical
+paths still receive user writes in some installs:
+
+    ~/.claude/skills/arka/projects/*.md
+    ~/.claude/skills/arka/knowledge/ecosystems.json
+
+This module returns the canonical new path when present, falls back to the
+legacy path with a one-shot deprecation warning, and returns None when
+neither exists. Callers treat None as empty. See ADR
+docs/adr/2026-04-17-user-data-separation.md.
+
+Legacy fallback sunsets in v2.21.0.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_LEGACY_SKILLS_ROOT = Path.home() / ".claude" / "skills" / "arka"
+_USER_DATA_ROOT = Path.home() / ".arkaos"
+
+_warned: set[str] = set()
+
+
+def user_data_root() -> Path:
+    """Root directory for ArkaOS user-local state."""
+    return _USER_DATA_ROOT
+
+
+def projects_dir() -> Path | None:
+    """Resolve the user projects directory.
+
+    Returns the new path when it exists, else the legacy path with a
+    one-shot deprecation warning, else None.
+    """
+    new = _USER_DATA_ROOT / "projects"
+    legacy = _LEGACY_SKILLS_ROOT / "projects"
+    return _resolve_with_fallback("projects_dir", new, legacy)
+
+
+def ecosystems_file() -> Path | None:
+    """Resolve the ecosystems registry file.
+
+    Returns the new path when it exists, else the legacy path with a
+    one-shot deprecation warning, else None.
+    """
+    new = _USER_DATA_ROOT / "ecosystems.json"
+    legacy = _LEGACY_SKILLS_ROOT / "knowledge" / "ecosystems.json"
+    return _resolve_with_fallback("ecosystems_file", new, legacy)
+
+
+def projects_dir_for_write() -> Path:
+    """Return the write target for user project descriptors.
+
+    Writers always target the new path. The directory is created if absent.
+    """
+    new = _USER_DATA_ROOT / "projects"
+    new.mkdir(parents=True, exist_ok=True)
+    return new
+
+
+def ecosystems_file_for_write() -> Path:
+    """Return the write target for the ecosystems registry.
+
+    Writers always target the new path. Parent directory is created if absent.
+    """
+    new = _USER_DATA_ROOT / "ecosystems.json"
+    new.parent.mkdir(parents=True, exist_ok=True)
+    return new
+
+
+def legacy_projects_dir() -> Path:
+    """Legacy projects directory (for migration tooling only)."""
+    return _LEGACY_SKILLS_ROOT / "projects"
+
+
+def legacy_ecosystems_file() -> Path:
+    """Legacy ecosystems file (for migration tooling only)."""
+    return _LEGACY_SKILLS_ROOT / "knowledge" / "ecosystems.json"
+
+
+def reset_warnings() -> None:
+    """Clear the per-process deprecation warning cache.
+
+    Intended for tests. Real runtime should emit each warning exactly once.
+    """
+    _warned.clear()
+
+
+def _resolve_with_fallback(kind: str, new: Path, legacy: Path) -> Path | None:
+    if new.exists():
+        return new
+    if legacy.exists():
+        _warn_once(kind, legacy)
+        return legacy
+    return None
+
+
+def _warn_once(kind: str, legacy: Path) -> None:
+    if kind in _warned:
+        return
+    _warned.add(kind)
+    logger.warning(
+        "ArkaOS: reading %s from legacy location %s. "
+        "This path is deprecated and will be removed in v2.21.0. "
+        "Run `npx arkaos@latest migrate-user-data` or `/arka update` to move your data to ~/.arkaos/.",
+        kind,
+        legacy,
+    )

package/core/sync/engine.py

@@ -11,6 +11,10 @@ import re
 import sys
 from pathlib import Path
 
+from core.runtime.user_paths import (
+    ecosystems_file as resolve_ecosystems_file,
+    projects_dir as resolve_projects_dir,
+)
 from core.sync.manifest import build_manifest
 from core.sync.discovery import discover_all_projects
 from core.sync.mcp_optimizer import optimize_all_mcps
@@ -169,13 +173,29 @@ def _parse_scan_dirs(projects_dir_str: str) -> list[Path]:
 
 
 def _discover_projects(arkaos_home: Path, skills_dir: Path) -> list:
-    """Combine profile.json dirs, descriptor dir, and ecosystems into projects."""
-    descriptor_dir = skills_dir / "arka" / "projects"
-    ecosystems_file = skills_dir / "arka" / "knowledge" / "ecosystems.json"
+    """Combine profile.json dirs, descriptor dir, and ecosystems into projects.
+
+    Project descriptors and the ecosystems registry are user-local data and
+    live under ~/.arkaos/ (see ADR 2026-04-17-user-data-separation). During
+    the deprecation window, reads fall back to the legacy paths under
+    skills_dir with a one-shot warning. `skills_dir` is kept in the
+    signature for backward compatibility and test ergonomics but is no
+    longer consulted for user data.
+    """
+    del skills_dir  # retained for signature stability; unused.
+
+    # resolve_*() returns None when neither the new nor legacy path exists.
+    # `discover_all_projects` requires concrete Path objects but calls
+    # `.exists()` internally, so substituting the (non-existent) canonical
+    # path keeps the contract: missing → returns an empty project list.
+    descriptor_dir = resolve_projects_dir() or (Path.home() / ".arkaos" / "projects")
+    ecosystems_path = resolve_ecosystems_file() or (
+        Path.home() / ".arkaos" / "ecosystems.json"
+    )
 
     scan_dirs = _load_scan_dirs_from_profile(arkaos_home)
 
-    return discover_all_projects(descriptor_dir, scan_dirs, ecosystems_file)
+    return discover_all_projects(descriptor_dir, scan_dirs, ecosystems_path)
 
 
 def _load_scan_dirs_from_profile(arkaos_home: Path) -> list[Path]:

package/installer/adapters/claude-code.js

@@ -105,19 +105,20 @@ export default {
     ];
 
     // Statusline — ArkaOS branded status bar
+    // Claude Code reads the camelCase "statusLine" key; the lowercase
+    // "statusline" variant is silently ignored.
     const configDir = join(installDir, "config");
     const statuslineFile = IS_WINDOWS ? "statusline.ps1" : "statusline.sh";
     const statuslinePath = join(configDir, statuslineFile);
     if (existsSync(statuslinePath)) {
-      if (IS_WINDOWS) {
-        settings.statusline = {
-          command: `powershell -NoProfile -ExecutionPolicy Bypass -File "${statuslinePath}"`,
-        };
-      } else {
-        settings.statusline = {
-          command: statuslinePath,
-        };
-      }
+      const command = IS_WINDOWS
+        ? `powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "${statuslinePath}"`
+        : statuslinePath;
+      settings.statusLine = {
+        type: "command",
+        command,
+        padding: 2,
+      };
     }
 
     writeFileSync(settingsPath, JSON.stringify(settings, null, 2));

package/installer/cli.js

@@ -41,6 +41,7 @@ Usage:
   npx arkaos init             Initialize project config (.arkaos.json)
   npx arkaos update           Update to latest version
   npx arkaos migrate          Migrate from v1 to v2
+  npx arkaos migrate-user-data  Move user data (~/.claude/skills/arka/ → ~/.arkaos/)
   npx arkaos dashboard        Start monitoring dashboard
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
   npx arkaos doctor           Run health checks
@@ -102,6 +103,12 @@ async function main() {
       await migrate();
       break;
 
+    case "migrate-user-data": {
+      const { migrateUserData, printMigrationReport } = await import("./migrate-user-data.js");
+      printMigrationReport(migrateUserData());
+      break;
+    }
+
     case "keys": {
       const { keys: keysCmd } = await import("./keys.js");
       await keysCmd(positionals.slice(1));

package/installer/index.js

@@ -34,8 +34,28 @@ export async function install({ runtime, path, force }) {
   // ═══ Step 1: Create directories ═══
   step(1, 14, "Creating directories...");
   ensureDir(installDir);
-  const dirs = ["config", "config/hooks", "agents", "media", "session-digests", "vault"];
+  const dirs = ["config", "config/hooks", "agents", "media", "session-digests", "vault", "projects", "logs"];
   for (const d of dirs) ensureDir(join(installDir, d));
+
+  // Seed an empty ecosystems.json the first time; never overwrite existing user data.
+  const ecosystemsPath = join(installDir, "ecosystems.json");
+  if (!existsSync(ecosystemsPath)) {
+    writeFileSync(
+      ecosystemsPath,
+      JSON.stringify(
+        {
+          _meta: {
+            description: "ArkaOS — user-local ecosystem registry",
+            note: "Populated by /arka onboard. Never committed to the public repo.",
+            updated: new Date().toISOString().slice(0, 10),
+          },
+          ecosystems: {},
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  }
   ok(`${dirs.length + 1} directories ready`);
 
   // ═══ Step 2: Detect v1 installation ═══
@@ -239,6 +259,27 @@ export async function install({ runtime, path, force }) {
   };
   writeFileSync(join(installDir, "install-manifest.json"), JSON.stringify(manifest, null, 2));
 
+  // Seed sync-state.json so session-start.sh does not read a missing file as
+  // version drift and permanently show [arka:update-available] on a fresh
+  // install. Schema aligned with core/sync/reporter.py write_sync_state.
+  const syncStatePath = join(installDir, "sync-state.json");
+  if (!existsSync(syncStatePath)) {
+    writeFileSync(
+      syncStatePath,
+      JSON.stringify(
+        {
+          version: VERSION,
+          last_sync: new Date().toISOString(),
+          projects_synced: 0,
+          skills_synced: 0,
+          errors: [],
+        },
+        null,
+        2,
+      ),
+    );
+  }
+
   const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
 
   console.log(`

package/installer/migrate-user-data.js

@@ -0,0 +1,132 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const LEGACY_SKILLS_ROOT = join(homedir(), ".claude", "skills", "arka");
+const USER_DATA_ROOT = join(homedir(), ".arkaos");
+
+const LEGACY_PROJECTS = join(LEGACY_SKILLS_ROOT, "projects");
+const LEGACY_ECOSYSTEMS = join(LEGACY_SKILLS_ROOT, "knowledge", "ecosystems.json");
+const NEW_PROJECTS = join(USER_DATA_ROOT, "projects");
+const NEW_ECOSYSTEMS = join(USER_DATA_ROOT, "ecosystems.json");
+const LOGS_DIR = join(USER_DATA_ROOT, "logs");
+
+/**
+ * Move user-local project descriptors and ecosystems registry from the
+ * legacy skill directory to ~/.arkaos/. Idempotent: items already present
+ * at the destination are left alone and logged as conflicts.
+ *
+ * @returns {{ moved: string[], skipped: string[], conflicts: string[], logPath: string|null }}
+ */
+export function migrateUserData({ dryRun = false } = {}) {
+  ensureDataRoot();
+
+  const projectsResult = migrateProjects({ dryRun });
+  const ecosystemsResult = migrateEcosystems({ dryRun });
+
+  const moved = [...projectsResult.moved, ...ecosystemsResult.moved];
+  const skipped = [...projectsResult.skipped, ...ecosystemsResult.skipped];
+  const conflicts = [...projectsResult.conflicts, ...ecosystemsResult.conflicts];
+
+  const logPath = writeReport({ moved, skipped, conflicts, dryRun });
+  return { moved, skipped, conflicts, logPath };
+}
+
+export function printMigrationReport(result) {
+  const { moved, conflicts, logPath } = result;
+  if (moved.length === 0 && conflicts.length === 0) {
+    console.log("  ✓ User data already migrated, nothing to move.");
+    return;
+  }
+  console.log(`  ✓ Migration: ${moved.length} moved, ${conflicts.length} conflicts`);
+  for (const m of moved) console.log(`    + ${m}`);
+  for (const c of conflicts) console.log(`    ! ${c}`);
+  if (logPath) console.log(`  Log: ${logPath}`);
+}
+
+function ensureDataRoot() {
+  if (!existsSync(USER_DATA_ROOT)) mkdirSync(USER_DATA_ROOT, { recursive: true });
+  if (!existsSync(NEW_PROJECTS)) mkdirSync(NEW_PROJECTS, { recursive: true });
+}
+
+function migrateProjects({ dryRun }) {
+  const moved = [];
+  const skipped = [];
+  const conflicts = [];
+
+  if (!existsSync(LEGACY_PROJECTS) || !statSync(LEGACY_PROJECTS).isDirectory()) {
+    skipped.push("projects/: legacy directory absent");
+    return { moved, skipped, conflicts };
+  }
+
+  for (const entry of readdirSync(LEGACY_PROJECTS)) {
+    const src = join(LEGACY_PROJECTS, entry);
+    const dst = join(NEW_PROJECTS, entry);
+    if (existsSync(dst)) {
+      conflicts.push(`projects/${entry}: destination already present, left source untouched`);
+      continue;
+    }
+    if (dryRun) {
+      moved.push(`projects/${entry} (dry-run)`);
+      continue;
+    }
+    try {
+      renameSync(src, dst);
+      moved.push(`projects/${entry}`);
+    } catch (err) {
+      conflicts.push(`projects/${entry}: ${err.message}`);
+    }
+  }
+  return { moved, skipped, conflicts };
+}
+
+function migrateEcosystems({ dryRun }) {
+  const moved = [];
+  const skipped = [];
+  const conflicts = [];
+
+  if (!existsSync(LEGACY_ECOSYSTEMS)) {
+    skipped.push("ecosystems.json: legacy file absent");
+    return { moved, skipped, conflicts };
+  }
+  if (existsSync(NEW_ECOSYSTEMS)) {
+    conflicts.push("ecosystems.json: destination already present, left source untouched");
+    return { moved, skipped, conflicts };
+  }
+  if (dryRun) {
+    moved.push("ecosystems.json (dry-run)");
+    return { moved, skipped, conflicts };
+  }
+  try {
+    renameSync(LEGACY_ECOSYSTEMS, NEW_ECOSYSTEMS);
+    moved.push("ecosystems.json");
+  } catch (err) {
+    conflicts.push(`ecosystems.json: ${err.message}`);
+  }
+  return { moved, skipped, conflicts };
+}
+
+function writeReport({ moved, skipped, conflicts, dryRun }) {
+  if (moved.length === 0 && conflicts.length === 0) return null;
+  if (!existsSync(LOGS_DIR)) mkdirSync(LOGS_DIR, { recursive: true });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const logPath = join(LOGS_DIR, `migration-${stamp}.log`);
+  const body = [
+    `ArkaOS user-data migration — ${new Date().toISOString()}`,
+    `Source: ${LEGACY_SKILLS_ROOT}`,
+    `Destination: ${USER_DATA_ROOT}`,
+    `Dry-run: ${dryRun}`,
+    "",
+    `Moved (${moved.length}):`,
+    ...moved.map(m => `  - ${m}`),
+    "",
+    `Conflicts (${conflicts.length}):`,
+    ...conflicts.map(c => `  - ${c}`),
+    "",
+    `Skipped (${skipped.length}):`,
+    ...skipped.map(s => `  - ${s}`),
+    "",
+  ].join("\n");
+  if (!dryRun) writeFileSync(logPath, body);
+  return logPath;
+}

package/installer/update.js

@@ -5,6 +5,7 @@ import { execSync } from "node:child_process";
 import { ensureVenv, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
+import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
 import { IS_WINDOWS, HOOK_EXT } from "./platform.js";
 import { fileURLToPath } from "node:url";
 
@@ -37,6 +38,14 @@ export async function update() {
     console.log(`         \u26a0 Legacy hook state migration skipped: ${err.message}`);
   }
 
+  // User-data separation (ADR 2026-04-17): move descriptors and ecosystems
+  // from ~/.claude/skills/arka/ to ~/.arkaos/. Idempotent, non-destructive.
+  try {
+    printMigrationReport(migrateUserData());
+  } catch (err) {
+    console.log(`         \u26a0 User-data migration skipped: ${err.message}`);
+  }
+
   const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
   const profile = existsSync(profilePath) ? JSON.parse(readFileSync(profilePath, "utf-8")) : {};
 
@@ -258,7 +267,7 @@ export async function update() {
   // main `/arka` skill, so any department skill (arka-dev, arka-brand,
   // etc.) or sub-skill (arka-code-review, arka-viral, etc.) or agent
   // persona added after the original install was silently missing on
-  // upgrade. Discovered during Marlon's bake-in: 233 top-level arka-*
+  // upgrade. Discovered during ClientAdvisory's bake-in: 233 top-level arka-*
   // skills on his WSL (deployed long ago by install.sh) vs 1 skill on
   // his Windows install (only the main /arka). The Node installer
   // never deployed anything else.

package/knowledge/ecosystems.json

@@ -2,7 +2,7 @@
   "_meta": {
     "description": "ARKA OS — Project Ecosystem Registry (user-local, populated after install)",
     "format": "Ecosystems group related projects that share squads, stacks, and conventions.",
-    "note": "This file ships empty. Users define their own ecosystems locally via /arka onboard or by editing ~/.claude/skills/arka/knowledge/ecosystems.json after installation. Client names and internal project data MUST NOT be committed to the public repository.",
+    "note": "This file ships empty. Users define their own ecosystems locally in ~/.arkaos/ecosystems.json (populated by /arka onboard). Client names and internal project data MUST NOT be committed to the public repository.",
     "updated": "2026-04-17"
   },
   "ecosystems": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.18.1",
+  "version": "2.19.1",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.18.1"
+version = "2.19.1"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}