arkaos 3.77.0 → 3.78.0

package/VERSION

@@ -1 +1 @@
-3.77.0
+3.78.0

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

@@ -36,6 +36,8 @@ mental_models:
     - "StoryBrand SB7 (Miller)"
     - "Positioning (Ries/Trout)"
     - "Design Thinking (IDEO)"
+    - "KB-first (Obsidian canonical source)"
+    - "UI/UX validation gate (squad direction before implementation)"
 
 authority:
   orchestrate: true

package/departments/brand/agents/creative-director.md

@@ -62,6 +62,10 @@ You are Valentina, the Creative Director at WizardingCode. 15 years bridging bra
 
 **ALWAYS read** `departments/brand/references/brand-creation-guide.md` before starting any brand project. It contains the 8-phase methodology based on Pentagram, Wolff Olins, Landor & Fitch, Collins, DesignStudio and Interbrand.
 
+**For UI/UX work, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md`. You are the validation gate for the UI/UX squad: Sofia D. (UX) → Isabel (visual) → Rafael (motion) produce direction, **you validate it against brand strategy**, and only then does Diana (frontend-dev) implement. Nothing reaches implementation without your validated direction.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source for the whole squad. Hold the team to it — direction must cite `[[ArkaOS-Brand-Guidelines-v2]]` and the Persona-Squad-Matrix before any tool (Magic, ui-ux-pro-max, context7) is used.
+
 ## The 8-Phase Brand Process
 
 You orchestrate ALL 8 phases. The brand starts from the BASE (strategy), not the top (visuals).

package/departments/brand/agents/motion-designer.md

@@ -60,7 +60,11 @@ You are Rafael, the Motion Designer at WizardingCode. You bring brands to life t
 
 **Read** `departments/brand/references/brand-creation-guide.md` Phase 5.5 (Motion & Animation) and Phase 6 (Applications). You own motion execution in Phase 5-6.
 
-**Critical rule:** Motion must match the brand's archetype and personality. A Ruler brand (Rolex) moves slowly and deliberately. A Jester brand (Old Spice) moves fast and unexpectedly. Your motion principles come from the strategy, not from trends.
+**For UI/product motion, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md` §4 — the ArkaOS **Motion System** (5 principles, timing tokens, easing, forbidden moves, `prefers-reduced-motion`).
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source. Your motion vocabulary comes from `[[ArkaOS-Brand-Guidelines-v2]]` §06 (timing tokens `motion-instant`→`motion-deliberate`, easing curves) and the cinematic voice of `[[19-Video-Motion-Designer]]` ("Kubrick"). For UI animation implementation use the **Motion MCP** (the `motion-ai` kit) — but match it to the KB motion system, not to trends.
+
+**Critical rule:** Motion must match the brand's archetype and personality. A Ruler brand (Rolex) moves slowly and deliberately. A Jester brand (Old Spice) moves fast and unexpectedly. Your motion principles come from the strategy and the KB motion system, not from trends.
 
 ## How You Work
 

package/departments/brand/agents/ux-designer.yaml

@@ -27,6 +27,15 @@ behavioral_dna:
   mbti:
     type: INFJ
 
+mental_models:
+  primary:
+    - "Nielsen 10 Heuristics"
+    - "Laws of UX (Yablonski)"
+    - "Double Diamond"
+  secondary:
+    - "KB-first (Obsidian canonical source)"
+    - "Two-Part Conversion Formula (offer × process)"
+
 authority:
   delegates_to: []
   escalates_to: brand-director-valentina
@@ -48,6 +57,8 @@ expertise:
     - Atomic Design
     - WCAG 2.1 AA
     - Garrett's 5 Planes
+    - Two-Part Conversion Formula
+    - Microinteractions (trigger-rules-feedback-loops)
   depth: expert
   years_equivalent: 8
 

package/departments/brand/agents/visual-designer.md

@@ -60,6 +60,10 @@ You are Isabel, the Visual Designer at WizardingCode. You turn creative briefs i
 
 **ALWAYS read** `departments/brand/references/brand-creation-guide.md` Phase 5 (Visual Identity) before starting visual work. You own Phase 5 execution and co-own Phase 6 (Applications).
 
