arkaos 3.77.0 → 4.0.0

package/departments/saas/agents/revops-lead.yaml

@@ -0,0 +1,73 @@
+id: revops-lead-vicente
+name: Vicente
+role: RevOps Lead
+department: saas
+tier: 1
+model: sonnet
+
+behavioral_dna:
+  disc:
+    primary: D
+    secondary: C
+    communication_style: "Numbers-first, dashboard-driven, breaks silos between mkt/sales/CS"
+    under_pressure: "Unifies the funnel view, fixes the leakiest stage first"
+    motivator: "One revenue engine — shared metrics, no departmental silos"
+  enneagram:
+    type: 3
+    wing: 2
+    core_motivation: "A predictable, compounding revenue machine end-to-end"
+    core_fear: "Siloed funnels and unowned hand-offs leaking revenue"
+    subtype: social
+  big_five:
+    openness: 72
+    conscientiousness: 82
+    extraversion: 58
+    agreeableness: 45
+    neuroticism: 26
+  mbti:
+    type: ENTJ
+
+mental_models:
+  primary:
+    - "Predictable Revenue (Ross)"
+    - "Shared revenue metrics (no silos)"
+    - "RevOps — unified CRM + funnel"
+  secondary:
+    - "LTV/CAC ≥ 3 & NRR > 100%"
+    - "KB-first (Obsidian canonical source)"
+
+authority:
+  orchestrate: true
+  delegates_to: []
+  escalates_to: saas-strategist-tiago
+
+expertise:
+  domains:
+    - revenue operations (cross mkt + sales + CS)
+    - unified funnel & CRM hygiene
+    - SLA MQL→SQL between marketing and sales
+    - revenue metrics (LTV/CAC, NRR, payback)
+    - lead scoring & routing
+    - commission & forecast modeling
+  frameworks:
+    - Predictable Revenue (Ross)
+    - "Loops > Funnels"
+    - Unit Economics (LTV/CAC, NRR)
+    - RevOps
+  knowledge_sources:
+    - "[[Receita Previsivel - Aaron Ross]]"
+    - "[[2026-05-30 G4 Pass - Metricas Comerciais Cluster]]"
+    - "[[2026-05-30 G4 Pass - Loops de Crescimento Sao Novos Funis]]"
+    - "[[Autonomia Por Missões (Não Departamentos)]]"
+  depth: expert
+  years_equivalent: 11
+
+communication:
+  language: en
+  tone: "data-driven, funnel-oriented, breaks silos"
+  vocabulary_level: specialist
+  preferred_format: "revenue dashboards, funnel maps, SLA definitions"
+  avoid:
+    - "departmental metrics that hide the whole funnel"
+    - "unowned hand-offs between mkt/sales/CS"
+    - "acquisition spend before fixing churn (Leaky Bucket)"

package/departments/saas/skills/leaky-bucket/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: saas/leaky-bucket
+description: >
+  Leaky-Bucket gate — audit churn and retention BEFORE approving acquisition
+  spend. Every 1% of churn compounds against LTV forever, so fix the bucket
+  before pouring more in. Owned by the RevOps squad.
+allowed-tools: [Read, Write, Edit, Agent]
+---
+
+# Leaky-Bucket Gate — `/saas leaky-bucket`
+
+> **Agent:** Vicente (RevOps Lead) + Patricia (Head of CS) · **Framework:** Leaky Bucket / Retention-first
+> KB: [[Leaky-Bucket Diagnostic]] · [[Retention Flywheel]] · [[Atendimento Como Gerador de Receita]]
+
+A **gate** to run before any acquisition campaign or CAC increase. If the bucket leaks, more traffic just leaks faster.
+
+## The gate (pass/fail before acquisition)
+1. **Measure current churn** (logo + revenue) vs benchmark: B2C 5-7%/mo, B2B 1-2%/mo, Enterprise <1%/mo.
+2. **NRR check:** is Net Revenue Retention > 100%? If < 100%, expansion is not covering churn → **gate fails**.
+3. **Activation check:** time-to-first-value and activation rate healthy? Most churn happens between onboarding and the first quick win (48-72h).
+4. **Compounding math:** show LTV at current churn vs LTV at target churn. A 1-point churn improvement usually beats a 1-point CAC improvement.
+
+## Verdict
+- **PASS** → acquisition is approved; the new revenue will stick.
+- **FAIL** → freeze/limit acquisition; route to the Retain & Recover missions to fix onboarding, NRR and win-back first, then re-run the gate.
+
+## Output
+A short gate report (churn, NRR, activation, LTV-at-current-vs-target) + verdict, in Obsidian. Wire into the Acquire mission as a pre-condition.

