arkaos 2.22.1 → 2.28.0

package/departments/brand/agents/design-ops/wcag-auditor.yaml

@@ -0,0 +1,76 @@
+id: wcag-auditor-oren
+name: Oren
+role: Accessibility Auditor
+department: brand
+tier: 2
+model: sonnet
+
+parent_squad: brand
+sub_squad_role: wcag-auditor
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: S
+    communication_style: "Methodical, cites the exact WCAG criterion, never bluffs"
+    under_pressure: "Reports findings in priority order with severity; refuses to skip levels"
+    motivator: "Interfaces every human can actually use, including with assistive tech"
+  enneagram:
+    type: 1
+    wing: 2
+    core_motivation: "Make accessibility the default rather than a retrofit"
+    core_fear: "A real user blocked by a contrast ratio or focus-trap nobody caught"
+    subtype: social
+  big_five:
+    openness: 55
+    conscientiousness: 92
+    extraversion: 38
+    agreeableness: 68
+    neuroticism: 32
+  mbti:
+    type: ISTJ
+
+mental_models:
+  primary:
+    - "WCAG 2.2 (AA + AAA)"
+    - "POUR Principles (Perceivable, Operable, Understandable, Robust)"
+    - "ARIA Authoring Practices"
+  secondary:
+    - "Inclusive Design Microsoft toolkit"
+    - "Cognitive Load Theory (Sweller)"
+    - "Universal Design (Mace)"
+
+authority:
+  orchestrate: false
+  approve_quality: false
+  delegates_to: []
+  escalates_to: design-ops-lead-iris
+
+expertise:
+  domains:
+    - WCAG 2.2 AA / AAA conformance auditing
+    - color contrast ratio analysis (4.5:1 text, 3:1 large text and UI)
+    - keyboard navigation and focus management
+    - screen reader compatibility (NVDA, JAWS, VoiceOver)
+    - ARIA pattern review (no-redundant-roles, correct landmarks)
+    - cognitive accessibility (reading level, error recovery)
+    - accessibility statement drafting
+  frameworks:
+    - WCAG 2.2
+    - WAI-ARIA 1.2
+    - ATAG 2.0
+    - EAA / EN 301 549
+    - axe-core ruleset
+    - Section 508
+  depth: master
+  years_equivalent: 11
+
+communication:
+  language: en
+  tone: "neutral, criterion-cited, never moralising"
+  vocabulary_level: advanced
+  preferred_format: "issue tables (severity / criterion / location / fix), conformance reports"
+  avoid:
+    - "claiming AAA without measurement"
+    - "blocking a ship on a Level AAA edge case"
+    - "fixing accessibility late instead of as a design constraint"

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

