@namch/agent-assistant 1.3.0 → 1.3.2

package/documents/knowledge-source-base/01-directory-structure.md

@@ -0,0 +1,312 @@
+# Agent Assistant — Directory Structure
+
+> **Purpose**: Complete annotated directory tree (depth 3-4) with functional purpose of every top-level directory and key files
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [Root Directory Overview](#root-directory-overview)
+2. [Annotated Directory Tree](#annotated-directory-tree)
+3. [Top-Level Directory Purposes](#top-level-directory-purposes)
+4. [Root File Purposes](#root-file-purposes)
+5. [File Count Summary](#file-count-summary)
+6. [Evidence Sources](#evidence-sources)
+
+---
+
+## Root Directory Overview
+
+The project root contains 10 top-level directories and 12 root-level files. The framework is organized into a clear separation: **framework content** (agents, commands, rules, skills, matrix-skills) that gets installed into AI tool directories, **CLI tooling** (cli/) that performs the installation, **platform templates** (code-assistants/) with per-tool customizations, **documentation** (documents/), and a **marketing website** (web/) that is an independent sub-project.
+
+---
+
+## Annotated Directory Tree
+
+```
+agent-assistant/                          # Project root — npm package @namch/agent-assistant
+│
+├── package.json                          # npm manifest: scripts, deps, engines, bin, files
+├── package-lock.json                     # Locked dependency tree
+├── .releaserc.json                       # semantic-release config (conventional commits, main branch)
+├── .gitignore                            # Excludes node_modules, dist, .env, reports/
+├── LICENSE                               # MIT license
+├── README.md                             # Project README (published to npm)
+├── CHANGELOG.md                          # Auto-generated version history (semantic-release)
+│
+├── AGENT.md                              # Generic agent entry point (platform-agnostic)
+├── AGENT-TEMPLATE.md                     # Template spec for creating new agent files (Matrix Skill Discovery)
+├── CLAUDE.md                             # Claude Code platform entry point
+├── CODEX.md                              # Codex platform entry point
+├── COPILOT.md                            # GitHub Copilot platform entry point
+├── CURSOR.md                             # Cursor platform entry point
+├── GEMINI.md                             # Gemini/Antigravity platform entry point
+│
+├── .husky/                               # Git hooks manager
+│   └── _/                                # Husky internal runtime files
+│
+├── agents/                               # 21 specialist agent definitions + 17 teams
+│   ├── backend-engineer.md               # Backend implementation specialist
+│   ├── brainstormer.md                   # Creative ideation agent
+│   ├── business-analyst.md               # Business requirements analysis
+│   ├── database-architect.md             # Database design specialist
+│   ├── debugger.md                       # Bug diagnosis and resolution
+│   ├── designer.md                       # UI/UX design specialist
+│   ├── devops-engineer.md                # CI/CD and infrastructure
+│   ├── docs-manager.md                   # Documentation architecture
+│   ├── frontend-engineer.md              # Frontend implementation specialist
+│   ├── game-engineer.md                  # Game development specialist
+│   ├── mobile-engineer.md                # Mobile app development
+│   ├── performance-engineer.md           # Performance optimization
+│   ├── planner.md                        # Project and task planning
+│   ├── project-manager.md               # Project coordination
+│   ├── reporter.md                       # Intelligence and analysis reporting
+│   ├── researcher.md                     # Research and exploration
+│   ├── reviewer.md                       # Code and design reviews
+│   ├── scouter.md                        # Codebase reconnaissance
+│   ├── security-engineer.md              # Security analysis and hardening
+│   ├── tech-lead.md                      # Architecture decisions and oversight
+│   ├── tester.md                         # Test strategy and implementation
+│   └── teams/                            # 17 team directories × 3 roles each = 51 team agents
+│       ├── backend-team/                 # executor.md, reviewer.md, techlead.md
+│       ├── database-team/                # executor.md, reviewer.md, techlead.md
+│       ├── debug-team/                   # executor.md, reviewer.md, techlead.md
+│       ├── design-team/                  # executor.md, reviewer.md, techlead.md
+│       ├── devops-team/                  # executor.md, reviewer.md, techlead.md
+│       ├── docs-team/                    # executor.md, reviewer.md, techlead.md
+│       ├── frontend-team/                # executor.md, reviewer.md, techlead.md
+│       ├── fullstack-team/               # executor.md, reviewer.md, techlead.md
+│       ├── game-team/                    # executor.md, reviewer.md, techlead.md
+│       ├── mobile-team/                  # executor.md, reviewer.md, techlead.md
+│       ├── performance-team/             # executor.md, reviewer.md, techlead.md
+│       ├── planning-team/                # executor.md, reviewer.md, techlead.md
+│       ├── project-team/                 # executor.md, reviewer.md, techlead.md
+│       ├── qa-team/                      # executor.md, reviewer.md, techlead.md
+│       ├── report-team/                  # executor.md, reviewer.md, techlead.md
+│       ├── research-team/                # executor.md, reviewer.md, techlead.md
+│       └── security-team/                # executor.md, reviewer.md, techlead.md
+│
+├── cli/                                  # CLI tooling — the only executable code
+│   ├── install.js                        # Main CLI entry (~600 lines, CommonJS, shebang)
+│   ├── install.test.js.example           # Example test file (not active)
+│   └── README.md                         # CLI usage documentation
+│
+├── code-assistants/                      # Platform-specific installation templates
+│   ├── antigravity-assistant/            # Gemini/Antigravity platform assets
+│   │   ├── GEMINI.md                     # Antigravity-specific entry point
+│   │   └── AntigravityGlobal.agent.md    # Global agent config for Antigravity
+│   ├── claude-assistant/                 # Claude Code platform assets
+│   │   └── CLAUDE.md                     # Claude-specific entry point
+│   ├── codex-assistant/                  # Codex platform assets
+│   │   ├── CODEX.md                      # Codex-specific entry point
+│   │   ├── config.toml                   # Codex TOML configuration
+│   │   ├── agents/                       # Codex-specific agent TOML files
+│   │   └── skills/                       # Codex-specific skill overrides
+│   ├── copilot-assistant/                # GitHub Copilot platform assets
+│   │   └── agent-assistant.agent.md      # Copilot agent definition file
+│   └── cursor-assistant/                 # Cursor platform assets
+│       ├── .cursorrules                  # Cursor rules file (becomes CURSOR.md on install)
+│       └── rules/                        # Cursor MDC rule files
+│
+├── commands/                             # 14 command routers + variant subdirectories
+│   ├── ask.md                            # /ask command router
+│   ├── ask/                              # fast.md, hard.md (2 variants)
+│   ├── auto.md                           # /auto command router (no variants)
+│   ├── brainstorm.md                     # /brainstorm command router
+│   ├── brainstorm/                       # fast.md, hard.md, team.md (3 variants)
+│   ├── code.md                           # /code command router
+│   ├── code/                             # fast.md, hard.md, team.md (4 variants)
+│   ├── cook.md                           # /cook command router
+│   ├── cook/                             # fast.md, hard.md, team.md (4 variants)
+│   ├── debug.md                          # /debug command router
+│   ├── debug/                            # fast.md, hard.md, team.md (4 variants)
+│   ├── deploy.md                         # /deploy command router
+│   ├── deploy/                           # check.md, preview.md, production.md, rollback.md (4 variants)
+│   ├── design.md                         # /design command router
+│   ├── design/                           # fast.md, hard.md, team.md (4 variants)
+│   ├── docs.md                           # /docs command router
+│   ├── docs/                             # audit.md, business.md, core.md (3 variants)
+│   ├── fix.md                            # /fix command router
+│   ├── fix/                              # fast.md, hard.md, team.md (4 variants)
+│   ├── plan.md                           # /plan command router
+│   ├── plan/                             # fast.md, hard.md, team.md (4 variants)
+│   ├── report.md                         # /report command router
+│   ├── report/                           # fast.md, hard.md, team.md (4 variants)
+│   ├── review.md                         # /review command router
+│   ├── review/                           # fast.md, hard.md, team.md (3 variants)
+│   ├── test.md                           # /test command router
+│   └── test/                             # fast.md, hard.md, team.md (4 variants)
+│
+├── documents/                            # Project documentation
+│   ├── HSOL-ASSESSMENT.md                # Assessment of HSOL system
+│   ├── SMART-SKILL-ORCHESTRATION-BLUEPRINT.md  # HSOL design blueprint
+│   └── knowledge-source-base/            # Technical knowledge base (this folder)
+│
+├── matrix-skills/                        # HSOL domain skill registries (YAML)
+│   ├── _index.yaml                       # Central HSOL registry — config, discovery settings, domain listing
+│   ├── _dynamic.yaml                     # Community/dynamic skill manifest
+│   ├── ai-ml.yaml                        # AI/ML domain skills
+│   ├── architecture.yaml                 # Architecture domain skills
+│   ├── backend.yaml                      # Backend domain skills
+│   ├── cloud.yaml                        # Cloud infrastructure skills
+│   ├── data.yaml                         # Data engineering skills
+│   ├── design.yaml                       # Design domain skills
+│   ├── devops.yaml                       # DevOps domain skills
+│   ├── frontend.yaml                     # Frontend domain skills
+│   ├── gaming.yaml                       # Game development skills
+│   ├── languages.yaml                    # Programming language skills
+│   ├── management.yaml                   # Management domain skills
+│   ├── mcp.yaml                          # Model Context Protocol skills
+│   ├── mobile.yaml                       # Mobile development skills
+│   ├── performance.yaml                  # Performance domain skills
+│   ├── planning.yaml                     # Planning domain skills
+│   ├── quality.yaml                      # Quality/testing domain skills
+│   ├── research.yaml                     # Research domain skills
+│   ├── security.yaml                     # Security domain skills
+│   └── tools.yaml                        # Developer tooling skills
+│
+├── rules/                                # Orchestration protocol rules (7 files)
+│   ├── CORE.md                           # v4.1 — Orchestrator identity, paths, 10 Laws (always loaded first)
+│   ├── PHASES.md                         # Phase execution order and output format
+│   ├── AGENTS.md                         # Tiered execution: sub-agent (Tier 1) vs embodiment (Tier 2)
+│   ├── SKILLS.md                         # HSOL skill resolution protocol
+│   ├── TEAMS.md                          # Multi-agent team coordination protocol
+│   ├── ERRORS.md                         # Error recovery procedures
+│   └── REFERENCE.md                      # Quick lookup tables
+│
+├── skills/                               # 1,430 skill folders (each with SKILL.md)
+│   ├── 00-andruia-consultant/            # Example: Andruia consultant skill
+│   ├── 007/                              # Example: 007 skill
+│   ├── find-skills/                      # Special: dynamic skill discovery skill
+│   ├── ...                               # (1,427 more skill folders)
+│   └── {skill-name}/                     # Each contains at minimum a SKILL.md file
+│       └── SKILL.md                      # Skill definition, instructions, and metadata
+│
+├── web/                                  # Marketing website (independent sub-project)
+│   ├── package.json                      # React 19, Vite, Tailwind CSS 4, framer-motion
+│   ├── package-lock.json                 # Web dependency lock
+│   ├── vite.config.ts                    # Vite config with React + Tailwind plugins
+│   ├── tsconfig.json                     # Root TS config (references app + node configs)
+│   ├── tsconfig.app.json                 # App TS config — ES2022, bundler module resolution
+│   ├── tsconfig.node.json                # Node TS config for build tooling
+│   ├── eslint.config.js                  # ESLint v9 flat config with TS + React plugins
+│   ├── vercel.json                       # Vercel deployment: SPA rewrites
+│   ├── index.html                        # Vite HTML entry point
+│   ├── .gitignore                        # Web-specific ignores
+│   ├── .npmrc                            # npm registry config
+│   ├── public/                           # Static assets
+│   ├── src/                              # React source code
+│   │   ├── main.tsx                      # React app mount point
+│   │   ├── App.tsx                       # Root component with routing
+│   │   ├── components/                   # Reusable UI components
+│   │   ├── pages/                        # Page-level route components
+│   │   ├── hooks/                        # Custom React hooks
+│   │   ├── lib/                          # Utility libraries
+│   │   ├── data/                         # Static data/content
+│   │   ├── styles/                       # Global styles (Tailwind)
+│   │   └── types/                        # TypeScript type definitions
+│   ├── dist/                             # Build output (gitignored in web/.gitignore)
+│   └── reports/                          # Web-specific reports
+│
+└── node_modules/                         # Installed dependencies (gitignored)
+```
+
+---
+
+## Top-Level Directory Purposes
+
+### `agents/` — Specialist Agent Definitions
+Contains 21 solo agent Markdown files and a `teams/` subdirectory with 17 team directories. Each solo agent file defines a specialist role (backend-engineer, debugger, tester, etc.) with YAML frontmatter for Matrix Skill Discovery and structured sections for identity, capabilities, and workflow. Team directories each contain three standardized roles: `executor.md`, `reviewer.md`, and `techlead.md`. Total: 72 agent files.
+
+### `cli/` — Command-Line Interface
+The only directory containing executable code. Houses `install.js` (~600 lines, CommonJS, shebang `#!/usr/bin/env node`) that handles install/uninstall/list operations for all 5 supported platforms. Uses exclusively Node.js built-in modules (fs, path, os, readline). Also contains an example test file and a CLI-specific README.
+
+### `code-assistants/` — Platform Installation Templates
+Contains 5 subdirectories, one per supported AI coding tool. Each provides platform-specific assets (entry point files, config files, rule files) that are copied during installation. The CLI reads from these directories to customize the installation for each platform's directory structure and file conventions.
+
+### `commands/` — Command Workflows
+Contains 14 command router files (`.md`) at the top level and corresponding subdirectories with variant strategies. Standard variants are `fast.md`, `hard.md`, `team.md`; deploy uses `check.md`, `preview.md`, `production.md`, `rollback.md`; docs uses `audit.md`, `business.md`, `core.md`. The command router file defines the base workflow, and variants modify execution strategy. Total: 61 Markdown files.
+
+### `documents/` — Project Documentation
+Stores long-form project documentation including the HSOL design blueprint, HSOL assessment, and the knowledge source base (this folder). Files here are included in the npm package and copied during installation to `~/.{tool}/skills/agent-assistant/documents/`.
+
+### `matrix-skills/` — HSOL Domain Registries
+Contains 21 YAML files: `_index.yaml` (central registry with HSOL configuration and discovery settings), `_dynamic.yaml` (community-installed dynamic skills), and 19 domain-specific registries. Each domain YAML maps skills to agents by profile, priority, and relevance. The HSOL version is 1.1 with 1,430 total matrix skills.
+
+### `rules/` — Orchestration Protocol
+Seven Markdown files that define the Orchestrator's "operating system." `CORE.md` (v4.1) is always loaded first and establishes the Orchestrator's identity, path conventions, and the 10 Laws. Other files are loaded on-demand: PHASES (execution order), AGENTS (tiered execution), SKILLS (HSOL resolution), TEAMS (multi-agent coordination), ERRORS (recovery), REFERENCE (lookup tables).
+
+### `skills/` — Skill Library
+Contains 1,430 skill folders, each with at minimum a `SKILL.md` file. Skills are the atomic units of capability in the HSOL system — each defines instructions, context, and metadata for a specific technique or domain. The special `find-skills/` skill handles dynamic skill discovery from the external skills.sh registry.
+
+### `web/` — Marketing Website
+An independent React 19 + Vite + Tailwind CSS 4 sub-project with its own `package.json`, TypeScript configuration, and ESLint setup. Deployed to Vercel with SPA rewrite rules. Uses framer-motion for animations, react-router-dom for routing, lucide-react for icons, and @xyflow/react for flow diagrams. Has a standard `src/` layout with components, pages, hooks, lib, data, styles, and types directories.
+
+### `.husky/` — Git Hooks
+Husky v8 git hooks manager directory. Contains the internal `_/` runtime directory. Used with the `prepare` script (`husky install || true`) to set up commit hooks for the development workflow.
+
+---
+
+## Root File Purposes
+
+| File | Purpose |
+|------|---------|
+| `package.json` | npm package manifest — defines name, version, scripts, bin, engines, files, devDependencies |
+| `package-lock.json` | Locked dependency tree for reproducible installs |
+| `.releaserc.json` | semantic-release configuration — conventional commits preset, main branch, changelog + npm + git + github plugins |
+| `.gitignore` | Git exclusion rules — node_modules, dist, .env, reports/, coverage/, logs |
+| `LICENSE` | MIT license |
+| `README.md` | Project README — published with npm package, copied during installation |
+| `CHANGELOG.md` | Auto-generated by semantic-release — version history with conventional commit sections |
+| `AGENT.md` | Platform-agnostic Orchestrator entry point |
+| `AGENT-TEMPLATE.md` | Specification template for creating new agent files with Matrix Skill Discovery frontmatter |
+| `CLAUDE.md` | Claude Code platform entry point — bootstraps Orchestrator for Claude |
+| `CODEX.md` | Codex platform entry point — bootstraps Orchestrator for Codex |
+| `COPILOT.md` | GitHub Copilot platform entry point — bootstraps Orchestrator for Copilot |
+| `CURSOR.md` | Cursor platform entry point — bootstraps Orchestrator for Cursor |
+| `GEMINI.md` | Gemini/Antigravity platform entry point — bootstraps Orchestrator for Gemini |
+
+---
+
+## File Count Summary
+
+| Directory | Files (approx.) | Format |
+|-----------|-----------------|--------|
+| `agents/` (solo) | 21 | Markdown |
+| `agents/teams/` | 51 (17 × 3) | Markdown |
+| `cli/` | 3 | JavaScript, Markdown |
+| `code-assistants/` | ~10 | Markdown, TOML, rules |
+| `commands/` | 61 (14 routers + 47 variants) | Markdown |
+| `documents/` | 2 + knowledge-source-base | Markdown |
+| `matrix-skills/` | 21 | YAML |
+| `rules/` | 7 | Markdown |
+| `skills/` | 1,430+ | Markdown (SKILL.md each) |
+| `web/src/` | ~30+ | TypeScript, TSX, CSS |
+| Root files | 14 | Markdown, JSON |
+
+---
+
+## Evidence Sources
+
+| File | Why it was used |
+|------|-----------------|
+| `package.json` | Verified project name, version, scripts, bin, files, engines, devDependencies |
+| `cli/install.js` | Confirmed TOOLS config with 5 platforms, CORE_DIRS, BUNDLED_AGENTS list, ROOT_FILES |
+| `.releaserc.json` | Verified semantic-release plugin chain and branch config |
+| `.gitignore` | Confirmed exclusion rules for node_modules, dist, .env, reports |
+| `AGENT-TEMPLATE.md` | Verified agent file structure with Matrix Skill Discovery frontmatter |
+| `matrix-skills/_index.yaml` | Confirmed HSOL v1.1, 1,430 matrix skills, discovery config |
+| `rules/CORE.md` | Confirmed CORE v4.1, Orchestrator identity, path conventions |
+| `web/package.json` | Verified React 19 dependencies, Vite scripts |
+| `web/vite.config.ts` | Confirmed React + Tailwind plugins, chunk splitting |
+| `web/vercel.json` | Confirmed SPA rewrite rules for Vercel deployment |
+| `web/tsconfig.json` | Confirmed TS project references (app + node) |
+| `web/tsconfig.app.json` | Confirmed ES2022 target, bundler module resolution |
+| `web/eslint.config.js` | Confirmed ESLint v9 flat config with TS + React plugins |
+| `agents/` directory listing | Counted 21 solo agent files |
+| `agents/teams/` directory listing | Counted 17 team directories, each with 3 role files |
+| `commands/` directory listing | Counted 14 router files and all variant subdirectories |
+| `code-assistants/` directory listing | Confirmed 5 platform template directories and their contents |

package/documents/knowledge-source-base/02-entry-points.md

@@ -0,0 +1,346 @@
+# Agent Assistant — Entry Points
+
+> **Purpose**: Maps all application entry files, the CLI boot sequence, build/script entry points, and configuration entry points
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+1. [Application Entry Files](#application-entry-files)
+2. [CLI Boot Sequence](#cli-boot-sequence)
+3. [Platform Entry Points](#platform-entry-points)
+4. [Build and Script Entry Points](#build-and-script-entry-points)
+5. [Config Entry Points](#config-entry-points)
+6. [Web Application Entry Points](#web-application-entry-points)
+7. [Evidence Sources](#evidence-sources)
+
+---
+
+## Application Entry Files
+
+### Primary: `cli/install.js`
+
+This is the **sole executable file** in the entire project. It is declared in `package.json` under both `main` and `bin`:
+
+```json
+{
+  "main": "cli/install.js",
+  "bin": {
+    "agent-assistant": "./cli/install.js"
+  }
+}
+```
+
+- **Shebang**: `#!/usr/bin/env node`
+- **Module System**: CommonJS (`require()`)
+- **Dependencies**: Node.js built-ins only — `node:fs`, `node:path`, `node:os`, `node:readline`
+- **Size**: ~600 lines
+- **Minimum Runtime**: Node.js >=18.0.0
+
+When installed globally via `npm install -g @namch/agent-assistant`, the `agent-assistant` binary becomes available system-wide. When invoked via `npx`, it runs directly from the package.
+
+### Secondary: Platform Entry Point Files (Root)
+
+These 6 Markdown files serve as the "boot" files that AI coding assistants read to initialize the Orchestrator:
+
+| File | Platform | Role |
+|------|----------|------|
+| `AGENT.md` | All platforms | Generic/platform-agnostic Orchestrator entry |
+| `CURSOR.md` | Cursor | Cursor-specific Orchestrator bootstrap |
+| `COPILOT.md` | GitHub Copilot | Copilot-specific Orchestrator bootstrap |
+| `CLAUDE.md` | Claude Code | Claude-specific Orchestrator bootstrap |
+| `CODEX.md` | Codex | Codex-specific Orchestrator bootstrap |
+| `GEMINI.md` | Antigravity/Gemini | Gemini-specific Orchestrator bootstrap |
+
+These files are **not executed** — they are read by AI coding assistants as instruction/configuration files. Each directs the AI to load `rules/CORE.md` and activate the Orchestrator role.
+
+---
+
+## CLI Boot Sequence
+
+When the user runs any CLI command, execution follows this sequence:
+
+### 1. Invocation
+
+```bash
+# Direct invocation
+node cli/install.js <command> [tool] [flags]
+
+# Via npm scripts
+npm run install:cursor     # → node cli/install.js install cursor
+npm run install:all        # → node cli/install.js install --all
+npm run uninstall:copilot  # → node cli/install.js uninstall copilot
+npm run list               # → node cli/install.js list
+
+# Via npx (after npm publish)
+npx agent-assistant install cursor
+npx @namch/agent-assistant install --all
+```
+
+### 2. Module Loading
+
+```
+cli/install.js loads:
+├── node:fs        — File system operations (read, write, copy, remove, exists, sync)
+├── node:path      — Path resolution and manipulation
+├── node:os        — Home directory detection via os.homedir()
+└── node:readline  — Interactive terminal prompts (confirmation dialogs)
+```
+
+### 3. Configuration Resolution
+
+```
+HOME = os.homedir()                    # e.g., /Users/username
+ROOT = path.join(__dirname, '..')      # Project root (relative to cli/)
+
+TOOLS = {
+  cursor:       { paths, replacements, assets }
+  copilot:      { paths, replacements, assets }
+  antigravity:  { paths, replacements, assets }
+  claude:       { paths, replacements, assets }
+  codex:        { paths, replacements, assets }
+}
+
+CORE_DIRS = ['agents', 'rules', 'documents', 'commands', 'matrix-skills']
+ROOT_FILES = ['README.md']
+```
+
+### 4. Argument Parsing
+
+The CLI parses `process.argv` to determine:
+- **Command**: `install`, `uninstall`, or `list`
+- **Tool**: one of `cursor`, `copilot`, `antigravity`, `claude`, `codex`
+- **Flags**: `--all` (operate on all platforms), `--force` (skip confirmation)
+
+### 5. Command Execution
+
+#### Install Flow
+```
+resetProgress()
+  → estimateInstallFiles()        # Counts files across CORE_DIRS + skills + agents
+  → Per-platform install function:
+      1. Copy platform-specific assets (rules, entry points, agent files)
+      2. Clean install: remove old ~/.{tool}/skills/agent-assistant/
+      3. Copy CORE_DIRS to agentAssistant path
+      4. Copy commands also to "workflows" for backward compatibility
+      5. Copy ROOT_FILES (README.md)
+      6. Copy skills/ directory (1,430 skill folders)
+      7. Copy agents/ directory (for native subagent support)
+      8. Text file replacements: {TOOL} → platform name, {HOME} → ~, path macros
+  → completeProgress()
+  → verifyInstallation()           # Check all copied files exist on disk
+  → printSummary()                 # Statistics: files copied, duration, errors
+```
+
+#### Uninstall Flow
+```
+resetProgress()
+  → Remove agentAssistant directory
+  → Remove platform-specific config files
+  → completeProgress()
+  → printSummary()
+```
+
+#### List Flow
+```
+For each tool in TOOLS:
+  → Check if agentAssistant path exists
+  → Print status (installed / not installed)
+```
+
+### 6. Progress Tracking
+
+The CLI implements real-time progress tracking:
+- **TTY mode**: Single-line progress bar with `█░` characters, percentage, file count, elapsed time
+- **Non-TTY mode** (piped output): Milestone-based logging at 10% intervals
+- **Throttling**: Redraws max every 50ms or on percent change
+- **Verification phase**: After copy, validates all target files exist on disk
+- **Summary report**: Files copied, duration, verified count, errors
+
+---
+
+## Platform Entry Points
+
+Each platform has a unique installation target structure. The `TOOLS` config object in `cli/install.js` defines these:
+
+### Cursor
+```
+~/.cursor/
+├── rules/                    # Global MDC rule files (from code-assistants/cursor-assistant/rules/)
+├── commands/                 # Global command suggestions (from commands/)
+├── CURSOR.md                 # Platform entry (from code-assistants/cursor-assistant/.cursorrules)
+├── AGENT.md                  # Generic entry (from root AGENT.md)
+├── CLAUDE.md                 # Claude entry (from root CLAUDE.md)
+├── agents/                   # Native subagent support (from agents/)
+└── skills/
+    └── agent-assistant/      # Core framework
+        ├── agents/           # CORE_DIRS[0]
+        ├── rules/            # CORE_DIRS[1]
+        ├── documents/        # CORE_DIRS[2]
+        ├── commands/         # CORE_DIRS[3]
+        ├── matrix-skills/    # CORE_DIRS[4]
+        ├── workflows/        # Backward compat copy of commands/
+        └── README.md         # ROOT_FILES[0]
+```
+
+### GitHub Copilot
+```
+~/.copilot/
+├── skills/
+│   └── agent-assistant/      # Core framework (same structure as Cursor)
+├── commands/                 # Global commands
+├── agents/                   # Native subagents
+├── rules/                    # Global rules
+└── [VS Code prompts folder]  # Platform-specific prompt location
+    └── agent-assistant.agent.md  # Copilot agent definition
+```
+
+The VS Code prompts folder path varies by OS:
+- **macOS**: `~/Library/Application Support/Code/User/prompts/`
+- **Windows**: `%APPDATA%/Code/User/prompts/`
+- **Linux**: `~/.config/Code/User/prompts/`
+
+### Antigravity (Gemini)
+```
+~/.gemini/
+├── antigravity/
+│   ├── skills/
+│   │   └── agent-assistant/  # Core framework
+│   └── global_workflows/     # Global workflows
+├── agents/                   # Global agent configs
+│   └── AntigravityGlobal.agent.md
+└── GEMINI.md                 # Platform entry
+~/.antigravity/
+├── agents/                   # User-accessible agents
+└── workflows/                # User workflows
+```
+
+### Claude Code
+```
+~/.claude/
+├── skills/
+│   └── agent-assistant/      # Core framework
+├── commands/                 # Global commands
+├── agents/                   # Native subagents
+└── CLAUDE.md                 # Platform entry
+```
+
+### Codex
+```
+~/.codex/
+├── skills/
+│   └── agent-assistant/      # Core framework
+├── commands/                 # Global commands
+├── agents/                   # Native subagents (TOML format from code-assistants/codex-assistant/agents/)
+└── config.toml               # Codex config (from code-assistants/codex-assistant/config.toml)
+```
+
+---
+
+## Build and Script Entry Points
+
+All scripts are defined in the root `package.json`:
+
+### Installation Scripts
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `install:cursor` | `node cli/install.js install cursor` | Install framework for Cursor |
+| `install:copilot` | `node cli/install.js install copilot` | Install framework for Copilot |
+| `install:antigravity` | `node cli/install.js install antigravity` | Install framework for Antigravity |
+| `install:codex` | `node cli/install.js install codex` | Install framework for Codex |
+| `install:all` | `node cli/install.js install --all` | Install for all platforms |
+
+### Uninstall Scripts
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `uninstall:cursor` | `node cli/install.js uninstall cursor` | Uninstall from Cursor |
+| `uninstall:copilot` | `node cli/install.js uninstall copilot` | Uninstall from Copilot |
+| `uninstall:antigravity` | `node cli/install.js uninstall antigravity` | Uninstall from Antigravity |
+| `uninstall:codex` | `node cli/install.js uninstall codex` | Uninstall from Codex |
+| `uninstall:all` | `node cli/install.js uninstall --all` | Uninstall from all platforms |
+
+### Utility Scripts
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `list` | `node cli/install.js list` | Show installed platforms |
+| `test` | `node --test cli/*.test.js` | Run test files (Node.js built-in test runner) |
+| `lint` | `node --check cli/install.js && echo '✅ JavaScript syntax valid'` | Syntax check CLI |
+| `lint:md` | `echo 'Run: npx markdownlint ...'` | Markdown lint hint |
+| `semantic-release` | `semantic-release` | Automated version/publish |
+| `prepare` | `husky install \|\| true` | Git hooks setup (fails silently if husky not available) |
+
+### Web Scripts (in `web/package.json`)
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `dev` | `vite` | Start Vite dev server with HMR |
+| `build` | `tsc -b && vite build` | TypeScript check + production build |
+| `lint` | `eslint .` | Lint web sources |
+| `preview` | `vite preview` | Preview production build locally |
+
+---
+
+## Config Entry Points
+
+Configuration files that affect system behavior:
+
+| File | Loaded By | Purpose |
+|------|-----------|---------|
+| `package.json` | npm/node | Package manifest, scripts, bin, engines |
+| `.releaserc.json` | semantic-release | Release automation: branch `main`, conventional commits preset, plugins chain |
+| `.gitignore` | git | Exclusion rules |
+| `.husky/_/` | husky | Git hooks runtime |
+| `matrix-skills/_index.yaml` | HSOL (read by AI agents) | Central skill registry configuration, discovery settings |
+| `matrix-skills/_dynamic.yaml` | HSOL (read by AI agents) | Dynamic/community skill manifest |
+| `rules/CORE.md` | AI agents (always first) | Orchestrator protocol — paths, identity, laws |
+| `web/vite.config.ts` | Vite | Build configuration with React + Tailwind plugins |
+| `web/tsconfig.json` | TypeScript | Root TS config with project references |
+| `web/tsconfig.app.json` | TypeScript | App compilation: ES2022, bundler resolution, react-jsx |
+| `web/eslint.config.js` | ESLint v9 | Flat config with TS + React hooks + React refresh |
+| `web/vercel.json` | Vercel | Deployment config with SPA rewrites |
+
+---
+
+## Web Application Entry Points
+
+The web sub-project has its own entry chain:
+
+```
+web/index.html              # Vite HTML entry — contains <div id="root"> and <script type="module" src="/src/main.tsx">
+  └── web/src/main.tsx      # React app mount — ReactDOM.createRoot(document.getElementById('root'))
+      └── web/src/App.tsx   # Root component — routing, layout, providers
+          ├── web/src/pages/        # Route components
+          ├── web/src/components/   # Shared UI components
+          ├── web/src/hooks/        # Custom hooks
+          ├── web/src/lib/          # Utility functions
+          ├── web/src/data/         # Static content/data
+          ├── web/src/styles/       # Tailwind global styles
+          └── web/src/types/        # TypeScript definitions
+```
+
+Build output goes to `web/dist/` with manual chunk splitting:
+- `react-vendor` chunk: react, react-dom, react-router-dom
+- `animation-vendor` chunk: framer-motion
+
+---
+
+## Evidence Sources
+
+| File | Why it was used |
+|------|-----------------|
+| `package.json` | Verified `main`, `bin`, all scripts, engines, devDependencies |
+| `cli/install.js` (lines 1-30) | Confirmed shebang, CommonJS requires (fs, path, os, readline), JSDoc usage |
+| `cli/install.js` (lines 37-170) | Verified TOOLS config: 5 platforms with paths, replacements, assets |
+| `cli/install.js` (lines 172-190) | Confirmed CORE_DIRS, ROOT_FILES, BUNDLED_AGENTS constants |
+| `cli/install.js` (lines 460-600) | Verified install functions: progress tracking, copy logic, verification, summary |
+| `AGENT.md` | Confirmed platform-agnostic Orchestrator entry |
+| `CLAUDE.md` | Confirmed Claude-specific Orchestrator bootstrap with CORE.md load directive |
+| `rules/CORE.md` (lines 1-40) | Confirmed v4.1, mandatory first-load, Orchestrator identity, path templates |
+| `web/package.json` | Verified React 19, Vite, Tailwind, scripts (dev, build, lint, preview) |
+| `web/vite.config.ts` | Confirmed plugins (react, tailwindcss), manual chunk splitting |
+| `web/vercel.json` | Confirmed SPA rewrite rule: `/(.*) → /index.html` |
+| `web/index.html` | Confirmed Vite HTML entry structure |
+| `web/src/` directory listing | Confirmed App.tsx, main.tsx, components, pages, hooks, lib, data, styles, types |
+| `.releaserc.json` | Confirmed plugin chain: commit-analyzer, release-notes, changelog, npm, git, github |