pixelcrew 0.2.3 → 0.2.6

package/README.md

@@ -1,421 +1,495 @@
-# PixelCrew (`@hiroqt/pixelcrew`)
+<p align="center">
+  <img src="assets/banner.png" alt="Pixel Agents — Autonomous Agents. Real Impact." width="100%" />
+</p>
+
+<h1 align="center">PixelCrew</h1>
 
 <p align="center">
-  <strong>Local Multi-Agent Orchestration Engine & Retro Pixel-Art Tech Startup Office</strong><br>
-  <em>Transform any codebase into an observable, autonomous, and choreographed AI engineering workspace with a single command.</em>
+  <strong>Autonomous Multi-Agent Engineering Swarm and Software Synthesis Framework</strong>
 </p>
 
 <p align="center">
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache 2.0 License"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg" alt="Node.js 18+"></a>
-  <a href="package.json"><img src="https://img.shields.io/badge/Runtime_Dependencies-Zero-orange.svg" alt="Zero Runtime Dependencies"></a>
-  <a href="https://github.com/hiroqt/PixelCrew"><img src="https://img.shields.io/badge/Release-v0.2.0-blueviolet.svg" alt="Release v0.2.0"></a>
-  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-Welcome-brightgreen.svg" alt="PRs Welcome"></a>
+  <a href="https://github.com/hiroqt/PixelCrew"><img src="https://img.shields.io/badge/version-0.2.5-7c3aed?style=flat-square" alt="Version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-22c55e?style=flat-square" alt="License" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-0ea5e9?style=flat-square" alt="Node.js" /></a>
+  <a href="#zero-runtime-dependencies"><img src="https://img.shields.io/badge/dependencies-0-f59e0b?style=flat-square" alt="Zero Dependencies" /></a>
 </p>
 
-```text
-┌────────────────────────────────────────────────────────────────────────┐
-│  PIXELCREW HQ  ::  FLOOR 42                              ● SWARM LIVE  │
-├────────────────────────────────────────────────────────────────────────┤
-│                                                                        │
-│                    ┌──────────────────────┐                            │
-│                    │   LEAD ORCHESTRATOR  │                            │
-│                    │        [ ◉ _ ◉ ]     │                            │
-│                    │      DAG Dispatch    │                            │
-│                    └──────────┬───────────┘                            │
-│                               │                                        │
-│          ┌────────────────────┼────────────────────┐                   │
-│          │                    │                    │                   │
-│          ▼                    ▼                    ▼                   │
-│    ┌───────────┐        ┌───────────┐        ┌───────────┐             │
-│    │ FRONTEND  │        │  BACKEND  │        │ DATABASE  │             │
-│    │  [ ◉ ▂ ◉ ]│        │  [ ◉ ▂ ◉ ]│        │  [ ◉ ⊙ ]  │             │
-│    │  working  │        │  working  │        │ analyzing │             │
-│    └───────────┘        └───────────┘        └───────────┘             │
-│          │                    │                    │                   │
-│          ▼                    ▼                    ▼                   │
-│    ┌───────────┐        ┌───────────┐        ┌───────────┐             │
-│    │ CREATIVE  │        │ANTI-AI QA │        │TOKEN SAVER│             │
-│    │  [ ★ _ ★ ]│        │  [ 🔍_🔍 ]│        │  [ ◉ ▂ ◉ ]│             │
-│    │ Director  │        │Critic >=8.5│       │72% Savings│             │
-│    └───────────┘        └───────────┘        └───────────┘             │
-│                                                                        │
-│  LIVE TELEMETRY STREAM                                                 │
-│  ────────────────────────────────────────────────────────────────────  │
-│  03:41:02  orchestrator     → decomposed objective into parallel tasks │
-│  03:41:03  creativeDirector → formulated asymmetric editorial style    │
-│  03:41:04  designSystem     → compiled fluid clamp type & tokens       │
-│  03:41:05  visualCritic     → ★ Visual Score: 9.4/10 (Passed >= 8.5)   │
-│                                                                        │
-│  ACTIVE SKILL ENGINES                                                  │
-│  ────────────────────────────────────────────────────────────────────  │
-│  ✓ Codebase Intelligence   ✓ Design Director (Anti-AI)  ✓ Token Saver  │
-│  ◉ Frontend Engineering    ◉ Database Engineering       ◉ Visual QA    │
-│                                                                        │
-└────────────────────────────────────────────────────────────────────────┘
-```
+<p align="center">
+  <a href="#overview">Overview</a> •
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#floor-42-slash-commands-suite">Slash Commands</a> •
+  <a href="#cross-ide-integration-architecture">IDE Integration</a> •
+  <a href="#agent-roster-and-state-machine">Agent Roster</a> •
+  <a href="#architecture">Architecture</a> •
+  <a href="#visual-dashboard">Dashboard</a> •
+  <a href="#anti-ai-design-guardian">Design Guardian</a> •
+  <a href="#cli-reference">CLI Reference</a> •
+  <a href="#testing">Testing</a> •
+  <a href="#roadmap">Roadmap</a> •
+  <a href="CONTRIBUTING.md">Contributing</a>
+</p>
 
 ---
 
-## ⚡ 10-Second Ignition
+<a id="overview"></a>
 
-No global installations or complex configuration required. Run directly in your repository:
+## Overview
 
-```bash
-# 1. ✦ OneShot Website Generation (Design-First Multi-Agent Synthesis)
-npx pixelcrew oneshot "Build a modern website for a design agency specializing in AI products. Dark, editorial, premium."
+Modern AI coding assistants frequently operate as black boxes, concealing agent cognition behind non-descriptive status indicators or emitting unstructured terminal log dumps. Developers are left unable to observe what specific tasks an agent is executing, where dependencies are stalled, or how individual architectural decisions were reached.
 
-# 2. Launch the orchestrator daemon and real-time visual office dashboard
-npx pixelcrew start
+PixelCrew resolves this observability and coordination challenge by structuring development into a coordinated, observable multi-agent engineering swarm. The workspace is modeled as a retro-themed virtual technology office on Floor 42 of Pixel Corps HQ, where specialized agent personas collaborate across design direction, frontend construction, backend engineering, data modeling, performance analysis, security verification, and quality assurance.
 
-# 3. Initialize and adapt PixelCrew to an existing codebase
-npx pixelcrew init
-
-# 4. Run an instant multi-agent sprint simulation demo
-npx pixelcrew demo
-```
+### Architectural Comparison
 
