arkaos 2.22.1 → 2.25.0

package/core/specs/SPEC-installer-cross-os.md

@@ -0,0 +1,227 @@
+---
+type: spec
+status: approved
+feature: installer-cross-os
+project: ArkaOS
+version: 2.24.0
+pr: PR2 of 6 (Conclave roadmap 2026-05-13)
+branch: feature/v2.24.0-installer-cross-os
+date_created: 2026-05-13
+tags: [spec, arkaos, installer, cross-os, v2.24.0, conclave-pr2]
+---
+
+# SPEC: Installer Cross-OS Completo (v2.24.0)
+
+## Overview
+
+**Problem.** ArkaOS installer is ~65 % cross-OS complete. Obsidian is never auto-installed (only path-detected). Node.js is never validated. `install.sh` hardcodes the GitHub repo URL on line 25 and only scans macOS paths for Obsidian vaults on lines 625–640.
+
+**Goal.** Deliver a full cross-OS install flow (macOS / Linux / Windows) that auto-installs what it can without sudo, reports what needs sudo with copy-paste-ready commands, and falls back gracefully when no package manager is available.
+
+**Actors.** End users running `npx arkaos install` on fresh macOS / Linux / Windows machines; CI pipelines running headless.
+
+## Scope
+
+**In scope (PR2 / v2.24.0):**
+
+| Item | Purpose |
+|---|---|
+| new `installer/package-manager.js` | brew / winget / snap / apt / choco detection + install helpers |
+| new `installer/system-tools.js` | `ensureSystemTools()` phase: Obsidian, Node.js ≥ 20, Python ≥ 3.12 |
+| modify `installer/index.js` | call `ensureSystemTools()` before venv creation |
+| modify `installer/update.js` | re-run `ensureSystemTools()` on `npx arkaos update` |
+| modify `installer/cli.js` | new `npx arkaos doctor` subcommand + `--no-system` flag |
+| new `installer/doctor.js` | diagnose-only report (table format, exit codes 0/1/2) |
+| modify `install.sh` line 25 | `ARKAOS_REPO_URL` env override (default canonical URL) |
+| modify `install.sh` lines 625-640 | add Linux + Windows vault detection |
+| modify `installer/index.js` dashboard step | `pnpm install` / `npm ci` in `dashboard/` if Node ≥ 20 |
+| new `tests/installer/test_package_manager.mjs` | ≥ 10 Node tests |
+| new `tests/installer/test_system_tools.mjs` | ≥ 5 Node tests |
+
+**Out of scope:**
+
+- Auto-update of system tools when newer versions exist (just detect + report).
+- Flatpak / AppImage Obsidian variants on Linux (defer to PR6 cleanup if user demand).
+- Interactive sudo prompt (André chose "print command for manual run" — headless-safe).
+- Aggressive auto-install (André chose hybrid: install what can be installed without sudo; report rest).
+
+## Acceptance Criteria
+
+1. **Fresh macOS install.** Given a Mac without Obsidian, when `npx arkaos install` runs, then `brew install --cask obsidian` is invoked (or printed if brew missing) and Obsidian binary is detected on completion.
+
+2. **Fresh Ubuntu install.** Given Ubuntu without Obsidian / Node, when `npx arkaos install` runs, then the installer prints copy-paste commands like:
+   ```
+   To finish install, run:
+     sudo apt update && sudo apt install -y nodejs
+     sudo snap install obsidian --classic
+   Then re-run: npx arkaos install
+   ```
+   and exits with code 0 (informational, not a failure).
+
+3. **Fresh Windows 11.** Given Windows without Obsidian / Node, when `npx arkaos install` runs, then it invokes `winget install --id Obsidian.Obsidian --silent` (and similar for Node), or prints the command if elevation is denied.
+
+4. **`npx arkaos doctor`.** Given any state, when `npx arkaos doctor` runs, then it prints a table with Obsidian / Node / Python rows showing installed/version/location/action, with exit code 0 (all OK), 1 (missing), or 2 (version mismatch).
+
+5. **`install.sh` GitHub URL configurable.** Given `ARKAOS_REPO_URL=https://gitlab.example.com/x/y.git` is set, when `install.sh` runs in curl|bash mode, then it clones from the custom URL.
+
+6. **`install.sh` Linux vault detection.** Given Ubuntu user with vault at `~/.local/share/obsidian/vault` OR `~/Documents/Obsidian`, when `install.sh` runs vault auto-detection, then both candidate paths are scanned.
+
+7. **`install.sh` Windows vault detection.** Given Git Bash on Windows with vault at `$USERPROFILE/Documents/Obsidian`, when `install.sh` runs vault auto-detection, then the path is scanned.
+
+8. **`--no-system` flag.** Given `npx arkaos install --no-system`, when installer runs, then `ensureSystemTools()` is bypassed (legacy install-only flow preserved for CI).
+
+9. **Idempotent.** Given `ensureSystemTools()` has already installed everything, when it runs again, then no install commands fire, no side effects, exit success.
+
+10. **Regression-free.** Given PR2 merges, when full pytest suite runs, then all 3049 tests still pass. New Node tests add ≥ 15 cases for package-manager + system-tools.
+
+11. **shellcheck clean.** Given the updated `install.sh`, when `shellcheck install.sh` runs, then zero new warnings vs baseline.
+
+## Data Model
+
+N/A — pure installer logic, no persisted schema changes.
+
+## API Contracts
+
+### `installer/package-manager.js`
+
+```javascript
+/**
+ * Detect the highest-priority package manager available on this host.
+ *
+ * Priority order:
+ *   macOS:   brew
+ *   Linux:   apt > snap (apt for Node, snap for Obsidian classic-confined)
+ *   Windows: winget > choco
+ *
+ * Returns the canonical name string or null when nothing is available.
+ */
+export function detectPackageManager(): string | null
+
+/**
+ * Install a single package via the detected (or specified) manager.
+ * Never invokes sudo automatically. When sudo is required, returns
+ * the command for the caller to print and the user to run.
+ */
+export function installViaPackageManager(
+  pkg: string,
+  options?: { manager?: string, fallbackUrl?: string }
+): {
+  success: boolean,
+  command: string,           // command that ran or should run
+  needsSudo: boolean,
+  installed: boolean,        // did we actually install in this call?
+  fallbackOpened?: boolean,  // did we open the download URL?
+  error?: string,
+}
+
+/** Format an array of missing-package commands into copy-paste text. */
+export function formatSudoInstructions(missing: SudoCommand[]): string
+```
+
+### `installer/system-tools.js`
+
+```javascript
+export type ToolStatus = {
+  name: "obsidian" | "node" | "python",
+  installed: boolean,
+  version?: string,
+  location?: string,
+  needsAction: "none" | "install" | "upgrade",
+  suggestedCommand?: string,
+  needsSudo?: boolean,
+}
+
+/**
+ * Check each required system tool. Install what can be installed without
+ * sudo. Collect commands for tools that need sudo into `sudoCommands`
+ * so the caller can print them to the user.
+ *
+ * Idempotent: tools already installed at sufficient version are no-ops.
+ */
+export function ensureSystemTools(options?: {
+  skipSystem?: boolean,
+  dryRun?: boolean,
+}): {
+  obsidian: ToolStatus,
+  node: ToolStatus,
+  python: ToolStatus,
+  sudoCommands: string[],
+}
+
+export function checkObsidian(): ToolStatus
+export function checkNode(): ToolStatus
+export function checkPython(): ToolStatus
+```
+
+### `installer/doctor.js`
+
+```javascript
+/**
+ * `npx arkaos doctor` — diagnose-only report. Never installs.
+ * Returns exit code 0 (all OK), 1 (missing tool), 2 (version mismatch).
+ */
+export function runDoctor(): number
+```
+
+### CLI integration
+
+`installer/cli.js` gains:
+- `npx arkaos doctor` subcommand → calls `runDoctor()`
+- `--no-system` global flag → sets `options.skipSystem = true` for `ensureSystemTools()`
+
+## Edge Cases
+
+1. **brew not installed on macOS** → print Homebrew install one-liner, exit 0 with informational message.
+2. **snap available but `obsidian` not in store** (older Ubuntu) → fall back to `https://obsidian.md/download` opened in browser, or printed for headless.
+3. **Windows < 1809 without winget** → choco fallback, or printed download URL.
+4. **Node installed but version < 20** → `needsAction: "upgrade"`, suggested command per OS.
+5. **Multiple Python versions present** → prefer 3.12+, recommend `pyenv` if mixed.
+6. **User installed Obsidian via Flatpak** → detect via `flatpak list md.obsidian` (best-effort), accept as installed.
+7. **Concurrent installer runs** → checks read filesystem only; install commands themselves are idempotent (apt/brew/winget handle already-installed packages gracefully).
+8. **curl|bash mode** → `install.sh` clones repo first; `ARKAOS_REPO_URL` env wins over hardcoded default; supports private fork redirection.
+9. **Sudo denied** on Windows winget → print the command and ask user to re-run from an elevated prompt; do not loop or retry.
+10. **Headless CI** → `--no-system` flag skips entirely; `arka doctor` exit codes drive CI decisions.
+11. **Network failure during install** → catch, report, exit with copy-paste recovery command.
+
+## Test Scenarios
+
+| # | Scenario | Type | Expected |
+|---|---|---|---|
+| 1 | `detectPackageManager` on macOS w/ brew | Unit | `"brew"` |
+| 2 | `detectPackageManager` on Ubuntu w/ apt+snap | Unit | `"apt"` (then `"snap"` for Obsidian-specific calls) |
+| 3 | `detectPackageManager` on Windows w/ winget | Unit | `"winget"` |
+| 4 | `detectPackageManager` on Linux w/ none | Unit | `null` |
+| 5 | `checkObsidian` when binary in PATH | Unit | `installed: true, location: <path>` |
+| 6 | `checkObsidian` when binary missing | Unit | `installed: false, needsAction: "install"` |
+| 7 | `checkNode` when version < 20 | Unit | `needsAction: "upgrade"` |
+| 8 | `checkNode` when version ≥ 20 | Unit | `needsAction: "none"` |
+| 9 | `checkPython` when 3.11 only | Unit | `needsAction: "upgrade"` |
+| 10 | `ensureSystemTools` w/ all 3 missing | Integration | `sudoCommands` array populated |
+| 11 | `ensureSystemTools` idempotent | Integration | second call: no commands |
+| 12 | `runDoctor` exit codes | Integration | 0 / 1 / 2 verified |
+| 13 | `install.sh` with `ARKAOS_REPO_URL` override | Manual / shell | clones from custom URL |
+| 14 | `install.sh` Linux vault detection | Manual / shell | finds `~/.local/share/obsidian/...` |
+| 15 | `install.sh` Windows vault detection | Manual / shell | finds `$USERPROFILE/Documents/Obsidian` |
+| 16 | `--no-system` flag bypass | Integration | `ensureSystemTools` not called |
+| 17 | full pytest regression | Integration | 3049 still pass |
+
+## Dependencies
+
+- `installer/platform.js` (existing) — `IS_WINDOWS`, `CMD_FINDER`, `PYTHON_CMD`.
+- `installer/path-resolver.js` (PR1) — for any path template substitution.
+- `installer/python-resolver.js` (existing) — Python detection logic.
+- Node.js `node:child_process` for `execSync` (already used).
+- No new npm deps.
+
+## Quality Gate Criteria
+
+- **Eduardo:** all error / status messages read naturally in EN; copy-paste sudo commands are accurate and OS-specific; no AI clichés.
+- **Francisca:** package-manager detection covers macOS/Ubuntu/Debian/Fedora/Arch/Windows 10+/11; `ensureSystemTools()` is fully idempotent; no shell injection vectors in execSync calls; shellcheck clean on install.sh.
+- **Marta:** verified on 3 synthetic environments — macOS with brew, Ubuntu without snap, Windows with winget — each producing the right printed commands and side effects.
+
+## References
+
+- Plan: `~/.arkaos/plans/2026-05-13-arkaos-next-level-conclave.md` (PR2 section)
+- Memory: [[project_next_level_conclave]]
+- Existing: [[SPEC-paths-portability]] (PR1, dependency), [[platform.js]] (platform abstraction)
+- HIGH items inherited from PR1 audit: `install.sh:25`, `install.sh:625-640`

