arkaos 5.5.0 → 5.6.0

package/README.md

@@ -4,7 +4,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 337 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 338 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install
@@ -97,7 +97,7 @@ npx arkaos doctor    # Health check
 
 ### Skill packs, à la carte
 
-The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 263 skills, generated straight from the same sources the core uses. Inside Claude Code:
+The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 264 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.5.0 — 89 agents, 17 departments, 337 skills, 299 commands, 20 ADRs.
+> v5.6.0 — 89 agents, 17 departments, 338 skills, 299 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.5.0
+5.6.0

package/arka/SKILL.md

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

package/config/skills-provenance.yaml

@@ -139,6 +139,15 @@ derived:
     origin: community
     source: https://github.com/AThevon/genjutsu
     license: MIT
+  # Animation/design absorption campaign PR-4 — dev/threejs. Dual-source:
+  # the SKILL.md core is ArkaOS-authored from the three.js project's own
+  # LLM guidance (docs/llms.txt, MIT — recorded in THIRD-PARTY-NOTICES);
+  # references/r3f.md, scene-setup.md and shaders.md derive from
+  # AThevon/genjutsu's threejs-r3f skill (MIT, primary source here).
+  departments/dev/skills/threejs:
+    origin: community
+    source: https://github.com/AThevon/genjutsu
+    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/departments/dev/skills/canvas-generative/SKILL.md

@@ -8,8 +8,8 @@ description: >
   TRIGGER: "generative art", "arte generativa", "particles background",
   "fundo de partículas", "noise field", "flow field", "canvas animation",
   "fundo processual", "creative coding em canvas", "/dev canvas-generative".