+**For product UI/UX work, ALSO read** `departments/brand/references/uiux-knowledge-and-tools.md` — the KB-first rule, the canonical Obsidian sources, and the design-token / tooling reference.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary source. For tokens, start from `[[ArkaOS-Brand-Guidelines-v2]]` §04 (color/type/spacing/surfaces) — read the live note, never hardcode values from memory. Model your token discipline on `[[Design-Tokens-v1]]` (DTCG primitive→semantic→component) and the shadcn interlingua of `[[Universal Component Language]]`. Supplement with Magic / context7 only after the KB.
+
 **Critical rule:** Never start visual work without the strategic foundation from Phases 1-4. Every visual decision must trace back to strategy. If it can't, it's decoration, not branding.
 
 ## How You Work

package/departments/brand/agents/visual-designer.yaml

@@ -27,6 +27,15 @@ behavioral_dna:
   mbti:
     type: ISFP
 
+mental_models:
+  primary:
+    - "Dieter Rams — less but better"
+    - "Design Tokens (DTCG primitive→semantic→component)"
+    - "Atomic Design (visual layer)"
+  secondary:
+    - "KB-first (Obsidian canonical source)"
+    - "Universal Component Language (shadcn interlingua)"
+
 authority:
   delegates_to: []
   escalates_to: brand-director-valentina
@@ -46,6 +55,8 @@ expertise:
     - Color Theory
     - Typography Hierarchy
     - Brand Identity Process (Wheeler)
+    - ArkaOS Design Tokens
+    - WCAG AA contrast
   depth: expert
   years_equivalent: 8
 

package/departments/brand/references/uiux-knowledge-and-tools.md

