@alaagh/brainkit 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [2.0.0] - 2026-02-14
+
+### Added
+
+- Restructured repository into multi-skill layout with:
+  - `skills/*` for source skill folders
+  - `skill-artifacts/*.skill` for packaged artifacts
+- Added npm package support under `@alaagh/brainkit`.
+- Added CLI tool `brainkit` with commands for list/manifest/path/install.
+- Added JavaScript API for listing and installing skills.
+- Added comprehensive automated test suite covering API, CLI, build output, and scripts.
+- Added release publish workflow for npm on GitHub release publish.
+
+### Changed
+
+- Renamed project/repo identity to `brainkit`.
+- Upgraded CI to run tests on every push and pull request across Node 18/20/22.
+
+### Removed
+
+- Removed legacy single-skill root structure.
+- Removed tracked `dist` artifact from repository; build output is generated.
+
+## [1.1.0] - 2026-02-14
+
+### Added
+
+- Expanded README with badges, quick start, demo links, and community sections.
+- Added contributor guidance in `CONTRIBUTING.md`.
+- Added MIT `LICENSE`.
+- Added docs set:
+  - `docs/DEMO.md`
+  - `docs/USE_CASES.md`
+  - `docs/API_REFERENCE.md`
+  - `docs/LAUNCH_PLAYBOOK.md`
+  - `docs/SHOWCASE.md`
+- Added GitHub workflow for skill structure validation.
+- Added issue templates and pull request template.
+
+## [1.0.0] - 2026-02-14
+
+### Added
+
+- Initial release of `threejs-performance-optimizer` skill.
+- Reference modules for workflow, render loop, assets/loaders, draw calls, memory, and R3F.
+- Packaged distributable skill artifact.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alaa Alghazouli
+
+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/README.md