-The interactive dashboard opens automatically at:  
-👉 **`http://localhost:4747`** *(auto-recovers to `4748`+ if port 4747 is occupied)*
+| Capability | PixelCrew | Conventional AI Tools |
+|:---|:---|:---|
+| **Observability** | Real-time 2D canvas with per-agent state machines, live event stream, and audio telemetry | Static spinner animations or raw JSON log dumps |
+| **Runtime Footprint** | Zero npm dependencies; built entirely on Node.js standard library | Heavy dependency trees and required container runtimes |
+| **IDE Interoperability** | Native slash command and skill generation across Claude Code, Cursor, Kiro, and Antigravity | Single-environment lock-in |
+| **Codebase Awareness** | Automated static profiling for frameworks (Next.js, React), ORMs (Prisma, Drizzle), and testing suites | Generic prompt wrappers lacking repository context |
+| **Design Integrity** | Six-dimension anti-AI quality gate enforcing fluid typography and asymmetric layouts | Repetitive card grids and generic purple gradient templates |
+| **Task Scheduling** | Directed Acyclic Graph (DAG) planner resolving dependency barriers with parallel dispatch | Monolithic single-thread code generation |
 
 ---
 
-## ✦ OneShot Website Synthesis & Anti-AI Visual Critic
+<a id="quickstart"></a>
 
-### The Problem: Why Generated Websites Look Generic
-Most AI coding tools follow a naive linear prompt pattern:
-```
-User Prompt  ──>  AI immediately writes React/HTML code  ──>  Generic AI Slop
-```
-This produces cookie-cutter outputs: purple mesh gradients, repeating 3-column rounded cards, fake floating glassmorphism blobs, and cliché copy like *"Revolutionize your workflow"*.
-
-### The Solution: Decouple Design Direction from Coding
-PixelCrew enforces a strict multi-agent creative pipeline before generating code:
-
-```mermaid
-flowchart TD
-    User["User Prompt"] --> CD["Creative Director Agent"]
-    CD --> Direction["Creative Direction JSON (Archetype, Palette, Fonts, Negative Constraints)"]
-    Direction --> UX["UX Planner Agent"]
-    UX --> Topology["Asymmetric Section Topology (Hero, Bento, Manifesto, Specs, CTA)"]
-    Topology --> DS["Design System Agent"]
-    DS --> Tokens["Design Tokens (Fluid clamp(), Google Fonts, Tailwind Config)"]
-    Tokens --> FE["Frontend Builder Agent"]
-    FE --> Code["Clean HTML5 / Tailwind / Vanilla / React Code (Zero Placeholders)"]
-    Code --> QA["Visual Critic & Anti-AI Guardian"]
-    QA --> Review{"Rubric >= 8.5/10?"}
-    Review -- No (Refine) --> FE
-    Review -- Yes (Approved) --> Done["Modern Finished Website (index.html + creative-direction.json)"]
-```
+## Quickstart
 
-### 1. Creative Director Decision Schema
-Before writing code, PixelCrew determines:
-- **Design Archetype**: *Editorial Asymmetric Grid*, *Technical Lab*, or *Kinetic Studio*.
-- **Visual Personality**: High-contrast, intentional whitespace, expressive typography.
-- **Negative Constraints**: Strictly bans purple/blue blobs, symmetrical card grids, and placeholder copy.
+### Prerequisites
 
-### 2. 6-Dimension Visual Critic Rubric ($\ge 8.5/10.0$)
-Every generated site is scored across a weighted human design rubric:
+- Node.js >= 18.0.0
+- npm >= 9.0.0
+- Zero external runtime packages required
 
-$$\text{Final Score} = \frac{\text{Originality} + \text{Typography} + \text{Layout} + \text{Visual Hierarchy} + \text{Brand Consistency} + (10 - \text{Generic AI Penalty})}{6}$$
+### 1. Initialize a Project Workspace
 
-```text
-╔═════════════════════════════════════════════════════════════════════╗
-║                      PIXEL CREW VISUAL SCORE                        ║
-╠═════════════════════════════════════════════════════════════════════╣
-║  Originality:           9.1 / 10                                    ║
-║  Typography:            9.7 / 10                                    ║
-║  Layout & Rhythm:       9.1 / 10                                    ║
-║  Visual Hierarchy:      9.4 / 10                                    ║
-║  Brand Consistency:     9.3 / 10                                    ║
-║  Generic AI Penalty:    -0.4 / 10                                   ║
-║                                                                     ║
-║  FINAL VISUAL SCORE:    9.4 / 10.0   [✓ APPROVED >= 8.5]            ║
-╚═════════════════════════════════════════════════════════════════════╝
+Run initialization directly via `npx` in any project directory or greenfield workspace:
+
+```bash
+# Preview proposed files and directories without writing to disk
+npx pixelcrew init --dry-run
+
+# Automatically configure the workspace for all detected and available AI IDEs
+npx pixelcrew init --yes
+
+# Initialize exclusively for a specific environment
+npx pixelcrew init --provider claude-code
 ```
 
----
+During initialization, PixelCrew performs an architectural scan of your repository, establishes `.pixel-crew/` configuration, generates agent personas adapted to your stack, and creates IDE-native slash command definitions.
 
-## ⚡ Universal Cross-IDE Token Optimization Engine
+### 2. Configure Cross-Device Global Slash Commands
 
-PixelCrew includes built-in token optimization rules and metrics across all major AI coding agents:
-- **Claude Code**: Prefix prompt cache anchoring ($\ge 1024$ tokens) $\to$ 90% cache read discount.
-- **Google Antigravity**: Line-range targeted edits and subagent context encapsulation.
-- **Cursor / Kiro / Windsurf**: Compact rule sets ($\le 250$ tokens) and AST symbol extraction over raw files.
-- **GitHub Copilot**: Context pruning and structured schema validation.
+To make PixelCrew slash commands available globally across all projects on your machine:
 
-```text
-╔═════════════════════════════════════════════════════════════════════╗
-║               CROSS-IDE TOKEN OPTIMIZATION METRICS                  ║
-╠═════════════════════════════════════════════════════════════════════╣
-║  Raw Estimated Tokens:  42,500 tokens                               ║
-║  Actual Tokens Used:    11,800 tokens                               ║
-║  Tokens Conserved:      30,700 tokens (72% Savings)                 ║
-║  Active Strategy:       AST Skeletons + Pruned Boundaries           ║
-╚═════════════════════════════════════════════════════════════════════╝
+```bash
+# Distribute command files and skills to global user directories (~/.claude, ~/.cursor, ~/.gemini, ~/.kiro)
+npx pixelcrew install --global
+
+# Verify installation health across all providers
+npx pixelcrew doctor
 ```
 