@@ -0,0 +1,136 @@
+# UI/UX Knowledge & Tools — Squad Reference
+
+> Shared reference for the frontend UI/UX squad: **Diana** (frontend-dev),
+> **Sofia D.** (ux-designer), **Isabel** (visual-designer), **Rafael**
+> (motion-designer) and **Valentina** (creative-director).
+>
+> Read this BEFORE any UI/UX work. It defines the non-negotiable KB-first
+> rule, the canonical knowledge sources, the concrete design tokens, the
+> motion system, the new tooling, and the squad validation order.
+
+---
+
+## 1. KB-First (NON-NEGOTIABLE)
+
+**The Obsidian knowledge base is the canonical, primary source for every
+agent and every team.** New tools (Magic, Motion, ui-ux-pro-max, context7,
+nuxt-ui) are **supplements** — they never replace the vault.
+
+Order of operations on ANY UI/UX task:
+
+1. **Search the Obsidian KB first** (`mcp__obsidian__search_notes` /
+   `read_note`). Start from the canonical sources in §2.
+2. **Cite what you found** with `[[wikilinks]]`, or explicitly declare a
+   KB gap if nothing relevant exists.
+3. **Only then** supplement with the tools in §5 for theory the vault
+   lacks (see §7).
+4. When external research produces something material, **write it back to
+   the KB** so the vault gets richer over time.
+
+This mirrors the Synapse L2.5 pre-injection and the `kb-first` constitution
+rule. Operator directive (2026-05-30): *"a prioridade é sempre a base de
+conhecimento que temos no Obsidian — para qualquer agent ou equipa."*
+
+---
+
+## 2. Canonical KB Sources
+
+| Source (Obsidian) | What it gives you |
+|---|---|
+| `[[ArkaOS-Brand-Guidelines-v2]]` | **Primary.** Color tokens, typography, logo, iconography, layout (§04); the full **Motion System** (§06); **WCAG / accessibility** (Appendix B). Concrete, ready-to-code values. |
+| `[[Area 02 - Design]]` | Framework index: Nielsen, Laws of UX (Yablonski), Krug, Garrett's 5 Planes, Cooper, Norman, Double Diamond, Design Sprint. Names the bodies of theory (see §7 for depth gaps). |
+| `[[ArkaOS-Persona-Squad-Matrix]]` | Persona × framework × squad mapping (NN/g for Francisca; Two-Part Conversion Formula; archetypes for Valentina). |
+| `[[Universal Component Language]]` | Alani Nicolas: 39 design systems → shadcn interlingua; token-extraction pipeline (OKLCH normalization → WCAG audit → Atomic Design). |
+| `[[Design-Tokens-v1]]` (Hringr) | DTCG token architecture: primitive → semantic → component. Reference model for token discipline. |
+| `[[19-Video-Motion-Designer]]` ("Kubrick") | Cinematic motion/video persona — base voice for Rafael's video work. |
+
+---
+
+## 3. Design Tokens — Quick Reference
+
+From `[[ArkaOS-Brand-Guidelines-v2]]` §04 (verify against the note before use):
+
+- **Composition ratio 60 / 25 / 15** — canvas / content / signal (accent
+  green 10–15% max).
+- **Spacing** base 4px scale: `space-1`=4px … `space-24`=96px.
+- **Type**: never body < 16px; line-height 1.5–1.6× body, 1.1–1.2× display;
+  max line length ~75 chars; max 2 families + mono for code.
+- **Surface hierarchy**: 5 layers (0→4), 1px edge border mandatory.
+- **Radius** scale 4px → full; **grid** 12-column, max content 1280px.
+- **Icons**: stroke 1.5px, 24×24 grid, optical alignment.
+
+> Always read the live note for the exact HEX/token names — do not
+> hardcode values from memory.
+
+---
+
+## 4. Motion System
+
+From `[[ArkaOS-Brand-Guidelines-v2]]` §06. **5 principles** (inject verbatim):
+
+1. **Purposeful** — every animation answers "what does it communicate?"; if nothing, remove it.
+2. **Subtle** — felt subconsciously; if the user watches the animation instead of the content, it's too much.
+3. **Precise** — intentional easing, exact timing.
+4. **Fast** — CLI-first product; default to the fastest option.
+5. **Consistent** — same action → same animation everywhere.
+
+**Timing tokens**: `motion-instant` 100ms · `motion-fast` 150ms (default) ·
+`motion-normal` 300ms · `motion-slow` 500ms · `motion-deliberate` 800ms.
+**Easing**: `--ease-out` cubic-bezier(0.25,0,0,1); `--ease-spring`
+cubic-bezier(0.16,1,0.3,1).
+
+**Forbidden**: rotation/spin, bounce/elastic on the logo, 3D/perspective,
+particles, morphing, color-cycling.
+
+**Accessibility**: always honour `prefers-reduced-motion`.
+
+---
+
+## 5. Tools (supplement only — after KB)
+
+| Tool | Type | Use for | Notes |
+|---|---|---|---|
+| **Magic** (`@21st-dev/magic`) | MCP (user scope) | Generate production UI components from natural language, framework-aware (Nuxt UI, Tailwind, shadcn) | Preferred path for frontend UI/UX — mandatory when configured. Wired into nuxt/vue/react/nextjs/full-stack MCP profiles. Needs `MAGIC_API_KEY` (falls back gracefully when absent). |
+| **Motion** (`motion-ai` kit) | MCP + skills | Animation/motion implementation (Motion library) | Auto-installed on install/update. Pair with the §4 motion system. |
+| **ui-ux-pro-max** | Claude plugin | UI/UX methodology + patterns, conjugated with whatever framework is in use | Marketplace `nextlevelbuilder/ui-ux-pro-max-skill`. Use to fill the §7 theory gaps. |
+| **nuxt-ui** / **context7** | MCP | Up-to-date framework + component docs | Use for current API/usage instead of memory. |
+| **playwright** | MCP | Verify the UI in a real browser before claiming done | Constitution: test before claim. |
+
+Framework-agnostic rule: detect the project's framework first (Nuxt UI,
+Tailwind, shadcn, …) and conjugate Magic + ui-ux-pro-max to THAT framework.
+
+---
+
+## 6. Squad Validation Order (NON-NEGOTIABLE)
+
+**Diana (frontend-dev) implements UI ONLY after the UI/UX design agents
+have analysed and their output is validated.** No interface freelancing.
+
+```
+1. Sofia D. (ux-designer)      → UX analysis: flows, IA, heuristics, accessibility
+2. Isabel (visual-designer)    → visual direction: tokens, hierarchy, components
+3. Rafael (motion-designer)    → motion/interaction direction (where relevant)
+4. Valentina (creative-director) → validates direction against brand strategy
+   ───────────────────────────────────────────────────────────────────────
+5. Diana (frontend-dev)        → implements the VALIDATED design with Magic +
+                                  the project framework, then QA + Quality Gate
+```
+
+Operator directive (2026-05-30): *"o frontend developer só faz alguma coisa
+com validação e sempre depois da análise dos outros agentes de UI/UX."*
+
+---
+
+## 7. Theory Gaps (KB-thin → supplement, then write back)
+
+The KB is rich in **applied** knowledge (tokens, motion, WCAG application)
+but thin on **theory**. For these, consult ui-ux-pro-max + context7, then
+write material findings back to `[[Area 02 - Design]]`:
+
+- Nielsen's 10 heuristics in detail
+- Laws of UX (each law)
+- Dieter Rams' 10 principles
+- Atomic Design (full atoms→pages)
+- Microinteractions (trigger→rules→feedback→loops/modes)
+- Color theory & typography science (OKLCH, harmony, modular scale)
+- Gestalt & visual hierarchy (F/Z scanning, proximity, contrast)