@@ -0,0 +1,87 @@
+# brainkit
+
+[![CI](https://github.com/alaa-alghazouli/brainkit/actions/workflows/ci.yml/badge.svg)](https://github.com/alaa-alghazouli/brainkit/actions/workflows/ci.yml)
+[![Latest Release](https://img.shields.io/github/v/release/alaa-alghazouli/brainkit)](https://github.com/alaa-alghazouli/brainkit/releases)
+[![npm version](https://img.shields.io/npm/v/%40alaagh%2Fbrainkit)](https://www.npmjs.com/package/@alaagh/brainkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+`brainkit` is an installable npm package for AI-ready assets:
+
+- skills
+- skill artifacts (`.skill`)
+- tool registry space (future)
+
+It currently includes one production skill: `threejs-performance-optimizer`.
+
+## Install with npm
+
+```bash
+npm install @alaagh/brainkit
+```
+
+## Install the skill
+
+1. List available skills:
+
+```bash
+npx brainkit list
+```
+
+2. Install the packaged skill artifact:
+
+```bash
+npx brainkit install threejs-performance-optimizer --dest ~/.config/opencode/skills
+```
+
+This creates:
+
+`~/.config/opencode/skills/threejs-performance-optimizer.skill`
+
+3. Optional: install source folder instead of `.skill` artifact:
+
+```bash
+npx brainkit install threejs-performance-optimizer --mode source --dest ~/.config/opencode/skills
+```
+
+## CLI quick reference
+
+```bash
+brainkit list
+brainkit manifest
+brainkit catalog
+brainkit where threejs-performance-optimizer
+brainkit install <skill|all> --dest <path> [--mode artifact|source]
+```
+
+## JavaScript API
+
+```js
+import { listSkills, installSkill } from "@alaagh/brainkit";
+
+const skills = listSkills();
+await installSkill("threejs-performance-optimizer", "./local-skills");
+```
+
+## What is included today
+
+- `threejs-performance-optimizer`: profile-first optimization playbook for Three.js and React Three Fiber performance.
+
+## Repository layout
+
+- `skills/` source skills
+- `skill-artifacts/` packaged `.skill` files
+- `tools/` AI tool metadata and future tool bundles
+- `src/` package API and CLI implementation
+- `scripts/` build and validation scripts
+- `tests/` API, CLI, build, and script tests
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+## Contributing
+
+See `CONTRIBUTING.md`.

package/dist/cli.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+
+import {
+  getManifest,
+  getSkillArtifactPath,
+  getSkillSourcePath,
+  getToolsManifest,
+  installAll,
+  installSkill,
+  listSkills,
+} from "./index.js";
+
+function parseOptions(argv) {
+  const options = {
+    mode: "artifact",
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (token === "--dest") {
+      options.dest = argv[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (token === "--mode") {
+      options.mode = argv[index + 1];
+      index += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`brainkit CLI
+
+Usage:
+  brainkit list
+  brainkit catalog
+  brainkit manifest
+  brainkit where <skill> [--mode artifact|source]
+  brainkit install <skill|all> --dest <path> [--mode artifact|source]
+
+Examples:
+  brainkit list
+  brainkit catalog
+  brainkit install threejs-performance-optimizer --dest ~/.config/opencode/skills
+  brainkit install all --mode source --dest ./local-skills
+`);
+}
+
+async function run() {
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+
+  if (
+    !command ||
+    command === "help" ||
+    command === "--help" ||
+    command === "-h"
+  ) {
+    printHelp();
+    return;
+  }
+
+  if (command === "list") {
+    const skills = listSkills();
+    for (const skill of skills) {
+      console.log(skill);
+    }
+    return;
+  }
+
+  if (command === "manifest") {
+    console.log(JSON.stringify(getManifest(), null, 2));
+    return;
+  }
+
+  if (command === "catalog") {
+    const manifest = getManifest();
+    const tools = getToolsManifest();
+
+    console.log(
+      JSON.stringify(
+        {
+          version: 1,
+          skills: manifest.skills,
+          tools: tools.tools,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  if (command === "where") {
+    const skillName = argv[1];
+    if (!skillName) {
+      throw new Error('Skill name is required for "where" command.');
+    }
+
+    const options = parseOptions(argv.slice(2));
+    if (options.mode === "source") {
+      console.log(getSkillSourcePath(skillName));
+      return;
+    }
+
+    console.log(getSkillArtifactPath(skillName));
+    return;
+  }
+
+  if (command === "install") {
+    const skillName = argv[1];
+    if (!skillName) {
+      throw new Error('Skill name is required for "install" command.');
+    }
+
+    const options = parseOptions(argv.slice(2));
+    if (!options.dest) {
+      throw new Error("Destination path is required. Use --dest <path>.");
+    }
+
+    if (!["artifact", "source"].includes(options.mode)) {
+      throw new Error("Invalid mode. Use --mode artifact or --mode source.");
+    }
+
+    if (skillName === "all") {
+      const results = await installAll(options.dest, { mode: options.mode });
+      for (const result of results) {
+        console.log(`${result.skill} -> ${result.outputPath}`);
+      }
+      return;
+    }
+
+    const result = await installSkill(skillName, options.dest, {
+      mode: options.mode,
+    });
+    console.log(`${result.skill} -> ${result.outputPath}`);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+run().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
+});

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+export type InstallMode = "artifact" | "source";
+
+export interface InstallOptions {
+  mode?: InstallMode;
+}
+
+export interface InstallResult {
+  skill: string;
+  mode: InstallMode;
+  outputPath: string;
+}
+
+export interface SkillManifestEntry {
+  slug: string;
+  name?: string;
+  description?: string;
+  version?: string;
+}
+
+export interface SkillManifest {
+  version: number;
+  skills: SkillManifestEntry[];
+}
+
+export interface ToolManifestEntry {
+  slug: string;
+  name?: string;
+  description?: string;
+  version?: string;
+}
+
+export interface ToolManifest {
+  version: number;
+  tools: ToolManifestEntry[];
+}
+
+export function listSkills(): string[];
+export function getManifest(): SkillManifest;
+export function getToolsManifest(): ToolManifest;
+export function getSkillSourcePath(skillName: string): string;
+export function getSkillArtifactPath(skillName: string): string;
+export function installSkill(
+  skillName: string,
+  destination: string,
+  options?: InstallOptions,
+): Promise<InstallResult>;
+export function installAll(
+  destination: string,
+  options?: InstallOptions,
+): Promise<InstallResult[]>;

package/dist/index.js

@@ -0,0 +1,153 @@
+import {
+  cpSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const moduleDirectory = fileURLToPath(new URL(".", import.meta.url));
+const localSkillsDir = path.join(moduleDirectory, "skills");
+const localArtifactsDir = path.join(moduleDirectory, "skill-artifacts");
+const dataRoot =
+  existsSync(localSkillsDir) && existsSync(localArtifactsDir)
+    ? moduleDirectory
+    : path.resolve(moduleDirectory, "..");
+
+const skillsDir = path.join(dataRoot, "skills");
+const artifactsDir = path.join(dataRoot, "skill-artifacts");
+const manifestPath = path.join(skillsDir, "manifest.json");
+const toolsManifestPath = path.join(dataRoot, "tools", "manifest.json");
+const validInstallModes = new Set(["artifact", "source"]);
+
+function ensureDirectoryExists(directoryPath, label) {
+  if (!existsSync(directoryPath)) {
+    throw new Error(`${label} not found: ${directoryPath}`);
+  }
+}
+
+function resolveDestination(destination) {
+  if (!destination) {
+    throw new Error("Destination path is required.");
+  }
+
+  const absolutePath = path.resolve(destination);
+  mkdirSync(absolutePath, { recursive: true });
+  return absolutePath;
+}
+
+function assertSkillExists(skillName) {
+  const availableSkills = listSkills();
+  if (!availableSkills.includes(skillName)) {
+    throw new Error(
+      `Unknown skill: ${skillName}. Available skills: ${availableSkills.join(", ")}`,
+    );
+  }
+}
+
+function resolveInstallMode(mode) {
+  const installMode = mode ?? "artifact";
+
+  if (!validInstallModes.has(installMode)) {
+    throw new Error(
+      `Invalid mode: ${installMode}. Use \"artifact\" or \"source\".`,
+    );
+  }
+
+  return installMode;
+}
+
+export function listSkills() {
+  ensureDirectoryExists(skillsDir, "Skills directory");
+
+  const entries = readdirSync(skillsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export function getManifest() {
+  if (!existsSync(manifestPath)) {
+    return {
+      version: 1,
+      skills: listSkills().map((skillName) => ({
+        slug: skillName,
+      })),
+    };
+  }
+
+  return JSON.parse(readFileSync(manifestPath, "utf8"));
+}
+
+export function getToolsManifest() {
+  if (!existsSync(toolsManifestPath)) {
+    return {
+      version: 1,
+      tools: [],
+    };
+  }
+
+  return JSON.parse(readFileSync(toolsManifestPath, "utf8"));
+}
+
+export function getSkillSourcePath(skillName) {
+  assertSkillExists(skillName);
+  return path.join(skillsDir, skillName);
+}
+
+export function getSkillArtifactPath(skillName) {
+  assertSkillExists(skillName);
+  ensureDirectoryExists(artifactsDir, "Skill artifacts directory");
+
+  const artifactPath = path.join(artifactsDir, `${skillName}.skill`);
+  if (!existsSync(artifactPath)) {
+    throw new Error(`Missing artifact for ${skillName}: ${artifactPath}`);
+  }
+
+  return artifactPath;
+}
+
+export async function installSkill(skillName, destination, options = {}) {
+  const mode = resolveInstallMode(options.mode);
+  const outputDirectory = resolveDestination(destination);
+
+  if (mode === "source") {
+    const sourcePath = getSkillSourcePath(skillName);
+    const targetPath = path.join(outputDirectory, skillName);
+
+    cpSync(sourcePath, targetPath, { recursive: true, force: true });
+
+    return {
+      skill: skillName,
+      mode,
+      outputPath: targetPath,
+    };
+  }
+
+  const artifactPath = getSkillArtifactPath(skillName);
+  const targetPath = path.join(outputDirectory, `${skillName}.skill`);
+
+  copyFileSync(artifactPath, targetPath);
+
+  return {
+    skill: skillName,
+    mode,
+    outputPath: targetPath,
+  };
+}
+
+export async function installAll(destination, options = {}) {
+  const skills = listSkills();
+  const installations = [];
+
+  for (const skillName of skills) {
+    const result = await installSkill(skillName, destination, options);
+    installations.push(result);
+  }
+
+  return installations;
+}

package/dist/skills/manifest.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "slug": "threejs-performance-optimizer",
+      "name": "Threejs Performance Optimizer",
+      "description": "Profile-first optimization workflow for Three.js and React Three Fiber performance.",
+      "version": "1.1.0",
+      "artifact": "threejs-performance-optimizer.skill",
+      "source": "skills/threejs-performance-optimizer"
+    }
+  ]
+}

package/dist/skills/threejs-performance-optimizer/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: threejs-performance-optimizer
+description: Optimize and refactor Three.js and React Three Fiber code for runtime performance, memory efficiency, loading speed, and rendering quality using a profile-first workflow grounded in current Three.js and R3F docs. Use when requests mention low FPS, frame drops, stutter/jank, high draw calls, heavy post-processing, shadow cost, large GLB/texture payloads, mobile 3D slowness, memory leaks, dispose/cleanup issues, WebGPU or WebGL fallback concerns, frameloop demand/invalidate patterns, instancing, batching, LOD, or general Three.js performance tuning.
+---
+
+# Threejs Performance Optimizer
+
+Optimize performance by measurement, not folklore. Prioritize high-impact changes, preserve visual intent, and avoid stale APIs.
+
+## Core Behavior
+
+Follow this sequence every time:
+
+1. Measure baseline first.
+2. Classify the bottleneck (CPU, GPU, memory, or loading).
+3. Apply one focused optimization pass.
+4. Re-measure and keep only verified improvements.
+
+Never start by rewriting everything. Prefer the smallest change that hits the biggest bottleneck.
+
+## Reference Loading Order
+
+Read references in this order and stop when enough context is collected:
+
+1. `references/performance-workflow.md` for triage and reporting structure.
+2. `references/renderer-and-loop-patterns.md` for render loop and renderer choices.
+3. `references/assets-and-loaders.md` for asset and decoder/transcoder pipeline.
+4. `references/draw-calls-materials-lighting.md` for scene/render cost tuning.
+5. `references/memory-and-disposal.md` for leaks, cleanup, and update flags.
+6. `references/r3f-rules.md` when code uses React Three Fiber.
+7. `references/outdated-guidance.md` before finalizing recommendations.
+
+## Mandatory Workflow
+
+### 1) Measure
+
+Collect at least:
+
+- FPS or frame time trend.
+- Draw calls and triangles (`renderer.info`).
+- Memory trend for textures/geometries/programs.
+- Main-thread and GPU hotspots from profiler.
+
+If performance metrics are missing, request them or add lightweight instrumentation.
+
+### 2) Classify
+
+Classify the primary bottleneck before prescribing fixes:
+
+- CPU-bound: heavy JS/React work, allocations, simulation, or scene graph churn.
+- GPU-bound: high draw call count, expensive shaders/lights/shadows/postprocessing.
+- Memory-bound: growing texture/geometry/render-target counts, context pressure.
+- Load-time bound: large payloads, slow decode/transcode, blocking startup work.
+
+### 3) Fix in ROI Order
+
+Use this order unless data proves otherwise:
+
+1. Asset payload and decode pipeline.
+2. Draw call reduction (instancing, batching, static merges).
+3. Render loop policy (on-demand and adaptive DPR where suitable).
+4. Lighting/shadow/postprocessing cost.
+5. Memory lifecycle and disposal correctness.
+
+### 4) Verify and Report
+
+Report:
+
+- What changed.
+- Expected impact.
+- Measured before/after.
+- Tradeoffs and rollback criteria.
+
+## Non-Negotiable Rules
+
+- Prefer official, current APIs over old blog snippets.
+- Treat hard numeric targets as heuristics, not universal truths.
+- Keep static scenes from rendering continuously when not needed.
+- Avoid per-frame object allocation in hot paths.
+- Explicitly dispose resources no longer needed.
+- Keep anti-aliasing strategy profile-driven, not dogmatic.
+
+## Hard Anti-Rules
+
+- Do not use deprecated renderer APIs in recommendations.
+- Do not claim guaranteed multipliers (2x, 10x) without measurement.
+- Do not assume removing from scene frees GPU memory.
+- Do not use React state updates for per-frame animation.
+- Do not force one compression or AA approach for all projects.
+
+## Output Contract
+
+When delivering optimization advice or edits, always include:
+
+1. Bottleneck diagnosis.
+2. Ordered action plan.
+3. Risk notes (visual quality, compatibility, complexity).
+4. Verification steps and expected metrics movement.
+
+Keep recommendations practical, testable, and version-safe.

package/dist/skills/threejs-performance-optimizer/references/assets-and-loaders.md

@@ -0,0 +1,100 @@
+# Assets and Loaders
+
+## Table of Contents
+
+- Asset Strategy
+- CLI Pipeline
+- Loader Wiring
+- Compression Choices
+- Loading UX
+
+## Asset Strategy
+
+Prefer glTF/GLB for runtime delivery.
+
+Apply optimizations in this order:
+
+1. Remove unnecessary geometry and textures at source.
+2. Compress geometry (Draco or Meshopt).
+3. Compress textures (KTX2 Basis ETC1S or UASTC).
+4. Verify visual quality and decode cost on target devices.
+
+## CLI Pipeline
+
+Use inspection before optimization:
+
+```bash
+gltf-transform inspect input.glb
+```
+
+Use a baseline optimization pass:
+
+```bash
+gltf-transform optimize input.glb output.glb --compress draco --texture-compress webp
+```
+
+Use KTX2 workflows when GPU texture compression is needed:
+
+```bash
+gltf-transform etc1s input.glb output-etc1s.glb
+gltf-transform uastc input.glb output-uastc.glb
+```
+
+For R3F projects, consider:
+
+```bash
+npx gltfjsx model.glb -S -T -t
+```
+
+## Loader Wiring
+
+Configure shared loaders once and reuse instances:
+
+```js
+import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
+import { DRACOLoader } from "three/addons/loaders/DRACOLoader.js";
+import { KTX2Loader } from "three/addons/loaders/KTX2Loader.js";
+
+const draco = new DRACOLoader().setDecoderPath("/draco/");
+const ktx2 = new KTX2Loader()
+  .setTranscoderPath("/basis/")
+  .detectSupport(renderer);
+
+const gltfLoader = new GLTFLoader().setDRACOLoader(draco).setKTX2Loader(ktx2);
+```
+
+Important loader rules:
+
+- Call `detectSupport(renderer)` before KTX2 loads.
+- Reuse decoder/transcoder instances to avoid repeated startup overhead.
+- Dispose loader internals when the loader is no longer needed.
+
+## Compression Choices
+
+Use content-aware defaults:
+
+- ETC1S: smaller files, higher compression artifacts.
+- UASTC: higher quality, larger files.
+
+Evaluate Draco vs Meshopt per project:
+
+- Draco often yields strong geometry compression.
+- Meshopt may decode faster in some scenarios.
+
+Always compare:
+
+- Network transfer size.
+- Decode/transcode time.
+- Runtime memory.
+- Visual quality.
+
+## Loading UX
+
+Improve startup behavior:
+
+- Preload only above-the-fold critical assets.
+- Lazy-load offscreen 3D sections.
+- Use placeholder or low-detail proxies while heavy assets load.
+- Stream or chunk large worlds instead of one monolithic load.
+
+Treat loading optimization as performance work, not only UX polish.

package/dist/skills/threejs-performance-optimizer/references/draw-calls-materials-lighting.md

@@ -0,0 +1,78 @@
+# Draw Calls, Materials, Lighting
+
+## Table of Contents
+
+- Draw Call Reduction
+- Geometry Strategy
+- Material Strategy
+- Lighting and Shadows
+- Postprocessing
+
+## Draw Call Reduction
+
+Treat draw-call reduction as a primary lever.
+
+Use this escalation path:
+
+1. Share materials and geometry where possible.
+2. Use `InstancedMesh` for repeated objects.
+3. Use batch or merged static geometry for non-interactive sets.
+4. Use LOD and distance-based simplification.
+
+Use draw-call budgets as heuristics, not hard guarantees. Validate on target devices.
+
+## Geometry Strategy
+
+For repeated meshes, prefer instancing:
+
+```js
+const mesh = new THREE.InstancedMesh(geometry, material, count);
+for (let i = 0; i < count; i += 1) {
+  mesh.setMatrixAt(i, matrix);
+}
+mesh.instanceMatrix.needsUpdate = true;
+mesh.computeBoundingSphere();
+```
+
+For static scene chunks, consider merged geometry:
+
+- Merge by material compatibility.
+- Keep interactable parts separate.
+- Avoid over-merging when per-object behavior is required.
+
+## Material Strategy
+
+Control shader variant explosion:
+
+- Reuse shared material instances whenever possible.
+- Avoid unnecessary feature toggles at runtime that trigger recompilation.
+- Update uniforms/data values instead of replacing whole materials.
+
+Prefer simpler materials where quality permits.
+
+## Lighting and Shadows
+
+Use dynamic lights selectively:
+
+- Keep active shadow-casting lights minimal.
+- Tighten shadow camera frustums.
+- Use smallest acceptable shadow map sizes.
+- Disable shadow auto-updates for static scenes and trigger only when needed.
+
+Point-light shadow cost reminder:
+
+- One point light shadow map requires six faces.
+- Cost scales quickly with object count.
+
+Prefer environment lighting and baked/static lighting when practical.
+
+## Postprocessing
+
+Treat each pass as measurable cost.
+
+- Start with the minimal pass chain.
+- Merge compatible effects when possible.
+- Re-test antialiasing strategy per project.
+- Reduce internal effect resolution when quality permits.
+
+Avoid rigid recommendations like "always disable native AA" or "always use FXAA". Measure and choose.

package/dist/skills/threejs-performance-optimizer/references/memory-and-disposal.md

@@ -0,0 +1,95 @@
+# Memory and Disposal
+
+## Table of Contents
+
+- Disposal Rules
+- Cleanup Patterns
+- Update Flags
+- Bounding Volumes
+- Leak Detection
+
+## Disposal Rules
+
+Removing an object from a scene does not free GPU resources.
+
+Explicitly dispose resources no longer needed:
+
+- `BufferGeometry.dispose()`
+- `Material.dispose()`
+- `Texture.dispose()`
+- `WebGLRenderTarget.dispose()`
+- `Skeleton.dispose()` for unused shared skeletons
+
+If texture data uses `ImageBitmap`, close CPU-side data explicitly:
+
+```js
+texture.source.data.close?.();
+texture.dispose();
+```
+
+## Cleanup Patterns
+
+Use a traversal cleanup utility for scene teardown:
+
+```js
+function disposeScene(root) {
+  root.traverse((obj) => {
+    if (obj.geometry) {
+      obj.geometry.dispose();
+    }
+
+    if (!obj.material) {
+      return;
+    }
+
+    const materials = Array.isArray(obj.material)
+      ? obj.material
+      : [obj.material];
+    for (const material of materials) {
+      for (const key of Object.keys(material)) {
+        const value = material[key];
+        if (value && value.isTexture) {
+          value.dispose();
+        }
+      }
+      material.dispose();
+    }
+  });
+}
+```
+
+Dispose loader internals or worker resources when loader lifecycle ends.
+
+## Update Flags
+
+Use update flags only when required:
+
+- Buffer attribute changes: `attribute.needsUpdate = true`
+- Texture content changes: `texture.needsUpdate = true`
+- Material feature or define changes: `material.needsUpdate = true`
+
+For static objects, disable automatic matrix updates:
+
+```js
+object.matrixAutoUpdate = false;
+object.updateMatrix();
+```
+
+## Bounding Volumes
+
+Recompute bounds after structural data updates:
+
+- Geometry vertex changes: `computeBoundingBox()` and `computeBoundingSphere()`
+- Instanced transforms update: `instancedMesh.computeBoundingBox()` and `computeBoundingSphere()`
+
+Accurate bounds protect culling and interaction correctness.
+
+## Leak Detection
+
+Track `renderer.info` over repeated scene mount/unmount cycles:
+
+- `renderer.info.memory.textures`
+- `renderer.info.memory.geometries`
+- `renderer.info.programs`
+
+Stable plateaus are normal. Monotonic growth under repeated teardown/rebuild indicates leaks.

package/dist/skills/threejs-performance-optimizer/references/outdated-guidance.md

@@ -0,0 +1,25 @@
+# Outdated Guidance Guardrails
+
+Use this table to avoid stale recommendations.
+
+| Avoid this guidance                                         | Why                                   | Use this instead                                                          |
+| ----------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| "Use `renderAsync()` in the main loop"                      | Deprecated in current renderer docs   | Use `setAnimationLoop()` with `render()` and explicit compute workflow    |
+| "Use `gammaFactor` / `outputEncoding` as default advice"    | Legacy color pipeline terminology     | Use current color-space workflow and current renderer properties          |
+| "`Geometry` / `BoxBufferGeometry` naming as modern default" | Legacy naming and old-era examples    | Use current geometry APIs and confirm version-specific docs               |
+| "All textures must be power-of-two"                         | Too absolute for modern contexts      | Prefer POT for compatibility/perf-sensitive paths; profile and validate   |
+| "Always disable native MSAA and use FXAA/SMAA"              | Highly scene/device dependent         | Compare native AA vs post AA using measurements                           |
+| "Always keep under 100 draw calls"                          | Useful heuristic, not universal rule  | Use target-device budgets and verify frame stability                      |
+| "Removing mesh from scene frees memory"                     | Incorrect resource lifecycle model    | Explicitly call `dispose()` on geometry/material/texture/targets          |
+| "Use React state for per-frame animation"                   | Causes re-render overhead and jank    | Mutate refs in `useFrame`, use state for coarse events                    |
+| "Always migrate to WebGPU now"                              | Context-dependent project constraints | Evaluate project requirements, browser/device support, and measured gains |
+
+## Source Confidence Priority
+
+Prefer recommendations in this order:
+
+1. Current official docs and API reference.
+2. Official manuals and examples.
+3. Community articles and blog heuristics.
+
+When community advice conflicts with official docs, prioritize docs and annotate the conflict.

package/dist/skills/threejs-performance-optimizer/references/performance-workflow.md

@@ -0,0 +1,99 @@
+# Performance Workflow
+
+## Table of Contents
+
+- Baseline Checklist
+- Bottleneck Classification
+- Priority Matrix
+- Verification Template
+
+## Baseline Checklist
+
+Capture these values before touching code:
+
+- Runtime profile: FPS and frame-time variance (average and worst spikes).
+- Renderer stats: `renderer.info.render.calls`, triangles, and points.
+- Memory trend: `renderer.info.memory.textures`, geometries, and programs.
+- Startup profile: bundle size, model size, texture payload, decode/transcode duration.
+- Device context: desktop/mobile, GPU class, browser, resolution, DPR.
+
+Use at least one user interaction scenario and one idle scenario.
+
+## Bottleneck Classification
+
+Use this decision path:
+
+1. Check profiler for long JS tasks or React re-render churn.
+2. Check draw calls, shader complexity, light/shadow/post stack cost.
+3. Check memory growth over time in repeated navigation or scene swaps.
+4. Check network/decode/transcode delays before first interactive frame.
+
+Interpretation guide:
+
+- CPU-bound indicators:
+  - Frequent long tasks.
+  - Per-frame allocations.
+  - High-frequency state updates.
+- GPU-bound indicators:
+  - High draw calls.
+  - Heavy transparency, postprocessing, shadow passes.
+  - Lower FPS with high DPR and dense scene content.
+- Memory-bound indicators:
+  - Steadily growing texture/geometry counts.
+  - Context loss or large spikes during scene transitions.
+- Load-time bound indicators:
+  - Long time-to-first-render.
+  - Large GLB and texture payloads.
+  - Decoder/transcoder setup errors or delays.
+
+## Priority Matrix
+
+Apply fixes in this order unless measurements suggest otherwise.
+
+1. Asset pipeline:
+   - Compress geometry and textures.
+   - Remove unused assets.
+   - Preload only critical resources.
+2. Draw-call pressure:
+   - Instancing and batching.
+   - Merge static geometry.
+   - Share materials.
+3. Render-loop policy:
+   - On-demand rendering where possible.
+   - Adaptive DPR and quality scaling.
+4. Shading and lighting:
+   - Reduce dynamic lights/shadows.
+   - Tighten shadow frustums and map sizes.
+   - Trim postprocessing passes.
+5. Memory lifecycle:
+   - Dispose obsolete resources.
+   - Reuse pooled objects.
+
+Heuristic budgets (starting points only):
+
+- Draw calls: aim for a few hundred or less on typical target hardware.
+- Dynamic shadowed point lights: keep minimal, each adds substantial pass cost.
+- DPR on mobile: cap aggressively when frame stability drops.
+
+Do not treat these as hard rules. Validate against project goals.
+
+## Verification Template
+
+Use this response structure after each optimization pass:
+
+- Baseline:
+  - FPS/frame time:
+  - Draw calls:
+  - Memory counters:
+- Change applied:
+  - What changed:
+  - Why it targets the bottleneck:
+- Result:
+  - New FPS/frame time:
+  - New draw calls:
+  - Memory delta:
+- Tradeoffs:
+  - Visual impact:
+  - Compatibility risk:
+  - Complexity cost:
+- Keep or rollback decision:

package/dist/skills/threejs-performance-optimizer/references/r3f-rules.md

@@ -0,0 +1,84 @@
+# React Three Fiber Rules
+
+## Table of Contents
+
+- Frame Loop Discipline
+- Resource Reuse
+- Rendering Policy
+- Adaptive Quality
+- Strict Anti-Patterns
+
+## Frame Loop Discipline
+
+Use mutation in `useFrame` for high-frequency updates.
+
+```jsx
+const ref = useRef();
+
+useFrame((_, delta) => {
+  ref.current.rotation.y += delta;
+});
+```
+
+Use `delta` for frame-rate independence.
+
+Avoid `setState` in `useFrame` or any high-frequency event loop.
+
+## Resource Reuse
+
+Reuse geometry/material instances and loaded assets:
+
+- Use `useLoader` for cached resource loading.
+- Use memoization for reusable Three.js objects.
+- Prefer visibility toggles over frequent mount/unmount churn.
+
+Example:
+
+```jsx
+const geometry = useMemo(() => new THREE.BoxGeometry(), []);
+const material = useMemo(() => new THREE.MeshStandardMaterial(), []);
+```
+
+## Rendering Policy
+
+For mostly static scenes:
+
+```jsx
+<Canvas frameloop="demand" />
+```
+
+Trigger renders when external mutations happen:
+
+```jsx
+const { invalidate } = useThree();
+invalidate();
+```
+
+Attach controls change events to invalidate when needed.
+
+## Adaptive Quality
+
+Use `PerformanceMonitor` or equivalent to adapt quality:
+
+- Lower DPR on decline.
+- Disable expensive postprocessing first.
+- Apply fallback quality profile if repeated flip-flops occur.
+
+Use transitions for expensive UI state updates:
+
+```jsx
+const [isPending, startTransition] = useTransition();
+startTransition(() => {
+  setHeavyState(next);
+});
+```
+
+## Strict Anti-Patterns
+
+Avoid these patterns:
+
+- `setState` inside `useFrame`.
+- Per-frame object allocation (`new Vector3()` in hot path).
+- Constant remounting of heavy 3D subtrees.
+- Fast pointer-driven transforms through React state.
+- Unbounded postprocessing and DPR at all times.

package/dist/skills/threejs-performance-optimizer/references/renderer-and-loop-patterns.md

@@ -0,0 +1,113 @@
+# Renderer and Loop Patterns
+
+## Table of Contents
+
+- Renderer Selection
+- WebGPU/WebGL Initialization
+- Render Loop Patterns
+- On-Demand Rendering
+- Adaptive DPR
+- Renderer Flags
+
+## Renderer Selection
+
+Use a profile-first selection strategy:
+
+- Prefer `WebGPURenderer` for new work when available.
+- Rely on fallback behavior when WebGPU is unavailable.
+- Keep compatibility checks for advanced features.
+
+Do not use deprecated renderer methods in new guidance.
+
+## WebGPU/WebGL Initialization
+
+```js
+import { WebGPURenderer } from "three/webgpu";
+
+const renderer = new WebGPURenderer({
+  antialias: false,
+  powerPreference: "high-performance",
+});
+await renderer.init();
+```
+
+Use `forceWebGL: true` only for explicit fallback testing or compatibility debugging.
+
+## Render Loop Patterns
+
+Prefer `setAnimationLoop` for continuous rendering cases:
+
+```js
+renderer.setAnimationLoop(() => {
+  renderer.render(scene, camera);
+});
+```
+
+Avoid recommending deprecated async render loop APIs.
+
+## On-Demand Rendering
+
+Use on-demand rendering for mostly static scenes.
+
+Vanilla pattern:
+
+```js
+let renderRequested = false;
+
+function render() {
+  renderRequested = false;
+  renderer.render(scene, camera);
+}
+
+function requestRenderIfNotRequested() {
+  if (renderRequested) {
+    return;
+  }
+
+  renderRequested = true;
+  requestAnimationFrame(render);
+}
+```
+
+Hook this to input/resize/loading events.
+
+R3F pattern:
+
+```jsx
+<Canvas frameloop="demand" />
+```
+
+```jsx
+const { invalidate } = useThree();
+controls.addEventListener("change", invalidate);
+```
+
+If damping is enabled, request frames through a guard to avoid redundant scheduling.
+
+## Adaptive DPR
+
+Use adaptive DPR when frame stability drops.
+
+R3F example:
+
+```jsx
+<PerformanceMonitor
+  onIncline={() => setDpr(2)}
+  onDecline={() => setDpr(1)}
+  flipflops={3}
+  onFallback={() => setDpr(1)}
+/>
+```
+
+Treat DPR changes as one tool, not a complete fix.
+
+## Renderer Flags
+
+Set renderer flags by requirement, not cargo cult defaults:
+
+- Disable `alpha` if transparent canvas is not required.
+- Disable `stencil` when unused.
+- Keep `depth` enabled unless the rendering model proves otherwise.
+- Choose antialiasing strategy by profiling native MSAA vs post AA.
+
+When using postprocessing, re-check final color-space and tone-mapping pipeline correctness.

package/dist/tools/manifest.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tools": []
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@alaagh/brainkit",
+  "version": "2.0.0",
+  "description": "Installable npm bundle of AI skills with CLI and JavaScript API.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "brainkit": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "test": "npm run build && npm run validate:skills && node --test --test-concurrency=1 tests/*.test.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "skills",
+    "threejs",
+    "react-three-fiber",
+    "webgl",
+    "webgpu",
+    "performance",
+    "llm",
+    "codex"
+  ],
+  "author": "Alaa Alghazouli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alaa-alghazouli/brainkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alaa-alghazouli/brainkit/issues"
+  },
+  "homepage": "https://github.com/alaa-alghazouli/brainkit#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}