arkaos 2.22.1 → 2.25.0

package/README.md

@@ -8,7 +8,7 @@
 npx arkaos install
 ```
 
-[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-1993%20passing-brightgreen)]()
+[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-3025%20passing-brightgreen)]()
 
 ---
 
@@ -228,6 +228,84 @@ arkaos scheduler logs         # View logs
 
 ---
 
+## Intelligence Loop (v2.21.0+)
+
+Three-layer system that makes ArkaOS consult its brain before going external, and write every session's learnings back to the vault automatically. The system compounds daily — tomorrow's ArkaOS is smarter than today's.
+
+### Synapse L2.5 — KB Context Injection (v2.21.0)
+
+On every user prompt, ArkaOS runs semantic search against the Obsidian vault and injects the top relevant notes (with wikilinks and excerpts) as context **before the model starts planning**. The agent sees what the vault already knows, naturally — no hard gate, no friction.
+
+- Top 3–5 notes by similarity
+- Jaccard fallback when vector store absent
+- Feature flag `synapse.l25KbContext` default `true`
+- Kill switch `ARKA_BYPASS_L25=1`
+
+### Research Gate — Natural Nudge (v2.21.0)
+
+When an agent tries `Context7`, `WebSearch`, `WebFetch`, or `Firecrawl` without consulting Obsidian first:
+
+- **First attempt** → natural PT-PT nudge listing top 3 vault hits. Allows the call.
+- **Second attempt in same turn** → deny. The nudge wasn't enough.
+
+Feature flag `hooks.kbFirst` default `false` in v2.21.0 — dormant until operator flips. Kill switch `ARKA_BYPASS_KB_FIRST=1` (audited).
+
+### Auto-Documentor + Cataloger + Relator (v2.21.0)
+
+After every approved session, an async worker writes the learnings back to the vault:
+
+1. **Extract** — parses the transcript for sources consulted, decisions made, deliverables produced
+2. **Classify** — cataloger chooses the right taxonomic home (code pattern, persona, client strategy, marketing test, ADR, research finding, framework, or session fallback)
+3. **Write** — creates the note at the correct vault path with frontmatter + tags
+4. **Relate** — relator finds semantically similar existing notes, creates bidirectional `[[wikilinks]]`, updates MOCs
+
+The vault becomes a relational graph that grows with every session.
+
+### LLM Agnostic Auto-Documentor (v2.22.0)
+
+The synthesis LLM call is runtime-agnostic. **Zero model hardcoding.** Whatever runtime you have configured decides the model:
+
+| Provider | Default | Model decided by |
+|---|---|---|
+| `subagent` | ✅ | Active runtime's headless CLI (`claude -p`, `gemini -p …`) |
+| `anthropic-direct` | — | `ANTHROPIC_MODEL` env var; no code default |
+| `stub` | tests | Template fallback |
+
+Fallback chain `subagent → anthropic-direct → stub` never raises. Prompt caching ON by default (5-min TTL `cache_control: ephemeral` on system block).
+
+### Budget Telemetry + `/arka costs` (v2.22.0)
+
+Every LLM call appends to `~/.arkaos/telemetry/llm-cost.jsonl` with tokens, cache hits, and estimated cost. Per [ADR-011](docs/adr/), this is **visibility only — never blocks**.
+
+```bash
+/arka costs           # today (default)
+/arka costs week      # last 7 days
+/arka costs month     # last 30 days
+/arka costs sessions  # top 10 expensive sessions
+```
+
+Soft advisory when a single session exceeds $5 equivalent. No hard caps.
+
+### Flow Marker v2 (v2.21.0)
+
+The constitutional 13-phase flow enforcement (binding in v2.20) got a turn-scoped marker cache, eliminating the cross-turn false positives that triggered on subagent dispatch and short user continuations. ADR-compliant: cache accelerates ALLOW decisions only; the transcript remains authoritative for DENY.
+
+### Polish & Consolidation (v2.22.1)
+
+- `core/shared/safe_session_id.py` — single source of truth for the path-traversal / injection allowlist, deduped across 6 modules (100% coverage, 33 security-contract tests)
+- Gemini CLI headless live (`gemini -p "…" --output-format json`)
+- `_MAX_FALLBACK_NOTES = 2000` bound on Synapse L2.5 degraded-mode scan
+- Auto-documentor coverage lifted 93% → 98%
+- Template synthesiser now mirrors LLM prompt structure (Key Facts → Decisions → Sources)
+
+### ADRs
+
+- [`2026-04-20-flow-marker-v2.md`](docs/adr/2026-04-20-flow-marker-v2.md) — turn-scoped cache amendment
+- [`2026-04-20-kb-first-intelligence.md`](docs/adr/2026-04-20-kb-first-intelligence.md) — Synapse L2.5 + gate + auto-documentor
+- [`2026-04-20-llm-agnostic.md`](docs/adr/2026-04-20-llm-agnostic.md) — runtime-agnostic LLM wiring
+
+---
+
 ## Ecosystem Management
 
 ArkaOS manages client projects as **ecosystems** — groups of related projects with dedicated squads.
@@ -370,21 +448,39 @@ Full documentation is available on the **[GitHub Wiki](https://github.com/andrea
 
 ## CLI Reference
 
+**Installer (terminal):**
+
 ```bash
