arkaos 4.31.0 → 4.33.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 329 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 331 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.31.0 — 89 agents, 17 departments, 329 skills, 297 commands, 16 ADRs.
+> v4.33.0 — 89 agents, 17 departments, 331 skills, 297 commands, 16 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.31.0
+4.33.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 329 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 331 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

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

@@ -190,6 +190,16 @@ Tell user: "Visual companion available at http://localhost:<port>/forge-<id>.htm
 Note: For `shallow` tier, companion is not generated (`should_suggest_companion()` returns `"none"`).
 For `standard`, it is available on request. For `deep`, proactively suggest it.
 
+**Richer option — plan diagram via `dev/diagram`:** for `standard`/`deep`
+tiers, additionally offer an interactive plan diagram. Load the
+`dev/diagram` skill, author a `workflow` IR from the plan (`plan_phases`
+→ lane nodes in execution order, phase dependencies → edges, key
+deliverables → cards), and deliver it to the same `/tmp` directory as
+`/tmp/diagram-forge-<plan_id>.html` — the `http.server` above serves
+both artifacts side by side. The radar remains the default companion
+(zero Node dependency); if Node is unavailable, the radar is the only
+companion — never block the Forge on the diagram.
+
 ### Step 9 — Handoff (on Approve)
 
 1. Check for repo drift since the snapshot:

package/config/claude-agents/architect.md

@@ -1,7 +1,7 @@
 ---
 name: architect
 description: >
-  Gabriel — Software Architect (dev squad). Executes: system design, domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA), business / domain analysis.
+  Gabriel — Software Architect (dev squad). Executes: system design, system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts), domain modeling (event storming, bounded contexts), design patterns (GoF, PoEAA).
 model: sonnet
 ---
 

package/config/claude-agents/backend-dev.md

@@ -1,7 +1,7 @@
 ---
 name: backend-dev
 description: >
-  Andre — Backend Core Lead (dev squad). Executes: Laravel 11 / PHP 8.3, PostgreSQL / Supabase, REST API design, Service + Repository pattern.
+  Andre — Backend Core Lead (dev squad). Executes: Laravel 11 / PHP 8.3, PostgreSQL / Supabase, REST API design, API flow visualization via dev/diagram (sequence diagrams for endpoint contracts and async jobs).
 model: sonnet
 ---
 

package/config/claude-agents/brand-director.md

@@ -1,7 +1,7 @@
 ---
 name: brand-director
 description: >
-  Valentina — Creative Director (brand squad). Executes: brand identity creation, visual design direction, UX/UI strategy, design systems.
+  Valentina — Creative Director (brand squad). Executes: brand identity creation, reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots), visual design direction, UX/UI strategy.
 model: sonnet
 ---
 

package/config/claude-agents/content-strategist.md

@@ -1,7 +1,7 @@
 ---
 name: content-strategist
 description: >
-  Rafael — Content Strategist (content squad). Executes: viral content design, hook writing & packaging, script structure, content operating systems.
+  Rafael — Content Strategist (content squad). Executes: viral content design, reference-video analysis via dev/watch (frames + timestamped transcript before judging any video), hook writing & packaging, script structure.
 model: sonnet
 ---
 

package/config/claude-agents/devops-eng.md

@@ -1,7 +1,7 @@
 ---
 name: devops-eng
 description: >
-  Carlos — DevOps Lead (dev squad). Executes: CI/CD pipelines (GitHub Actions, GitLab CI), container orchestration (Docker, Kubernetes), infrastructure as code (Terraform, Pulumi), cloud platforms (Vercel, Azure, AWS).
+  Carlos — DevOps Lead (dev squad). Executes: CI/CD pipelines (GitHub Actions, GitLab CI), release visualization via dev/diagram (lifecycle + workflow diagrams for pipelines and rollouts), container orchestration (Docker, Kubernetes), infrastructure as code (Terraform, Pulumi).
 model: sonnet
 ---
 

package/config/claude-agents/frontend-dev.md

@@ -1,7 +1,7 @@
 ---
 name: frontend-dev
 description: >
