@namch/agent-assistant 1.3.0 → 1.3.1

package/documents/knowledge-source-base/04-configuration.md

@@ -0,0 +1,467 @@
+# Agent Assistant — Configuration
+
+> **Purpose**: Complete inventory of all configuration files, environment variables, and secrets management across the framework and web sub-project
+> **Parent**: [00-index.md](./00-index.md)
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Root Package Configuration](#root-package-configuration)
+- [Release Configuration](#release-configuration)
+- [Git Configuration](#git-configuration)
+- [Git Hooks](#git-hooks)
+- [HSOL Configuration](#hsol-configuration)
+- [Web Application Configuration](#web-application-configuration)
+- [Platform-Specific Configuration](#platform-specific-configuration)
+- [Environment Variables](#environment-variables)
+- [Secrets Management](#secrets-management)
+- [Configuration Hierarchy](#configuration-hierarchy)
+- [Evidence Sources](#evidence-sources)
+
+---
+
+## Overview
+
+Agent Assistant uses two distinct configuration layers:
+
+1. **Tooling Config** — Standard Node.js/npm/Vite config files for building, linting, releasing, and deploying
+2. **Framework Config** — YAML and Markdown files that configure the AI orchestration behavior (HSOL, rules, agents)
+
+The project has zero production dependencies. All config files serve either the CLI installer, the release pipeline, or the marketing website.
+
+---
+
+## Root Package Configuration
+
+### package.json
+
+| Field | Value | Purpose |
+|-------|-------|---------|
+| `name` | `@namch/agent-assistant` | Scoped npm package name |
+| `version` | `1.3.0` | Current version (managed by semantic-release) |
+| `description` | Multi-agent orchestration framework... | npm registry description |
+| `main` | `cli/install.js` | Default module entry for `require()` |
+| `bin.agent-assistant` | `./cli/install.js` | CLI binary name for `npx` invocation |
+| `engines.node` | `>=18.0.0` | Minimum Node.js version constraint |
+| `license` | `MIT` | Open source license |
+| `author` | `NamCH` | Package author |
+| `publishConfig.access` | `public` | npm publish visibility |
+
+### files Array (Published Contents)
+
+Defines exactly what gets included in the npm tarball:
+
+```json
+[
+  "cli/",
+  "agents/",
+  "commands/",
+  "rules/",
+  "matrix-skills/",
+  "skills/",
+  "documents/",
+  "code-assistants/",
+  "LICENSE",
+  "README.md",
+  "CHANGELOG.md"
+]
+```
+
+**Notably excluded** from npm package:
+- `web/` — Marketing site (independent deployment)
+- `AGENT.md`, `CLAUDE.md`, `COPILOT.md`, `CURSOR.md`, `CODEX.md`, `GEMINI.md` — Root platform files (exist in repo but only the `code-assistants/` versions are published)
+- `AGENT-TEMPLATE.md` — Developer reference only
+- `.releaserc.json`, `.husky/`, `.gitignore` — Development tooling
+
+### scripts
+
+| Script | Command | Category |
+|--------|---------|----------|
+| `install:cursor` | `node cli/install.js install cursor` | Platform install |
+| `install:copilot` | `node cli/install.js install copilot` | Platform install |
+| `install:antigravity` | `node cli/install.js install antigravity` | Platform install |
+| `install:codex` | `node cli/install.js install codex` | Platform install |
+| `install:all` | `node cli/install.js install --all` | Batch install |
+| `uninstall:cursor` | `node cli/install.js uninstall cursor` | Platform uninstall |
+| `uninstall:copilot` | `node cli/install.js uninstall copilot` | Platform uninstall |
+| `uninstall:antigravity` | `node cli/install.js uninstall antigravity` | Platform uninstall |
+| `uninstall:codex` | `node cli/install.js uninstall codex` | Platform uninstall |
+| `uninstall:all` | `node cli/install.js uninstall --all` | Batch uninstall |
+| `list` | `node cli/install.js list` | Status check |
+| `test` | `node --test cli/*.test.js` | Testing |
+| `lint` | `node --check cli/install.js && echo '✅ JavaScript syntax valid'` | Syntax validation |
+| `lint:md` | `echo 'Run: npx markdownlint ...'` | Informational |
+| `semantic-release` | `semantic-release` | Release automation |
+| `prepare` | `husky install \|\| true` | Git hooks setup |
+
+### devDependencies
+
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `@semantic-release/changelog` | ^6.0.3 | Generate CHANGELOG.md entries |
+| `@semantic-release/commit-analyzer` | ^11.1.0 | Analyze commits for version bumps |
+| `@semantic-release/exec` | ^6.0.3 | Execute custom commands during release |
+| `@semantic-release/git` | ^10.0.1 | Commit version files back to repo |
+| `@semantic-release/github` | ^9.2.6 | Create GitHub releases |
+| `@semantic-release/npm` | ^11.0.2 | Publish to npm registry |
+| `@semantic-release/release-notes-generator` | ^12.1.0 | Generate release notes from commits |
+| `conventional-changelog-conventionalcommits` | ^7.0.2 | Conventional commits changelog preset |
+| `husky` | ^8.0.3 | Git hooks framework |
+| `semantic-release` | ^22.0.12 | Core release automation engine |
+
+---
+
+## Release Configuration
+
+### .releaserc.json
+
+**Branch**: `main` (single release branch)
+
+**Plugin Pipeline** (executed in order):
+
+| Step | Plugin | Configuration |
+|------|--------|---------------|
+| 1. Analyze | `@semantic-release/commit-analyzer` | Preset: `conventionalcommits` |
+| 2. Notes | `@semantic-release/release-notes-generator` | Preset: `conventionalcommits` with section grouping |
+| 3. Changelog | `@semantic-release/changelog` | Output: `CHANGELOG.md` |
+| 4. npm | `@semantic-release/npm` | Publishes to npm (uses `publishConfig.access: public`) |
+| 5. Git | `@semantic-release/git` | Commits `CHANGELOG.md` + `package.json`, message: `chore(release): ${nextRelease.version} [skip ci]` |
+| 6. GitHub | `@semantic-release/github` | Creates GitHub release with notes |
+
+**Release Rules**:
+
+| Commit Type | Release | Changelog Section |
+|-------------|---------|-------------------|
+| `feat` | minor | Features |
+| `fix` | patch | Bug Fixes |
+| `perf` | patch | Performance |
+| `refactor` | patch | Refactoring |
+| `docs` (scope: README) | patch | Documentation |
+| `chore` | none | (hidden) |
+| `style` | none | (hidden) |
+| `test` | none | (hidden) |
+| `breaking: true` | **major** | (in respective section) |
+
+---
+
+## Git Configuration
+
+### .gitignore
+
+```gitignore
+# Build outputs
+out
+dist
+*.vsix
+.vscode-test
+
+# Dependencies
+node_modules
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Environment files
+.env
+.env.*
+!.env.example
+
+# Generated reports (user-specific)
+reports/
+
+# Logs
+*.log
+npm-debug.log*
+
+# Coverage
+coverage/
+.nyc_output/
+```
+
+Key exclusions:
+- `.env` and `.env.*` (except `.env.example`) — prevents secrets from being committed
+- `reports/` — user-generated report output from commands like `/report`
+- `dist/` — build artifacts
+- `node_modules/` — dependencies
+
+---
+
+## Git Hooks
+
+### .husky/
+
+The `.husky/` directory contains a `_/` subdirectory (husky internal). The `prepare` script in `package.json` runs `husky install || true` with `|| true` to gracefully handle CI environments where husky installation is not needed.
+
+---
+
+## HSOL Configuration
+
+### matrix-skills/_index.yaml
+
+The central config for the Hybrid Skill Orchestration Layer:
+
+| Key | Value | Purpose |
+|-----|-------|---------|
+| `version` | `"1.1"` | HSOL protocol version |
+| `last_updated` | `"2026-01-30"` | Last registry update date |
+| `total_matrix_skills` | `1430` | Total curated skills across all domains |
+| `hsol.enabled` | `true` | HSOL is active |
+| `hsol.version` | `"1.1"` | HSOL engine version |
+| `hsol.find_skills.skill_path` | `"{SKILLS_PATH}/find-skills/SKILL.md"` | Path to discovery skill |
+| `hsol.find_skills.browse_url` | `"https://skills.sh/"` | External skill marketplace URL |
+| `hsol.find_skills.cli_commands.search` | `"npx skills find [query]"` | Search for skills |
+| `hsol.find_skills.cli_commands.install` | `"npx skills add <owner/repo@skill> -g -y"` | Install skill globally for current tool |
+| `hsol.find_skills.cli_commands.check` | `"npx skills check"` | Check installed skills |
+| `hsol.find_skills.cli_commands.update` | `"npx skills update"` | Update installed skills |
+| `hsol.dynamic_manifest` | `"_dynamic.yaml"` | Dynamic skill manifest file |
+| `hsol.discovery.enabled` | `true` | Dynamic discovery is active |
+| `hsol.discovery.timeout_ms` | `5000` | Discovery request timeout |
+| `hsol.discovery.cache_ttl_seconds` | `3600` | Cache duration (1 hour) |
+| `hsol.discovery.async_threshold` | `0.8` | Skip discovery if matrix fitness exceeds this |
+| `hsol.discovery.apply_for_variants` | `["hard", "focus"]` | Only run discovery for these variants; `fast` skips it |
+
+### matrix-skills/_dynamic.yaml
+
+Community-installed skill manifest. Populated via `npx skills add` commands. Not pre-filled in the repository.
+
+### 19 Domain Registry Files
+
+Each domain YAML file maps a set of skills from the `skills/` directory with priority and relevance metadata. Domains: `ai-ml`, `architecture`, `backend`, `cloud`, `data`, `design`, `devops`, `frontend`, `gaming`, `languages`, `management`, `mcp`, `mobile`, `performance`, `planning`, `quality`, `research`, `security`, `tools`.
+
+---
+
+## Web Application Configuration
+
+### web/package.json
+
+| Field | Value |
+|-------|-------|
+| `name` | `web` |
+| `private` | `true` |
+| `version` | `0.0.0` |
+| `type` | `module` (ESM) |
+
+**Scripts**:
+| Script | Command |
+|--------|---------|
+| `dev` | `vite` |
+| `build` | `tsc -b && vite build` |
+| `lint` | `eslint .` |
+| `preview` | `vite preview` |
+
+### web/vite.config.ts
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    target: 'esnext',
+    minify: 'esbuild',
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'react-vendor': ['react', 'react-dom', 'react-router-dom'],
+          'animation-vendor': ['framer-motion'],
+        }
+      }
+    }
+  },
+  // ... resolve.alias config
+})
+```
+
+**Key settings**:
+- **Build target**: `esnext` (modern browsers only)
+- **Minifier**: `esbuild` (fastest)
+- **Code splitting**: Two manual chunks to optimize caching
+
+### web/tsconfig.json
+
+Project references configuration:
+```json
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
+```
+
+### web/tsconfig.app.json
+
+| Option | Value | Purpose |
+|--------|-------|---------|
+| `target` | `ES2022` | Output JavaScript version |
+| `module` | `ESNext` | Module system |
+| `moduleResolution` | `bundler` | Vite-compatible resolution |
+| `jsx` | `react-jsx` | React 19 JSX transform |
+| `lib` | `["ES2022", "DOM", "DOM.Iterable"]` | Type libraries |
+| `noEmit` | `true` | Type-check only (Vite handles output) |
+| `types` | `["vite/client"]` | Vite-specific type definitions |
+| `verbatimModuleSyntax` | `true` | Strict import/export syntax |
+
+### web/eslint.config.js
+
+ESLint v9 flat config:
+- Extends: `@eslint/js` recommended, `typescript-eslint` recommended
+- Plugins: `eslint-plugin-react-hooks` (flat recommended), `eslint-plugin-react-refresh` (vite config)
+- Global ignores: `dist/`
+- File pattern: `**/*.{ts,tsx}`
+- ECMAScript version: 2020
+- Globals: `browser`
+
+### web/vercel.json
+
+```json
+{
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
+```
+
+SPA fallback — all routes rewrite to `index.html` for client-side routing.
+
+---
+
+## Platform-Specific Configuration
+
+### Codex: config.toml
+
+Located at `code-assistants/codex-assistant/config.toml`. TOML-format configuration specific to the OpenAI Codex CLI. Installed to `~/.codex/` during setup.
+
+### Cursor: .cursorrules
+
+Located at `code-assistants/cursor-assistant/.cursorrules`. Cursor's native rules format. During installation, this file is transformed and installed as `CURSOR.md` in `~/.cursor/`.
+
+### Cursor: rules/ directory
+
+Located at `code-assistants/cursor-assistant/rules/`. Contains MDC (Markdown Cursor) files installed to `~/.cursor/rules/` for Cursor's native rule system.
+
+### Copilot: agent-assistant.agent.md
+
+Located at `code-assistants/copilot-assistant/agent-assistant.agent.md`. Installed to the VS Code prompts folder:
+- **macOS**: `~/Library/Application Support/Code/User/prompts/`
+- **Windows**: `%APPDATA%/Code/User/prompts/`
+- **Linux**: `~/.config/Code/User/prompts/`
+
+---
+
+## Environment Variables
+
+### CLI Environment
+
+The CLI (`cli/install.js`) uses no environment variables for core functionality. All paths are derived from:
+- `os.homedir()` — User home directory
+- `__dirname` — Script location (resolves to project root via `path.join(__dirname, '..')`)
+- `process.platform` — OS detection for VS Code prompts path (`win32`, `darwin`, default)
+
+One optional debug variable:
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DEBUG` | undefined | When set, enables verbose logging of symlink skips and copy errors |
+
+### Web Application Environment
+
+The `web/` directory has `.env` and `.env.*` excluded via `.gitignore`. No `.env.example` file exists in the repository. Vercel-specific environment variables may be configured in the Vercel dashboard but are not tracked in the repo.
+
+### CI/CD Environment
+
+semantic-release requires these environment variables (set in CI, not in repo):
+| Variable | Purpose |
+|----------|---------|
+| `NPM_TOKEN` | npm registry authentication for publishing |
+| `GITHUB_TOKEN` | GitHub API authentication for release creation |
+| `GH_TOKEN` | Alternative to GITHUB_TOKEN (semantic-release convention) |
+
+---
+
+## Secrets Management
+
+### Approach: No Secrets in Repository
+
+The project follows a "no secrets" approach:
+- `.gitignore` excludes `.env` and `.env.*` files
+- CLI uses no API keys, tokens, or secrets at runtime
+- All CI/CD secrets are managed via the CI platform's secret management (GitHub Actions environment variables)
+- The only sensitive values are `NPM_TOKEN` and `GITHUB_TOKEN`/`GH_TOKEN` for the release pipeline
+
+### Secret Locations
+
+| Secret | Where It Lives | Used By |
+|--------|---------------|---------|
+| npm auth token | CI platform (GitHub Actions secrets) | `semantic-release` npm publish |
+| GitHub token | CI platform (auto-provided `GITHUB_TOKEN` or manual `GH_TOKEN`) | `semantic-release` GitHub release + git push |
+
+---
+
+## Configuration Hierarchy
+
+```
+package.json                    ← Root package config
+├── .releaserc.json             ← Release pipeline (references package.json)
+├── .gitignore                  ← Git exclusions
+├── .husky/                     ← Git hooks
+│
+├── matrix-skills/_index.yaml   ← HSOL master config
+│   ├── matrix-skills/_dynamic.yaml  ← Dynamic skills manifest
+│   └── matrix-skills/*.yaml         ← 19 domain registries
+│
+├── rules/CORE.md               ← Orchestrator protocol (uses {TOOL} from install)
+│   ├── rules/PHASES.md
+│   ├── rules/AGENTS.md
+│   ├── rules/SKILLS.md
+│   ├── rules/TEAMS.md
+│   ├── rules/ERRORS.md
+│   └── rules/REFERENCE.md
+│
+├── code-assistants/*/          ← Platform-specific configs
+│   ├── cursor: .cursorrules, rules/
+│   ├── copilot: agent-assistant.agent.md
+│   ├── antigravity: GEMINI.md, AntigravityGlobal.agent.md
+│   ├── claude: CLAUDE.md
+│   └── codex: CODEX.md, config.toml, agents/, skills/
+│
+└── web/                        ← Independent web config
+    ├── package.json
+    ├── vite.config.ts
+    ├── tsconfig.json → tsconfig.app.json, tsconfig.node.json
+    ├── eslint.config.js
+    └── vercel.json
+```
+
+---
+
+## Evidence Sources
+
+| File | Why it was used |
+|------|-----------------|
+| `package.json` | All root package fields: name, version, main, bin, engines, scripts, files, devDependencies, publishConfig |
+| `.releaserc.json` | Full release pipeline configuration: branch, plugins, release rules, changelog sections |
+| `.gitignore` | Complete exclusion patterns |
+| `.husky/` listing | Git hooks directory structure |
+| `cli/install.js` (lines 31–170) | TOOLS config: platform paths, replacements, assets; getVSCodePromptsFolder() for cross-platform VS Code paths |
+| `cli/install.js` (lines 171–210) | CORE_DIRS, ROOT_FILES constants |
+| `matrix-skills/_index.yaml` | HSOL v1.1 full configuration: enabled flag, version, find_skills, discovery settings |
+| `web/package.json` | Web app package fields: name, private, version, type, scripts, dependencies, devDependencies |
+| `web/vite.config.ts` | Vite plugins, build target, minifier, manual chunks |
+| `web/tsconfig.json` | Project references |
+| `web/tsconfig.app.json` | TypeScript compiler options: target, module, jsx, moduleResolution |
+| `web/eslint.config.js` | ESLint v9 flat config: plugins, extends, file patterns, globals |
+| `web/vercel.json` | SPA rewrite rules |
+| `code-assistants/cursor-assistant/` listing | Cursor-specific assets |
+| `code-assistants/copilot-assistant/` listing | Copilot-specific assets |
+| `code-assistants/antigravity-assistant/` listing | Antigravity-specific assets |
+| `code-assistants/claude-assistant/` listing | Claude-specific assets |
+| `code-assistants/codex-assistant/` listing | Codex-specific assets with TOML and subdirectories |
+| `rules/CORE.md` | Platform resolution table for {TOOL} placeholder mapping |

package/documents/knowledge-standards/00-index.md

@@ -0,0 +1,129 @@
+# Knowledge Standards
+
+> **Purpose**: Standards summary, table of contents, quick reference of naming conventions, cross-references, and known gaps for the Agent Assistant project
+> **Last Updated**: 2026-03-26
+> **Generated By**: docs-core skill
+
+---
+
+## Quick Summary
+
+Agent Assistant (`@namch/agent-assistant` v1.3.0) enforces a lean set of standards primarily through convention and tooling defaults rather than exhaustive configuration. The project uses Conventional Commits via semantic-release for versioning and publishing, Husky for git hooks, and Node.js built-in syntax checking for the CLI. The web sub-project adds ESLint 9 and TypeScript. There is no project-wide formatter (no Prettier), no CI/CD pipeline, no commitlint, no lint-staged, no editorconfig, and no test coverage tooling. Standards are largely implicit — derived from observed naming patterns, directory structure conventions, and YAML frontmatter schemas repeated consistently across hundreds of agent and command files.
+
+---
+
+## Table of Contents
+
+1. [Quick Summary](#quick-summary)
+2. [Sub-Files](#sub-files)
+3. [Quick Reference — Naming Conventions](#quick-reference--naming-conventions)
+4. [Quick Facts](#quick-facts)
+5. [Cross-References](#cross-references)
+6. [Known Gaps](#known-gaps)
+
+---
+
+## Sub-Files
+
+| # | File | Description |
+|---|------|-------------|
+| 1 | [01-code-style.md](./01-code-style.md) | Formatting rules, naming conventions by content type (Markdown, YAML, JS, TSX), observed patterns |
+| 2 | [02-conventions.md](./02-conventions.md) | File/directory organization, YAML frontmatter schemas, import patterns, module structure, document numbering |
+| 3 | [03-git-workflow.md](./03-git-workflow.md) | Conventional Commits format, semantic-release pipeline, branch naming, Husky hooks, release process |
+| 4 | [04-testing-standards.md](./04-testing-standards.md) | Test file organization, Node built-in test runner usage, coverage status, what exists vs what is missing |
+
+---
+
+## Quick Reference — Naming Conventions
+
+| Content Type | Pattern | Examples |
+|-------------|---------|----------|
+| Agent files | kebab-case `.md` | `backend-engineer.md`, `tech-lead.md` |
+| Team directories | kebab-case dirs | `agents/teams/backend-team/` |
+| Team role files | lowercase `.md` (fixed names) | `techlead.md`, `executor.md`, `reviewer.md` |
+| Command files | kebab-case `.md` | `cook.md`, `brainstorm.md` |
+| Command variants | kebab-case in subdirs | `commands/cook/fast.md`, `commands/cook/hard.md` |
+| Rule files | UPPER_CASE `.md` | `CORE.md`, `PHASES.md`, `AGENTS.md` |
+| Skill directories | kebab-case dirs | `skills/find-skills/`, `skills/ab-test-setup/` |
+| Matrix skill files | kebab-case `.yaml` | `backend.yaml`, `ai-ml.yaml` |
+| Special matrix files | underscore prefix `.yaml` | `_index.yaml`, `_dynamic.yaml` |
+| Platform entries | UPPER_CASE `.md` | `CLAUDE.md`, `COPILOT.md`, `CURSOR.md` |
+| Code assistant dirs | kebab-case dirs | `cursor-assistant/`, `copilot-assistant/` |
+| Document directories | kebab-case dirs | `knowledge-overview/`, `knowledge-standards/` |
+| Document files | numbered prefix + kebab-case | `00-index.md`, `01-project-identity.md` |
+| Web components | PascalCase `.tsx` | `App.tsx` |
+| Web entry points | camelCase `.tsx` | `main.tsx` |
+| CLI source | camelCase `.js` | `install.js` |
+| CLI test files | camelCase `.test.js` | `install.test.js.example` |
+
+---
+
+## Quick Facts
+
+| Standard | Status | Enforced By |
+|----------|--------|-------------|
+| Conventional Commits | Active | semantic-release commit-analyzer |
+| Semantic Versioning | Active | semantic-release |
+| Git Hooks | Active | Husky ^8.0.3 |
+| JS Syntax Check | Active | `node --check` (lint script) |
+| ESLint (web only) | Active | ESLint ^9.39.1 + typescript-eslint |
+| TypeScript (web only) | Active | TypeScript compiler via tsconfig |
+| Markdown Linting | Suggested, not enforced | `lint:md` script is echo-only |
+| Prettier / Formatter | Not configured | — |
+| CI/CD Pipeline | Not configured | — |
+| commitlint | Not configured | — |
+| lint-staged | Not configured | — |
+| editorconfig | Not configured | — |
+| Test Coverage | Not configured | — |
+| Containerization | Not configured | — |
+
+---
+
+## Cross-References
+
+| Resource | Path | Relationship |
+|----------|------|-------------|
+| Knowledge Overview | [../knowledge-overview/00-index.md](../knowledge-overview/00-index.md) | Project summary and tech stack |
+| Knowledge Architecture | [../knowledge-architecture/00-index.md](../knowledge-architecture/00-index.md) | System architecture and design |
+| Knowledge Source Base | [../knowledge-source-base/00-index.md](../knowledge-source-base/00-index.md) | Directory structure and key modules |
+| Knowledge Domain | [../knowledge-domain/00-index.md](../knowledge-domain/00-index.md) | Domain model and business logic |
+| Package Manifest | [../../package.json](../../package.json) | Scripts, dependencies, engine requirements |
+| Release Config | [../../.releaserc.json](../../.releaserc.json) | semantic-release plugin chain and rules |
+| Git Ignore | [../../.gitignore](../../.gitignore) | Excluded paths and patterns |
+| Core Rules | [../../rules/CORE.md](../../rules/CORE.md) | Orchestrator protocol and governance laws |
+| Web ESLint Config | [../../web/eslint.config.js](../../web/eslint.config.js) | ESLint 9 flat config for web sub-project |
+
+---
+
+## Known Gaps
+
+These are documented absences — not recommendations. They reflect the current state of the project as of v1.3.0.
+
+| Gap | Impact | Notes |
+|-----|--------|-------|
+| No CI/CD pipeline | Releases depend on local `npx semantic-release` execution; no automated PR checks | No `.github/workflows/` directory exists |
+| No Prettier or formatter | Code style consistency relies entirely on developer discipline | No `.prettierrc`, no formatting script |
+| No commitlint | Commit message format is only validated at release time by semantic-release, not at commit time | semantic-release will skip unrecognized types silently |
+| No lint-staged | No pre-commit hook runs linters on staged files | Husky is installed but no lint-staged integration |
+| No editorconfig | No cross-editor formatting defaults (indent size, charset, line endings) | No `.editorconfig` file |
+| No test coverage tool | No way to measure or enforce code coverage thresholds | No nyc, c8, or istanbul configured |
+| No integration/e2e tests | Only unit-level test examples exist; no end-to-end testing of the install flow | Test file is an example (`.example` extension) |
+| No Dockerfile | No containerization support | Not applicable for current use case (CLI tool + static site) |
+| Markdown linting is advisory | `lint:md` script only echoes a suggestion; does not actually run markdownlint | Would need `npx markdownlint` to be wired in |
+
+---
+
+## Evidence Sources
+
+| Source | Path |
+|--------|------|
+| Package manifest | [../../package.json](../../package.json) |
+| Release configuration | [../../.releaserc.json](../../.releaserc.json) |
+| Git ignore patterns | [../../.gitignore](../../.gitignore) |
+| Husky directory | `../../.husky/` |
+| Web ESLint config | [../../web/eslint.config.js](../../web/eslint.config.js) |
+| Agent file examples | [../../agents/backend-engineer.md](../../agents/backend-engineer.md) |
+| Command file examples | [../../commands/cook.md](../../commands/cook.md) |
+| CLI source | [../../cli/install.js](../../cli/install.js) |
+| Example test file | [../../cli/install.test.js.example](../../cli/install.test.js.example) |
+| Rule files | `../../rules/CORE.md`, `../../rules/PHASES.md` |