arkaos 2.22.1 → 2.28.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.28.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/bootstrap-agent/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: arka-bootstrap-agent
+description: >
+  Formalises the "agents set up agents" pattern surfaced in the 2026-05-13
+  Nick Saraev × Greg Isenberg podcast on the Orgo agent business. When the
+  user asks to spin up a new specialist or an integration that requires
+  research-heavy setup, this skill orchestrates The Forge to dispatch
+  research subagents (Perplexity / Exa / Context7 / Firecrawl / XMCP),
+  synthesises the findings, and produces a ready-to-use agent YAML or
+  installation guide.
+allowed-tools: [Agent, Read, Write, Bash]
+---
+
+# /arka bootstrap-agent — agents that set up agents
+
+> Pattern source: Nick Saraev (Orgo) interview, 2026-05-13. ArkaOS already
+> has The Forge for complexity-based planning; this skill is the explicit
+> entry point users invoke when they want a new specialist or a setup
+> playbook rather than a feature.
+
+## Subcommands
+
+| Command | What it does |
+| --- | --- |
+| `/arka bootstrap-agent specialist <slug>` | Generates a new Tier 2 agent YAML for a domain you describe. Dispatches research subagents to gather domain frameworks, conventions, and common pitfalls. Produces `departments/<dept>/agents/<slug>.yaml` with full 4-framework DNA. |
+| `/arka bootstrap-agent integration <tool>` | Installation playbook for an external tool (e.g. Hermes, Composio, Agent Mail). Researches official docs + community recipes, outputs a step-by-step setup guide and any required MCP config. |
+| `/arka bootstrap-agent persona <name>` | Builds an AI persona profile (DISC + Enneagram + OCEAN + MBTI) from learned content. Delegates to `/kb` (Clara) for source ingestion. |
+
+## How it works
+
+```
+User: /arka bootstrap-agent specialist "design-tokens-engineer"
+  │
+  ▼
+1. The Forge classifies request complexity (usually "medium" — single
+   specialist, multiple research dimensions).
+2. Spawns 3-5 research subagents in parallel:
+     - Perplexity MCP → real-time framework discovery
+     - Exa AI → semantic search for prior art
+     - Context7 → official documentation pulls
+     - Firecrawl → scrape competitor / canonical sources
+     - XMCP → Twitter / X conversations for community wisdom
+3. Critic synthesis: a Tier 0 reviewer collapses overlap, surfaces
+   contradictions, prioritises by source weight.
+4. Generates the deliverable (YAML / playbook / persona) and saves to
+   the canonical path.
+5. Quality Gate (Marta + Eduardo + Francisca) approves before output
+   reaches the user.
+```
+
+## Why this exists
+
+Per the Orgo interview, the recurring pattern in successful one-person
+agent businesses is "use agents to set up agents". ArkaOS already had
+the primitives — The Forge for planning, the Agent tool for subagent
+dispatch, KB-first research — but no single entry point that made the
+pattern *the* way to add capability. This skill is that entry.
+
+## Boundaries
+
+- This skill **generates**. It does not modify production code.
+- The generated YAML lands in `departments/<dept>/agents/` for review;
+  it is **not** auto-registered until the user commits and the next
+  loader pass picks it up.
+- Personas built via this skill go through `/kb` for the actual
+  content ingestion (YouTube / PDFs / articles). This skill orchestrates,
+  it does not bypass the knowledge pipeline.
+
+## Cross-references
+
+- Source pattern: 2026-05-13 Orgo podcast (Nick Saraev × Greg Isenberg)
+- Related: `/arka forge` (planning engine, lower level)
+- Related: `/kb persona` (content-driven persona builder)
+- Related: `/arka research` (the same research-fan-out pattern for
+  one-off knowledge tasks rather than agent generation)
+- Memory: [[project_next_level_conclave]]

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/arka/skills/design-ops/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: arka-design-ops
+description: >
+  Brand Design Ops sub-squad orchestrator. Routes design-system extraction,
+  WCAG audit, and shadcn padronisation work to Iris (lead) + Nia
+  (extraction) + Oren (WCAG) + Leo (shadcn). Inspired by the AIOX Squad
+  → Sub-Squad pattern documented in the 2026-04-30 KB live and unblocked
+  for ArkaOS by the v2.27.0 Conclave roadmap.
+allowed-tools: [Read, Write, Bash, Edit]
+---
+
+# /brand design-ops — Design Ops sub-squad
+
+> Sub-squad of `/brand` (Valentina). Operational specialists for the
+> production rails of design systems: tokens, audits, components.
+
+## Squad
+
+| Agent | Role | Tier | Owns |
+| --- | --- | --- | --- |
+| **Iris** (`design-ops-lead`) | Lead | 1 | governance, escalation to Valentina |
+| **Nia** (`extraction-script-writer`) | Specialist | 2 | reverse-engineer tokens from sites / figma |
+| **Oren** (`wcag-auditor`) | Specialist | 2 | WCAG 2.2 AA conformance + reports |
+| **Leo** (`shadcn-padronizer`) | Specialist | 2 | shadcn/ui canonical components |
+
+## Subcommands
+
+| Command | Owner | What it does |
+| --- | --- | --- |
+| `/brand design-ops extract <url>` | Nia | Extract color, typography, spacing tokens from a live URL or figma file. Writes JSON to `~/.arkaos/design-ops/<slug>/tokens.json`. |
+| `/brand design-ops wcag <url\|path>` | Oren | Run WCAG 2.2 AA audit. Outputs issue table (severity / criterion / location / fix) + conformance score. |
+| `/brand design-ops shadcn <component>` | Leo | Generate or refactor a component to the shadcn/ui canonical form (CVA variants, Radix primitives, theme tokens). |
+| `/brand design-ops audit <project>` | Iris | Orchestrate full audit: tokens drift, WCAG conformance, component-library variance. Produces a single report. |
+
+## Scripts (under `scripts/`)
+
+The scripts library is intentionally small at v2.27.0 — three reference
+implementations to anchor the pattern. Nia / Oren / Leo extend it as
+ArkaOS evolves; AIOX's reference set is ~30 scripts and ArkaOS will
+catch up incrementally.
+
+| Script | Owner | Input | Output |
+| --- | --- | --- | --- |
+| `scripts/extract-colors.py` | Nia | URL or local HTML | `colors.json` (DTCG-compliant token list) |
+| `scripts/wcag-contrast.py` | Oren | hex pairs OR CSS file | Issue list with contrast ratios + AA / AAA verdict |
+| `scripts/shadcn-tokens.py` | Leo | tokens.json | shadcn CSS variables block + Tailwind config snippet |
+
+Run any script with `python3 scripts/<name>.py --help` for usage.
+
+## Output
+
+All design-ops output writes to:
+- `~/.arkaos/design-ops/<slug>/` — generated artefacts (JSON, CSS, reports)
+- `${VAULT_PATH}/Projects/Design Ops/<slug>.md` — human-readable summary (Obsidian)
+
+## Boundaries
+
+- Strategy and visual direction stay with **Valentina** (`/brand`).
+- Iris escalates anything that requires brand-level taste calls.
+- Design-ops never opens PRs or pushes code; it produces specs, tokens,
+  audits. Implementation goes back to `/dev` via Paulo.
+
+## Cross-references
+
+- Pattern source: KB note `🧠 Knowledge Base/Frameworks/AIOX Squads` (2026-04-30 live)
+- ADR: this skill is the v2.27.0 Conclave instantiation of the sub-squad pattern
+- Parent: `/brand` (Valentina)
+- Stack origin: v2.27.0 (PR5 of 6 from the 2026-05-13 Conclave roadmap)