----
+### 3. Launch the Orchestration Server and Visual Dashboard
 
-## 💡 The Paradigm: Why PixelCrew?
-
-Traditional AI agent tooling runs inside black-box terminal loops: you type a prompt, wait minutes in silence, and hope the agent doesn't hallucinate or clobber your codebase.
-
-**PixelCrew turns the invisible execution loop into an observable, choreographed engineering office.**
-
-```mermaid
-flowchart TD
-    UserPrompt["Developer Prompt / Objective"] --> Analyzer["Codebase Static Analyzer\n(Scans Frameworks, ORMs, Testing)"]
-    Analyzer --> ContextCache[".pixel-agents/context.json\n(Project DNA & Architecture Profile)"]
-    ContextCache --> Orchestrator["Orchestrator Engine (DAG Task Planner)"]
-    
-    subgraph Swarm ["Autonomous Agent Swarm"]
-        Orchestrator --> FE["Frontend Engineer (React 19 / Next.js)"]
-        Orchestrator --> BE["Backend Architect (REST / gRPC / Auth)"]
-        Orchestrator --> DB["Database DBA (Postgres / Prisma / Drizzle)"]
-        Orchestrator --> SEC["Security Sentinel (OWASP / RLS)"]
-        Orchestrator --> PERF["Performance SRE (CWV / Profiling)"]
-        Orchestrator --> QA["QA Automation (Vitest / Playwright)"]
-    end
-
-    Swarm --> Telemetry["Event Pipeline (SSE & Append-only JSONL)"]
-    Telemetry --> Canvas["Floor 42 2D Canvas Dashboard\n(Procedural Sprites, CRT Shader, Web Audio SFX)"]
-    Telemetry --> IDESync["IDE Telemetry Feedback (Antigravity, Cursor, Claude)"]
-```
+```bash
+# Launch local daemon on default port 4747 and open the browser dashboard
+npx pixelcrew start
 
-### Core Innovations
-- **Zero Runtime Dependencies**: Pure Node.js ESM orchestrator with lightweight HTML5/CSS/Canvas. No bloated node_modules. Instant launch.
-- **Codebase Context Adaptation**: Auto-discovers frameworks (Next.js, Vite, React, Vue), ORMs (Prisma, Drizzle), and test runners (Vitest, Playwright) to tailor agent permissions and skill injection.
-- **Bi-Directional Telemetry**: Accepts event streams over CLI flags, HTTP REST endpoints (`/api/emit`), and append-only `.pixel-agents/events.jsonl` files.
-- **Floor 42 Office Engine**: Procedural 2D canvas with CRT scanline simulation, daytime/night-mode cyberpunk lighting, and retro 8-bit Web Audio chimes.
+# Run headless or bind to a custom port
+npx pixelcrew start --port 8080 --no-open
+```
 
----
+### 4. Execute Multi-Agent Synthesis
 
-## 🧠 The 8 Engineering Skill Pillars
+Generate an application or execute a structured sprint:
 
-PixelCrew equips agents with production-grade engineering skill modules located under `.agents/skills/` (and mirrored to `.pixel-agents/skills/`):
+```bash
+# Run full multi-agent synthesis pipeline from natural language specification
+npx pixelcrew assemble "Build a modern analytics dashboard with dark theme and API routes"
 
-### 1. `design-director`
-Lead creative direction and authentic visual personality engine. Decouples artistic strategy, typographic clamp scales, and negative constraints before frontend code generation.
+# Generate section topology and task DAG without writing code
+npx pixelcrew blueprint "High-throughput customer billing platform"
 
-### 2. `anti-ai-patterns`
-Strict Anti-AI-Generated Design Critic and Quality Guardian. Automatically detects purple mesh gradients, repeating 3-card grids, and cliché copy, enforcing intentional asymmetry and brand-specific visual language.
+# View token-optimized git activity changelog
+npx pixelcrew recap
+```
 
-### 3. `token-efficiency`
-Universal token optimization and context conservation engine across Claude, Google Antigravity, Cursor, Kiro, Windsurf, and Copilot. Slashes token usage by 50% to 75% through AST symbol extraction, prompt caching, and boundary pruning.
+---
 
-### 4. `codebase-intelligence`
-Static analysis and project adaptation. Automatically inspects repository dependencies, directory structures, ORMs, API routes, and testing runners to ground every subagent in current architectural patterns.
+<a id="floor-42-slash-commands-suite"></a>
 
-### 5. `frontend-engineering`
-Modern frontend architecture across React 19, Next.js App Router, Vue 3, Svelte 5, and vanilla CSS. Enforces strict anti-slop design rules, fluid `clamp()` typography, semantic HTML, and WCAG AA accessibility compliance.
+## Floor 42 Slash Commands Suite
 
-### 6. `backend-engineering`
-Enterprise backend standards: Clean Architecture, Hexagonal / Ports & Adapters, OpenAPI 3.1, RFC 7807 error envelopes, sliding-window rate limiting, idempotency key middleware, and OAuth 2.1 / PASETO security.
+PixelCrew provides 24 specialized slash commands that can be typed directly into your AI IDE chat interface (Claude Code CLI, Cursor Chat, Kiro AI, Google Antigravity) or invoked from your terminal via `npx pixelcrew <command>`.
 
-### 7. `database-engineering`
-Advanced query tuning and indexing: B-Tree, GIN, GiST, BRIN, composite indexing column order, EXPLAIN ANALYZE interpretation, UUIDv7 vs ULID primary keys, Row-Level Security (RLS) isolation, and connection pooling.
+To browse the interactive command menu at any time:
+```bash
+# Display the complete command catalog in your terminal
+npx pixelcrew /
+npx pixelcrew commands
+```
 