-  Diana — Senior Frontend Developer (dev squad). Executes: Vue 3 (Composition API), Nuxt 3, React 19 / Next.js 15, TypeScript.
+  Diana — Senior Frontend Developer (dev squad). Executes: Vue 3 (Composition API), motion-reference analysis via dev/watch (scroll/animation benchmarks from frames + transcript before implementing), user-flow visualization via dev/diagram (workflow diagrams for page and interaction flows), Nuxt 3.
 model: opus
 ---
 

package/config/claude-agents/marketing-director.md

@@ -1,7 +1,7 @@
 ---
 name: marketing-director
 description: >
-  Luna — Marketing Director (marketing squad). Executes: growth strategy, content marketing, SEO, paid acquisition.
+  Luna — Marketing Director (marketing squad). Executes: growth strategy, video-ad teardown via dev/watch (hook, pacing and spoken-copy evidence from frames + transcript), content marketing, SEO.
 model: sonnet
 ---
 

package/config/claude-agents/ops-lead.md

@@ -1,7 +1,7 @@
 ---
 name: ops-lead
 description: >
-  Daniel — Operations Lead (ops squad). Executes: workflow automation (Zapier, Make, n8n), process mapping & optimization, SOP creation & management, bottleneck analysis.
+  Daniel — Operations Lead (ops squad). Executes: workflow automation (Zapier, Make, n8n), SOP/process visualization via dev/diagram (workflow + lifecycle diagrams for automations and runbooks), process mapping & optimization, SOP creation & management.
 model: sonnet
 ---
 

package/config/claude-agents/pm-director.md

@@ -1,7 +1,7 @@
 ---
 name: pm-director
 description: >
-  Carolina — Product Manager (pm squad). Executes: continuous product discovery (daily habit), weekly customer interviewing, dual-track agile (discovery + delivery), product risk assessment (value/usability/feasibility/viability).
+  Carolina — Product Manager (pm squad). Executes: continuous product discovery (daily habit), deliverable visualization via dev/diagram (workflow diagrams so stakeholders see scope before build), weekly customer interviewing, dual-track agile (discovery + delivery).
 model: sonnet
 ---
 

package/config/claude-agents/scriptwriter.md

@@ -1,7 +1,7 @@
 ---
 name: scriptwriter
 description: >
-  Joana — Scriptwriter (content squad). Executes: video scriptwriting (YouTube, Reels, TikTok), cinematic narrative for short and long-form, storyboard-ready scene writing (scene/shot/VO/on-screen-text columns), narrative structure (hook-bridge-body-CTA; beat sheets; story circles).
+  Joana — Scriptwriter (content squad). Executes: video scriptwriting (YouTube, Reels, TikTok), reference-video teardown via dev/watch (hook, pacing and beat analysis from frames + transcript), cinematic narrative for short and long-form, storyboard-ready scene writing (scene/shot/VO/on-screen-text columns).
 model: opus
 ---
 

package/config/claude-agents/strategy-director.md

@@ -1,7 +1,7 @@
 ---
 name: strategy-director
 description: >
-  Tomas — Chief Strategist (strategy squad). Executes: competitive strategy, market analysis, business model design, positioning.
+  Tomas — Chief Strategist (strategy squad). Executes: competitive strategy, business-flow visualization via dev/diagram (architecture + dataflow diagrams of business models and value chains), market analysis, business model design.
 model: sonnet
 ---
 

package/config/claude-agents/trends-analyst.md

@@ -1,7 +1,7 @@
 ---
 name: trends-analyst
 description: >
-  Margarida — Trends & Niche Analyst (content squad). Executes: trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa), niche viability scoring (audience size, competition density, monetization path, brand fit), platform algorithm shift monitoring, whitespace analysis for new channels and formats.
+  Margarida — Trends & Niche Analyst (content squad). Executes: trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa), viral-video deconstruction via dev/watch (scene-aware frames + transcript, timestamp-cited), niche viability scoring (audience size, competition density, monetization path, brand fit), platform algorithm shift monitoring.
 model: sonnet
 ---
 