package/departments/saas/skills/voc-loop/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: saas/voc-loop
+description: >
+  Voice of Customer loop — collect signal, close the loop with the customer,
+  cluster the themes, and run PDCA. Only 1 in 26 unhappy customers complains,
+  so closing the loop beats collecting more. Owned by the RevOps squad.
+allowed-tools: [Read, Write, Edit, Agent]
+---
+
+# Voice of Customer Loop — `/saas voc-loop`
+
+> **Agent:** Rita S. (SaaS Metrics & VoC Analyst) · **Framework:** Voice of Customer + CX metrics
+> KB: [[Processo Voice of Customer (VoC)]] · [[8 Métricas de CX (Nardon-Siqueira)]]
+
+A continuous loop, not a one-off survey. For every 26 dissatisfied customers, only 1 complains — so the signal is scarce and closing the loop matters more than collecting.
+
+## The loop (continuous)
+1. **Collect** across sources: NPS, CSAT (interaction), CES (friction), support tickets, churn reasons, sales-lost reasons.
+2. **Close the loop** with the customer who gave the signal — respond, acknowledge, tell them what changed. (This is the step most teams skip and where the value is.)
+3. **Cluster** signals into themes before acting (don't react to single anecdotes).
+4. **PDCA:** Plan a fix for the top theme → Do (ship) → Check (did the metric move?) → Act (standardise or revert).
+
+## Metric distinctions (don't conflate)
+- **NPS** = macro loyalty (would you recommend?)
+- **CSAT** = immediate interaction satisfaction
+- **CES** = effort/friction (96% of high-effort customers become less loyal)
+
+## Output
+A VoC theme report (clustered, ranked) + closed-loop log + the PDCA experiment status, in Obsidian. Feed themes to the Activate/Retain missions and to Product (Carolina) for discovery.

package/departments/sales/agents/sales-director.yaml

@@ -33,6 +33,8 @@ mental_models:
     - "Challenger Sale (Dixon/Adamson)"
     - "MEDDIC Qualification"
   secondary:
+    - "Predictable Revenue (Ross)"
+    - "Living ICP"
     - "Sandler Selling System"
     - "Pipeline Velocity Formula"
     - "BATNA Negotiation"
@@ -53,6 +55,10 @@ expertise:
     - discovery calls
     - deal qualification
     - revenue forecasting
+    - The Ask Method (diagnose before offering)
+    - living ICP definition (top 20% most profitable; quarterly review; ICP != Persona)
+    - MQL→SQL funnel with SLAs
+    - predictable revenue engine (Seeds/Nets/Spears; SDR→AE→CSM specialization)
   frameworks:
     - SPIN Selling
     - Challenger Sale
@@ -60,6 +66,9 @@ expertise:
     - Sandler
     - Pipeline Velocity
     - BATNA
+    - The Ask Method
+    - "Predictable Revenue (Seeds/Nets/Spears) [[Receita Previsivel - Aaron Ross]]"
+    - "MQL→SQL conversion & ICP [[Conversao MQL-SQL e ICP]]"
   depth: expert
   years_equivalent: 12
 

package/departments/sales/agents/sdr.yaml

@@ -0,0 +1,72 @@
+id: sdr-martim
+name: Martim
+role: SDR / Pre-Sales
+department: sales
+tier: 2
+model: sonnet
+
+behavioral_dna:
+  disc:
+    primary: I
+    secondary: D
+    communication_style: "Energetic, outreach-driven, qualifies fast and warmly"
+    under_pressure: "Doubles outreach volume, sharpens the qualifying questions"
+    motivator: "A full, well-qualified pipeline handed clean to the closers"
+  enneagram:
+    type: 3
+    wing: 2
+    core_motivation: "Opening doors and qualifying the right-fit prospects at scale"
+    core_fear: "An empty or junk-filled pipeline; wasting the closer's time"
+    subtype: social
+  big_five:
+    openness: 66
+    conscientiousness: 68
+    extraversion: 78
+    agreeableness: 60
+    neuroticism: 28
+  mbti:
+    type: ESFP
+
+mental_models:
+  primary:
+    - "Predictable Revenue — Spears / Cold Calling 2.0 (Ross)"
+    - "MQL→SQL qualification with SLA"
+    - "ICP fit scoring (not persona)"
+  secondary:
+    - "The Ask Method (ask before pitching)"
+    - "KB-first (Obsidian canonical source)"
+
+authority:
+  push_code: false
+  delegates_to: []
+  escalates_to: sales-director-miguel
+
+expertise:
+  domains:
+    - top-of-funnel prospecting & outreach
+    - lead qualification (MQL→SQL)
+    - cold email & cold calling 2.0
+    - ICP fit scoring & disqualification
+    - cadence / sequence design
+    - hand-off to Account Executive
+  frameworks:
+    - Predictable Revenue (Seeds/Nets/Spears)
+    - "MQL/SQL + SLA"
+    - The Ask Method
+    - ICP (top 20% most profitable)
+  knowledge_sources:
+    - "[[Receita Previsivel - Aaron Ross]]"
+    - "[[2026-05-30 G4 Pass - MQL e SQL]]"
+    - "[[2026-05-30 G4 Pass - Conversao MQL-SQL e ICP]]"
+  depth: expert
+  years_equivalent: 6
+
+communication:
+  language: en
+  tone: "energetic, concise, qualification-first"
+  vocabulary_level: advanced
+  preferred_format: "outreach sequences, qualification notes, clean SQL hand-offs"
+  avoid:
+    - "pitching before qualifying"
+    - "passing unqualified leads to closers"
+    - "ignoring the ICP fit"

package/departments/strategy/agents/decision-quality.yaml

@@ -0,0 +1,72 @@
+id: decision-quality-guilherme
+name: Guilherme
+role: Decision Quality & Strategic Foresight
+department: strategy
+tier: 2
+model: sonnet
+
+behavioral_dna:
+  disc:
+    primary: C
+    secondary: D
+    communication_style: "Asks for the 3rd alternative, surfaces the trade-off and the bet"
+    under_pressure: "Runs a premortem, separates reversible from irreversible decisions"
+    motivator: "Decisions that are well-framed, debiased, and revisited"
+  enneagram:
+    type: 5
+    wing: 6
+    core_motivation: "Clear thinking under uncertainty — the right call, well-reasoned"
+    core_fear: "A big irreversible bet made on HiPPO, consensus, or bias"
+    subtype: self-preservation
+  big_five:
+    openness: 85
+    conscientiousness: 82
+    extraversion: 32
+    agreeableness: 45
+    neuroticism: 26
+  mbti:
+    type: INTJ
+
+mental_models:
+  primary:
+    - "Strategy is trade-off (we do A, NOT B)"
+    - "Premortem + two-way doors (Bezos)"
+    - "Debiasing (anti-HiPPO / anti-consensus)"
+  secondary:
+    - "Strategic foresight (scenarios, anticipate trends)"
+    - "KB-first (Obsidian canonical source)"
+
+authority:
+  push_code: false
+  delegates_to: []
+  escalates_to: strategy-director-tomas
+
+expertise:
+  domains:
+    - decision framing & 3+ alternatives
+    - reversible vs irreversible (two-way doors)
+    - cognitive debiasing (HiPPO, consensus, anchoring)
+    - premortem / postmortem facilitation
+    - scenario planning & strategic foresight
+    - bias-to-action check
+  frameworks:
+    - HBR 5-Element Decision Process
+    - Premortem (Klein)
+    - Two-Way Doors (Bezos)
+    - "4 Strategic Insight Techniques"
+  knowledge_sources:
+    - "[[2026-05-30 G4 Pass - Cluster Estrategia e Decisao HBR]]"
+    - "[[2026-05-30 G4 Pass - Bias to Action]]"
+    - "[[Vieses - Erros para Decisao]]"
+  depth: expert
+  years_equivalent: 10
+
+communication:
+  language: en
+  tone: "analytical, probing, trade-off explicit"
+  vocabulary_level: specialist
+  preferred_format: "decision briefs (problem, 3+ options, trade-off, decider, review date)"
+  avoid:
+    - "single-option decisions"
+    - "HiPPO or consensus as the deciding force"
+    - "irreversible bets without a premortem"

package/departments/strategy/agents/strategy-director.yaml

@@ -29,10 +29,14 @@ behavioral_dna:
 
 mental_models:
   primary:
+    - "Strategy is trade-off (we choose A, we do NOT do B)"
+    - "7 Strata + BHAG (Harnish)"
     - "Playing to Win Cascade (Roger Martin)"
     - "Porter's Five Forces"
     - "Blue Ocean Strategy (Kim/Mauborgne)"
   secondary:
+    - "Strategic foresight (scenarios, anticipate trends)"
+    - "KB-first (Obsidian canonical source)"
     - "7 Powers / Moat Analysis (Helmer)"
     - "Wardley Maps (Wardley)"
     - "Business Model Canvas (Osterwalder)"
@@ -53,6 +57,9 @@ expertise:
     - positioning
     - innovation strategy
     - scenario planning
+    - trade-off framing (explicit choose A / NOT B)
+    - strategic foresight (scenarios, trend anticipation)
+    - long-range vision setting (BHAGs)
   frameworks:
     - Five Forces (Porter)
     - Playing to Win (Martin)
@@ -62,8 +69,14 @@ expertise:
     - 7 Powers (Helmer)
     - TAM/SAM/SOM
     - SWOT/PESTLE
+    - 7 Strata of Strategy (Scaling Up / Harnish)
+    - BHAG - Big Hairy Audacious Goal (Collins/Harnish)
+    - One-Page Strategic Plan (Scaling Up / Harnish)
   depth: expert
   years_equivalent: 12
+  knowledge_sources:
+    - "[[Scaling Up - Verne Harnish]]"
+    - "[[Cluster Estrategia e Decisao HBR]]"
 
 communication:
   language: en

package/departments/strategy/skills/premortem/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: strat/premortem
+description: >
+  Run a premortem before a big bet and a blameless postmortem after.
+  Decision-quality ritual: imagine the failure, surface risks, then learn
+  from the outcome without blame. Owned by the Governance squad.
+allowed-tools: [Read, Write, Edit, Agent]
+---
+
+# Premortem & Blameless Postmortem — `/strat premortem`
+
+> **Agent:** Guilherme (Decision Quality & Strategic Foresight) · escalates to the Governance squad (Afonso)
+> **Framework:** Premortem (Klein) + Blameless Postmortem · KB: [[2026-05-30 G4 Pass - Cluster Estrategia e Decisao HBR]]
+
+Use **before** any irreversible or high-stakes bet (a "two-way door" is reversible — skip it; a "one-way door" needs this).
+
+## Premortem (before the decision)
+1. **State the bet** in one sentence + the decider (RACI) + the deadline.
+2. **Assume it failed.** "It's 6 months from now and this was a disaster. Why?"
+3. Each participant writes failure causes independently (avoids groupthink/HiPPO).
+4. Cluster the causes; rank by likelihood × impact.
+5. For the top causes: add a mitigation or a kill-criterion. If a cause is fatal and unmitigable → **don't take the bet**.
+6. Record: 3+ alternatives considered, the trade-off ("we do A, NOT B"), the decider, the review date.
+
+## Blameless Postmortem (after the outcome)
+1. **Timeline of what happened** — facts, not blame. Systems fail, not people.
+2. What did we predict in the premortem that came true / didn't?
+3. **Root cause** (5 Whys) — stop at a system/process, never at a person.
+4. Lessons → concrete changes (a guardrail, a check, a default). Assign an owner.
+5. Cheap failure is learning: Coca-Cola, Netflix and Amazon institutionalise this.
+
+## Output
+A decision record (premortem) + a postmortem note in Obsidian, linked to the bet. Feeds the org's learning loop.

package/installer/claude-plugins.js

@@ -16,10 +16,18 @@ import { execSync, spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+// Third-party marketplaces that must be registered (via
+// `claude plugin marketplace add <repo>`) before their plugins can be
+// installed. Each entry is a GitHub `owner/repo` shorthand.
+export const DEFAULT_CLAUDE_MARKETPLACES = [
+  "nextlevelbuilder/ui-ux-pro-max-skill",
+];
+
 // Each entry is "name@marketplace" matching the `claude plugin install`
 // CLI argument format.
 export const DEFAULT_CLAUDE_PLUGINS = [
   "frontend-design@claude-plugins-official",
+  "ui-ux-pro-max@ui-ux-pro-max-skill",
 ];
 
 const _INSTALLED_REGISTRY = join(
@@ -29,19 +37,40 @@ const _INSTALLED_REGISTRY = join(
 export function installDefaultClaudePlugins({
   runtime = "claude-code",
   plugins = DEFAULT_CLAUDE_PLUGINS,
+  marketplaces = DEFAULT_CLAUDE_MARKETPLACES,
   home = homedir(),
 } = {}) {
   if (runtime !== "claude-code") {
-    return { skipped: "runtime-not-claude-code", results: [] };
+    return { skipped: "runtime-not-claude-code", results: [], marketplaces: [] };
   }
   if (!isClaudeCliAvailable()) {
-    return { skipped: "claude-cli-not-found", results: [] };
+    return { skipped: "claude-cli-not-found", results: [], marketplaces: [] };
   }
+  // Marketplaces must be registered before their plugins can resolve.
+  const marketplaceResults = marketplaces.map((m) => addMarketplace(m));
   const alreadyInstalled = readInstalledRegistry(home);
   const results = plugins.map((p) =>
     installOne(p, alreadyInstalled),
   );
-  return { skipped: null, results };
+  return { skipped: null, results, marketplaces: marketplaceResults };
+}
+
+// Register a third-party plugin marketplace. Idempotent and never-throws:
+// a marketplace that is already known is reported as already-present.
+function addMarketplace(marketplace) {
+  const out = spawnSync("claude", ["plugin", "marketplace", "add", marketplace], {
+    timeout: 60_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+  });
+  if (out.status === 0) {
+    return { marketplace, action: "added" };
+  }
+  const msg = (out.stderr || out.error?.message || "").toLowerCase();
+  if (msg.includes("already") || msg.includes("exists")) {
+    return { marketplace, action: "already-present" };
+  }
+  return { marketplace, action: "failed", reason: msg.trim().slice(0, 200) };
 }
 
 function isClaudeCliAvailable() {

package/installer/doctor.js

@@ -195,6 +195,21 @@ const checks = [
     },
     fix: () => "Upgrade Claude Code: npm install -g @anthropic-ai/claude-code@latest",
   },
+  {
+    name: "magic-api-key",
+    description: "Magic API key configured (frontend UI/UX — Magic MCP)",
+    severity: "warn",
+    check: () => {
+      if (process.env.MAGIC_API_KEY) return true;
+      const keysPath = join(INSTALL_DIR, "keys.json");
+      if (!existsSync(keysPath)) return false;
+      try {
+        const keys = JSON.parse(readFileSync(keysPath, "utf-8"));
+        return !!keys.MAGIC_API_KEY;
+      } catch { return false; }
+    },
+    fix: () => "Run: npx arkaos keys set MAGIC_API_KEY <your-21st-dev-key>  (or re-run npx arkaos@latest update)",
+  },
 ];
 
 // ─── Windows-only checks ───────────────────────────────────────────────

package/installer/frontend-tooling.js

@@ -0,0 +1,150 @@
+// Frontend UI/UX tooling setup for `npx arkaos install` and
+// `npx arkaos@latest update`.
+//
+// Wires three operator-mandated tools into the install/update flow:
+//   1. Magic MCP (@21st-dev/magic) — user-scope, API-key gated. The key is
+//      prompted interactively when missing and never stored in the repo;
+//      it lives only in ~/.arkaos/keys.json (chmod 600) + Claude user config.
+//   2. Motion AI Kit (npx motion-ai) — auto-run on every install/update.
+//   3. (ui-ux-pro-max plugin + marketplace is handled in claude-plugins.js.)
+//
+// Invariants (.claude/rules/node-installer.md):
+//   - ESM, os.homedir()/path.join only, never hardcoded paths.
+//   - No interactive prompts during headless/CI runs (guarded by isTTY).
+//   - Never throws — every failure is logged and swallowed so the installer
+//     never breaks on optional tooling.
+
+import { existsSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { execSync, spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const MAGIC_ENV = "MAGIC_API_KEY";
+
+function keysPath(home) {
+  return join(home, ".arkaos", "keys.json");
+}
+
+function loadKeys(home) {
+  const path = keysPath(home);
+  if (!existsSync(path)) return {};
+  try { return JSON.parse(readFileSync(path, "utf-8")); } catch { return {}; }
+}
+
+function saveKey(home, name, value) {
+  const path = keysPath(home);
+  const keys = loadKeys(home);
+  keys[name] = value;
+  writeFileSync(path, JSON.stringify(keys, null, 2));
+  try { chmodSync(path, 0o600); } catch {}
+}
+
+// Resolve the Magic API key from (in order) keys.json, then the environment.
+function resolveMagicKey(home) {
+  const keys = loadKeys(home);
+  return keys[MAGIC_ENV] || process.env[MAGIC_ENV] || "";
+}
+
+// Prompt once for the key. Resolves to "" in headless contexts so the
+// installer never blocks on a closed stdin (node-installer rule).
+function promptMagicKey() {
+  if (!process.stdin.isTTY) return Promise.resolve("");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const q = "  21st.dev Magic API key (frontend UI/UX, leave empty to skip): ";
+  return new Promise((resolve) => {
+    rl.question(q, (answer) => { rl.close(); resolve((answer || "").trim()); });
+  });
+}
+
+// Ensure MAGIC_API_KEY exists, prompting interactively when missing.
+// Returns the resolved key (possibly "").
+export async function ensureMagicApiKey({ home = homedir() } = {}) {
+  const existing = resolveMagicKey(home);
+  if (existing) return existing;
+  const entered = await promptMagicKey();
+  if (entered) {
+    saveKey(home, MAGIC_ENV, entered);
+    console.log("         Magic API key saved to ~/.arkaos/keys.json (chmod 600).");
+  }
+  return entered;
+}
+
+function isClaudeCliAvailable() {
+  try {
+    execSync("claude --version", { stdio: "pipe", timeout: 5000 });
+    return true;
+  } catch { return false; }
+}
+
+function isMagicMcpRegistered() {
+  const out = spawnSync("claude", ["mcp", "list"], {
+    timeout: 10_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
+  });
+  return out.status === 0 && /(^|\s)magic(\s|:)/.test(out.stdout || "");
+}
+
+// Register the Magic MCP at Claude Code user scope. Idempotent and
+// never-throws. Skips on non-Claude runtimes, missing CLI, or missing key.
+export function registerMagicMcp({ runtime = "claude-code", apiKey = "" } = {}) {
+  if (runtime !== "claude-code") return { action: "skipped", reason: "runtime-not-claude-code" };
+  if (!isClaudeCliAvailable()) return { action: "skipped", reason: "claude-cli-not-found" };
+  if (!apiKey) return { action: "skipped", reason: "no-api-key" };
+  if (isMagicMcpRegistered()) return { action: "already-present" };
+  // NOTE (known limitation): the key is passed as a CLI argument because
+  // `claude mcp add` offers no stdin/file alternative. It is briefly
+  // visible to `ps`/proc while the child runs. It is NEVER written to the
+  // repo or to any log (only stderr is captured into `reason`).
+  const out = spawnSync("claude", [
+    "mcp", "add", "magic", "--scope", "user",
+    "--env", `API_KEY=${apiKey}`,
+    "--", "npx", "-y", "@21st-dev/magic@latest",
+  ], { timeout: 60_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+  if (out.error || out.status !== 0) {
+    const reason = (out.stderr || out.error?.message || "unknown").trim().slice(0, 200);
+    return { action: "failed", reason };
+  }
+  return { action: "registered" };
+}
+
+function motionMarkerPath(home) {
+  return join(home, ".arkaos", ".motion-kit-installed");
+}
+
+// Run the Motion AI Kit. Auto-runs (no prompt) per operator decision
+// (2026-05-30), but idempotently: a one-time marker in ~/.arkaos/ means
+// re-runs (e.g. every `npx arkaos update`) skip the 180s kit instead of
+// re-downloading it. Claude-runtime only, requires the claude CLI (the
+// kit installs Motion skills into the Claude agent), never-throws.
+export function installMotionKit({ runtime = "claude-code", home = homedir() } = {}) {
+  if (runtime !== "claude-code") return { action: "skipped", reason: "runtime-not-claude-code" };
+  if (!isClaudeCliAvailable()) return { action: "skipped", reason: "claude-cli-not-found" };
+  if (existsSync(motionMarkerPath(home))) return { action: "already-present" };
+  const out = spawnSync("npx", ["-y", "motion-ai"], {
+    timeout: 180_000, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
+  });
+  if (out.error || out.status !== 0) {
+    const reason = (out.stderr || out.error?.message || "unknown").trim().slice(0, 200);
+    return { action: "failed", reason };
+  }
+  try { writeFileSync(motionMarkerPath(home), new Date().toISOString()); } catch {}
+  return { action: "installed" };
+}
+
+// Orchestrate the full frontend tooling setup. Single entry point wired
+// into both installer/index.js and installer/update.js.
+export async function setupFrontendTooling({ runtime = "claude-code", home = homedir() } = {}) {
+  const results = {};
+  try {
+    const apiKey = await ensureMagicApiKey({ home });
+    results.magicMcp = registerMagicMcp({ runtime, apiKey });
+  } catch (err) {
+    results.magicMcp = { action: "failed", reason: err.message };
+  }
+  try {
+    results.motionKit = installMotionKit({ runtime, home });
+  } catch (err) {
+    results.motionKit = { action: "failed", reason: err.message };
+  }
+  return results;
+}

package/installer/index.js

@@ -352,6 +352,13 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     const { installDefaultClaudePlugins } = await import("./claude-plugins.js");
     const pluginResult = installDefaultClaudePlugins({ runtime });
     if (!pluginResult.skipped) {
+      for (const m of pluginResult.marketplaces || []) {
+        if (m.action === "added") {
+          console.log(`         marketplace ${m.marketplace} added.`);
+        } else if (m.action === "failed") {
+          console.log(`         marketplace ${m.marketplace} failed (${m.reason}).`);
+        }
+      }
       for (const r of pluginResult.results) {
         if (r.action === "installed") {
           console.log(`         ${r.plugin} installed.`);
@@ -366,6 +373,27 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
     console.log(`         Warning: could not install default Claude plugins (${err.message})`);
   }
 
+  // Frontend UI/UX tooling — Magic MCP (user scope, API-key gated) + Motion
+  // AI Kit. Key is prompted when missing (interactive only). Never blocks.
+  try {
+    const { setupFrontendTooling } = await import("./frontend-tooling.js");
+    const ft = await setupFrontendTooling({ runtime });
+    if (ft.magicMcp?.action === "registered") {
+      console.log("         Magic MCP registered (user scope).");
+    } else if (ft.magicMcp?.action === "already-present") {
+      console.log("         Magic MCP already registered (skipped).");
+    } else if (ft.magicMcp?.action === "failed") {
+      console.log(`         Magic MCP registration failed (${ft.magicMcp.reason}).`);
+    }
+    if (ft.motionKit?.action === "installed") {
+      console.log("         Motion AI Kit installed.");
+    } else if (ft.motionKit?.action === "failed") {
+      console.log(`         Motion AI Kit install failed (${ft.motionKit.reason}).`);
+    }
+  } catch (err) {
+    console.log(`         Warning: could not set up frontend tooling (${err.message})`);
+  }
+
   const manifest = {
     version: VERSION,
     runtime,

package/installer/keys.js

@@ -8,6 +8,7 @@ const PROVIDERS = {
   OPENAI_API_KEY: { name: "OpenAI", used_for: "Whisper transcription, embeddings, GPT" },
   GOOGLE_API_KEY: { name: "Google", used_for: "Gemini API, Nano Banana, Google Cloud AI" },
   FAL_API_KEY: { name: "fal.ai", used_for: "Image generation, video generation" },
+  MAGIC_API_KEY: { name: "21st.dev Magic", used_for: "Frontend UI/UX component generation (Magic MCP)" },
 };
 
 function loadKeys() {