package/arka/skills/design-ops/scripts/extract-colors.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Extract colour tokens from CSS / HTML / JSON (Nia's reference script).
+
+Scans the input for hex colours and named CSS variables, normalises to
+lower-case 6-digit hex, deduplicates, and emits a DTCG-compliant
+``colors.json`` token list.
+
+Usage:
+    python3 extract-colors.py path/to/styles.css
+    python3 extract-colors.py --stdin < styles.css
+    cat styles.css | python3 extract-colors.py --stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+HEX = re.compile(r"#([0-9a-fA-F]{3,8})\b")
+RGB = re.compile(r"rgb(?:a)?\((\d+)\s*,\s*(\d+)\s*,\s*(\d+)")
+
+
+def normalise(hex_value: str) -> str | None:
+    h = hex_value.lower()
+    if len(h) == 3:
+        h = "".join(c * 2 for c in h)
+    elif len(h) == 4:
+        h = "".join(c * 2 for c in h[:3])
+    elif len(h) == 8:
+        h = h[:6]
+    if len(h) != 6:
+        return None
+    return f"#{h}"
+
+
+def rgb_to_hex(r: int, g: int, b: int) -> str:
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+def extract(text: str) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+    for m in HEX.finditer(text):
+        norm = normalise(m.group(1))
+        if norm and norm not in seen:
+            seen.add(norm)
+            out.append(norm)
+    for r, g, b in RGB.findall(text):
+        norm = rgb_to_hex(int(r), int(g), int(b))
+        if norm not in seen:
+            seen.add(norm)
+            out.append(norm)
+    return out
+
+
+def to_dtcg(colors: list[str]) -> dict:
+    tokens = {}
+    for i, c in enumerate(colors):
+        slug = f"color-{i:03d}"
+        tokens[slug] = {"$value": c, "$type": "color"}
+    return {"$schema": "https://design-tokens.org/draft", "colors": tokens}
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("source", nargs="?", help="path to CSS / HTML file")
+    parser.add_argument("--stdin", action="store_true", help="read from stdin")
+    args = parser.parse_args(argv)
+
+    if args.stdin or args.source == "-":
+        text = sys.stdin.read()
+    elif args.source:
+        text = Path(args.source).read_text(encoding="utf-8")
+    else:
+        parser.error("provide a source path or use --stdin")
+
+    colors = extract(text)
+    print(json.dumps(to_dtcg(colors), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/arka/skills/design-ops/scripts/shadcn-tokens.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""Convert DTCG colour tokens into shadcn/ui CSS variables (Leo's script).
+
+Reads a DTCG-style ``colors.json`` (as produced by ``extract-colors.py``)
+and emits the canonical shadcn/ui CSS variable block plus a matching
+``tailwind.config.js`` ``theme.extend.colors`` snippet.
+
+Usage:
+    python3 shadcn-tokens.py colors.json
+    python3 shadcn-tokens.py colors.json --prefix brand-
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def to_css_var(slug: str, value: str, prefix: str) -> str:
+    return f"  --{prefix}{slug}: {value};"
+
+
+def to_tailwind_entry(slug: str, prefix: str) -> str:
+    key = slug.replace("color-", "")
+    return f'        "{prefix}{slug}": "var(--{prefix}{slug})",'
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("source", help="path to DTCG colors.json")
+    parser.add_argument("--prefix", default="", help="CSS variable prefix (e.g. 'brand-')")
+    args = parser.parse_args(argv)
+
+    data = json.loads(Path(args.source).read_text(encoding="utf-8"))
+    tokens = data.get("colors", {})
+    if not tokens:
+        print("no colours found in source", file=sys.stderr)
+        return 1
+
+    css_vars = [to_css_var(slug, t["$value"], args.prefix) for slug, t in tokens.items()]
+    tailwind = [to_tailwind_entry(slug, args.prefix) for slug in tokens]
+
+    print(":root {")
+    print("\n".join(css_vars))
+    print("}\n")
+
+    print("// tailwind.config.js — theme.extend.colors")
+    print("{")
+    print('  theme: { extend: { colors: {')
+    print("\n".join(tailwind))
+    print("  } } }")
+    print("}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/arka/skills/design-ops/scripts/wcag-contrast.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""WCAG 2.2 contrast ratio checker (Oren's reference script).
+
+Compares foreground / background colours and reports whether the pair
+passes WCAG 2.2 Level AA (4.5 : 1 normal text, 3 : 1 large text and UI
+components) and AAA (7 : 1 normal, 4.5 : 1 large).
+
+Usage:
+    python3 wcag-contrast.py "#1a1a1a" "#ffffff"
+    python3 wcag-contrast.py --json "#0f172a" "#ffffff" "#3b82f6" "#ffffff"
+
+Outputs a single-line verdict or, with --json, a structured report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def relative_luminance(rgb: tuple[int, int, int]) -> float:
+    """WCAG relative luminance formula."""
+    def channel(c: int) -> float:
+        s = c / 255
+        return s / 12.92 if s <= 0.03928 else ((s + 0.055) / 1.055) ** 2.4
+
+    r, g, b = (channel(c) for c in rgb)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(fg: tuple[int, int, int], bg: tuple[int, int, int]) -> float:
+    lf, lb = relative_luminance(fg), relative_luminance(bg)
+    lighter, darker = max(lf, lb), min(lf, lb)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    s = hex_color.lstrip("#")
+    if len(s) == 3:
+        s = "".join(c * 2 for c in s)
+    if len(s) != 6:
+        raise ValueError(f"Invalid hex colour: {hex_color}")
+    return int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
+
+
+def verdict(ratio: float) -> dict[str, bool]:
+    return {
+        "AA_normal": ratio >= 4.5,
+        "AA_large": ratio >= 3.0,
+        "AAA_normal": ratio >= 7.0,
+        "AAA_large": ratio >= 4.5,
+    }
+
+
+def check_pair(fg_hex: str, bg_hex: str) -> dict[str, object]:
+    fg = hex_to_rgb(fg_hex)
+    bg = hex_to_rgb(bg_hex)
+    ratio = round(contrast_ratio(fg, bg), 2)
+    return {
+        "fg": fg_hex,
+        "bg": bg_hex,
+        "ratio": ratio,
+        **verdict(ratio),
+    }
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("colors", nargs="*", help="alternating fg bg pairs")
+    parser.add_argument("--json", action="store_true", help="emit JSON report")
+    args = parser.parse_args(argv)
+
+    if len(args.colors) < 2 or len(args.colors) % 2 != 0:
+        parser.error("provide pairs of hex colours: <fg> <bg> [<fg> <bg> ...]")
+
+    pairs = list(zip(args.colors[::2], args.colors[1::2]))
+    results = [check_pair(fg, bg) for fg, bg in pairs]
+
+    if args.json:
+        print(json.dumps({"results": results}, indent=2))
+        return 0
+
+    for r in results:
+        flags = [k for k, v in r.items() if k.startswith("AA") and v]
+        flag_str = "+".join(flags) if flags else "FAILS_ALL"
+        print(f"{r['fg']} on {r['bg']}: {r['ratio']}:1  → {flag_str}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))