package/config/claude-agents/video-producer.md

@@ -1,7 +1,7 @@
 ---
 name: video-producer
 description: >
-  Simão — Video Producer & Production Lead (content squad). Executes: video production pipelines (script → storyboard → assets → edit → render), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe), shot lists and EDLs (scene/shot/VO/on-screen-text columns).
+  Simão — Video Producer & Production Lead (content squad). Executes: video production pipelines (script → storyboard → assets → edit → render), cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate), Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4), Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe).
 model: opus
 ---
 

package/config/skills-curated.yaml

@@ -24,7 +24,8 @@ curated_subskills:
   community: [moderation]
   content: [calendar, hook-write]
   dev: [api-design, architecture-design, clean-code-review, code-review,
-        db-design, refactor-plan, runbook, security-audit, spec, tdd-cycle]
+        db-design, diagram, refactor-plan, runbook, security-audit, spec,
+        tdd-cycle, watch]
   ecom: [cart-recovery, store-audit]
   finance: [financial-model, unit-economics]
   kb: [search-kb, zettelkasten-process]

package/config/skills-provenance.yaml

@@ -91,6 +91,19 @@ derived:
     origin: community
     source: https://github.com/nutlope/hallmark
     license: MIT
+  # Watch absorption campaign — video-input primitive derived from
+  # bradautomates/claude-video v0.2.0 (MIT), maintained natively.
+  departments/dev/skills/watch:
+    origin: community
+    source: https://github.com/bradautomates/claude-video
+    license: MIT
+  # Diagram absorption campaign — visual spec/plan output derived from
+  # tt-a1i/archify v2.11.0 (MIT; portions Cocoon AI), vendored verbatim
+  # under vendor/ and maintained natively.
+  departments/dev/skills/diagram:
+    origin: community
+    source: https://github.com/tt-a1i/archify
+    license: MIT
   # Marketing skills integration campaign — derived from
   # coreyhaines31/marketingskills (MIT). Frontmatter metadata must match
   # each entry field-for-field (test_registry_matches_frontmatter_field_for_field).

package/core/keys.py

@@ -7,15 +7,27 @@ import json
 import os
 import stat
 from pathlib import Path
-from typing import Optional
 
 KEYS_PATH = Path.home() / ".arkaos" / "keys.json"
 
 # Known providers with descriptions
 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"},
+    "OPENAI_API_KEY": {
+        "name": "OpenAI",
+        "used_for": "Whisper transcription (/watch fallback), 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",
+    },
+    "GROQ_API_KEY": {
+        "name": "Groq",
+        "used_for": "Whisper transcription for /watch (whisper-large-v3 — cheaper, faster)",
+    },
 }
 
 
@@ -31,7 +43,7 @@ def _save(keys: dict[str, str]) -> None:
     os.chmod(KEYS_PATH, stat.S_IRUSR | stat.S_IWUSR)  # 600
 
 
-def get_key(name: str) -> Optional[str]:
+def get_key(name: str) -> str | None:
     """Get an API key by name. Also checks environment variables."""
     env_val = os.environ.get(name)
     if env_val:

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

@@ -52,6 +52,7 @@ authority:
 expertise:
   domains:
     - brand identity creation
+    - reference-video visual analysis via dev/watch (complete frames + transcript — motion and art direction judged on evidence, never on screenshots)
     - visual design direction
     - UX/UI strategy
     - design systems

package/departments/content/agents/content-strategist.yaml

@@ -48,6 +48,7 @@ authority:
 expertise:
   domains:
     - viral content design
+    - reference-video analysis via dev/watch (frames + timestamped transcript before judging any video)
     - hook writing & packaging
     - script structure
     - content operating systems

package/departments/content/agents/production/trends-analyst.yaml

@@ -45,6 +45,7 @@ authority:
 expertise:
   domains:
     - "trend detection across platforms (Agent-Reach: X, Reddit, YouTube, RSS, Exa)"