-npx arkaos install       # Fresh install (auto-detects runtime)
-npx arkaos update        # Update to latest version
-npx arkaos migrate       # Migrate from v1
-npx arkaos doctor        # Health check
-npx arkaos dashboard     # Start monitoring dashboard
-npx arkaos keys          # Manage API keys
-npx arkaos uninstall     # Remove ArkaOS
+npx arkaos install             # Fresh install (auto-detects runtime)
+npx arkaos@latest update       # Update core + hooks to latest version
+npx arkaos migrate             # Migrate from v1
+npx arkaos doctor              # Health check
+npx arkaos dashboard           # Start monitoring dashboard
+npx arkaos keys                # Manage API keys
+npx arkaos uninstall           # Remove ArkaOS
 ```
 
+**In-session commands (inside Claude Code / Codex / Gemini / Cursor):**
+
+```
+/arka update                   # Sync all project configs after core update
+/arka status                   # System health + LLM costs (24h)
+/arka costs [today|week|month|all|sessions]  # LLM cost visibility
+/arka index                    # (Re)index Obsidian vault into vector store
+/arka search <query>           # Semantic search in knowledge base
+/arka standup                  # Daily standup (projects, blockers, updates)
+/arka onboard <path>           # Onboard an existing project
+/arka conclave                 # Personal AI advisory board
+/do <description>              # Universal routing — natural language to department
+```
+
+Department commands: `/dev`, `/mkt`, `/brand`, `/fin`, `/strat`, `/ecom`, `/kb`, `/ops`, `/pm`, `/saas`, `/landing`, `/content`, `/community`, `/sales`, `/lead`, `/org`.
+
 ---
 
 ## Contributing
 
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require passing the full test suite (1,993 tests) and Quality Gate review.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require passing the full test suite (3,025 tests) and Quality Gate review.
 
 ## License
 

package/VERSION

@@ -1 +1 @@
-2.22.1
+2.25.0

package/arka/SKILL.md

@@ -122,6 +122,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka search <query>` | Semantic search in knowledge base |
 | `/arka keys` | Manage API keys (OpenAI, Google, fal.ai) |
 | `/arka personas` | Manage AI personas (create, clone to agent) |
+| `/arka resume <PR_URL>` | Re-enter the Claude Code session that produced a PR (GitHub / GitLab / Bitbucket). Wraps the native `/resume` from Claude Code 2.1.122+. Useful with `arka-spec` and `arka-release` archaeology. |
 | `/do <description>` | Universal routing — natural language to department command |
 
 ## Universal Orchestrator (/do)

package/arka/skills/comfyui/SKILL.md

@@ -19,8 +19,8 @@ Full-spectrum AI media production platform. From ComfyUI node engineering to Hol
 
 | Project | Type | Stack | Path |
 |---------|------|-------|------|