-### 8. `performance-engineering`
-Full-stack profiling: Core Web Vitals (LCP, INP, CLS), main-thread yielding, streaming SSR, multi-tier caching (L1 in-memory, L2 Redis, L3 CDN), database connection pool sizing, and automated k6 stress testing.
+### Creation and Architecture
+
+| Command | Aliases | Description |
+|:---|:---|:---|
+| `/assemble` | `/fullstack`, `/build-app`, `/make-app` | Dispatches the complete 16-step multi-agent sprint pipeline from brand direction to full-stack code synthesis. |
+| `/blueprint` | `/plan-app`, `/architecture`, `/spec` | Generates section topology, schema definitions, and task dependency DAG without generating code. |
+| `/oneshot` | `/make`, `/generate` | Rapid single-prompt website and component synthesis with creative direction constraints. |
+| `/manifest` | `/agents`, `/crew-status` | Displays active agent personas, assigned skills, and file system permission boundaries. |
+| `/retrofit` | `/modernize`, `/upgrade` | Inspects legacy component code, extracts inline styles into design tokens, and restructures layouts. |
+| `/init` | `/setup`, `/bootstrap` | Scans workspace dependencies, generates `.pixel-crew/` configuration, and adapts agent prompts. |
+
+### Retro Aesthetic and Anti-AI Direction
+
+| Command | Aliases | Description |
+|:---|:---|:---|
+| `/render` | `/art-direction`, `/visual-style` | Applies bespoke typography pairings, high-contrast surface tiers, and distinctive brand aesthetics. |
+| `/8bit` | `/pixel-art`, `/retro` | Injects retro 8-bit styling, pixelated border treatments, and arcade monospace typography. |
+| `/chromatic` | `/cyberpunk`, `/neon` | Applies high-contrast cyberpunk color schemes, duotone accents, and darkroom styling. |
+| `/bento` | `/grid`, `/cards` | Reorganizes uniform content sections into dynamic, asymmetrical Bento grid arrangements. |
+| `/de-slop` | `/anti-ai`, `/clean` | Scans and strips generic AI design tropes (purple gradient blobs, uniform 3-card layouts, cliché copywriting). |
+| `/typeset` | `/typography`, `/fonts` | Applies mathematical fluid typography using CSS `clamp()` scales from body text to display headings. |
+| `/polish` | `/refine`, `/tune` | Inspects micro-interactions, hover states, transitions, and accessibility contrast compliance. |
+| `/animate` | `/motion`, `/transitions` | Introduces purposeful CSS micro-animations and entrance reveals while respecting reduced motion preferences. |
+| `/bolder` | `/high-contrast`, `/loud` | Increases contrast ratios, heading weight, border definitions, and visual punch. |
+| `/quieter` | `/minimal`, `/subtle` | Softens borders, reduces accent saturation, and expands whitespace for minimal editorial presentations. |
+
+### Production Hardening and SRE
+
+| Command | Aliases | Description |
+|:---|:---|:---|
+| `/sentinel` | `/security`, `/harden` | Runs automated security checks covering OWASP Top 10 vulnerabilities, authentication posture, and security headers. |
+| `/boss-fight` | `/debug-swarm`, `/swarm-fix` | Deploys specialized agents to isolate and resolve complex multi-file bugs and build failures. |
+| `/warp` | `/performance`, `/speed` | Profiles Core Web Vitals (LCP, INP, CLS), bundle dimensions, and server-side streaming efficiency. |
+| `/calibrate` | `/benchmark`, `/eval` | Evaluates synthesized code against quality thresholds for accessibility, performance, and type safety. |
+| `/audit` | `/inspect`, `/health` | Conducts holistic architecture, dependency, and security audits across the codebase. |
+| `/overdrive` | `/stress-test`, `/load` | Analyzes endpoint resilience, connection pooling, and rate-limiting behaviors under load. |
+
+### Floor 42 Operations and Session Management
+
+| Command | Aliases | Description |
+|:---|:---|:---|
+| `/recap` | `/summary`, `/changelog`, `/whatdone` | Generates a compact, token-optimized git activity changelog and session summary without prompt overhead. |
+| `/office` | `/dashboard`, `/hq` | Displays real-time Floor 42 workstation telemetry, agent occupancy, and background daemon status. |
+| `/roster` | `/team`, `/who` | Lists agent specialization matrices, active assignments, and runtime capabilities. |
+| `/onboard` | `/quickstart`, `/tour` | Interactive walkthrough introducing multi-agent workflows and command shortcuts. |
+| `/distill` | `/compact`, `/shrink` | Prunes redundant multi-turn chat context to preserve prompt token limits. |
+| `/commands` | `/slash-commands`, `/help`, `/menu` | Displays the complete Floor 42 command catalog, syntax rules, and IDE integration details. |
 
 ---
 
-## 🛠️ Cross-Harness Installation & IDE Setup
+<a id="cross-ide-integration-architecture"></a>
 
-PixelCrew integrates seamlessly with all leading AI coding assistants and agent environments:
+## Cross-IDE Integration Architecture
 
-### Google Antigravity IDE (Recommended)
-Register PixelCrew globally so Antigravity agents automatically stream to your visual office:
+PixelCrew is designed to eliminate provider lock-in. When commands or skills are installed, PixelCrew translates them into the native discovery format expected by each target editor.
 