package/core/specs/SPEC-paths-portability.md

@@ -0,0 +1,209 @@
+---
+type: spec
+status: approved
+feature: paths-portability
+project: ArkaOS
+version: 2.23.0
+pr: PR1 of 6 (Conclave roadmap 2026-05-13)
+branch: feature/v2.23.0-paths-portability
+date_created: 2026-05-13
+date_updated: 2026-05-13
+tags: [spec, arkaos, paths, portability, refactor, v2.23.0, conclave-pr1]
+---
+
+# SPEC: Paths Portability (v2.23.0)
+
+## Overview
+
+**Problem.** ArkaOS source contains hardcoded user-specific paths (`/Users/andreagroferreira/...`) across SKILL.md files, JSON configs, Python regexes, and cognitive prompts. These break for the **~20K users** currently running ArkaOS with different home directories and OS layouts.
+
+**Goal.** Replace 7 CRITICAL hardcoded paths with profile-driven templates resolved at runtime, with **non-breaking auto-migration** for the existing user base.
+
+**Actors.** ArkaOS core (skill loader, cognition collector, installer migration), end users (via `~/.arkaos/profile.json`).
+
+## Scope
+
+**In scope (PR1 / v2.23.0):**
+
+| # | File | Fix |
+|---|---|---|
+| 1 | `knowledge/obsidian-config.json:6` | `vault_path` value resolved at load via `path_resolver.resolve_dict` (profile.vaultPath) |
+| 2 | `core/cognition/capture/collector.py:15-17` | Regex generated from `profile.projectRoots`; fallback `os.getcwd()` |
+| 3 | `departments/kb/skills/knowledge/SKILL.md:25` | `${VAULT_PATH}` template |
+| 4 | `departments/ops/skills/operations/SKILL.md:59` | `${VAULT_PATH}` template |
+| 5 | `arka/skills/comfyui/SKILL.md:22-23` + `references/workflows.md` | `${ARKA_OS_REPOS}/{purz-comfyui-workflows,lora_tester}` |
+| 6 | `config/cognition/prompts/dreaming.md` | `${VAULT_PATH}` template |
+| 7 | `config/cognition/prompts/research.md` | `${VAULT_PATH}` template |
+| 8 | `departments/dev/skills/scaffold/SKILL.md:19` | `${GIT_HOST}` template, default `github.com` HTTPS |
+| — | new `core/runtime/path_resolver.py` | `resolve()`, `resolve_dict()`, `load_profile()` |
+| — | new `installer/migrations/v3_path_schema.js` | Auto-migrate `projectsDir` text → `projectRoots` list + `reposRoot` |
+| — | skill loader extension | Substitute `${VAR}` tokens at SKILL.md load |
+| — | new `tests/python/test_path_resolver.py` | ≥ 15 tests |
+
+**Out of scope (deferred):**
+
+- `install.sh:25, 631-634` (GitHub URL hardcode + Mac-only Obsidian detection) → **PR2 v2.24.0** (cross-OS installer is the natural home for OS-aware logic)
+- 50+ docs/superpowers/plans hardcoded paths (LOW priority, examples only) → **PR6 v2.28.0** cleanup pass
+- Vision bridge migration (test_vision_bridge.py + scripts/tools/vision/*) → file was discarded; not relevant to PR1
+- Migration of installed user skills under `~/.claude/skills/arka/` — installer rewrites these from source on every update; fixing source covers it
+
+## Acceptance Criteria
+
+1. **Zero CRITICAL grep hits.** Given a fresh checkout of `feature/v2.23.0-paths-portability`, when `grep -rn "/Users/andreagroferreira" core/ arka/ installer/ config/ departments/ knowledge/ --exclude-dir=node_modules --exclude-dir=__pycache__ --exclude-dir=.git --exclude-dir=docs` runs, then it returns **0 CRITICAL hits**. Hits inside `docs/superpowers/plans/` are tracked but acceptable (PR6 cleanup).
+
+2. **Synthetic install works end-to-end.** Given `$HOME=/tmp/testuser` and `~/.arkaos/profile.json` containing `{"version":"3","vaultPath":"/tmp/testuser/vault","reposRoot":"/tmp/testuser/repos","projectRoots":["/tmp/testuser/code"]}`, when every SKILL.md is loaded, then `${VAULT_PATH}`, `${ARKA_OS_REPOS}` and `${GIT_HOST}` resolve to the configured values with zero `${` leakage.
+
+3. **20K-user safe migration.** Given a legacy profile.json missing `projectRoots` and `reposRoot`, when `npx arkaos@latest update` runs, then:
+   - `projectRoots` is derived from parsing `projectsDir` text (regex extracts absolute paths).
+   - If parsing finds 0 paths, sensible defaults are applied (`["~/Herd","~/Work","~/AIProjects"]`).
+   - `reposRoot` defaults to `~/AIProjects` (or first match containing `AIProjects` if any).
+   - `version` bumps to `"3"`, `migrated_at` timestamp added.
+   - A `.bak-<timestamp>` backup is written first.
+   - `[arka:migrated] profile.json schema v2 → v3` logged.
+
+4. **Hard error on truly missing profile.** Given `~/.arkaos/profile.json` is absent or unparseable JSON, when any `path_resolver` call runs, then `ProfileMissingError("Run /arka setup to configure ArkaOS paths")` is raised. No silent fallback.
+
+5. **Env-var override.** Given `ARKAOS_VAULT_PATH=/tmp/override` is set, when `${VAULT_PATH}` is resolved, then the env var wins over profile. Same for `ARKAOS_REPOS_ROOT`, `ARKAOS_PROJECT_ROOTS`, `ARKAOS_GIT_HOST`. Empty string is treated as unset.
+
+6. **Regression-free.** Given PR1 is merged, when full pytest suite runs, then all existing 542+ tests pass and ≥ 15 new path_resolver tests pass. Coverage ≥ 80%.
+
+7. **Migration idempotent.** Given migration ran once, when it runs again, then profile.json is unchanged (no version re-bump, no second backup).
+
+## Data Model
+
+| Field (new in profile.json v3) | Type | Default | Source |
+|---|---|---|---|
+| `version` | `"3"` (str) | — | bumped by migration |
+| `projectRoots` | `list[str]` | `["~/Herd","~/Work","~/AIProjects"]` | parsed from `projectsDir` text on migration |
+| `reposRoot` | `str` | `"~/AIProjects"` | matches first path containing `AIProjects`, else default |
+| `migrated_at` | ISO8601 `str` | — | written at migration time |
+
+**Backwards-compat fields kept verbatim:** `language`, `market`, `role`, `company`, `projectsDir` (kept for human reference), `vaultPath`, `created`, `updated`.
+
+## API Contracts
+
+### `core/runtime/path_resolver.py`
+
+```python
+class ProfileMissingError(RuntimeError):
+    """Raised when ~/.arkaos/profile.json is absent or unparseable."""
+
+@dataclass
+class ProfileV3:
+    version: str
+    vault_path: str          # ${VAULT_PATH}
+    repos_root: str          # ${ARKA_OS_REPOS}
+    project_roots: list[str] # ${PROJECT_ROOTS}
+    raw: dict                # full profile.json for forward-compat
+
+def load_profile() -> ProfileV3:
+    """Load and cache ~/.arkaos/profile.json. Raises ProfileMissingError."""
+
+def resolve(template: str) -> str:
+    """Substitute known tokens. Unknown tokens pass through unchanged.
+
+    Tokens:
+      ${VAULT_PATH}      -> ARKAOS_VAULT_PATH env or profile.vaultPath
+      ${ARKA_OS_REPOS}   -> ARKAOS_REPOS_ROOT env or profile.reposRoot
+      ${PROJECT_ROOTS}   -> os.pathsep-joined profile.projectRoots
+      ${GIT_HOST}        -> ARKAOS_GIT_HOST env or "github.com"
+      ${HOME}            -> os.path.expanduser("~")
+    """
+
+def resolve_dict(d: dict) -> dict:
+    """Recursively resolve string values in a JSON-shaped dict."""
+
+def project_root_regex() -> re.Pattern:
+    """Compile regex from profile.projectRoots for collector.py."""
+```
+
+### Skill loader extension
+
+Find existing skill loader (likely `core/agents/loader.py` or `arka/skills/.../loader`); extend:
+
+```python
+def load_skill_markdown(path: Path) -> str:
+    return path_resolver.resolve(path.read_text())
+```
+
+### Migration script `installer/migrations/v3_path_schema.js`
+
+```javascript
+function migrateV3(profile) {
+  if (profile.version === "3" || profile.projectRoots) return profile;
+  const roots = parseProjectsDirText(profile.projectsDir);
+  const reposRoot = roots.find(r => r.includes("AIProjects")) || "~/AIProjects";
+  return { ...profile, version: "3", projectRoots: roots,
+           reposRoot, migrated_at: new Date().toISOString() };
+}
+```
+
+Wired into `installer/migrate-user-data.js` (existing framework).
+
+## Edge Cases
+
+1. **`projectsDir` text is empty / null** → defaults applied (no error).
+2. **`vaultPath` empty string** → treated as missing → `ProfileMissingError`.
+3. **SKILL.md contains literal `${SOME_BASH_VAR}` for agent instructions** → resolver only touches the 5 known tokens; unknown tokens pass through.
+4. **Windows path separators in `${PROJECT_ROOTS}`** → uses `os.pathsep` (`;` on Windows, `:` on Unix). Internal storage is POSIX `/`.
+5. **Digest path from foreign OS** (cross-machine Obsidian sync) → `_detect_project` falls back to `os.getcwd()` if no `projectRoots` match (existing behaviour).
+6. **Concurrent calls during migration** → migration uses temp-file + atomic rename; safe.
+7. **User edits profile.json manually mid-session** → load_profile is cached per-process; re-import to refresh. Documented.
+8. **Migration corrupts profile** → `.bak-<timestamp>` rollback file always exists.
+
+## Test Scenarios
+
+| # | Scenario | Type | Expected |
+|---|---|---|---|
+| 1 | `resolve("${VAULT_PATH}/foo")` with `vaultPath="/v"` | Unit | `"/v/foo"` |
+| 2 | `resolve("${HOME}/bar")` | Unit | `"$HOME/bar"` expanded |
+| 3 | `resolve("${UNKNOWN}/baz")` | Unit | `"${UNKNOWN}/baz"` unchanged |
+| 4 | `resolve` with absent profile.json | Unit | `ProfileMissingError` |
+| 5 | `resolve` with `ARKAOS_VAULT_PATH=/x` | Unit | env wins over profile |
+| 6 | `resolve_dict` on obsidian-config.json fixture | Unit | All string values resolved |
+| 7 | `_detect_project` with `projectRoots=["~/Herd"]` | Unit | matches path under `~/Herd` |
+| 8 | `_detect_project` on Windows-style path | Unit | matches with `\` separator |
+| 9 | `load_skill_markdown` on kb SKILL.md | Integration | `${VAULT_PATH}` substituted |
+| 10 | full pytest suite | Regression | all 542+ tests pass |
+| 11 | `migrateV3` on legacy profile (v2 schema) | Integration | new fields added, old kept, .bak written |
+| 12 | `migrateV3` idempotent (second run no-op) | Integration | profile unchanged, no second .bak |
+| 13 | Grep audit (CRITICAL paths) | Audit | 0 hits in core/ arka/ installer/ config/ departments/ knowledge/ |
+| 14 | `scaffold SKILL.md ${GIT_HOST}` | Integration | `github.com` default |
+| 15 | `comfyui SKILL.md ${ARKA_OS_REPOS}` | Integration | substituted correctly |
+| 16 | `migrateV3` with empty `projectsDir` | Unit | defaults applied, no crash |
+| 17 | env vars with empty string values | Unit | treated as unset, profile wins |
+
+## Dependencies
+
+- No external deps. Reuses existing `installer/migrate-user-data.js` framework + `core/specs/` Living Specs engine.
+- New Python module only depends on stdlib (`json`, `os`, `pathlib`, `re`, `dataclasses`).
+
+## Migration Plan for 20K Users
+
+`npx arkaos@latest update` runs `migrate-user-data.js` which includes the new `migrateV3` step. Flow:
+
+1. Read `~/.arkaos/profile.json`. If absent → skip migration (user must run `/arka setup`).
+2. If `version === "3"` or `projectRoots` exists → no-op (idempotent).
+3. Otherwise:
+   - Write backup: `~/.arkaos/profile.json.bak-<unix-timestamp>`.
+   - Parse `projectsDir` text with `/((?:\/Users|\/home|[A-Z]:\\Users)\/\S+?\/(?:Herd|Work|AIProjects|code|repos))/g`.
+   - Apply defaults if parsing yields 0 results.
+   - Atomic write: temp file + `fs.rename`.
+   - Log `[arka:migrated] profile.json schema v2 → v3 ({N} roots, repos=...)` to `~/.arkaos/logs/migrate.log`.
+
+**Rollback procedure (documented in installer):** restore `.bak-<timestamp>` over profile.json.
+
+## Quality Gate Criteria
+
+Marta (CQO) requires APPROVED from all three reviewers:
+
+- **Eduardo (Copy):** All SKILL.md files read naturally after substitution — no `${` leakage in human-facing prose. Error messages clear and actionable.
+- **Francisca (Tech):** path_resolver handles all 8 edge cases. Migration is atomic + idempotent + reversible. 17 test scenarios all green. No crash on corrupt profile.
+- **Marta (CQO):** Migration verified non-breaking by simulating 5 different legacy profile shapes (André's current one + 4 synthetic variants representing common 20K-user variations).
+
+## References
+
+- Plan: `~/.arkaos/plans/2026-05-13-arkaos-next-level-conclave.md` (PR1 section)
+- Memory: [[project_next_level_conclave]]
+- KB: [[2026-04-29-claude-code-2-1-122-and-2-1-123]] (Claude Code features unblocked by 2.1.122)
+- Existing Specs in this project: [[SPEC-cognitive-layer-feedback-loop]], [[SPEC-wave1-single-source-of-truth]]

package/departments/dev/skills/scaffold/SKILL.md

@@ -16,7 +16,7 @@ Create new projects from real git repositories with full automation: dependencie
 
 | Command | Git Repository | Stack |
 |---------|---------------|-------|
-| `/dev scaffold laravel <name>` | `git@andreagroferreira:andreagroferreira/laravel-starter-kit.git` | Laravel + Herd |
+| `/dev scaffold laravel <name>` | `https://${GIT_HOST}/laravel/laravel.git` (override with `ARKAOS_LARAVEL_STARTER_REPO` env) | Laravel + Herd |
 | `/dev scaffold nuxt-saas <name>` | `https://github.com/nuxt-ui-templates/dashboard.git` | Nuxt 3 Dashboard |
 | `/dev scaffold nuxt-landing <name>` | `https://github.com/nuxt-ui-templates/landing.git` | Nuxt 3 Landing |
 | `/dev scaffold nuxt-docs <name>` | `https://github.com/nuxt-ui-templates/docs.git` | Nuxt 3 Docs |
@@ -136,7 +136,7 @@ cp PROJECT.md "$ARKA_OS/projects/<name>/PROJECT.md"
 
 Create pages in the Obsidian vault:
 
-**Main page:** `Documents/Personal/Projects/<name>/Home.md`
+**Main page:** `${VAULT_PATH}/Projects/<name>/Home.md`
 ```markdown
 ---
 type: project
@@ -165,7 +165,7 @@ tags:
 - *Part of the [[Projects MOC]]*
 ```
 
-**Architecture page:** `Documents/Personal/Projects/<name>/Architecture/decisions.md`
+**Architecture page:** `${VAULT_PATH}/Projects/<name>/Architecture/decisions.md`
 ```markdown
 ---
 type: adr-log
@@ -242,7 +242,7 @@ Both directories get their respective dependencies installed, and the full-stack
 
 ## Error Handling
 
-- If `git clone` fails: check SSH keys (`git@andreagroferreira:` for private repos)
+- If `git clone` fails: check SSH keys / repo access permissions for the configured `${GIT_HOST}`
 - If `composer install` fails: check PHP version (`php -v`, need 8.3+)
 - If `pnpm install` fails: check Node version (`node -v`, need 18+)
 - If `herd link` fails: check Herd is installed and running

package/departments/kb/skills/knowledge/SKILL.md

@@ -22,7 +22,7 @@ Dynamic knowledge acquisition and management system. Learn from YouTube videos,
 
 ## Obsidian Configuration
 
-- **Vault:** `/Users/andreagroferreira/Documents/Personal`
+- **Vault:** `${VAULT_PATH}`
 - **Config:** Read `knowledge/obsidian-config.json` for full path/convention details
 - **MCP:** Use Obsidian MCP when available, fallback to direct file Write
 - **Conventions:** YAML frontmatter, wikilinks `[[]]`, MOC references, kebab-case tags

package/departments/ops/skills/operations/SKILL.md

@@ -56,7 +56,7 @@ Every phase transition announced to the user.
 
 ## Obsidian Output
 
-Vault root: `/Users/andreagroferreira/Documents/Personal`
+Vault root: `${VAULT_PATH}`
 
 | Content | Path |
 |---------|------|

package/installer/cli.js

@@ -19,6 +19,7 @@ const { values, positionals } = parseArgs({
     runtime: { type: "string", short: "r" },
     path: { type: "string", short: "p" },
     force: { type: "boolean", short: "f" },
+    "no-system": { type: "boolean" },
   },
   allowPositionals: true,
   strict: false,
@@ -74,7 +75,7 @@ async function main() {
   switch (command) {
     case "install":
       const runtime = values.runtime || await detectRuntime();
-      await install({ runtime, path: values.path, force: values.force });
+      await install({ runtime, path: values.path, force: values.force, skipSystem: values["no-system"] });
       break;
 
     case "init": {

package/installer/doctor.js

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { execSync } from "node:child_process";
 import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
+import { checkNode, checkObsidian } from "./system-tools.js";
 
 const INSTALL_DIR = join(homedir(), ".arkaos");
 
@@ -124,6 +125,53 @@ const checks = [
     check: () => existsSync(join(INSTALL_DIR, "schedules.yaml")),
     fix: () => "Run: npx arkaos@latest update (deploys scheduler)",
   },
+  {
+    name: "obsidian",
+    description: "Obsidian app installed",
+    severity: "warn",
+    check: () => checkObsidian().installed,
+    fix: () => {
+      const s = checkObsidian();
+      if (s.suggestedCommand) return `Run: ${s.suggestedCommand}`;
+      return `Install Obsidian from ${s.fallbackUrl || "https://obsidian.md/download"}`;
+    },
+  },
+  {
+    name: "node",
+    description: "Node.js 20+ available",
+    severity: "warn",
+    check: () => checkNode().needsAction === "none",
+    fix: () => {
+      const s = checkNode();
+      if (s.suggestedCommand) return `Run: ${s.suggestedCommand}`;
+      return `Install Node.js 20+ from ${s.fallbackUrl || "https://nodejs.org/en/download"}`;
+    },
+  },
+  {
+    name: "claude-code-version",
+    description: "Claude Code 2.1.122+ (ToolSearch late-binding + hooks isolation)",
+    severity: "warn",
+    check: () => {
+      if (!commandExists("claude")) return true; // no claude binary = not applicable
+      try {
+        const out = execSync("claude --version 2>&1", {
+          stdio: "pipe",
+        }).toString().trim();
+        const m = out.match(/(\d+)\.(\d+)\.(\d+)/);
+        if (!m) return false;
+        const [, maj, min, patch] = m.map(Number);
+        // 2.1.122 minimum
+        if (maj > 2) return true;
+        if (maj < 2) return false;
+        if (min > 1) return true;
+        if (min < 1) return false;
+        return patch >= 122;
+      } catch {
+        return false;
+      }
+    },
+    fix: () => "Upgrade Claude Code: npm install -g @anthropic-ai/claude-code@latest",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────

package/installer/index.js

@@ -12,7 +12,7 @@ const __dirname = dirname(__filename);
 const ARKAOS_ROOT = resolve(__dirname, "..");
 const VERSION = JSON.parse(readFileSync(join(ARKAOS_ROOT, "package.json"), "utf-8")).version;
 
-export async function install({ runtime, path, force }) {
+export async function install({ runtime, path, force, skipSystem }) {
   const startTime = Date.now();
   const config = getRuntimeConfig(runtime);
   const isUpgrade = existsSync(join(path || join(homedir(), ".arkaos"), "install-manifest.json"));
@@ -72,6 +72,31 @@ export async function install({ runtime, path, force }) {
     ok("No v1 installation found");
   }
 
+  // ═══ Step 2.5: Ensure system tools (Obsidian, Node ≥ 20, Python ≥ 3.12) ═══
+  // Wrapped in try/catch so a regression in system-tools.js cannot break a
+  // fresh `npx arkaos install` for the ~20K user base. We degrade to a warn
+  // and proceed to venv creation rather than exiting non-zero.
+  if (!skipSystem) {
+    try {
+      const { ensureSystemTools } = await import("./system-tools.js");
+      const { formatSudoInstructions } = await import("./package-manager.js");
+      const sys = ensureSystemTools({ skipSystem: false });
+      if (sys.sudoCommands && sys.sudoCommands.length > 0) {
+        console.log(formatSudoInstructions(sys.sudoCommands));
+      }
+      for (const tool of [sys.obsidian, sys.node]) {
+        if (!tool) continue;
+        if (tool.justInstalled) ok(`${tool.name} installed`);
+        else if (tool.needsAction === "none") ok(`${tool.name} ready`);
+        else warn(`${tool.name} ${tool.needsAction} — see commands above`);
+      }
+    } catch (err) {
+      warn(`System tool check failed: ${err.message}. Continuing without it.`);
+    }
+  } else {
+    warn("System tool checks skipped (--no-system)");
+  }
+
   // ═══ Step 3: Check Python + create venv ═══
   step(3, 14, "Checking Python 3.11+ and creating virtual environment...");
   const systemPython = findSystemPython();

package/installer/migrate-user-data.js

@@ -2,6 +2,8 @@ import { existsSync, mkdirSync, readdirSync, renameSync, statSync, writeFileSync
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { migrateProfileSchemaV3 } from "./migrations/v3_path_schema.js";
+
 const LEGACY_SKILLS_ROOT = join(homedir(), ".claude", "skills", "arka");
 const USER_DATA_ROOT = join(homedir(), ".arkaos");
 
@@ -28,8 +30,22 @@ export function migrateUserData({ dryRun = false } = {}) {
   const skipped = [...projectsResult.skipped, ...ecosystemsResult.skipped];
   const conflicts = [...projectsResult.conflicts, ...ecosystemsResult.conflicts];
 
+  let profileSchemaResult = null;
+  if (!dryRun) {
+    try {
+      profileSchemaResult = migrateProfileSchemaV3();
+      if (profileSchemaResult?.migrated) {
+        moved.push(
+          `profile.json schema v2 → v3 (${profileSchemaResult.projectRoots.length} roots)`
+        );
+      }
+    } catch (err) {
+      conflicts.push(`profile schema v3 migration failed: ${err.message}`);
+    }
+  }
+
   const logPath = writeReport({ moved, skipped, conflicts, dryRun });
-  return { moved, skipped, conflicts, logPath };
+  return { moved, skipped, conflicts, logPath, profileSchemaResult };
 }
 
 export function printMigrationReport(result) {