-  SKIP: real-time 3D or shader work -> no dedicated skill yet, use the
-  frontend workflows; a pre-rendered 3D world scrubbed by scroll ->
+  SKIP: real-time 3D or shader work -> dev/threejs; a pre-rendered 3D
+  world scrubbed by scroll ->
   dev/scroll-world; turning an existing video into a scroll site ->
   dev/animated-website; charts and data graphics -> the dataviz skill.
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
@@ -352,7 +352,7 @@ function update() {
 |---|---|
 | Noise implementations, particle pool, flow field, L-system, attractors | `references/algorithms.md` |
 | Timing and easing for animated transitions | the brand guidelines' Motion System (§06), reached via the source-of-truth table in `departments/brand/references/uiux-knowledge-and-tools.md` |
-| 3D generative (shaders, GPU particles) | out of this skill's scope — Canvas 2D only; scope a WebGL approach with the frontend squad |
+| 3D generative (shaders, GPU particles) | `departments/dev/skills/threejs/SKILL.md` |
 
 ## Output
 

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

@@ -0,0 +1,173 @@
+---
+name: dev/threejs
+description: >
+  Real-time 3D in the browser with three.js and React Three Fiber: modern
+  setup (import maps, WebGL vs WebGPU renderer choice, TSL), the
+  scene-camera-renderer wiring, geometries, materials and lights, loaders,
+  disposal discipline against GPU memory leaks, performance budgets — and
+  the R3F layer (hooks, drei, postprocessing) for React projects.
+  TRIGGER: "three.js", "threejs", "react three fiber", "r3f", "webgl",
+  "webgpu", "shader", "GLSL", "cena 3D", "3D interativo no browser",
+  "drei", "/dev threejs".
+  SKIP: a pre-rendered 3D world scrubbed by scroll (no real-time engine)
+  -> dev/scroll-world; generative 2D canvas -> dev/canvas-generative;
+  generating a 3D asset (GLB mesh) from an image -> the higgsfield-generate
+  skill; React motion without 3D -> dev/framer-motion.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
+metadata:
+  origin: community
+  source: https://github.com/AThevon/genjutsu
+  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 -->
+
+# Three.js — `/dev threejs`
+
+> **Agent:** Diana (Frontend Dev) | **Framework:** three.js (MIT) + React Three Fiber
+> Core authored from the three.js project's own LLM guidance
+> (`docs/llms.txt`, MIT); the R3F layer derives from genjutsu (MIT) — see
+> `references/`.
+
+## Setup — the modern shape
+
+Import maps, never legacy CDN script tags. Pin one version for `three`
+and `three/addons/` together — mixing versions across the two specifiers
+is the classic silent breaker:
+
+```html
+<script type="importmap">
+{ "imports": {
+    "three": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.module.js",
+    "three/webgpu": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.webgpu.js",
+    "three/tsl": "https://cdn.jsdelivr.net/npm/three@<version>/build/three.tsl.js",
+    "three/addons/": "https://cdn.jsdelivr.net/npm/three@<version>/examples/jsm/" } }
+</script>
+```
+
+`WebGPURenderer` is not exported from `three` — it lives in the
+`three/webgpu` entry, and it is async: `await renderer.init()` before the
+first frame. The TSL node functions live in `three/tsl`, not in
+`three/webgpu`. Omit either entry and the import fails at runtime.
+
+In a bundled project, `npm i three` and import the same specifiers. Check
+the installed version before writing code — the API moves, and the
+project's lockfile outranks your memory of it.
+
+**Renderer choice.** `WebGLRenderer` is the default and safe everywhere.
+`WebGPURenderer` (with TSL node materials) is the forward path but needs
+feature detection and a WebGL fallback; choose it only when the project
+targets browsers you control or ships the fallback. Never mix GLSL
+`ShaderMaterial` into a WebGPU pipeline — that renderer wants TSL
+`NodeMaterial` classes.
+
+## The irreducible core
+
+Scene, camera, renderer, loop — everything else hangs off these:
+
+```js
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(75, w / h, 0.1, 100);
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.setSize(w, h);
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2)); // cap DPR: 3x buys nothing visible and burns fill rate
+renderer.setAnimationLoop(tick);                        // not a hand-rolled rAF: in XR it swaps to the session's loop; outside XR it is rAF with correct teardown via setAnimationLoop(null)
+```
+
+On resize: update `camera.aspect`, call `camera.updateProjectionMatrix()`,
+then `renderer.setSize`. Forgetting the middle step is why "resize
+stretches everything".
+
+**Animate with elapsed time, not the frame count.** A per-frame delta
+keeps speed identical at 30 and 144 fps; per-frame increments do not.
+Use `THREE.Timer` (`timer.update(); timer.getDelta()`) — `THREE.Clock`
+is deprecated since r183 and warns at runtime.
+
+## Disposal — GPU memory does not garbage-collect
+
+Removing a mesh from the scene frees nothing on the GPU. Every geometry,
+material, texture and render target you create, you `dispose()` when its
+life ends — and a material's textures are disposed separately from the
+material. For a whole subtree, collect first, dispose once: `traverse`
+visits Groups and Lights that have no material, and shared resources must
+not be disposed per-mesh:
+
+```js
+function disposeSubtree(root) {
+  const geometries = new Set(), materials = new Set(), textures = new Set();
+  root.traverse((obj) => {
+    if (!obj.isMesh && !obj.isPoints && !obj.isLine && !obj.isSprite) return;
+    // Sprites share one engine-owned quad geometry app-wide: never dispose it
+    if (obj.geometry && !obj.isSprite) geometries.add(obj.geometry);
+    const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+    for (const m of mats) {
+      if (!m) continue;
+      materials.add(m);
+      for (const v of Object.values(m)) if (v?.isTexture) textures.add(v);
+      // ShaderMaterial textures live in uniforms, not on the material —
+      // and a uniform's value can be an ARRAY of textures (atlas shape)
+      if (m.uniforms) for (const u of Object.values(m.uniforms)) {
+        const vals = Array.isArray(u?.value) ? u.value : [u?.value];
+        for (const v of vals) if (v?.isTexture) textures.add(v);
+      }
+    }
+  });
+  textures.forEach((t) => t.dispose());
+  materials.forEach((m) => m.dispose());
+  geometries.forEach((g) => g.dispose());
+}
+```
+
+This covers the shapes meshes ordinarily carry — geometries, material
+maps, scalar and array texture uniforms. When a resource is shared
+with meshes OUTSIDE the subtree — a texture atlas, a cached material —
+exclude it: ownership is yours to model, and dispose belongs to the owner.
+
+A single-page app that mounts and unmounts scenes without this leaks
+until the tab dies. This is the number-one three.js production bug.
+
+## Performance budget
+
+- **Draw calls first.** Hundreds of meshes sharing one geometry+material
+  belong in an `InstancedMesh`; thousands of distinct static meshes merge
+  via `BufferGeometryUtils.mergeGeometries`.
+- Reuse geometries and materials across meshes; clone only when a
+  property must diverge.
+- Textures: compressed formats (KTX2/Basis) for anything big, and never
+  larger than the screen area they cover; mipmaps come from the loader or
+  `generateMipmaps`, with no power-of-two constraint in WebGL 2.
+- Lights are per-fragment cost: prefer one directional + ambient or an
+  environment map over a constellation of point lights. Bake what does
+  not move.
+- Shadows are a render pass per caster: tight `shadow.camera` frustum,
+  modest map sizes, `castShadow` only where it is visible.
+
+## Loading models
+
+`GLTFLoader` (with `DRACOLoader` or `KTX2Loader` when the asset uses
+them) from `three/addons/`. Load asynchronously, add a loading state,
+and dispose the loader's intermediates. glTF is the format; converting
+from anything else happens in the asset pipeline, not at runtime.
+
+## React Three Fiber
+
+For React projects, R3F replaces the imperative wiring: the component
+tree IS the scene graph, `useFrame` is the loop, drei supplies the
+controls/loaders/staging you would otherwise hand-write. The full layer —
+hooks discipline, drei picks, postprocessing, and the Do-Nots (from
+setState in useFrame to forgotten dispose) — lives
+in [references/r3f.md](references/r3f.md), with canvas/scene wiring in
+[references/scene-setup.md](references/scene-setup.md) and GLSL/TSL
+patterns in [references/shaders.md](references/shaders.md).
+
+## Output
+
+A working scene module (or R3F component tree) with the render loop,
+resize handling and disposal wired, a stated performance budget (draw
+calls, texture memory, DPR cap), and the renderer choice justified in one
+line. Anything WebGPU/TSL states its fallback.

package/departments/dev/skills/threejs/references/genjutsu.LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrien Thevon
+
+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.

package/departments/dev/skills/threejs/references/r3f.md

@@ -0,0 +1,249 @@
+> Derived from genjutsu's `threejs-r3f` skill (MIT — `genjutsu.LICENSE`
+> in this directory). The React Three Fiber layer of `dev/threejs`.
+
+# Three.js & React Three Fiber
+
+> 3D on the web. Three.js is the engine, R3F is the React renderer.
+> Concise rules here. Deep-dive in `references/`.
+
+---
+
+## When to Use What
+
+| Need | Tool | Why |
+|---|---|---|
+| Full 3D scene (models, lights, physics) | R3F + drei | Declarative, React-friendly, ecosystem |
+| Vanilla 3D (no React) | Three.js direct | Lighter, no React overhead |
+| Simple 3D transforms on UI | CSS `transform3d` | GPU-composited, no WebGL context |
+| 2D particles / generative | Canvas 2D | Simpler API, less GPU overhead |
+| Shader-only visuals (no scene graph) | Raw WebGL / ShaderMaterial | Maximum control, minimal abstraction |
+
+---
+
+## Scene Setup Patterns
+
+```tsx
+import { Canvas } from '@react-three/fiber'
+import { Environment, OrbitControls } from '@react-three/drei'
+import { Suspense } from 'react'
+
+<Canvas camera={{ position: [0, 2, 5], fov: 45 }} dpr={[1, 2]} gl={{ antialias: true }}>
+  <Suspense fallback={null}>
+    <Environment preset="studio" />
+    <OrbitControls makeDefault />
+    <Scene />
+  </Suspense>
+</Canvas>
+```
+
+**Rules:**
+- Always wrap scene content in `<Suspense>` -- loaders (GLTF, textures, HDRI) need it
+- Set `dpr={[1, 2]}` to clamp pixel ratio (Retina without melting GPUs)
+- Keep the Canvas parent component minimal -- re-renders propagate into the scene
+
+---
+
+## R3F Hooks
+
+| Hook | Purpose | Gotcha |
+|---|---|---|
+| `useFrame((state, delta) => {})` | Per-frame logic (animation, physics) | Never setState inside |
+| `useThree()` | Access gl, scene, camera, size, viewport, pointer | Destructure only what you need |
+| `useLoader(TextureLoader, url)` | Load any Three.js resource | Wrap parent in Suspense |
+| `useGraph(scene)` | Extract nodes/materials from loaded scene | Useful after useGLTF |
+
+### useFrame Tips
+
+```tsx
+useFrame((state, delta) => {
+  // Use delta for framerate-independent animation
+  meshRef.current.rotation.y += delta * 0.5
+  // Access clock for time-based effects
+  material.uniforms.uTime.value = state.clock.elapsedTime
+})
+```
+
+---
+
+## Drei Essentials
+
+| Component | Use Case |
+|---|---|
+| `Environment` | HDRI lighting (presets: studio, sunset, city, forest, dawn) |
+| `Float` | Idle floating animation (speed, rotationIntensity, floatIntensity) |
+| `Text3D` | Extruded 3D text (needs JSON font from Facetype.js) |
+| `useGLTF` | Load .glb/.gltf models (returns { nodes, materials, scene }) |
+| `useGLTF.preload(url)` | Preload model before component mounts |
+| `MeshTransmissionMaterial` | Glass/crystal/liquid refraction effects |
+| `PresentationControls` | Drag-to-rotate for product showcases |
+| `Center` | Auto-center any group of meshes |
+| `Detailed` | LOD -- swap geometry by camera distance |
+| `useTexture` | Load textures with Suspense support |
+| `Instances` | Declarative instancing for repeated meshes |
+
+---
+
+## Postprocessing
+
+```tsx
+import { EffectComposer, Bloom, ChromaticAberration } from '@react-three/postprocessing'
+import { BlendFunction } from 'postprocessing'
+
+<EffectComposer>
+  <Bloom
+    luminanceThreshold={1}
+    luminanceSmoothing={0.4}
+    intensity={0.6}
+  />
+  <ChromaticAberration
+    blendFunction={BlendFunction.NORMAL}
+    offset={[0.002, 0.002]}
+  />
+</EffectComposer>
+```
+
+**Rules:**
+- Bloom is selective by default -- lift material color/emissive above 1.0 to make it glow
+- `luminanceThreshold={1}` = nothing glows unless explicitly emissive
+- Order matters inside EffectComposer
+- Effects are merged into a single pass (performant by design)
+
+---
+
+## Performance Patterns
+
+| Pattern | When |
+|---|---|
+| `<Instances>` / `InstancedMesh` | 100+ identical meshes (particles, trees, crowds) |
+| `<Detailed distances={[0, 50, 100]}>` | LOD: swap hi/lo models by distance |
+| `dispose={null}` on `<primitive>` | Prevent auto-dispose when reusing shared geometry |
+| `useGLTF` + Draco | Compress .glb models (70-90% size reduction) |
+| `useKTX2` (drei) | Compressed GPU textures (1/4 VRAM) — `useTexture` is TextureLoader-only and cannot decode .ktx2 |
+| `frameloop="demand"` on Canvas | Only render when something changes (static scenes) |
+| `invalidate()` from useThree | Trigger a render in demand mode |
+| `<Canvas eventSource={ref}>` | Delegate pointer events to an ancestor element (overlay UIs); rendering stays on the main thread |
+
+**Target metrics:** < 100 draw calls, < 1M triangles, 60fps on mid-range GPU.
+Use `stats-gl` or `r3f-perf` to monitor.
+
+---
+
+## Do Not
+
+### 1. Never setState in useFrame
+
+Causes full React re-render 60x/second. Mutate refs directly.
+
+```tsx
+// BAD
+useFrame(() => {
+  setRotation(prev => prev + 0.01) // React re-render every frame
+})
+
+// GOOD
+useFrame((_, delta) => {
+  meshRef.current.rotation.y += delta * 0.5 // Direct mutation, zero re-renders
+})
+```
+
+### 2. Never allocate in the render loop
+
+`new Vector3()` per frame = GC spikes = stutter.
+
+```tsx
+// BAD
+useFrame((state) => {
+  const target = new THREE.Vector3(0, Math.sin(state.clock.elapsedTime), 0)
+  meshRef.current.position.copy(target)
+})
+
+// GOOD
+const _target = useMemo(() => new THREE.Vector3(), [])
+useFrame((state) => {
+  _target.set(0, Math.sin(state.clock.elapsedTime), 0)
+  meshRef.current.position.copy(_target)
+})
+```
+
+### 3. Never forget dispose (memory leak)
+
+Three.js textures, geometries, and materials live on the GPU. Unmounting a React component does NOT free them.
+
+```tsx
+// BAD -- texture stays in VRAM after unmount
+const texture = useLoader(TextureLoader, '/big-texture.jpg')
+
+// GOOD -- R3F auto-disposes objects mounted as JSX primitives.
+// useLoader results are CACHED globally: disposing the texture directly
+// poisons the cache and the next consumer renders a disposed resource.
+// Evict from the cache instead, then dispose:
+useEffect(() => {
+  return () => {
+    useLoader.clear(TextureLoader, '/big-texture.jpg')
+    texture.dispose()
+  }
+}, [texture])
+
+// Resources YOU constructed (not via useLoader) are yours to dispose:
+useEffect(() => () => { geometry.dispose(); material.dispose() }, [])
+```
+
+### 4. Never re-render the Canvas parent
+
+Parent state changes re-render the Canvas subtree — the Canvas does not
+remount, but every child re-renders, props reconcile against the scene
+graph, and R3F work you meant to keep out of React's render path runs
+again. Keep fast-changing state out of the Canvas parent (zustand or
+refs).
+
+```tsx
+// BAD
+function App() {
+  const [uiState, setUiState] = useState(false) // fast-changing state here re-renders the whole Canvas subtree
+  return (
+    <>
+      <button onClick={() => setUiState(!uiState)}>Toggle</button>
+      <Canvas><Scene config={uiState} /></Canvas>
+    </>
+  )
+}
+
+// GOOD -- isolate Canvas in its own component
+function App() {
+  return (
+    <>
+      <UI />
+      <SceneCanvas />
+    </>
+  )
+}
+```
+
+### 5. Never load assets without Suspense
+
+Loaders (useGLTF, useTexture, useLoader) throw promises. Without Suspense, you get crashes.
+
+```tsx
+// BAD
+<Canvas>
+  <Model /> {/* useGLTF inside -- will throw */}
+</Canvas>
+
+// GOOD
+<Canvas>
+  <Suspense fallback={<Loader />}>
+    <Model />
+  </Suspense>
+</Canvas>
+```
+
+---
+
+## Quick Reference: Loading Sub-resources
+
+| Need | Load |
+|---|---|
+| Scene boilerplate, lighting rigs, controls | `scene-setup.md` (this directory) |
+| Custom shaders, GLSL patterns, uniforms | `shaders.md` (this directory) |
+| Animation principles, easing, timing | the brand guidelines' Motion System (§06), reached via `departments/brand/references/uiux-knowledge-and-tools.md` |
+| Scroll-scrubbed pre-rendered worlds (no live engine) | `departments/dev/skills/scroll-world/SKILL.md` |