-```bash
-# Register global plugin
-mkdir -p ~/.gemini/config/plugins/pixel-agents/skills/pixel-agents
-cp plugins/plugin.json ~/.gemini/config/plugins/pixel-agents/
-cp .agents/skills/pixel-agents/SKILL.md ~/.gemini/config/plugins/pixel-agents/skills/pixel-agents/
+```text
+                                  ┌─────────────────────────────┐
+                                  │      PIXEL CREW CORE        │
+                                  │   FLOOR 42 COMMAND SUITE    │
+                                  └──────────────┬──────────────┘
+                                                 │
+            ┌─────────────────────┬──────────────┴──────────────┬─────────────────────┐
+            │                     │                             │                     │
+            ▼                     ▼                             ▼                     ▼
+┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
+│     CLAUDE CODE       │ │      CURSOR IDE       │ │        KIRO AI        │ │   GOOGLE ANTIGRAVITY  │
+│                       │ │                       │ │                       │ │                       │
+│ • .claude/commands/   │ │ • .cursor/commands/   │ │ • .kiro/workflows/    │ │ • AGENTS.md           │
+│   *.md (with YAML &   │ │   *.md                │ │   *.md                │ │ • GEMINI.md           │
+│   $ARGUMENTS)         │ │ • .cursor/rules/      │ │ • .kiro/prompts/      │ │ • .agents/rules/      │
+│ • CLAUDE.md           │ │   pixelcrew.mdc       │ │   *.md                │ │   pixelcrew.md        │
+│ • .claude-plugin/     │ │ • .cursorrules        │ │ • .kirorules          │ │ • .agents/skills/     │
+└───────────────────────┘ └───────────────────────┘ └───────────────────────┘ └───────────────────────┘
 ```
 
-Whenever you prompt inside Antigravity:
-> *"Synthesize a modern website for an AI architecture lab using PixelCrew"*
+### Editor Discovery Formats
 
-The agent automatically loads the skill, executes the task, and streams live sprite animations and status logs to your browser.
+1. **Anthropic Claude Code**
+   - Individual slash commands are written to `.claude/commands/<command>.md` (workspace) and `~/.claude/commands/<command>.md` (global).
+   - Each command file includes YAML frontmatter describing its behavior and embeds `$ARGUMENTS` to capture user input passed after the slash command.
+   - Comprehensive workspace instructions are placed in `CLAUDE.md`.
 
----
+2. **Cursor IDE**
+   - Command specifications are generated under `.cursor/commands/<command>.md`.
+   - Structural coding rules and anti-AI-slop constraints are established in `.cursor/rules/pixelcrew.mdc` and `.cursorrules`.
 
-### Claude Code
-Install project-locally or link globally:
+3. **Kiro AI**
+   - Prompts are generated in `.kiro/prompts/<command>.md` and registered as workflows in `.kiro/workflows/<command>.md`.
+   - Operational boundaries and rules are configured in `.kirorules` and `.kiro/rules/pixelcrew.md`.
 
-```bash
-# Project-local install
-mkdir -p .claude/skills/pixel-agents
-cp .agents/skills/pixel-agents/SKILL.md .claude/skills/pixel-agents/
-```
+4. **Google Antigravity and Universal Coding Agents**
+   - Instructions and persona roles are generated in `AGENTS.md` and `GEMINI.md`.
+   - Global and workspace rules are maintained in `.agents/rules/pixelcrew.md`.
+   - Standardized capabilities are distributed to `.agents/skills/<skill>/SKILL.md`.
+
+### Clean Greenfield Installation Behavior
+
+When running `pixelcrew init --yes` on a new computer or clean environment:
+- If an ambient IDE is detected via environment variables (e.g., `CLAUDE_CODE`, `CURSOR_VERSION`, `KIRO`), PixelCrew targets that environment.
+- If existing workspace markers are detected, those specific editor configurations are generated.
+- If global IDE directories exist in the user home directory (`~/.claude`, `~/.cursor`, `~/.kiro`, `~/.gemini`), PixelCrew configures files for all detected editors.
+- If no specific IDE is present and `--yes` is used without an explicit `--provider` flag, PixelCrew defaults to generating universal support across all environments. If the user passes `--provider none`, clean CLI mode is used without external IDE files.
 
 ---
 
-### Cursor IDE
-Add to your project's agent rules or skills:
+<a id="agent-roster-and-state-machine"></a>
 
-```bash
-mkdir -p .cursor/skills/pixel-agents
-cp .agents/skills/pixel-agents/SKILL.md .cursor/skills/pixel-agents/
-```
+## Agent Roster and State Machine
 
-*Ensure Agent Skills are enabled under Cursor Settings → Beta.*
+PixelCrew provisions 7 specialized agents with distinct domain boundaries, filesystem permissions, and operational responsibilities:
 
----
+| Agent Persona | Color Tag | Specialization | Core Responsibilities |
+|:---|:---|:---|:---|
+| **Orchestrator** | Purple | Lead Systems Architect | Analyzes user requests, constructs DAG dependency graphs, coordinates sprint checkpoints, and validates architectural compliance. |
+| **Frontend Engineer** | Cyan | UI/UX & Interactivity | Synthesizes responsive React and Next.js App Router components, fluid typography, CSS architecture, and accessible micro-interactions. |
+| **Backend Engineer** | Magenta | APIs & Business Logic | Builds route handlers, server actions, data schemas, authentication middleware, validation layers, and external service adapters. |
+| **Database Architect** | Gold | Data Layer & Persistence | Designs relational database schemas, migrations, ORM entity definitions (Prisma, Drizzle), and indexing strategies. |
+| **Security Sentinel** | Red | Security & Audit | Evaluates authorization flows, CSRF protection, input sanitation, dependency vulnerabilities, and security header configurations. |
+| **Performance SRE** | Green | Optimization & Core Web Vitals | Inspects Largest Contentful Paint (LCP), Interaction to Next Paint (INP), Cumulative Layout Shift (CLS), code splitting, and caching. |
+| **QA Automation** | Purple | Verification & Testing | Generates automated test suites (unit, integration, end-to-end), validates regression resistance, and audits accessibility compliance. |
 
-### OpenAI Codex CLI
-Install project-locally with native hook support:
+### Deterministic Lifecycle States
 
-```bash
-mkdir -p .agents/skills
-cp -r .agents/skills/* .agents/skills/
+```text
+[IDLE]
+  │
+  ├─► User submits task or slash command
+  │
+[ANALYZING]
+  │   • Reads codebase context and project manifest
+  │   • Evaluates file boundaries and dependencies
+  │
+[WORKING]
+  │   • Generates code, configuration, or documentation
+  │   • Emits live telemetry events to events.jsonl and dashboard
+  │
+[VERIFYING]
+  │   • Runs automated tests, syntax linting, and quality scoring
+  │   • Validates anti-slop rubric thresholds
+  │
+[COMPLETED]
+      • Emits task completion event
+      • Returns agent workstation to idle state
 ```
 
 ---
 
-### GitHub Copilot / Grok Build / Gemini CLI / Trae / OpenCode
-Copy the `.agents/skills/` directory into your tool's native skills folder:
-- **GitHub Copilot**: `.github/skills/pixel-agents/`
-- **Gemini CLI**: `~/.gemini/config/skills/pixel-agents/`
-- **Grok Build**: `.grok/skills/pixel-agents/`
-- **Trae**: `~/.trae/skills/` or `~/.trae-cn/skills/`
+<a id="architecture"></a>
 
----
+## Architecture
+
+PixelCrew is implemented with a strictly modular architecture containing zero third-party runtime dependencies. All functionality relies directly on Node.js standard library APIs (`node:http`, `node:events`, `node:fs/promises`, `node:path`, `node:child_process`, `node:crypto`).
+
+```text
+┌────────────────────────────────────────────────────────────────────────┐
+│                        DEVELOPER WORKSPACE                             │
+│       CLI: npx pixelcrew <cmd>  │  IDE: /assemble, /blueprint, etc.   │
+└───────────────────────────────────┬────────────────────────────────────┘
+                                    │
+                                    ▼
+┌────────────────────────────────────────────────────────────────────────┐
+│                      ORCHESTRATION DAEMON                              │
+│                                                                        │
+│   ┌───────────────────┐  ┌───────────────────┐  ┌──────────────────┐  │
+│   │ Codebase Profiler │  │ DAG Task Graph    │  │ Parallel         │  │
+│   │                   │  │                   │  │ Concurrency      │  │
+│   │ Detects runtime,  │  │ Decomposes tasks, │  │ Limiter          │  │
+│   │ frameworks, ORMs, │  │ resolves barriers,│  │ Dispatches tasks │  │
+│   │ and test runners  │  │ prevents cycles   │  │ across slots     │  │
+│   └─────────┬─────────┘  └─────────┬─────────┘  └─────────┬────────┘  │
+│             └──────────────────────┼──────────────────────┘           │
+└───────────────────────────────────┬────────────────────────────────────┘
+                                    │
+                  ┌─────────────────┴─────────────────┐
+                  ▼                                   ▼
+┌───────────────────────────────────┐   ┌────────────────────────────────┐
+│          EVENT PIPELINE           │   │       MULTI-AGENT SWARM        │
+│                                   │   │                                │
+│ • Append-only events.jsonl        │   │ • 7 Persona State Machines     │
+│ • Server-Sent Events (SSE) stream │◄──┤ • Filesystem Permission Gates  │
+│ • REST Dispatch (/api/emit)       │   │ • Floor 42 Workstation Sprites │
+│ • Token Telemetry Collector       │   │ • Context Pruning Engine       │
+└─────────────────┬─────────────────┘   └────────────────────────────────┘
+                  │
+                  ▼
+┌───────────────────────────────────┐
+│     PIXEL CORPS HQ DASHBOARD      │
+│                                   │
+│ • 960x420 HTML5 Double-Buffered   │
+│ • Web Audio API Synthesizer       │
+│ • Live #engineering-feed Stream   │
+│ • Token Usage & Cost Scorecard    │
+└───────────────────────────────────┘
+```
+
+### Zero Runtime Dependencies
+
+PixelCrew enforces a strict zero-dependency policy for runtime code:
 
-## 💻 CLI Terminal Reference
-
-| Command | Action | Example |
-| :--- | :--- | :--- |
-| `npx pixelcrew oneshot "<prompt>"` | **Synthesizes modern website with Visual Critic loop** | `npx pixelcrew oneshot "Dark editorial AI studio"` |
-| `npx pixelcrew start` | Launches orchestrator, SSE stream, and web dashboard | `npx pixelcrew start --port 4747` |
-| `npx pixelcrew init` | Scaffolds `.pixel-agents/` and adapts to repository | `npx pixelcrew init --yes` |
-| `npx pixelcrew analyze` | Prints detected frameworks, database, ORM, and test stack | `npx pixelcrew analyze` |
-| `npx pixelcrew demo` | Launches an interactive multi-agent simulated sprint | `npx pixelcrew demo` |
-| `npx pixelcrew task "<text>"` | Dispatches a direct objective to the running agent swarm | `npx pixelcrew task "Optimize SQL queries"` |
-| `npx pixelcrew emit [flags]` | Emits a custom telemetry event into the stream | `npx pixelcrew emit --agent db --message "Done"` |
-| `npx pixelcrew dashboard` | Opens or serves the standalone Floor 42 dashboard UI | `npx pixelcrew dashboard` |
-| `npx pixelcrew status` | Prints ASCII summary of swarm states and active sprints | `npx pixelcrew status` |
-| `npx pixelcrew help` | Displays full CLI manual and flag details | `npx pixelcrew help` |
-
-### CLI Options & Flags:
-- `--target <framework>`: Target framework for OneShot (`vanilla`, `nextjs`)
-- `--out <dir>`: Custom destination directory for generated site (default: `./generated-site`)
-- `--port <number>`: Dashboard port (default: `4747`)
-- `--no-open`: Prevents auto-launching browser on startup
-- `--yes`, `-y`: Bypasses interactive prompts during initialization
-- `--agent <name>`: Target agent for event emission (`frontend`, `backend`, `database`, `security`, `performance`, `qa`, `creativeDirector`, `uxPlanner`, `designSystem`, `visualCritic`)
-- `--type <type>`: Event category (`spawn`, `thinking`, `tool`, `skill`, `complete`, `error`)
-- `--message <text>`: Description payload for the event log
-- `--skill <name>`: Skill tag associated with the action
+| Capability | Standard Library Module | Implementation Role |
+|:---|:---|:---|
+| Web Server & SSE | `node:http` | Serves dashboard assets, REST API, and Server-Sent Events stream |
+| Filesystem I/O | `node:fs/promises`, `node:fs` | Atomic read/write operations, directory trees, and events logging |
+| Event Bus | `node:events` | Internal decoupled pub/sub message pipeline |
+| Path Resolution | `node:path`, `node:url` | Cross-platform file path normalization |
+| Process Execution | `node:child_process` | Git execution and toolchain diagnostic execution |
+| Cryptography | `node:crypto` | Session IDs, task hashes, and unique event identifiers |
+| System Diagnostics | `node:os` | CPU profiling, user home path resolution, platform detection |
+| Test Harness | `node:test`, `node:assert` | Comprehensive automated unit, integration, and E2E test suites |
 
 ---
 
-## 🎮 Dashboard Controls & Keybindings
-
-| Key / Control | Function | Description |
-| :--- | :--- | :--- |
-| `[O]` | **OneShot Studio** | Opens the interactive OneShot Multi-Agent Synthesis studio |
-| `[R]` | **Audit Reports** | Toggles the comprehensive multi-agent audit reports drawer |
-| `[SPACE]` | **Launch Demo** | Boots the swarm and runs a simulated multi-agent sprint |
-| `[1] - [6]` | **Agent Inspector** | Opens the dedicated status drawer and permissions for agents 1 through 6 |
-| `[ESC]` | **Close Modals** | Closes any active OneShot studio, reports drawer, or inspector modal |
-| `CRT Button` | **Scanline Shader** | Toggles retro arcade phosphor scanlines and vignette effect |
-| `NIGHT Button` | **Cyberpunk Shift** | Switches between warm day office and neon cyberpunk night lighting |
-| `SFX Button` | **Web Audio Synth** | Toggles procedural 8-bit chip-tune feedback sounds |essage "Done"` |
-| `npx pixelcrew dashboard` | Opens or serves the standalone Floor 42 dashboard UI | `npx pixelcrew dashboard` |
-| `npx pixelcrew status` | Prints ASCII summary of swarm states and active sprints | `npx pixelcrew status` |
-| `npx pixelcrew help` | Displays full CLI manual and flag details | `npx pixelcrew help` |
-
-### CLI Options & Flags:
-- `--port <number>`: Dashboard port (default: `4747`)
-- `--no-open`: Prevents auto-launching browser on startup
-- `--yes`, `-y`: Bypasses interactive prompts during initialization
-- `--agent <name>`: Target agent for event emission (`frontend`, `backend`, `database`, `security`, `performance`, `qa`)
-- `--type <type>`: Event category (`spawn`, `thinking`, `tool`, `skill`, `complete`, `error`)
-- `--message <text>`: Description payload for the event log
-- `--skill <name>`: Skill tag associated with the action
+<a id="visual-dashboard"></a>
+
+## Visual Dashboard — Floor 42
+
+The PixelCrew dashboard renders an interactive 2D pixel-art startup office running at 60 FPS using an HTML5 Canvas with hardware-accelerated double buffering.
+
+### Key Capabilities
+
+- **Workstation Matrix**: 8 dedicated office pods representing each agent's active desk, computer monitors, and status beacons.
+- **Procedural Character Sprites**: Distinct pixel characters that visually transition between idle breathing, active typing, test verification, and completion states.
+- **Engineering Activity Stream**: A live Slack-style activity log (`#engineering-feed`) displaying real-time events, modified file paths, and build statuses.
+- **Synthesized 8-Bit Audio Engine**: Procedural chiptune sound effects generated directly via the Web Audio API without external audio files.
+- **Token Telemetry Monitor**: Visual tracking of input/output token volume, estimated cost savings, and context pruning efficiency.
+- **Keyboard Shortcuts**:
+  - `[O]` Open OneShot Studio
+  - `[R]` View Audit & Security Reports
+  - `[1-7]` Inspect individual agent status and skill cards
+  - `[SPACE]` Run interactive multi-agent demonstration sprint
+  - `[ESC]` Dismiss modal overlays
 
 ---
 
-## 📂 Workspace Manifest & Architecture
+<a id="anti-ai-design-guardian"></a>
 
-Initializing PixelCrew creates a self-contained `.pixel-agents/` control directory in your repository:
+## Anti-AI Design Guardian
 
-```
-your-project/
-├── .pixel-agents/
-│   ├── config.json              # Swarm concurrency, agent permissions, and dashboard settings
-│   ├── context.json             # Cached static analysis of frameworks, ORMs, and paths
-│   ├── state.json               # Real-time state of every agent persona
-│   ├── events.jsonl             # Append-only persistent telemetry event log
-│   ├── agents/                  # Specialized agent persona definitions
-│   └── skills/                  # Grounded engineering skill markdown manuals
-├── .pixel-dashboard/            # Zero-dependency HTML5 canvas visual office bundle
-├── DESIGN.md                    # Visual tokens, canvas coordinate engine & audio specs
-├── PRODUCT.md                   # Product vision, technical roadmap, and architectural goals
-└── README.md
+To ensure synthesized user interfaces maintain genuine production quality and avoid generic AI design patterns, PixelCrew includes an automated Anti-AI Quality Gate. Generated pages are evaluated across a six-dimension scoring rubric:
+
+```text
+Final Score = (Originality + Typography + Layout + Visual Hierarchy + Brand Consistency + (10 - Generic AI Penalty)) / 6
 ```
 
----
+**Passing Threshold**: >= 8.5 / 10.0
+
+### Explicitly Blocked Design Patterns
+
+- Repetitive, blurred cyan-and-purple gradient blobs placed on flat black surfaces.
+- Uniform, symmetrical 3-card repeating grids with identical dimensions.
+- Generic marketing copy (*"Unlock the power of AI"*, *"Seamlessly elevate your workflow"*).
+- Nested card-in-card containers with redundant padding and border clutter.
+- Reliance on default system fonts without curated typographic scales.
+- Decorative, non-functional pill badges placed above headings.
 
-## 🎮 Dashboard Controls & Keybindings
+### Curated Design Archetypes
 
-| Key / Control | Function | Description |
-| :--- | :--- | :--- |
-| `[O]` | **OneShot Studio** | Opens the interactive OneShot Multi-Agent Synthesis studio |
-| `[R]` | **Audit Reports** | Toggles the comprehensive multi-agent audit reports drawer |
-| `[SPACE]` | **Launch Demo** | Boots the swarm and runs a simulated multi-agent sprint |
-| `[1] - [6]` | **Agent Inspector** | Opens the dedicated status drawer and permissions for agents 1 through 6 |
-| `[ESC]` | **Close Modals** | Closes any active OneShot studio, reports drawer, or inspector modal |
-| `CRT Button` | **Scanline Shader** | Toggles retro arcade phosphor scanlines and vignette effect |
-| `NIGHT Button` | **Cyberpunk Shift** | Switches between warm day office and neon cyberpunk night lighting |
-| `SFX Button` | **Web Audio Synth** | Toggles procedural 8-bit chip-tune feedback sounds |
+| Archetype | Display Font | Body Font | Color Strategy | Spatial Layout |
+|:---|:---|:---|:---|:---|
+| **Editorial Asymmetric** | *Instrument Serif* | *Plus Jakarta Sans* | Off-black, Warm Cream, Amber accent | 7:5 asymmetric columns, overlapping boundaries |
+| **Technical Lab** | *Space Grotesk* | *JetBrains Mono* | Deep Obsidian, Steel, Emerald signal | Monospaced metrics, terminal containers |
+| **Kinetic Studio** | *Syne* | *DM Sans* | Pure Void, High-contrast Stark White, Electric Cyan | High-impact scale contrast, Bento matrices |
 
 ---
 
-## 🧪 Development & Testing
+<a id="cli-reference"></a>
 
-Run unit tests across the orchestrator engine, scaffolders, and server endpoints:
+## CLI Reference
 
 ```bash
-# Clone the repository
-git clone https://github.com/hiroqt/PixelCrew.git
-cd PixelCrew
-
-# Run the zero-dependency test suite
-npm test
+npx pixelcrew <command> [arguments] [flags]
 ```
 
+### Primary Commands
+
+| Command | Arguments | Description |
+|:---|:---|:---|
+| `init` | `[targetDir]` | Analyzes codebase and bootstraps `.pixel-crew/` configuration. |
+| `start` | | Launches orchestration daemon and opens the visual dashboard. |
+| `assemble` | `"<prompt>"` | Executes end-to-end software synthesis pipeline. |
+| `blueprint` | `"<prompt>"` | Generates architecture specifications and dependency DAGs without generating code. |
+| `oneshot` | `"<prompt>"` | Rapid application synthesis using tailored creative direction. |
+| `recap` | `[commitCount]` | Summarizes recent git activity into a token-optimized changelog. |
+| `doctor` | | Runs system diagnostic checks across Node.js, Git, and installed AI IDEs. |
+| `status` | | Outputs running agent statuses, active tasks, and server health. |
+| `install` | | Distributes agent skills to workspace or global IDE directories. |
+| `add` | `<skillId>` | Adds a specific skill to designated provider directories. |
+| `sync` | | Synchronizes installed skills across all active IDE environments. |
+| `commands` | `[category]` | Displays the Floor 42 command catalog and syntax guide. |
+| `stop` | | Gracefully terminates background orchestration server. |
+
+### Configuration Flags
+
+| Flag | Type | Default | Description |
+|:---|:---|:---|:---|
+| `--dry-run` | Boolean | `false` | Previews planned file operations without writing to disk. |
+| `--yes`, `-y` | Boolean | `false` | Bypasses interactive confirmation prompts. |
+| `--provider <name>` | String | `all` | Specifies target provider (`claude-code`, `cursor`, `kiro`, `antigravity`, `all`, `none`). |
+| `--global` | Boolean | `false` | Targets user-level configuration directories instead of current repository. |
+| `--target <tech>` | String | `nextjs` | Sets target generation framework (`nextjs`, `vanilla`). |
+| `--port <number>` | Number | `4747` | Port for local orchestration server and dashboard. |
+| `--no-open` | Boolean | `false` | Suppresses automatic browser launch when running `start`. |
+| `--out <directory>` | String | `.` | Destination path for synthesized application code. |
+
 ---
 
-## 📚 Documentation & Specifications
+<a id="testing"></a>
+
+## Testing
+
+PixelCrew includes an automated test suite implemented directly on Node.js native `node:test` and `node:assert` modules.
+
+```bash
+# Run the automated test suite
+node --test tests/commands-discovery.e2e.test.js tests/commands.test.js tests/installer.test.js tests/init-multi-ide.test.js tests/sync-providers.test.js
+```
+
+### Verified Test Areas
 
-- [📐 DESIGN.md](DESIGN.md) — 2D Canvas coordinate matrix, sprite frame animations, color tokens, and Web Audio oscillator formulas.
-- [🎯 PRODUCT.md](PRODUCT.md) — Product vision, target personas, problem analysis, and development roadmap (v0.1 to v0.5).
-- [🤝 CONTRIBUTING.md](CONTRIBUTING.md) — How to author new skills, add custom agent sprites, and submit pull requests.
-- [⚖️ LICENSE](LICENSE) — Apache 2.0 open-source license.
+- **End-to-End Slash Command Discovery**: Validates slash command generation on clean devices across Claude Code, Cursor, Kiro, Antigravity, and CLI.
+- **Provider Synchronization**: Verifies that skills, workflows, and prompts remain identical across all target IDE directories.
+- **Dry-Run Integrity**: Confirms that operations executed with `--dry-run` perform zero file system writes.
+- **DAG Execution & Concurrency**: Validates dependency resolution, cycle prevention, and parallel execution in the task scheduler.
+- **Git Recap Engine**: Ensures git changelogs are extracted accurately, windowed properly, and formatted cleanly without token waste.
 
 ---
 
-## 🌟 Community & Contributing
+<a id="roadmap"></a>
 
-Contributions of all types are warmly welcomed!
+## Roadmap
 
-- **Create New Skills**: Add new technology guides to `.pixel-agents/skills/` (e.g. GraphQL, Supabase, Redis, Rust, Astro).
-- **Design Office Packs**: Add custom pixel-art furniture, workstations, and seasonal office themes.
-- **Improve Orchestration**: Enhance DAG task scheduling, automated error recovery, and concurrency management.
-- **Report Bugs**: Submit issues and feature proposals at [github.com/hiroqt/PixelCrew/issues](https://github.com/hiroqt/PixelCrew/issues).
+| Milestone | Target Scope | Current Status |
+|:---|:---|:---|
+| **v0.1** | Core CLI, codebase profiler, Floor 42 canvas, SSE telemetry pipeline, 8-bit audio synth | [Completed] |
+| **v0.2** | 24 Floor 42 slash commands, cross-IDE command discovery, Anti-AI quality gate, git recap engine | [Completed] |
+| **v0.3** | Automated Git worktree isolation, three-way merge conflict resolver, multi-branch swarming | [In Progress] |
+| **v0.4** | External model provider runtime adapters (Gemini API, Claude API, OpenAI API, Ollama) | [Planned] |
+| **v0.5** | Multi-floor office expansions, distributed peer-to-peer swarms via WebSockets and WebRTC | [Planned] |
 
 ---
 
-## 📄 License
+<a id="documentation-and-contributing"></a>
+
+## Documentation and Contributing
+
+| Resource | Scope |
+|:---|:---|
+| [PRODUCT.md](PRODUCT.md) | Product strategy, persona definitions, and feature release milestones |
+| [DESIGN.md](DESIGN.md) | Design specifications, color systems, canvas engine, and typography standards |
+| [TESTING.md](TESTING.md) | Testing conventions, fixture runner documentation, and CI workflows |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution standards, code style guides, and pull request checklist |
+| [LICENSE](LICENSE) | Apache License, Version 2.0 |
 
-PixelCrew is open-source software licensed under the **[Apache License, Version 2.0](LICENSE)**.
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on code formatting and test verification before submitting changes.
 
 ---
 
 <p align="center">
-  Crafted with precision by <strong>Arnel</strong> (<a href="https://github.com/hiroqt">@hiroqt</a>).
+  <sub>Built with care and zero runtime dependencies by <a href="https://github.com/hiroqt">@hiroqt</a></sub>
 </p>