+    - viral-video deconstruction via dev/watch (scene-aware frames + transcript, timestamp-cited)
     - niche viability scoring (audience size, competition density, monetization path, brand fit)
     - platform algorithm shift monitoring
     - whitespace analysis for new channels and formats

package/departments/content/agents/production/video-producer.yaml

@@ -51,6 +51,7 @@ authority:
 expertise:
   domains:
     - video production pipelines (script → storyboard → assets → edit → render)
+    - cut review via dev/watch (frame + transcript evidence on own renders before the Quality Gate)
     - Hyperframes video-as-code editing (HTML/CSS/JS + GSAP → MP4)
     - Higgsfield generation orchestration (image, video, audio, motion control, upscale, reframe)
     - shot lists and EDLs (scene/shot/VO/on-screen-text columns)

package/departments/content/agents/scriptwriter.yaml

@@ -43,6 +43,7 @@ authority:
 expertise:
   domains:
     - video scriptwriting (YouTube, Reels, TikTok)
+    - reference-video teardown via dev/watch (hook, pacing and beat analysis from frames + transcript)
     - cinematic narrative for short and long-form
     - storyboard-ready scene writing (scene/shot/VO/on-screen-text columns)
     - narrative structure (hook-bridge-body-CTA; beat sheets; story circles)

package/departments/dev/agents/architect.yaml

@@ -50,6 +50,7 @@ authority:
 expertise:
   domains:
     - system design
+    - system visualization via dev/diagram (architecture + dataflow diagrams delivered as browser artifacts)
     - domain modeling (event storming, bounded contexts)
     - design patterns (GoF, PoEAA)
     - business / domain analysis

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

@@ -53,6 +53,7 @@ expertise:
     - Laravel 11 / PHP 8.3
     - PostgreSQL / Supabase
     - REST API design
+    - API flow visualization via dev/diagram (sequence diagrams for endpoint contracts and async jobs)
     - Service + Repository pattern
     - Database migrations & indexing
     - Queue systems (Horizon)

package/departments/dev/agents/devops-eng.yaml

@@ -46,6 +46,7 @@ authority:
 expertise:
   domains:
     - CI/CD pipelines (GitHub Actions, GitLab CI)
+    - release visualization via dev/diagram (lifecycle + workflow diagrams for pipelines and rollouts)
     - container orchestration (Docker, Kubernetes)
     - infrastructure as code (Terraform, Pulumi)
     - cloud platforms (Vercel, Azure, AWS)

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

@@ -47,6 +47,8 @@ authority:
 expertise:
   domains:
     - Vue 3 (Composition API)
+    - motion-reference analysis via dev/watch (scroll/animation benchmarks from frames + transcript before implementing)
+    - user-flow visualization via dev/diagram (workflow diagrams for page and interaction flows)
     - Nuxt 3
     - React 19 / Next.js 15
     - TypeScript

package/departments/dev/agents/tech-lead.yaml

@@ -50,6 +50,7 @@ authority:
 expertise:
   domains:
     - workflow orchestration
+    - visual spec/plan companions via dev/diagram (typed IR -> interactive HTML the user opens before build)
     - code quality enforcement
     - sprint/cycle management
     - technical decision-making

package/departments/dev/skills/animated-website/SKILL.md

@@ -76,7 +76,20 @@ If the user gives just a video path and a vague concept, ask ONE clarifying ques
 
 ### Step 1: Analyze the Video
 