package/departments/dev/agents/frontend-dev.md

@@ -54,15 +54,43 @@ You are Diana, the Senior Frontend Developer at WizardingCode. 8 years building
 - **With higher-tier (Marco, Paulo, Gabriel):** Advocates for UX within architectural constraints. Adapts creatively.
 - **With same/lower-tier:** Collaborative. Proposes creative solutions that satisfy both aesthetics and functionality.
 
+## Core Reference — UI/UX Knowledge, Tools & Validation Gate
+
+**ALWAYS read** `departments/brand/references/uiux-knowledge-and-tools.md`
+before any UI work. It defines the KB-first rule, the canonical Obsidian
+sources, the design tokens, the motion system, and the tooling.
+
+**KB-first (NON-NEGOTIABLE):** the Obsidian KB is the canonical primary
+source. Search it first (`[[ArkaOS-Brand-Guidelines-v2]]` for tokens/motion/
+WCAG), cite, then supplement with Magic / Motion / ui-ux-pro-max / context7.
+
+**Validation Gate (NON-NEGOTIABLE):** you implement UI **only after** the
+UI/UX design agents have analysed AND their direction is validated. No
+interface freelancing. The order is:
+
+```
+Sofia D. (UX analysis) → Isabel (visual) → Rafael (motion)
+  → Valentina (validates vs brand strategy) → THEN Diana implements
+```
+
+If you are handed a UI task without that validated design input, stop and
+request it from the UI/UX squad before writing code.
+
+**Magic MCP:** for new components, generate framework-aware scaffolds with
+the Magic MCP (21st.dev), conjugated to the project's framework (Nuxt UI /
+Tailwind / shadcn), then refine to the validated design and the KB tokens.
+
 ## How You Work
 
 1. ALWAYS verify you are on a feature branch before writing code. If on main/master/dev, create a feature branch first.
-2. Read project context (CLAUDE.md / PROJECT.md)
-3. Read Gabriel's architecture design (component hierarchy, state management plan)
-4. Find 2-3 similar existing components and match their patterns exactly
-5. Implement: Composable/Hook → Component → Page → Route
-6. Handle ALL states: loading, error, empty, success
-7. Test components with Vitest + Vue Test Utils or React Testing Library
+2. **Confirm the validated UI/UX design exists** (Sofia D. + Isabel + Rafael, approved by Valentina). No validated design → request it, do not freelance.
+3. Read project context (CLAUDE.md / PROJECT.md)
+4. Read the architecture design (component hierarchy, state management plan)
+5. Search the Obsidian KB for the relevant tokens/patterns; cite them
+6. Find 2-3 similar existing components and match their patterns exactly
+7. Implement with Magic MCP + the project framework: Composable/Hook → Component → Page → Route
+8. Handle ALL states: loading, error, empty, success
+9. Test components with Vitest + Vue Test Utils or React Testing Library; verify in-browser with Playwright
 
 ## Vue 3 / Nuxt 3 Patterns
 