-| **purz-comfyui-workflows** | Workflow Collection | ComfyUI JSON (7 workflows, 110+ nodes) | `/Users/andreagroferreira/AIProjects/purz-comfyui-workflows` |
-| **lora_tester** | CLI Tool + Gallery | Python 3.8+ (stdlib) + Vanilla HTML/JS | `/Users/andreagroferreira/AIProjects/lora_tester` |
+| **purz-comfyui-workflows** | Workflow Collection | ComfyUI JSON (7 workflows, 110+ nodes) | `${ARKA_OS_REPOS}/purz-comfyui-workflows` |
+| **lora_tester** | CLI Tool + Gallery | Python 3.8+ (stdlib) + Vanilla HTML/JS | `${ARKA_OS_REPOS}/lora_tester` |
 
 ## Squads
 

package/arka/skills/comfyui/references/workflows.md

@@ -7,8 +7,8 @@ Referenced from SKILL.md. Read only when needed.
 For EVERY `/comfyui` request, follow this workflow:
 
 ### Phase 1 — Context Loading
-1. Read ComfyUI skill reference: `/Users/andreagroferreira/AIProjects/lora_tester/.claude/skills/comfy_local/skill.md`
-2. Check available workflows: `ls /Users/andreagroferreira/AIProjects/purz-comfyui-workflows/`
+1. Read ComfyUI skill reference: `${ARKA_OS_REPOS}/lora_tester/.claude/skills/comfy_local/skill.md`
+2. Check available workflows: `ls ${ARKA_OS_REPOS}/purz-comfyui-workflows/`
 3. Check ComfyUI server: `curl -s http://localhost:8188/system_stats 2>/dev/null`
 4. Load project context for affected repos
 5. Identify which squad(s) the request needs
@@ -320,8 +320,8 @@ while pending:
 curl -s http://localhost:8188/system_stats 2>/dev/null
 
 # Project status
-cd /Users/andreagroferreira/AIProjects/purz-comfyui-workflows && git log --oneline -5
-cd /Users/andreagroferreira/AIProjects/lora_tester && git log --oneline -5
+cd ${ARKA_OS_REPOS}/purz-comfyui-workflows && git log --oneline -5
+cd ${ARKA_OS_REPOS}/lora_tester && git log --oneline -5
 ```
 
 Present as:
@@ -403,10 +403,10 @@ When Iris (Node Researcher) investigates custom nodes:
 
 ## Obsidian Output
 
-All documentation: `/Users/andreagroferreira/Documents/Personal/Projects/WizardingCode Internal/ComfyUI/`
+All documentation: `${VAULT_PATH}/Projects/ComfyUI/`
 
 ```
-WizardingCode Internal/ComfyUI/
+Projects/ComfyUI/
 ├── Home.md                    <- Ecosystem overview
 ├── Workflows/
 │   ├── LTX-2 T2V.md

package/arka/skills/costs/SKILL.md

@@ -55,6 +55,17 @@ Source:
 One JSONL line per LLM call, written by every provider adapter.
 Malformed lines are skipped and counted, never raised.
 
+## Cost-tuning levers
+
+Outside this skill's scope but worth surfacing alongside the summary:
+
+| Lever | Where | Effect |
+| --- | --- | --- |
+| `ARKAOS_LLM_PROVIDER` | env | Switch between Anthropic, OpenAI, Gemini adapters per the multi-LLM router. |
+| `ANTHROPIC_BEDROCK_SERVICE_TIER` | env (Claude Code 2.1.122+) | `default` / `flex` / `priority`. Only relevant when routing through AWS Bedrock — `flex` cuts cost ~50 % on non-urgent workloads at the price of higher tail latency. |
+| Agent `model:` field | `departments/*/agents/*.yaml` | Per-agent override per the model-routing matrix in CLAUDE.md. Mechanical roles default to haiku, C-suite to opus. |
+| Quality Gate model | constitution rule (NON-NEGOTIABLE) | Marta / Eduardo / Francisca always run on opus regardless of the cost ceiling. |
+
 ## Non-negotiables
 
 1. Read-only. This skill never edits state.