-Probe the video to understand what you're working with:
+**See the content first (dev/watch primitive).** Before any design decision,
+watch the source with the native `dev/watch` skill so overlay copy, section
+pacing and dwell points are grounded in what is actually on screen — the
+"complete frames" doctrine, never screenshots or guesses:
+
+```bash
+PY="$HOME/.arkaos/bin/arka-py"; command -v "$PY" >/dev/null || PY=python3
+"$PY" ~/.claude/skills/arka-watch/scripts/watch.py "/path/to/video.mp4" --no-whisper
+```
+
+Read every frame the report lists, note the key visual beats (`t=MM:SS`) —
+they become section boundaries and dwell points in Step 4.
+
+Then probe the technical metadata:
 
 ```bash
 ffprobe -v quiet -print_format json -show_format -show_streams "/path/to/video.mp4"

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

@@ -0,0 +1,175 @@
+---
+name: dev/diagram
+description: >
+  Turn a spec, plan, or system description into an interactive diagram the
+  user opens in a browser — one self-contained HTML file, five typed modes
+  (architecture, workflow, sequence, dataflow, lifecycle). The agent authors
+  a JSON IR, a vendored zero-dependency Node CLI validates it against JSON
+  Schemas, renders it, runs semantic gates (clean-flow/clean-label), and
+  emits a sha256 receipt. TRIGGER: "diagrama", "desenha a arquitetura",
+  "mostra-me visualmente", "visual da spec", "quero ver o fluxo", "diagram
+  this", "/dev diagram"; the Visual Spec Companion step in dev/spec; the
+  Forge visual-companion option for MEDIUM/HIGH plans. SKIP: DECIDING or
+  evaluating the architecture itself -> dev/architecture-design (this
+  skill only draws the result); database ERDs -> dev/db-schema (Mermaid
+  ERD); page wireframes/sitemaps -> brand/wireframe and
+  landing/page-architect; data charts and dashboards -> the dataviz
+  skill; the Forge complexity radar -> the Forge's built-in companion
+  (core/forge/renderer.py).
+allowed-tools: [Read, Write, Bash, AskUserQuestion]
+metadata:
+  origin: community
+  source: https://github.com/tt-a1i/archify
+  license: MIT
+---
+
+<!-- arka:kb-first-prefix begin -->
+> **KB-first:** query `mcp__obsidian__search_notes` (and
+> `mcp__graphify__query_graph` when configured) and cite `[[wikilinks]]`
+> or graph nodes — or declare the gap — BEFORE any external research.
+> Full doctrine: `arka/SKILL.md` (KB-First Research).
+<!-- arka:kb-first-prefix end -->
+
+# /diagram — visual output for specs, plans, and systems
+
+> **Agent:** Gabriel (Architect) + Paulo (Tech Lead) | **Framework:** Typed JSON IR, JSON Schema 2020-12, semantic layout gates
+
+The user should SEE what will be built before it is built. This skill turns
+a described system into a single self-contained HTML diagram (~530KB) with
+theme switching, focused exploration, guided views, and PNG/SVG/WebM export
+— no runtime dependencies, no telemetry. The only external reference is an
+async Google Fonts stylesheet (JetBrains Mono) that degrades to system
+monospace offline.
+
+Absorbed from `tt-a1i/archify` v2.11.0 (MIT; portions Cocoon AI) and
+maintained natively by ArkaOS. The upstream engine lives verbatim under
+`vendor/`; you author the IR, the CLI does everything else. NEVER hand-edit
+the generated HTML — fix the IR and re-deliver.
+
+## Resolve `SKILL_DIR` (before any command)
+
+Set `SKILL_DIR` to the absolute path of the directory containing THIS
+SKILL.md (your harness showed it when you Read this file). Guard once:
+
+```bash
+[ -f "$SKILL_DIR/vendor/bin/archify.mjs" ] || { echo "archify.mjs not under $SKILL_DIR" >&2; exit 1; }
+```
+
+## Step 0 — preflight (silent on success)
+
+```bash
+command -v node >/dev/null && node -e 'process.exit(+process.versions.node.split(".")[0] >= 18 ? 0 : 1)'
+```
+
+Non-zero → stop and tell the user plainly: this skill needs Node.js >= 18
+(`brew install node` on macOS, https://nodejs.org elsewhere). There is no
+auto-install. When in doubt about the vendor payload itself, run
+`node "$SKILL_DIR/vendor/bin/archify.mjs" doctor`.
+
+## Step 1 — choose the diagram type
+
+| Type | Best for | IR collections |
+|------|----------|----------------|
+| `architecture` | components, services, storage, trust boundaries | `components` + `connections` |
+| `workflow` | CI/CD, approvals, tool calls, runbooks, plan phases | `nodes` (in `lanes`/`cols`) + `edges` |
+| `sequence` | API calls, cache fallback, auth handshakes, async traces | `participants` + `messages` |
+| `dataflow` | pipelines, lineage, PII paths, consumers | `nodes` + `flows` |
+| `lifecycle` | states, retries, waits, terminal outcomes | `states` + `transitions` |
+
+Unsure? Ask the recommender — it returns a bounded recipe:
+
+```bash
+node "$SKILL_DIR/vendor/bin/archify.mjs" guide "<one-line description of the situation>"
+```
+
+`examples` lists the 10 bundled sample IRs (`vendor/examples/*.json`) —
+Read the one closest to your case as a structural reference.
+
+## Step 2 — author the IR
+
+Write `<slug>.<type>.json` to `/tmp` (or the session scratchpad). Every IR
+needs `schema_version: 1`, `diagram_type: "<type>"`, and `meta.title`;
+`meta` also takes `subtitle`, `visual_preset` (`classic|signal-flow|
+blueprint`), `views` (max 5 guided views), and `animation: "trace"` (motion
+is opt-in — leave it off unless asked). Keep one bounded view: 8–12 core
+nodes, one primary path, supporting detail in `cards` instead of extra
+edges.
+
+For per-mode layout rules (lanes/cols, pinning, sequence ordering,
+architecture `pos` grid), Read ONLY the relevant mode section of the
+upstream deep guide at `$SKILL_DIR/vendor/SKILL.md` — do not load all 61KB.
+
+Validate before delivering; error messages carry the offending node
+`id`/`label` so you can fix the IR surgically:
+
+```bash
+node "$SKILL_DIR/vendor/bin/archify.mjs" validate <type> /tmp/<slug>.<type>.json --json
+```
+
+## Step 3 — deliver
+
+```bash
+node "$SKILL_DIR/vendor/bin/archify.mjs" deliver <type> /tmp/<slug>.<type>.json \
+  /tmp/diagram-<slug>.html --json --open --quality standard
+```
+
+Deliver renders to a staging file, runs the artifact checks, atomically
+renames on pass, and emits a JSON receipt. `--open` opens the artifact
+natively; on a headless/remote session drop `--open` and reuse the Forge
+Step 6a convention instead (`python -m http.server 0 --directory /tmp`,
+then `open http://localhost:<port>/diagram-<slug>.html`). Use
+`--quality showcase` only when the user asks for a presentation-grade
+artifact — it fails on dense-but-legal topologies that `standard` accepts.
+
+## Step 4 — read the receipt, report honestly
+
+Parse the receipt JSON. On success report: artifact path,
+`validation.checksPassed`/`checkCount`, `compositionProfile`/`Status`, and
+`artifact.sha256`. On failure the receipt carries `ok: false`, a `stage`,
+and the failing check — fix the IR accordingly and re-deliver. Two common
+gates: **clean-flow** (an edge crossing an unrelated node is always a hard
+failure — reroute or move the node) and **clean-label** (label mask too
+close to another route — nudge the label or spread lanes).
+
+## Step 5 — persistence (optional)
+
+The HTML is an ephemeral deliverable in `/tmp`. When the diagram belongs to
+a durable deliverable (a spec, a Forge plan, an SOP):
+
+- save the IR JSON (small, regenerable source of truth) to the vault next
+  to the note, e.g. `Projects/<name>/Specs/visuals/SPEC-<slug>.<type>.json`;
+- record the artifact in the note's frontmatter `visuals:` list as
+  `{type, ir, html, sha256}`;
+- copy the HTML itself into the vault only when the user asks.
+
+Ask before writing to the vault when the user did not request persistence.
+
+## Output template
+
+```
+Diagram: <type> — <title>
+IR:       /tmp/<slug>.<type>.json
+Artifact: /tmp/diagram-<slug>.html  (sha256 <first-12>)
+Checks:   <checksPassed>/<checkCount> passed · composition <status>
+Opened:   <natively | http://localhost:<port>/… | not opened (reason)>
+```
+
+## Failure modes
+
+- Node missing or < 18 → stop with the install hint; never degrade to
+  ASCII art silently — say the visual companion is unavailable and why.
+- `validate` fails → fix the IR at the reported `id`/`label`; re-validate.
+- `deliver` fails a gate → the previous artifact (if any) is untouched;
+  fix the IR, never the HTML.
+- Dense topology keeps failing `showcase` → deliver with `standard` and
+  say so; `standard` keeps renderable-but-dense layouts as warnings.
+
+## Security
+
+Local-only: the CLI spawns only `node` subprocesses; the generated HTML
+makes no network calls (no fetch/eval/telemetry) except the optional
+Google Fonts stylesheet, and the footer link (when present) carries only
+the diagram type — never the title, graph, or source. Receipts include the
+artifact sha256 for integrity. Vendored engine: `vendor/` (bin, renderers,
+schemas, recipes, template, examples, test) — byte-identical to upstream
+v2.11.0 except trims listed in `docs/THIRD-PARTY-NOTICES.md`.

package/departments/dev/skills/diagram/examples/archify-repo-grid.architecture.json

@@ -0,0 +1,57 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "Archify Pipeline",
+    "subtitle": "Grid placement demo — row/col instead of manual pos",
+    "output": "examples/archify-repo-grid.html"
+  },
+  "layout": {
+    "mode": "grid",
+    "origin": [40, 100],
+    "cols": 7,
+    "gapX": 24,
+    "gapY": 48,
+    "cellW": 120,
+    "cellH": 60
+  },
+  "components": [
+    { "id": "user", "type": "external", "label": "You", "sublabel": "NL / Mermaid", "row": 1, "col": 0 },
+    { "id": "agents", "type": "frontend", "label": "Agent Hosts", "sublabel": "Claude · Codex", "row": 1, "col": 1 },
+    { "id": "skill", "type": "frontend", "label": "SKILL.md", "sublabel": "layout rules", "row": 0, "col": 1 },
+    { "id": "ir", "type": "messagebus", "label": "JSON IR", "sublabel": "schema v1", "row": 1, "col": 2 },
+    { "id": "schemas", "type": "security", "label": "Schema", "sublabel": "ajv", "row": 0, "col": 2 },
+    { "id": "renderers", "type": "backend", "label": "Renderers ×5", "row": 1, "col": 3 },
+    { "id": "template", "type": "frontend", "label": "template.html", "row": 1, "col": 4 },
+    { "id": "checker", "type": "security", "label": "Output Check", "row": 1, "col": 5 },
+    { "id": "html", "type": "cloud", "label": "HTML", "sublabel": "artifact", "row": 1, "col": 6 }
+  ],
+  "boundaries": [
+    {
+      "kind": "region",
+      "label": "archify/ skill package",
+      "wraps": ["ir", "schemas", "renderers", "template", "checker"]
+    }
+  ],
+  "connections": [
+    { "from": "user", "to": "agents", "variant": "emphasis" },
+    { "from": "agents", "to": "skill", "fromSide": "top", "toSide": "bottom" },
+    { "from": "agents", "to": "ir", "variant": "emphasis" },
+    { "from": "ir", "to": "schemas", "variant": "security", "fromSide": "top", "toSide": "bottom" },
+    { "from": "ir", "to": "renderers", "variant": "emphasis" },
+    { "from": "renderers", "to": "template", "variant": "emphasis" },
+    { "from": "template", "to": "checker", "variant": "emphasis" },
+    { "from": "checker", "to": "html", "variant": "emphasis" }
+  ],
+  "cards": [
+    {
+      "dot": "cyan",
+      "title": "Grid mode",
+      "items": [
+        "Set layout.mode grid and place components with row/col",
+        "pos still overrides a cell when you need fine tuning",
+        "Not auto-layout — fixed cell spacing only"
+      ]
+    }
+  ]
+}

package/departments/dev/skills/diagram/vendor/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI (original "architecture-diagram-generator")
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.