aiteam-x 0.14.1 → 0.14.2

package/README.en.md

@@ -1,5 +1,5 @@
 <p align="right">
-  <a href="README.md">Portugues</a> | <strong>English</strong>
+  <a href="README.md">Português</a> | <strong>English</strong>
 </p>
 
 # AITeam Team Overview
@@ -14,7 +14,7 @@
 [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
 
 ```bash
-npx aiteam-x@latest
+npx 4aiteam-x@latest
 ```
 
 ---
@@ -23,11 +23,15 @@ npx aiteam-x@latest
 
 **AITeam Team Overview** is an interactive dashboard that turns AI agent management into a visual, intuitive experience. Inspired by *sim manager*-style simulation games, the panel displays BMAD agents as pixel-art characters in a virtual office, allowing you to:
 
-- **Visualize** each agent's status and location in real time
-- **Interact** directly with agents through integrated chat windows
-- **Orchestrate** workflows such as Party Mode and brainstorming sessions
-- **Monitor** usage metrics (messages, tokens in/out) per agent
-- **Persist** context and memories between work sessions with LLM extraction
+- **Visualize** each agent's status and location in real time — in 2D pixel art or a 3D isometric office (Three.js)
+- **Customize** the experience with 4 visual themes (Pixel Bots, Chibi, Hybrid, Teams) — each with distinct palettes and avatars
+- **Interact** directly with agents through a resizable lateral chat drawer with SSE streaming
+- **Create rooms** to group agents into custom work contexts
+- **Review diffs** of files modified by agents with inline approval/rejection before persisting changes
+- **Orchestrate** workflows such as Party Mode and brainstorming sessions via the workflow panel
+- **Monitor** usage metrics via a gamified Quest Log (messages, tokens in/out) and view tool calls in real time
+- **Persist** context and memories between work sessions with LLM extraction, compaction, and automatic migration
+- **Update** the platform with one click via integrated self-update (check, download, merge, restart)
 
 The project uses the **BMAD Method** as the agent framework, natively integrating with the **Cursor Agent CLI** and **Cursor ACP** (Agent Client Protocol) for bidirectional LLM communication.
 
@@ -69,23 +73,54 @@ The project uses the **BMAD Method** as the agent framework, natively integratin
 
 ## Key Features
 
-### Pixel Art Dashboard
+### Pixel Art Dashboard + 3D Scene
+- **2D/3D Toggle**: switch between the classic pixel art grid and a 3D isometric office (Three.js / React Three Fiber)
+- **3D Scene**: isometric environment with models loaded via `ModelLoader`, dynamic lighting (`DayNightLight`), agents as 3D characters (`AgentCharacter`), and pathfinding (`three-pathfinding`)
+- **Collapsible sidebar**: lateral navigation with agents organized by module, custom rooms, and real-time status indicators
 - Shared rooms: **Jarvis Office**, **Kitchen** — with agent activity context
-- Individual workspace grid per agent with module indicators (BMGD / BMM / CORE)
-- Pixel-art avatars with real-time visual status
+- Individual workspace grid per agent with module indicators (BMGD / BMM / CORE / BMB)
+- Pixel art or image-based avatars (depending on theme) with real-time visual status
 - Bottom bar with compact avatars and sprint timeline with granular per-story progress
-- Day/night cycle and ambient effects
+- Day/night cycle and ambient effects (reflected in both 2D and 3D)
+- **Starfield Canvas**: background animation with stellar particles as a decorative visual effect
 
 ### Agent Interaction
 - Agent selection (click) or multi-selection (Ctrl+click) for batch commands
-- Resizable chat windows with real-time SSE streaming
-- Animated "thinking" bubble during processing
-- Full Markdown rendering in responses
+- **Chat Drawer**: resizable panel pinned to the right with real-time SSE streaming (replaced floating windows)
+- Per-agent input history (↑ to navigate previous commands)
+- **Rich Message Rendering**: responses segmented into Markdown, terminal blocks, tool call indicators, and collapsible thinking blocks
+- **Thinking Block**: expandable view of the model's internal reasoning (chain-of-thought)
+- **Tool Call Indicators**: real-time badges showing agent actions (Read, Edit, Terminal, Grep, etc.) with contextual summaries
 - **Copy button**: appears on hover over agent responses for one-click copy
 - **Context menu**: right-click on any agent to see agent-specific MDC commands
 - Stop button to cancel ongoing processing
 - Conversation history persisted across reloads
-- Dynamic z-index system (bring-to-front on click)
+- Escape shortcut to close the drawer
+
+### Diff Approval (Change Review)
+- **Pre-command snapshot**: the system captures file state before each agent command and compares after the response, detecting changes with precision
+- **Inline diff cards**: unified diff cards appear directly in the agent conversation with per-line syntax highlighting (additions, removals, context)
+- **Granular approval**: Approve/Deny buttons per individual file, or "Approve All" for batch acceptance
+- **Automatic revert**: denied files are reverted to their original content via `/api/files/revert`
+- Visual counters of added/removed lines per file and status badges (Approved / Reverted)
+
+### Theme System
+- **4 visual themes**: Pixel Bots (cyberpunk), Chibi (anime), Hybrid (tech), Teams (corporate)
+- **Dynamic avatars**: Chibi and Hybrid themes use image-based avatars; Pixel Bots and Teams use SVG pixel art
+- **ThemePicker**: visual selector with color preview and icon per theme
+- **Persistence**: selected theme saved in `localStorage` and applied via CSS custom properties
+
+### Chat Rooms (Custom Rooms)
+- **Free creation**: group any combination of agents into themed rooms via `CreateRoomModal`
+- **Integrated sidebar**: rooms appear in the side bar with icon and member list
+- **RoomTransition**: smooth transition animation when switching between rooms
+- **API persistence**: rooms saved on the server (`/api/rooms`) and synchronized across reloads
+
+### Quest Log (Activity Log)
+- **Gamified panel**: RPG-style visualization of each agent's activities
+- **Per-agent status**: active (in conversation), complete (last session), idle (no activity)
+- **Metrics**: message count, tokens consumed, and last message sent
+- **Inline avatar**: each quest displays the corresponding agent's pixel art avatar
 
 ### Model Selector & Filters
 - **Model Bar**: LLM model selection applied to all agents
@@ -99,6 +134,7 @@ The project uses the **BMAD Method** as the agent framework, natively integratin
 - Automatic discovery of available models via ACP session `configOptions`
 - Per-session model switching via `session/set_config_option`
 - Persistent ACP process with 30-min session TTL and automatic reconnection
+- Streaming tool calls with rich metadata (type, title, summarized output)
 - Error fallback with actionable messages for the user
 
 ### BMAD Orchestration
@@ -107,16 +143,29 @@ The project uses the **BMAD Method** as the agent framework, natively integratin
 - Session state persisted on disk and synchronized via SSE
 - Per-agent message and token metrics
 
-### Persistent Memory System (v2.1)
+### Persistent Memory System (v2.2)
 - **Memory Vault**: full visual panel with 5 categories (decisions, lessons, tasks, projects, handoffs)
 - **Auto-extract via LLM**: when closing a session, the system analyzes the conversation and automatically extracts structured memories
 - **Badge 🤖 llm**: automatically extracted entries are flagged for 10 minutes with veto option
 - **BM25 Search**: relevance-based semantic search within each agent's vault
 - **Context Injection**: relevant memories automatically injected when starting new sessions (2,000-token budget)
+- **Automatic compaction**: `/api/memory/compact` cleans old checkpoints, merges duplicates, and rebuilds indexes
+- **Data migration**: `/api/memory/migrate` updates data structures from previous versions automatically
 - **Auto-save**: conversations saved every 30s + save on unload via `sendBeacon`
 - **Session Checkpoint**: history preserved even across unexpected restarts
 - **Shared Memory**: `_project.md` injected into all agents as global context
 
+### Self-Update
+- **Automatic check**: `/api/version/check` compares local version with the NPM registry
+- **UpdateModal**: step-by-step interface with visual progress (download → merge → install → restart)
+- **Smart merge**: updates only template files without overwriting local configurations
+- **Automatic restart**: restarts the development server after the update
+
+### Notifications & Easter Eggs
+- **Event Toast**: visual notification system with 4 types (success, error, info, milestone) and auto-dismiss
+- **Easter Eggs**: hidden interactions in the virtual office (fridge, coffee machine, and more) with rarities (common, rare, legendary)
+- **Sound system**: optional sound effects for interactions and discoveries
+
 ### Portability & Installation (v1.0)
 - **Dynamic Discovery**: automatically detects BMAD agents via CSV/YAML — no hardcoding
 - **Cross-platform**: works on Windows, macOS, and Linux
@@ -133,14 +182,18 @@ The project uses the **BMAD Method** as the agent framework, natively integratin
 |-------|-----------|---------|
 | Framework | Next.js (App Router) | 15.x |
 | UI | React | 19.x |
+| 3D Engine | Three.js + React Three Fiber + Drei | 0.183 / 9.5 / 10.7 |
 | Language | TypeScript | 5.x |
-| Styling | CSS custom (pixel art design system) | — |
+| Styling | CSS custom (design system with 4 themes) | — |
 | Font | VT323 (Google Fonts) | — |
-| Backend | Next.js API Routes + SSE | — |
-| Search | MiniSearch (BM25) | — |
+| Backend | Next.js API Routes + SSE (22 endpoints) | — |
+| Diff Engine | diff (npm) | 8.x |
+| Search | MiniSearch (BM25) | 7.2.x |
+| Pathfinding | three-pathfinding | 1.3.x |
 | Agents | Cursor Agent CLI + ACP | latest |
 | Protocol | ACP (JSON-RPC 2.0 / stdio) | v1 |
 | Parsing | yaml (npm) | 2.8.x |
+| Tests | Vitest + v8 coverage | 4.x |
 | Agent Framework | BMAD Method | — |
 
 ---
@@ -163,13 +216,13 @@ The project uses the **BMAD Method** as the agent framework, natively integratin
 **Option 1 — One command (recommended):**
 
 ```bash
-npx aiteam-x@latest
+npx 4aiteam-x@latest
 ```
 
 Creates the project in the current directory (must be empty). Or specify a folder name:
 
 ```bash
-npx aiteam-x@latest my-project
+npx 4aiteam-x@latest my-project
 ```
 
 The command downloads the template, installs dependencies, runs the setup wizard, and starts the server automatically.
@@ -203,18 +256,20 @@ The dashboard will be available at **http://localhost:3000**.
 |---------|-------------|
 | `npm run setup` | **Interactive setup wizard** (first install) |
 | `npm run dev` | Start the development server (port 3000) |
-| `npm run build` | Generate the production build |
+| `npm run dev:clean` | Start with cache cleanup (resolves state issues) |
+| `npm run build` | Generate the production build (with pre-build validations) |
 | `npm run start` | Start the production server |
 | `npm run lint` | Run the linter (ESLint) |
+| `npm run test` | Run tests with Vitest |
+| `npm run test:watch` | Tests in watch mode (re-runs on save) |
 
 ### Utility Scripts
 
 | Script | Description |
 |--------|-------------|
-| `node scripts/extract-memories.mjs --all` | Extract memories from historical conversations via LLM |
-| `node scripts/extract-memories.mjs --agent bmad-master` | Extract memories for a specific agent |
-| `node scripts/extract-memories.mjs --all --dry-run` | Simulate extraction without saving |
 | `node scripts/import-conversations.mjs` | Import conversation history into the vault |
+| `node scripts/generate-chibi-logo.mjs` | Generate chibi-style logo assets |
+| `node scripts/crop-avatars.mjs` | Crop avatars for image-based themes |
 
 > All scripts require the server running at `localhost:3000`.
 
@@ -225,82 +280,140 @@ The dashboard will be available at **http://localhost:3000**.
 ```
 AITeam/
 ├── app/                          # Next.js App Router
-│   ├── api/                      # API Routes (backend)
+│   ├── api/                      # API Routes (backend) — 22 endpoints
 │   │   ├── acp/
 │   │   │   └── models/route.ts   # GET: available models via ACP
 │   │   ├── agents/
 │   │   │   ├── route.ts          # GET: list agents with status
-│   │   │   ├── command/route.ts  # POST: send command via SSE (CLI or ACP)
+│   │   │   ├── command/route.ts  # POST: send command via SSE (CLI or ACP) + file diffs
 │   │   │   └── menus/route.ts    # GET: agent context menus
 │   │   ├── bridge/route.ts       # GET: ACP health check
 │   │   ├── config/route.ts       # GET: BMAD configuration
+│   │   ├── files/
+│   │   │   └── revert/route.ts   # POST: revert file to original content (diff denial)
 │   │   ├── memory/
 │   │   │   ├── route.ts          # GET/POST: memory and conversations (legacy)
 │   │   │   ├── vault/route.ts    # GET/POST/PUT/DELETE: structured vault
 │   │   │   ├── search/route.ts   # GET: BM25 search
 │   │   │   ├── checkpoint/route.ts # POST: session checkpoint
-│   │   │   ├── sleep/route.ts    # POST: end session + queue LLM extraction
-│   │   │   └── extract/route.ts  # POST: manual LLM extraction trigger
+│   │   │   ├── compact/route.ts  # POST: data compaction (cleanup + merge + reindex)
+│   │   │   └── migrate/route.ts  # POST: data structure migration from previous versions
+│   │   ├── rooms/route.ts        # GET/POST: custom agent rooms
 │   │   ├── session/
 │   │   │   ├── route.ts          # GET/POST: active session
 │   │   │   └── stream/route.ts   # GET: SSE for session changes
 │   │   ├── sprint/route.ts       # GET/POST: sprint status
+│   │   ├── terminal/
+│   │   │   └── execute/route.ts  # POST: terminal command execution
+│   │   ├── version/
+│   │   │   ├── check/route.ts    # GET: check latest version on NPM
+│   │   │   ├── update/route.ts   # POST: SSE download + merge + install
+│   │   │   └── restart/route.ts  # POST: restart the dev server
 │   │   └── workflows/route.ts    # GET: available workflows
 │   ├── actions/
 │   │   └── setup-save.ts         # Server Action: saves aiteam.config.json
 │   ├── setup/
 │   │   ├── page.tsx              # Setup page (health gate + Server Component)
 │   │   └── SetupWizard.tsx       # Animated 3-phase wizard (Client Component)
-│   ├── globals.css               # Pixel art design system (800+ lines)
+│   ├── globals.css               # Design system with 4 themes (800+ lines)
 │   ├── layout.tsx                # Root layout (VT323, pt-BR)
 │   ├── error.tsx                 # Error boundary
 │   └── page.tsx                  # Main page (health gate)
 │
-├── components/                   # React Components
-│   ├── rooms/                    # Virtual office rooms
+├── components/                   # React Components (~49 files)
+│   ├── rooms/                    # Virtual office rooms (2D)
 │   │   ├── ConferenceRoom.tsx
 │   │   ├── JarvisOffice.tsx
 │   │   └── Kitchen.tsx
+│   ├── scene/                    # 3D Scene (Three.js / R3F)
+│   │   ├── Scene3D.tsx           # Main 3D canvas
+│   │   ├── OfficeEnvironment.tsx # 3D office environment
+│   │   ├── ModelLoader.tsx       # 3D model loader
+│   │   ├── DayNightLight.tsx     # Day/night lighting system
+│   │   └── AgentCharacter.tsx    # 3D agent character
 │   ├── AgentContextMenu.tsx      # Per-agent context menu
+│   ├── AgentDetail.tsx           # Detailed agent view
+│   ├── AgentListItem.tsx         # Sidebar list item
 │   ├── AgentsProvider.tsx        # Global Context Provider
+│   ├── BottomBar.tsx             # Bottom bar with avatars and sprint
+│   ├── ChatDrawer.tsx            # Resizable lateral chat drawer + inline diffs
 │   ├── CommandPopup.tsx          # Multi-agent popup
 │   ├── CopyButton.tsx            # Copy button for responses
+│   ├── CreateRoomModal.tsx       # Modal for creating custom rooms
+│   ├── DayNightCycle.tsx         # Day/night cycle (2D)
+│   ├── DiffViewer.tsx            # Diff viewer with inline approval/rejection
+│   ├── EasterEggs.tsx            # Hidden office interactions
+│   ├── EventToast.tsx            # Toast notification system
 │   ├── FilterContext.tsx         # Filter context (status + module)
-│   ├── Layout.tsx                # Shell (TopBar + ModelBar + BottomBar)
-│   ├── MainContent.tsx           # Main orchestrator (~500 lines)
+│   ├── Layout.tsx                # Main shell
+│   ├── MainContent.tsx           # Main orchestrator
 │   ├── MarkdownRenderer.tsx      # Custom Markdown renderer
 │   ├── MemoryVault.tsx           # Memory Vault dashboard (modal)
+│   ├── MessageRenderer.tsx       # Segmented renderer (MD, terminal, tools, thinking)
 │   ├── ModelBar.tsx              # Model selection bar and filters
-│   ├── PixelAvatar.tsx           # Pixel art SVG avatar
+│   ├── PixelAvatar.tsx           # Pixel art SVG / image-based avatar
+│   ├── QuestLog.tsx              # Gamified agent activity panel
+│   ├── RoomTransition.tsx        # Room transition animation
+│   ├── Sidebar.tsx               # Collapsible sidebar (agents + rooms)
+│   ├── SpeechBubble.tsx          # Individual speech bubble
 │   ├── SpeechBubbleOverlay.tsx   # Chat overlay system
+│   ├── SprintPanel.tsx           # Dedicated sprint panel
+│   ├── StarfieldCanvas.tsx       # Background stellar particle animation
+│   ├── TerminalBlock.tsx         # Terminal block in responses
+│   ├── ThemePicker.tsx           # Visual theme selector
+│   ├── ThemeProvider.tsx         # Theme context provider
+│   ├── ThinkingBlock.tsx         # Collapsible reasoning block (thinking)
 │   ├── ThinkingBubble.tsx        # Animated thinking indicator
+│   ├── ToolCallIndicator.tsx     # Real-time tool call badge
+│   ├── TopBar.tsx                # Top bar with title and controls
+│   ├── UpdateModal.tsx           # Self-update modal with step-by-step progress
+│   ├── ViewToggle.tsx            # 2D ↔ 3D toggle
+│   ├── WorkflowPanel.tsx         # BMAD workflow panel with module filter
 │   ├── WorkspaceCell.tsx         # Individual workspace cell
-│   └── WorkspaceGrid.tsx         # Workspace grid
+│   ├── WorkspaceGrid.tsx         # Workspace grid
+│   └── WorkspaceProps.tsx        # Shared workspace props
 │
 ├── lib/                          # Business logic and utilities
 │   ├── acp-client.ts             # ACP client (JSON-RPC 2.0 over stdio)
 │   ├── acp-manager.ts            # ACP session manager
 │   ├── aiteam-config.ts          # Config loader (env var > file > defaults)
+│   ├── diff.ts                   # Unified diff engine (computeUnifiedDiff)
 │   ├── health.ts                 # Health check: BMAD, Cursor CLI, config
+│   ├── mock-agents.ts            # Mock data for testing and preview
+│   ├── model-config.ts           # Available LLM model options
+│   ├── parseMultiAgentResponse.ts # Multi-agent response parser
 │   ├── setup-discovery.ts        # Extended discovery for the web wizard
+│   ├── sound.ts                  # Sound effects system
+│   ├── synergy.ts                # Agent synergy logic
+│   ├── theme.ts                  # Theme definitions (4 themes + metadata)
+│   ├── types.ts                  # Global TypeScript types
+│   ├── useAgents.ts              # Agent management hook
+│   ├── version.ts                # Version check (NPM registry)
 │   ├── bmad/                     # BMAD Integration
 │   │   ├── discovery.ts          # Dynamic BMAD scanner + Cursor CLI detection
 │   │   ├── agent-mapping.ts      # BmadAgent -> Agent mapping
 │   │   ├── chat-sessions.ts      # Chat session persistence
+│   │   ├── memory-bank.ts        # Memory bank integration
 │   │   ├── parse-agents.ts       # agent-manifest.csv parser
 │   │   ├── parse-config.ts       # config.yaml parser
 │   │   ├── parse-persona.ts      # Persona (.mdc) parser
 │   │   ├── parse-session.ts      # Session state + SSE
 │   │   ├── parse-sprint.ts       # sprint-status.yaml parser
 │   │   └── parse-workflows.ts    # Workflows parser
-│   ├── memory/                   # Memory system v2
-│   │   ├── extract.ts            # LLM extraction engine
-│   │   ├── inject.ts             # Context injection (BM25 + budget)
-│   │   ├── session.ts            # Session lifecycle (sleep/recover)
-│   │   ├── types.ts              # Memory system types
-│   │   └── vault.ts              # Structured vault CRUD
-│   ├── model-config.ts           # Available LLM model options
-│   └── types.ts                  # Global TypeScript types
+│   └── memory/                   # Memory system v2.2
+│       ├── compact.ts            # Data compaction and cleanup
+│       ├── inject.ts             # Context injection (BM25 + budget)
+│       ├── migrate.ts            # Cross-version structure migration
+│       ├── search.ts             # BM25 search engine
+│       ├── session.ts            # Session lifecycle (sleep/recover)
+│       ├── types.ts              # Memory system types
+│       ├── vault.ts              # Structured vault CRUD
+│       └── __tests__/            # Unit tests (Vitest)
+│           ├── inject.test.ts
+│           ├── session.test.ts
+│           ├── vault.test.ts
+│           ├── search.test.ts
+│           └── migrate.test.ts
 │
 ├── .memory/                      # Memory Bank (persistent, gitignored)
 │   ├── _project.md               # Global context — injected into all agents
@@ -309,21 +422,39 @@ AITeam/
 │   └── .vault/                   # Structured vault and extraction queue
 │
 ├── docs/                         # Project documentation
+│   ├── index.md                  # Main documentation index
 │   ├── screenshots/              # UI screenshots
-│   ├── installation-guide.md     # Full installation guide
-│   ├── architecture.md           # System architecture
-│   ├── api-reference.md          # Complete API reference
-│   ├── developer-guide.md        # Developer guide
+│   ├── project-overview-aiteam-x.md  # Project overview (generated)
+│   ├── architecture-aiteam-x.md      # Detailed architecture (generated)
+│   ├── api-contracts-aiteam-x.md     # API contracts — 22 endpoints (generated)
+│   ├── component-inventory-aiteam-x.md # Component inventory (generated)
+│   ├── development-guide-aiteam-x.md  # Development guide (generated)
+│   ├── source-tree-analysis.md        # Source tree analysis (generated)
+│   ├── installation-guide.md     # Full installation guide (original)
+│   ├── architecture.md           # System architecture (original)
+│   ├── api-reference.md          # Complete API reference (original)
+│   ├── developer-guide.md        # Developer guide (original)
 │   ├── user-guide.md             # End-user guide
 │   ├── memory-system.md          # Memory system technical architecture
 │   ├── memory-system-guide.md    # Memory system functional guide
+│   ├── memory-system-comparison.md # Memory system comparative analysis
 │   ├── agent-catalog.md          # Complete BMAD agent catalog
-│   └── sprint-status.yaml        # Current sprint status
+│   ├── sprint-status.yaml        # Current sprint status
+│   └── superpowers/              # Future features (specs + plans)
+│       ├── specs/                # Design documents
+│       └── plans/                # Implementation plans
+│
+├── hooks/                         # Custom React hooks
+│   └── useVersionCheck.ts        # Version check hook (NPM registry)
 │
 ├── scripts/                      # Utility scripts
 │   ├── setup.mjs                 # Interactive setup wizard (6 steps)
-│   ├── extract-memories.mjs      # Batch LLM extraction
-│   └── import-conversations.mjs  # History import into vault
+│   ├── cli.mjs                   # CLI for npx 4aiteam-x (package entry point)
+│   ├── safe-build.mjs            # Safe build with pre-build validations
+│   ├── clean-start.mjs           # Dev server with cache cleanup
+│   ├── import-conversations.mjs  # History import into vault
+│   ├── generate-chibi-logo.mjs   # Chibi logo asset generation
+│   └── crop-avatars.mjs          # Avatar cropping for image-based themes
 │
 ├── aiteam.config.example.json    # Configuration example (reference)
 ├── .cursor/                      # Cursor IDE rules and skills
@@ -339,6 +470,20 @@ AITeam/
 
 ## Documentation
 
+### Generated Documentation (document-project workflow)
+
+| Document | Level | Description |
+|----------|-------|-------------|
+| [Documentation Index](docs/index.md) | All | Main entry point for all documentation |
+| [Project Overview](docs/project-overview-aiteam-x.md) | Executive | Executive summary, stack, metrics, and features |
+| [Detailed Architecture](docs/architecture-aiteam-x.md) | Architectural | Patterns, decisions, diagrams, and layers |
+| [API Contracts](docs/api-contracts-aiteam-x.md) | Technical | 22 endpoints with request/response schemas |
+| [Component Inventory](docs/component-inventory-aiteam-x.md) | Technical | ~49 components, hierarchy, state, and patterns |
+| [Development Guide](docs/development-guide-aiteam-x.md) | Developer | Setup, commands, conventions, and troubleshooting |
+| [Source Code Analysis](docs/source-tree-analysis.md) | Technical | Annotated structure with purpose of each directory |
+
+### Original Documentation
+
 | Document | Level | Description |
 |----------|-------|-------------|
 | [Installation Guide](docs/installation-guide.md) | Beginner | Step-by-step installation, setup wizard, troubleshooting |
@@ -348,6 +493,7 @@ AITeam/
 | [User Guide](docs/user-guide.md) | End User | How to use the dashboard, interact with agents, Memory Vault |
 | [Memory System (technical)](docs/memory-system.md) | Technical/Conceptual | Layered architecture of the memory system |
 | [Memory Guide (functional)](docs/memory-system-guide.md) | End User | How to use the Memory Vault, case studies, best practices |
+| [System Comparison](docs/memory-system-comparison.md) | Technical | Comparative analysis of memory systems |
 | [Agent Catalog](docs/agent-catalog.md) | Reference | All agents, specialties, and how to work with each one |
 
 ---
@@ -379,7 +525,7 @@ The system automatically discovers agents from `bmad/_cfg/agent-manifest.csv`. T
 
 ## Configuration
 
-AITEAM-X uses a local `aiteam.config.json` file (gitignored) generated by `npm run setup`. For advanced configuration, create a `.env.local`:
+4AITEAM-X uses a local `aiteam.config.json` file (gitignored) generated by `npm run setup`. For advanced configuration, create a `.env.local`:
 
 ```env
 # Alternate path to the BMAD installation
@@ -401,12 +547,15 @@ See the [Installation Guide](docs/installation-guide.md) for all configuration s
 
 ## Contributing
 
-1. Create a branch from `develop`
-2. Make your changes following project conventions
-3. Ensure `npm run lint` and `npm run build` pass
-4. Open a Pull Request to `develop`
+1. Fork the repository
+2. Create a branch from `develop` (`git checkout -b feature/my-feature develop`)
+3. Make your changes following project conventions
+4. Ensure `npm run lint` and `npm run build` pass without errors
+5. Open a Pull Request to `develop`
+
+> Report bugs or suggest improvements? Open an [issue on GitHub](https://github.com/INOSX/AITeam/issues).
 
-See the [Developer Guide](docs/developer-guide.md) for details.
+See the [Developer Guide](docs/developer-guide.md) for code conventions, commit patterns, and architecture details.
 
 ---
 
@@ -422,4 +571,4 @@ This project is distributed under the MIT License. See [LICENSE](LICENSE) for de
 
 ---
 
-*Built with the BMAD Method — where AI agents work as a team.*
+*Built with the BMAD Method — where AI agents work as a team.* | v0.14.1