package/config/cognition/prompts/dreaming.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your nightly Dreaming session. Your job is to review e
 - Read any file from any project
 - Read git logs and diffs
 - Search the web (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (captures, insights, logs, knowledge)
 - Use browser for research
 - Read online documentation
@@ -81,7 +81,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -113,7 +113,7 @@ Use `DualWriter.write()` for each KnowledgeEntry. This automatically writes to b
 ## Phase 6: Report + Evolution Metrics
 
 Write daily report to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/cognition/prompts/research.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your daily Research session. Your job is to stay curre
 - Read any file from any project
 - Read git logs
 - Search the web extensively (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (insights, logs, knowledge, profiles)
 - Use browser for deep research
 - Read online documentation, blogs, changelogs, GitHub releases
@@ -94,7 +94,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -114,7 +114,7 @@ writer.write(entry)
 ## Phase 5: Cross-Reference with Dreaming
 
 1. Read tonight's Dreaming report (if it exists):
-   `~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+   `${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 2. Read pending insights from `~/.arkaos/insights.db`:
 ```python
@@ -145,7 +145,7 @@ store.save(insight)
 ## Phase 6: Intelligence Briefing
 
 Write daily briefing to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Research/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Research/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/hooks/user-prompt-submit.sh

@@ -368,7 +368,12 @@ else
 fi
 
 # ─── Metrics ─────────────────────────────────────────────────────────────
+# Count @-mentions in the prompt for at_mention_frequency telemetry. Mirrors
+# the claude_code.at_mention OpenTelemetry event introduced in Claude Code
+# 2.1.122, but works on any version because we count from the same input
+# the hook already receives.
+at_mentions=$(printf '%s' "$user_input" | grep -oE '(^|[[:space:]])@[A-Za-z0-9_./-]+' | wc -l | tr -d ' ')
 elapsed=$(_hook_ms)
 if [ "$elapsed" -gt 0 ] 2>/dev/null; then
-  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
+  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed,\"at_mentions\":${at_mentions:-0}}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
 fi

package/core/cognition/capture/collector.py

@@ -7,13 +7,20 @@ from datetime import datetime, timezone
 
 from core.cognition.capture.store import CaptureStore
 from core.cognition.memory.schemas import RawCapture
+from core.runtime.path_resolver import ProfileMissingError, project_root_regex
+
+_FALLBACK_REGEX = re.compile(
+    r"((?:/Users|/home)/\S+/(?:Herd|Work|AIProjects|code|repos))[/\\]([^\s/\\]+)"
+)
 
 
 def _detect_project(digest: str) -> tuple[str, str]:
     """Try to detect project name and path from digest content."""
-    path_match = re.search(
-        r"(/Users/\S+/(?:Herd|Work|AIProjects)/([^\s/]+))", digest
-    )
+    try:
+        regex = project_root_regex()
+    except ProfileMissingError:
+        regex = _FALLBACK_REGEX
+    path_match = regex.search(digest)
     if path_match:
         return path_match.group(2).rstrip("/"), path_match.group(1).rstrip("/")
     return "unknown", os.getcwd()

package/core/cognition/scheduler/daemon.py

@@ -144,6 +144,11 @@ class ArkaScheduler:
         claude_bin = self._resolve_claude_binary()
         prompt_path = os.path.expanduser(schedule.prompt_file)
         prompt_content = Path(prompt_path).read_text(encoding="utf-8")
+        try:
+            from core.runtime.path_resolver import resolve
+            prompt_content = resolve(prompt_content)
+        except Exception:
+            pass  # fall back to raw template if profile unavailable
         return [claude_bin, "-p", prompt_content, "--dangerously-skip-permissions"]
 
     # ------------------------------------------------------------------

package/core/obsidian/writer.py

@@ -130,14 +130,15 @@ class ObsidianWriter:
 
         if config_path.exists():
             try:
+                from core.runtime.path_resolver import resolve
                 config = json.loads(config_path.read_text())
-                vault = config.get("vault_path", "")
-                if vault and Path(vault).exists():
+                vault = resolve(config.get("vault_path", ""))
+                if vault and not vault.startswith("${") and Path(vault).exists():
                     return Path(vault)
-            except (json.JSONDecodeError, OSError):
+            except (json.JSONDecodeError, OSError, Exception):
                 pass
 
-        # 3. Environment variable
+        # 3. Environment variable (legacy fallback only — path_resolver handles ARKAOS_VAULT_PATH)
         env_vault = os.environ.get("ARKAOS_VAULT", "")
         if env_vault and Path(env_vault).exists():
             return Path(env_vault)

package/core/runtime/path_resolver.py

@@ -0,0 +1,202 @@
+"""Template-token path resolver for ArkaOS.
+
+Resolves user-specific paths from ``~/.arkaos/profile.json`` and environment
+variables, so source files can use neutral tokens like ``${VAULT_PATH}`` and
+``${ARKA_OS_REPOS}`` instead of hardcoded absolute paths.
+
+Token precedence (highest → lowest):
+  1. Environment variable (e.g. ``ARKAOS_VAULT_PATH``)
+  2. profile.json field (e.g. ``vaultPath``)
+  3. For ``${GIT_HOST}`` only: hardcoded default ``github.com``
+
+If ``~/.arkaos/profile.json`` is missing or unparseable and an
+unconfigured token is requested, ``ProfileMissingError`` is raised
+with a clear remediation message. Unknown tokens pass through
+unchanged so that prompt strings containing ``${SOME_BASH_VAR}`` for
+the agent are preserved.
+
+See ``core/specs/SPEC-paths-portability.md`` for the full contract.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from core.runtime.user_paths import user_data_root
+
+_PROFILE_FILENAME = "profile.json"
+_TOKEN_PATTERN = re.compile(r"\$\{([A-Z_]+)\}")
+
+_DEFAULT_PROJECT_ROOTS = ["~/Herd", "~/Work", "~/AIProjects"]
+_DEFAULT_REPOS_ROOT = "~/AIProjects"
+_DEFAULT_GIT_HOST = "github.com"
+
+_PROFILE_CACHE: "ProfileV3 | None" = None
+
+
+class ProfileMissingError(RuntimeError):
+    """Raised when ``~/.arkaos/profile.json`` cannot be loaded."""
+
+
+@dataclass(frozen=True)
+class ProfileV3:
+    """In-memory representation of profile.json v3."""
+
+    version: str
+    vault_path: str
+    repos_root: str
+    project_roots: list[str] = field(default_factory=list)
+    raw: dict = field(default_factory=dict)
+
+
+def profile_path() -> Path:
+    """Absolute path to ``~/.arkaos/profile.json``."""
+    return user_data_root() / _PROFILE_FILENAME
+
+
+def load_profile(*, refresh: bool = False) -> ProfileV3:
+    """Load and validate profile.json.
+
+    Cached per process; pass ``refresh=True`` to force a re-read.
+
+    Raises:
+        ProfileMissingError: file absent, unreadable, or unparseable JSON.
+    """
+    global _PROFILE_CACHE
+    if _PROFILE_CACHE is not None and not refresh:
+        return _PROFILE_CACHE
+
+    path = profile_path()
+    if not path.exists():
+        raise ProfileMissingError(
+            f"~/.arkaos/profile.json not found at {path}. "
+            "Run /arka setup to configure ArkaOS paths."
+        )
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ProfileMissingError(
+            f"~/.arkaos/profile.json could not be parsed ({exc}). "
+            "Run /arka setup to repair, or restore from a .bak file."
+        ) from exc
+
+    _PROFILE_CACHE = _project_from_raw(raw)
+    return _PROFILE_CACHE
+
+
+def reset_cache() -> None:
+    """Drop the cached profile (for tests)."""
+    global _PROFILE_CACHE
+    _PROFILE_CACHE = None
+
+
+def resolve(template: str) -> str:
+    """Substitute known ``${VAR}`` tokens in *template*.
+
+    Tokens recognised:
+      - ``${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, default ``github.com``
+      - ``${HOME}``          → ``os.path.expanduser("~")``
+
+    Unknown tokens pass through unchanged.
+    """
+    return _TOKEN_PATTERN.sub(_resolve_token_match, template)
+
+
+def resolve_dict(obj):
+    """Recursively resolve every string value in nested dicts/lists."""
+    if isinstance(obj, str):
+        return resolve(obj)
+    if isinstance(obj, dict):
+        return {k: resolve_dict(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [resolve_dict(item) for item in obj]
+    return obj
+
+
+def project_root_regex() -> re.Pattern[str]:
+    """Compile a regex matching paths under any configured project root.
+
+    Used by ``core/cognition/capture/collector.py`` to detect project paths
+    inside captured session digests across macOS, Linux and Windows.
+    """
+    profile = load_profile()
+    roots = [os.path.expanduser(r) for r in profile.project_roots] or [
+        os.path.expanduser(r) for r in _DEFAULT_PROJECT_ROOTS
+    ]
+    alternation = "|".join(re.escape(r.rstrip("/").rstrip("\\")) for r in roots)
+    return re.compile(rf"({alternation})[/\\]([^\s/\\]+)")
+
+
+def _resolve_token_match(match: re.Match[str]) -> str:
+    return _resolve_token(match.group(1), match.group(0))
+
+
+def _resolve_token(name: str, original: str) -> str:
+    if name == "HOME":
+        return os.path.expanduser("~")
+    if name == "GIT_HOST":
+        return _env_or("ARKAOS_GIT_HOST", _DEFAULT_GIT_HOST)
+    if name == "VAULT_PATH":
+        env_val = _env_or("ARKAOS_VAULT_PATH", _env_or("ARKAOS_VAULT", ""))
+        return env_val or load_profile().vault_path
+    if name == "ARKA_OS_REPOS":
+        env_val = _env_or("ARKAOS_REPOS_ROOT", "")
+        return env_val or load_profile().repos_root
+    if name == "PROJECT_ROOTS":
+        env_val = _env_or("ARKAOS_PROJECT_ROOTS", "")
+        if env_val:
+            return env_val
+        return os.pathsep.join(load_profile().project_roots)
+    return original
+
+
+def _env_or(name: str, fallback: str) -> str:
+    value = os.environ.get(name, "")
+    return value if value else fallback
+
+
+def _project_from_raw(raw: dict) -> ProfileV3:
+    vault_path = raw.get("vaultPath") or raw.get("vault_path") or ""
+    if not vault_path:
+        raise ProfileMissingError(
+            "profile.json has no vaultPath. Run /arka setup to configure it."
+        )
+    repos_root = (
+        raw.get("reposRoot")
+        or raw.get("repos_root")
+        or _DEFAULT_REPOS_ROOT
+    )
+    project_roots = list(raw.get("projectRoots") or [])
+    if not project_roots:
+        project_roots = _derive_project_roots(raw.get("projectsDir", ""))
+    return ProfileV3(
+        version=str(raw.get("version", "2")),
+        vault_path=vault_path,
+        repos_root=repos_root,
+        project_roots=project_roots,
+        raw=raw,
+    )
+
+
+def _derive_project_roots(projects_dir_text: str) -> list[str]:
+    """Best-effort parse of the legacy free-text ``projectsDir`` field.
+
+    Looks for absolute paths on macOS/Linux/Windows. Falls back to
+    ``_DEFAULT_PROJECT_ROOTS`` when no path can be extracted. This keeps
+    the ~20K legacy users functional until ``npx arkaos update`` rewrites
+    their profile.json with the new ``projectRoots`` field.
+    """
+    if not projects_dir_text:
+        return list(_DEFAULT_PROJECT_ROOTS)
+    posix = r"(?:/Users|/home)/\S+?/(?:Herd|Work|AIProjects|code|repos)"
+    windows = r"[A-Z]:\\Users\\[^\s\\]+\\(?:Herd|Work|AIProjects|code|repos)"
+    pattern = re.compile(rf"({posix}|{windows})")
+    found = pattern.findall(projects_dir_text)
+    return found or list(_DEFAULT_PROJECT_ROOTS)