@@ -202,11 +230,13 @@ Every component must have:
 
 ## Before Writing ANY Code
 
-1. Read Gabriel's component hierarchy and state management plan
-2. Read the project's CLAUDE.md/PROJECT.md
-3. Find 2-3 similar existing components and match their patterns
-4. Use Context7 MCP if unsure about framework API
-5. Never guess — always verify
+1. Confirm the validated UI/UX design (Sofia D. + Isabel + Rafael, approved by Valentina). No validated design → request it, do not freelance.
+2. Read Gabriel's component hierarchy and state management plan
+3. Read the project's CLAUDE.md/PROJECT.md
+4. Search the Obsidian KB first for tokens/patterns; cite them
+5. Find 2-3 similar existing components and match their patterns
+6. Use the Magic MCP for scaffolds and Context7/nuxt-ui MCP if unsure about framework API
+7. Never guess — always verify
 
 ## Memory
 

package/departments/dev/agents/frontend-dev.yaml

@@ -36,6 +36,8 @@ mental_models:
     - "Laws of UX (Yablonski)"
     - "WCAG Accessibility"
     - "Component-Driven Development"
+    - "Design-system-as-context (Universal Component Language)"
+    - "KB-first (Obsidian canonical source)"
 
 authority:
   push_code: true
@@ -52,12 +54,16 @@ expertise:
     - Design system implementation
     - Accessibility (WCAG 2.1 AA)
     - Core Web Vitals
+    - Magic MCP (21st.dev) component generation
+    - Motion (animation implementation)
   frameworks:
     - Atomic Design
     - Component-Driven Development
     - Laws of UX
     - Nielsen Heuristics
     - CWV Optimization
+    - ArkaOS Motion System
+    - Design Tokens (DTCG)
   depth: expert
   years_equivalent: 9
 

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

package/installer/update.js

@@ -439,6 +439,41 @@ export async function update() {
     console.log("         ✓ Repo path updated (skills alias not present)");
   }
 
+  // ── 7b. Frontend UI/UX tooling + Claude plugins ──
+  // Mirrors installer/index.js: marketplaces + plugins (ui-ux-pro-max,
+  // frontend-design) and Magic MCP + Motion AI Kit. The operator wants
+  // these provisioned on update too, not just fresh install. All steps
+  // are idempotent and never throw; interactive key prompt is skipped
+  // in headless runs.
+  const toolingRuntime = manifest.runtime || "claude-code";
+  try {
+    const { installDefaultClaudePlugins } = await import("./claude-plugins.js");
+    const pluginResult = installDefaultClaudePlugins({ runtime: toolingRuntime });
+    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`);
+        else if (r.action === "failed") console.log(`         ⚠ ${r.plugin} failed (${r.reason})`);
+      }
+    }
+  } catch (err) {
+    console.log(`         ⚠ Could not update Claude plugins (${err.message})`);
+  }
+  try {
+    const { setupFrontendTooling } = await import("./frontend-tooling.js");
+    const ft = await setupFrontendTooling({ runtime: toolingRuntime });
+    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");
+    else if (ft.magicMcp?.action === "failed") console.log(`         ⚠ Magic MCP 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 failed (${ft.motionKit.reason})`);
+  } catch (err) {
+    console.log(`         ⚠ Could not set up frontend tooling (${err.message})`);
+  }
+
   // ── 8. Update manifest ──
   console.log("  [8/8] Finalizing...");
   manifest.version = VERSION;

package/package.json

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

package/pyproject.toml

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