@@ -118,3 +118,19 @@ The user should set these in their shell profile or project `.env`, or run `bash
 - `DISCORD_TOKEN` — Discord bot integration
 - `WHATSAPP_API_TOKEN` / `WHATSAPP_PHONE_ID` — WhatsApp Business API
 - `TEAMS_APP_ID` / `TEAMS_APP_SECRET` — Microsoft Teams
+
+## Recommended baseline (Orgo 2026-05-13)
+
+Three MCPs that the 2026-05-13 podcast pattern recommends for every
+agent-business setup. They are *optional* in the registry but worth
+adopting deliberately:
+
+| MCP | Why | When to add |
+| --- | --- | --- |
+| **Composio** | One connector, thousands of apps (Gmail, Slack, Notion, GitHub). Handles auth + tool calling without per-tool wiring. | Any agent that needs broad SaaS integration. Cuts setup time on every new customer. |
+| **Agent Mail** | Gives each agent a real email address that it can read and send from. Adds the "digital employee" feel that closes deals. | Customer-facing agents, executive assistants, follow-up workflows. |
+| **XMCP** | Twitter / X's official MCP. Brings community wisdom into the agent's context — recent threads, hot takes, real-time discourse. | Research-heavy workflows, content / community / sales squads. |
+
+These pair naturally with the existing `Firecrawl` (deep scrape),
+`Context7` (official docs), and `Perplexity` (real-time web). The
+`/arka research` skill fans out across all five.

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) {

package/installer/migrations/v3_path_schema.js

@@ -0,0 +1,109 @@
+/**
+ * Migration: profile.json schema v2 → v3 (paths-portability, v2.23.0).
+ *
+ * Adds the structured `projectRoots: string[]` and `reposRoot: string`
+ * fields to every existing profile.json so the new path_resolver token
+ * substitution can run for the 20K-user installed base.
+ *
+ * Strategy:
+ *   1. Skip if `version === "3"` or `projectRoots` already present (idempotent).
+ *   2. Otherwise:
+ *        - Write `.bak-<unix-timestamp>` backup beside the profile.
+ *        - Parse `projectsDir` free-text to extract absolute paths.
+ *        - Default to ["~/Herd","~/Work","~/AIProjects"] if parsing returns 0.
+ *        - reposRoot = first match containing "AIProjects", else "~/AIProjects".
+ *        - Atomic write (temp file + rename) with version: "3" and migrated_at.
+ *        - Log to ~/.arkaos/logs/migrate.log.
+ *
+ * Safe for concurrent invocations: the backup filename includes the
+ * timestamp, atomic rename prevents partial writes, and the idempotent
+ * guard means a second run is a no-op.
+ *
+ * Contract documented in core/specs/SPEC-paths-portability.md (PR1 v2.23.0).
+ */
+
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const DEFAULT_PROJECT_ROOTS = ["~/Herd", "~/Work", "~/AIProjects"];
+const DEFAULT_REPOS_ROOT = "~/AIProjects";
+
+export function migrateProfileSchemaV3({ profilePath, logPath } = {}) {
+  const profile = profilePath || join(homedir(), ".arkaos", "profile.json");
+  const log = logPath || join(homedir(), ".arkaos", "logs", "migrate.log");
+
+  if (!existsSync(profile)) {
+    return { skipped: true, reason: "profile.json absent" };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(profile, "utf8"));
+  } catch (err) {
+    return { skipped: true, reason: `parse error: ${err.message}` };
+  }
+
+  if (raw.version === "3" || Array.isArray(raw.projectRoots)) {
+    return { skipped: true, reason: "already migrated" };
+  }
+
+  const projectRoots = parseProjectsDirText(raw.projectsDir || "");
+  const reposRoot =
+    projectRoots.find((r) => r.includes("AIProjects")) || DEFAULT_REPOS_ROOT;
+
+  const migrated = {
+    ...raw,
+    version: "3",
+    projectRoots,
+    reposRoot,
+    migrated_at: new Date().toISOString(),
+  };
+
+  const backup = `${profile}.bak-${Math.floor(Date.now() / 1000)}`;
+  writeFileSync(backup, readFileSync(profile, "utf8"));
+
+  const tmp = `${profile}.tmp`;
+  writeFileSync(tmp, JSON.stringify(migrated, null, 2));
+  renameSync(tmp, profile);
+
+  writeLog(log, projectRoots, reposRoot);
+
+  return {
+    migrated: true,
+    projectRoots,
+    reposRoot,
+    backup,
+  };
+}
+
+export function parseProjectsDirText(text) {
+  if (!text) return [...DEFAULT_PROJECT_ROOTS];
+  const posix = /(?:\/Users|\/home)\/\S+?\/(?:Herd|Work|AIProjects|code|repos)/g;
+  const windows = /[A-Z]:\\Users\\[^\s\\]+\\(?:Herd|Work|AIProjects|code|repos)/g;
+  const found = [
+    ...(text.match(posix) || []),
+    ...(text.match(windows) || []),
+  ];
+  return found.length > 0 ? found : [...DEFAULT_PROJECT_ROOTS];
+}
+
+function writeLog(logPath, projectRoots, reposRoot) {
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+    const line =
+      `[arka:migrated] ${new Date().toISOString()} ` +
+      `profile.json schema v2 → v3 (` +
+      `${projectRoots.length} roots, reposRoot=${reposRoot})\n`;
+    appendFileSync(logPath, line);
+  } catch {
+    // Log failure should never block migration.
+  }
+}

package/installer/package-manager.js

@@ -0,0 +1,191 @@
+/**
+ * Cross-OS package manager abstraction for the ArkaOS installer.
+ *
+ * Centralises detection of brew (macOS), winget/choco (Windows) and
+ * apt/snap (Linux) so install/update flows can either run a non-sudo
+ * install themselves or return a copy-paste command for the user.
+ *
+ * **Never invokes sudo automatically.** When sudo is required (apt /
+ * snap on Linux, winget without elevation), `installViaPackageManager`
+ * returns `{ needsSudo: true, command }` and the caller is expected
+ * to print the command for the user to run. This keeps the installer
+ * headless-safe — it must not surprise a CI job with a password prompt.
+ *
+ * See core/specs/SPEC-installer-cross-os.md (PR2 v2.24.0).
+ */
+
+import { execSync } from "node:child_process";
+import { platform } from "node:os";
+import { IS_WINDOWS } from "./platform.js";
+
+const MAC = "darwin";
+const LINUX = "linux";
+
+/**
+ * Detect the highest-priority package manager available on this host.
+ *
+ * Priority order:
+ *   macOS:   brew
+ *   Linux:   apt > snap (apt for generic packages; snap preferred for
+ *            Obsidian because its tarball is classic-confined)
+ *   Windows: winget > choco
+ *
+ * Returns the canonical name string or null when nothing is available.
+ */
+export function detectPackageManager() {
+  const candidates = preferredCandidates();
+  for (const name of candidates) {
+    if (hasCommand(name)) return name;
+  }
+  return null;
+}
+
+/**
+ * Return every package manager available on this host, in priority order.
+ * Useful for callers that need a different manager per package (e.g.
+ * snap for Obsidian on a host that also has apt for Node).
+ */
+export function detectAllPackageManagers() {
+  return preferredCandidates().filter((name) => hasCommand(name));
+}
+
+/**
+ * Build the install command for a package on a given manager, without
+ * executing it. Useful for `formatSudoInstructions` and for dry-run paths.
+ */
+export function buildInstallCommand(manager, pkg) {
+  switch (manager) {
+    case "brew":
+      return pkg.startsWith("cask:")
+        ? `brew install --cask ${pkg.slice(5)}`
+        : `brew install ${pkg}`;
+    case "apt":
+      return `sudo apt update && sudo apt install -y ${pkg}`;
+    case "snap":
+      return pkg.endsWith(":classic")
+        ? `sudo snap install ${pkg.slice(0, -8)} --classic`
+        : `sudo snap install ${pkg}`;
+    case "winget":
+      return `winget install --id ${pkg} --silent --accept-source-agreements --accept-package-agreements`;
+    case "choco":
+      return `choco install ${pkg} -y`;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Whether a manager needs sudo (or Windows elevation) for install.
+ * brew on macOS is intentionally not sudo-gated (Homebrew runs as the user).
+ */
+export function managerNeedsSudo(manager) {
+  return manager === "apt" || manager === "snap";
+}
+
+/**
+ * Attempt a non-sudo install. When the chosen manager requires sudo
+ * we never invoke it ourselves — the caller surfaces the command to
+ * the user. Returns a structured result the caller can react to.
+ */
+export function installViaPackageManager(pkg, options = {}) {
+  const manager = options.manager || detectPackageManager();
+  if (!manager) {
+    return {
+      success: false,
+      manager: null,
+      command: "",
+      needsSudo: false,
+      installed: false,
+      error: "no_package_manager",
+      fallbackUrl: options.fallbackUrl || null,
+    };
+  }
+
+  const command = buildInstallCommand(manager, pkg);
+  const needsSudo = managerNeedsSudo(manager);
+
+  if (needsSudo) {
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: true,
+      installed: false,
+      error: null,
+    };
+  }
+
+  if (options.dryRun) {
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: false,
+      installed: false,
+      error: null,
+    };
+  }
+
+  try {
+    execSync(command, { stdio: "inherit" });
+    return {
+      success: true,
+      manager,
+      command,
+      needsSudo: false,
+      installed: true,
+      error: null,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      manager,
+      command,
+      needsSudo: false,
+      installed: false,
+      error: err?.message || "install_failed",
+    };
+  }
+}
+
+/**
+ * Format an array of sudo install commands into a copy-paste block.
+ * Used by ensureSystemTools to print a single, friendly block when
+ * several packages need privileged install on Linux.
+ */
+export function formatSudoInstructions(commands) {
+  if (!commands || commands.length === 0) return "";
+  const unique = [...new Set(commands.filter(Boolean))];
+  if (unique.length === 0) return "";
+  const lines = [
+    "",
+    "  To finish setup, please run these commands:",
+    "",
+    ...unique.map((c) => `    ${c}`),
+    "",
+    "  Then re-run: npx arkaos install",
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function preferredCandidates() {
+  const os = platform();
+  if (os === MAC) return ["brew"];
+  if (os === LINUX) return ["apt", "snap"];
+  if (IS_WINDOWS) return ["winget", "choco"];
+  return [];
+}
+
+function hasCommand(name) {
+  const finder = IS_WINDOWS ? "where" : "command -v";
+  try {
+    execSync(`${finder} ${name}`, {
+      stdio: ["ignore", "ignore", "ignore"],
+      shell: !IS_WINDOWS,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}