arkaos 2.0.0-alpha.1

package/departments/dev/skills/db-design/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/db-design
+description: >
+  Database design: schema, normalization, indexes, RLS policies, migration planning.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Db Design — `/dev db <action>`
+
+> **Agent:** Vasco (DBA) | **Framework:** Normalization + Indexing Best Practices
+
+## What It Does
+
+Database design: schema, normalization, indexes, RLS policies, migration planning.
+
+## Output
+
+ERD diagram, migration scripts, index strategy, RLS policy definitions

package/departments/dev/skills/db-schema/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dev/db-schema
+description: >
+  Design database schemas with normalization, indexing, migrations,
+  RLS policies, ERD generation, and cross-cutting concerns.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# DB Schema — `/dev db-schema <feature>`
+
+> **Agent:** Andre (Backend Dev) | **Framework:** Relational Schema Design + Laravel Conventions
+
+## Schema Design Process
+
+1. **Requirements -> Entities** -- extract nouns as candidate tables
+2. **Identify Relationships** -- 1:1, 1:N, M:N (junction tables)
+3. **Add Cross-cutting Concerns** -- see table below
+4. **Normalize** -- at least 3NF, denormalize only with measured need
+5. **Index Strategy** -- foreign keys, frequent WHERE/ORDER columns
+6. **Generate Migration** -- framework-specific migration code
+7. **Generate ERD** -- Mermaid diagram from schema
+
+## Cross-cutting Concerns
+
+| Concern | Implementation | When |
+|---------|---------------|------|
+| **Timestamps** | `created_at`, `updated_at` | Every table (NON-NEGOTIABLE) |
+| **Soft deletes** | `deleted_at TIMESTAMPTZ` | Auditable data (orders, users) |
+| **Multi-tenancy** | `organization_id` FK on all tenant-scoped tables | SaaS applications |
+| **Audit trail** | `created_by`, `updated_by` + audit log table | Regulated domains |
+| **Optimistic locking** | `version INTEGER` column | Concurrent update scenarios |
+| **Public IDs** | UUID/CUID for URLs/APIs, auto-increment internal | Public-facing resources |
+
+## Index Strategy
+
+| Index Type | When to Use | Example |
+|-----------|------------|---------|
+| **Single column** | FK columns, frequent WHERE | `INDEX idx_tasks_project_id ON tasks(project_id)` |
+| **Composite** | Multi-column WHERE clauses | `INDEX idx_tasks_org_status ON tasks(org_id, status)` |
+| **Partial** | Filtered queries on subset | `WHERE deleted_at IS NULL` |
+| **Covering** | Avoid table lookups | Include all SELECT columns in index |
+| **Unique** | Business key enforcement | `UNIQUE(org_id, slug)` |
+
+## Normalization Quick Reference
+
+| Form | Rule | Violation Example |
+|------|------|------------------|
+| **1NF** | Atomic values, no repeating groups | `tags: "a,b,c"` in one column |
+| **2NF** | No partial dependency on composite PK | Non-key depends on part of PK |
+| **3NF** | No transitive dependency | `city` depends on `zip`, not PK |
+
+Denormalize only when: measured query performance requires it AND read/write ratio justifies it.
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Soft delete without partial index | Add `WHERE deleted_at IS NULL` index |
+| Missing composite indexes | Profile queries, add composite for multi-column WHERE |
+| Mutable surrogate keys (email as PK) | Use UUID/CUID, keep email as unique constraint |
+| NOT NULL column without default on existing table | Provide default or multi-step migration |
+| No optimistic locking | Add `version` column for concurrent writes |
+| RLS not tested | Always test with non-superuser role |
+
+## Laravel Migration Convention
+
+```php
+Schema::create('tasks', function (Blueprint $table) {
+    $table->id();
+    $table->uuid('uuid')->unique();
+    $table->foreignId('project_id')->constrained()->cascadeOnDelete();
+    $table->foreignId('created_by_id')->constrained('users');
+    $table->string('title');
+    $table->text('description')->nullable();
+    $table->string('status')->default('todo');
+    $table->string('priority')->default('medium');
+    $table->integer('position')->default(0);
+    $table->integer('version')->default(1);
+    $table->timestamps();
+    $table->softDeletes();
+
+    $table->index(['project_id', 'status']);
+    $table->index(['created_by_id']);
+});
+```
+
+## ERD Output (Mermaid)
+
+```mermaid
+erDiagram
+    User ||--o{ Project : owns
+    Project ||--o{ Task : contains
+    Task }o--o{ Label : "tagged with"
+    Task ||--o{ Comment : has
+```
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Table with >20 columns → suggest normalization
+- Missing index on foreign key → flag query performance
+- No soft delete on user-facing data → flag compliance risk
+
+## Output
+
+```markdown
+## Schema Design: <Feature Name>
+
+### Entities
+| Table | Purpose | Key Columns |
+|-------|---------|------------|
+| ... | ... | ... |
+
+### Relationships
+| From | To | Type | FK |
+|------|-----|------|-----|
+| ... | ... | 1:N | ... |
+
+### Indexes
+| Table | Columns | Type | Reason |
+|-------|---------|------|--------|
+| ... | ... | composite | ... |
+
+### Migration
+<Laravel migration code>
+
+### ERD
+<Mermaid diagram>
+```

package/departments/dev/skills/ddd-model/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/ddd-model
+description: >
+  Domain-Driven Design modeling: bounded contexts, aggregates, domain events, context mapping, ubiquitous language.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Ddd Model — `/dev ddd <domain>`
+
+> **Agent:** Gabriel (Architect) | **Framework:** DDD (Eric Evans / Vaughn Vernon)
+
+## What It Does
+
+Domain-Driven Design modeling: bounded contexts, aggregates, domain events, context mapping, ubiquitous language.
+
+## Output
+
+DDD model with bounded context map, aggregate definitions, and domain event catalog

package/departments/dev/skills/dependency-audit/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dev/dependency-audit
+description: >
+  Audit project dependencies for vulnerabilities, license compliance, outdated packages, and supply chain risks.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Dependency Audit — `/dev dependency-audit`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** OWASP Supply Chain Security, SemVer
+
+## Audit Scope
+
+| Check | What | Tools |
+|-------|------|-------|
+| **Vulnerabilities** | Known CVEs in direct and transitive deps | `npm audit`, `composer audit`, `pip-audit`, `cargo audit` |
+| **Licenses** | Incompatible or copyleft licenses | `license-checker`, manifest inspection |
+| **Outdated** | Packages behind latest stable version | `npm outdated`, `composer outdated` |
+| **Unused** | Declared but never imported | `depcheck`, import analysis |
+| **Maintenance** | Abandoned or unmaintained packages | Last release date, commit activity |
+
+## Vulnerability Scanning
+
+Run these per ecosystem:
+
+| Ecosystem | Command | Lock File |
+|-----------|---------|-----------|
+| Node.js | `npm audit --production` | package-lock.json |
+| PHP | `composer audit` | composer.lock |
+| Python | `pip-audit` | requirements.txt / poetry.lock |
+| Go | `govulncheck ./...` | go.sum |
+| Rust | `cargo audit` | Cargo.lock |
+
+**Severity classification:**
+- **Critical/High** -- Fix before next deploy
+- **Medium** -- Fix within current sprint
+- **Low** -- Fix within next 30 days
+
+## License Compliance Matrix
+
+| License | Type | Commercial Use | Distribution Risk |
+|---------|------|---------------|-------------------|
+| MIT, ISC, BSD-2, BSD-3 | Permissive | Safe | None |
+| Apache 2.0 | Permissive | Safe | Patent clause |
+| MPL 2.0, LGPL | Weak copyleft | Caution | File-level copyleft |
+| GPL v2/v3 | Strong copyleft | Risk | Entire project must be GPL |
+| AGPL v3 | Network copyleft | High risk | Network use triggers copyleft |
+| Proprietary / Unknown | Restricted | Review required | Legal review mandatory |
+
+**Rules:**
+- [ ] No GPL/AGPL in proprietary projects
+- [ ] All dependencies have identifiable licenses
+- [ ] License changes between versions reviewed
+
+## Upgrade Risk Assessment
+
+| Update Type | Risk | Action |
+|-------------|------|--------|
+| Patch (1.2.3 -> 1.2.4) | Low | Auto-update, run tests |
+| Minor (1.2.3 -> 1.3.0) | Medium | Review changelog, run tests |
+| Major (1.2.3 -> 2.0.0) | High | Read migration guide, plan sprint work |
+| Deprecated | Critical | Find replacement, schedule migration |
+
+## Supply Chain Checks
+
+- [ ] Lock files committed and up to date
+- [ ] No typosquatting risks (verify package names)
+- [ ] Check for recent maintainer changes on critical deps
+- [ ] Verify package registry sources (no unknown registries)
+- [ ] Review transitive dependency tree depth (flag > 5 levels)
+
+## Audit Cadence
+
+| Check | Frequency |
+|-------|-----------|
+| Vulnerability scan | Every CI run |
+| License audit | Weekly / before release |
+| Outdated check | Monthly |
+| Full dependency audit | Quarterly |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- Critical CVE in production dependency → BLOCK until resolved
+- GPL dependency in commercial project → flag license violation risk
+- Dependency with no maintainer activity >1yr → flag supply chain risk
+
+## Output
+
+```markdown
+## Dependency Audit: <project>
+
+### Ecosystem: {Node.js / PHP / Python / etc.}
+- Direct dependencies: {count}
+- Transitive dependencies: {count}
+
+### Vulnerabilities
+| Package | Severity | CVE | Fix Version | Status |
+|---------|----------|-----|-------------|--------|
+
+### License Issues
+| Package | License | Risk | Action Required |
+|---------|---------|------|-----------------|
+
+### Outdated (top 10 by age)
+| Package | Current | Latest | Type | Risk |
+|---------|---------|--------|------|------|
+
+### Unused Dependencies
+- [list of packages declared but not imported]
+
+### Summary
+- Vulnerabilities: {critical} critical, {high} high, {medium} medium
+- License issues: {count}
+- Outdated: {count} ({major} major updates pending)
+- Recommendation: {SAFE TO DEPLOY | FIX BEFORE DEPLOY | BLOCK DEPLOY}
+```

package/departments/dev/skills/deploy/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/deploy
+description: >
+  Deploy to environment: pre-deploy checks, deployment execution, post-deploy verification.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Deploy — `/dev deploy <env>`
+
+> **Agent:** Carlos (DevOps) | **Framework:** Blue-Green + Canary Deployments
+
+## What It Does
+
+Deploy to environment: pre-deploy checks, deployment execution, post-deploy verification.
+
+## Output
+
+Deployment report with status, rollback plan, and monitoring links

package/departments/dev/skills/devops-pipeline/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/devops-pipeline
+description: >
+  CI/CD pipeline design: build, test, deploy stages with blue-green/canary strategies.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Devops Pipeline — `/dev pipeline <project>`
+
+> **Agent:** Carlos (DevOps) | **Framework:** Three Ways (Gene Kim) + GitOps
+
+## What It Does
+
+CI/CD pipeline design: build, test, deploy stages with blue-green/canary strategies.
+
+## Output
+
+Pipeline config (GitHub Actions/GitLab CI), deployment strategy, monitoring setup

package/departments/dev/skills/docs/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/docs
+description: >
+  Generate or update project documentation: README, API docs, architecture docs.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Docs — `/dev docs`
+
+> **Agent:** Lucas (Analyst) | **Framework:** Documentation Best Practices
+
+## What It Does
+
+Generate or update project documentation: README, API docs, architecture docs.
+
+## Output
+
+Updated documentation saved to project and Obsidian

package/departments/dev/skills/env-secrets/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dev/env-secrets
+description: >
+  Audit .env files for leaked secrets, validate .env.example sync, and guide vault integration.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Env & Secrets Manager — `/dev env-secrets`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** OWASP Secrets Management, DevSecOps
+
+## What It Does
+
+Audits environment files for leaked secrets, validates .env/.env.example drift, and provides vault integration guidance for production workloads.
+
+## Audit Checklist
+
+| Check | What to Verify | Severity |
+|-------|---------------|----------|
+| .gitignore | `.env` listed and not tracked | CRITICAL |
+| Hardcoded secrets | API keys, passwords, tokens in source code | CRITICAL |
+| .env.example sync | All keys present with placeholder values, no real values | HIGH |
+| Secret patterns | AWS keys, Stripe keys, JWT secrets, DB passwords | CRITICAL |
+| Git history | Secrets ever committed (even if removed) | HIGH |
+| CI/CD variables | Secrets masked and scoped to environments | MEDIUM |
+
+## Secret Detection Patterns
+
+| Pattern | Regex | Example Match |
+|---------|-------|--------------|
+| AWS Access Key | `AKIA[0-9A-Z]{16}` | `AKIAIOSFODNN7EXAMPLE` |
+| Stripe Key | `sk_(live\|test)_[0-9a-zA-Z]{24,}` | `sk_live_abc123...` |
+| JWT Secret | `(jwt\|JWT).*(secret\|key).*=.+` | `JWT_SECRET=mysecret` |
+| Generic Password | `(password\|passwd\|pwd).*=.{8,}` | `DB_PASSWORD=hunter2` |
+| Private Key | `-----BEGIN (RSA\|EC\|DSA) PRIVATE KEY-----` | PEM block |
+
+## Automated Scans
+
+| Tool | Purpose | Command |
+|------|---------|---------|
+| GitLeaks | Scan repo for secrets | `gitleaks detect --source . --report-path gitleaks.json` |
+| detect-secrets | Baseline + audit | `detect-secrets scan > .secrets.baseline` |
+| git log | History check | `git log --all --diff-filter=A -- '*.env' '*secret*'` |
+
+## Vault Integration Guide
+
+| Provider | Best For | Integration Pattern |
+|----------|----------|-------------------|
+| HashiCorp Vault | Multi-cloud / hybrid | SDK pull or sidecar injection |
+| AWS Secrets Manager | AWS-native | Lambda/ECS native, auto-rotation |
+| Azure Key Vault | Azure-native | Managed HSM, Azure AD RBAC |
+| GCP Secret Manager | GCP-native | IAM-based, automatic versioning |
+
+## Emergency Rotation Checklist
+
+- [ ] Revoke compromised credential immediately at provider
+- [ ] Generate and deploy replacement to all consumers
+- [ ] Audit access logs for unauthorized usage
+- [ ] Scan git history, CI logs, artifacts for leaked value
+- [ ] File incident report with scope and timeline
+- [ ] Tighten detection controls to prevent recurrence
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- .env file in git history → CRITICAL flag, rotation needed
+- Hardcoded API key in source → BLOCK until removed
+- Secrets without expiration → flag rotation risk
+
+## Output
+
+```markdown
+## Env & Secrets Audit: <project>
+
+### CRITICAL
+- [C1] `.env` committed to git — contains DB_PASSWORD and STRIPE_KEY
+  Fix: Remove from tracking, rotate credentials, add to .gitignore
+
+### HIGH
+- [H1] .env.example missing 3 keys present in .env
+- [H2] AWS key found in git history (commit abc123)
+
+### MEDIUM
+- [M1] CI secrets not scoped to production environment
+
+### Rotation Required: DB_PASSWORD, STRIPE_KEY, AWS_ACCESS_KEY_ID
+### Recommendation: BLOCK deploy until all CRITICAL items resolved
+```

package/departments/dev/skills/incident/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: dev/incident
+description: >
+  Incident response framework: severity classification, timeline reconstruction, runbook execution, stakeholder communication, and post-incident review.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Incident Response — `/dev incident`
+
+> **Agent:** Paulo (Dev Lead) | **Framework:** Google SRE Incident Management, Blameless PIR
+
+## Severity Classification
+
+| Level | Definition | Response Time | Comms Cadence | Escalation |
+|-------|-----------|---------------|---------------|------------|
+| **SEV1** | Full outage, data loss, security breach | 5 min | Every 15 min | Immediate exec notification |
+| **SEV2** | Partial degradation, >25% users affected | 15 min | Every 30 min | Team lead within 30 min |
+| **SEV3** | Single feature affected, workaround exists | 2 hours | Key milestones | Internal team only |
+| **SEV4** | Cosmetic, dev/test env, no user impact | Next business day | Standard cycle | Standard ticket |
+
+## Incident Commander Checklist
+
+### Detection (0-5 min)
+- [ ] Identify affected services and user impact
+- [ ] Classify severity using table above
+- [ ] Create incident tracking ticket
+- [ ] Establish war room (Slack channel / video bridge)
+
+### Response (5-30 min)
+- [ ] Assign Incident Commander (owns process, not debugging)
+- [ ] Assign Technical Lead (owns investigation)
+- [ ] Check recent deployments and config changes
+- [ ] Review error logs and monitoring dashboards
+- [ ] Send initial stakeholder notification
+
+### Mitigation
+- [ ] Decide: rollback vs. fix-forward
+- [ ] Execute mitigation (prefer rollback under pressure)
+- [ ] Validate fix with monitoring and end-to-end tests
+- [ ] Update status page and stakeholders
+
+### Resolution
+- [ ] Confirm service restored to normal
+- [ ] Send resolution notification
+- [ ] Schedule Post-Incident Review (within 48h)
+
+## Communication Templates
+
+**Initial notification:**
+```
+[SEV{level}] {Service} -- {Brief Description}
+Impact: {what users experience}
+Status: Investigating | Mitigating | Resolved
+IC: {name} | Tech Lead: {name}
+Next update: {time}
+```
+
+**Stakeholder update:**
+```
+[SEV{level}] Update #{n} -- {Service}
+Status: {current status}
+Actions taken: {what was done}
+Next steps: {what happens next}
+ETA: {estimate or "investigating"}
+```
+
+## Runbook Template
+
+| Section | Content |
+|---------|---------|
+| **Quick Reference** | Severity indicators, key contacts, critical commands |
+| **Detection** | Alert definitions, manual symptom checklist |
+| **Initial Response** | Severity assessment, command establishment, first investigation |
+| **Mitigation Strategies** | Step-by-step procedures with rollback plans |
+| **Recovery** | Service restoration, data consistency checks, notification |
+| **Common Pitfalls** | Known failure modes and how to avoid them |
+
+## Post-Incident Review (PIR)
+
+| Framework | When to Use |
+|-----------|------------|
+| **5 Whys** | Simple, linear root cause chains |
+| **Fishbone (Ishikawa)** | Multiple contributing factors |
+| **Timeline Analysis** | Complex incidents with many events |
+
+**PIR principles:**
+- Blameless -- focus on systems, not people
+- Action items have owners and due dates
+- Share learnings broadly
+- Update runbooks with new knowledge
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- SEV1 without defined escalation path → flag response gap
+- No PIR template → flag learning gap
+- Incident >30min without status update → flag communication failure
+
+## Output
+
+```markdown
+## Incident Report: <title>
+
+### Summary
+- Severity: SEV{level}
+- Duration: {start} to {end} ({total time})
+- Impact: {users/services affected}
+- Root Cause: {1-2 sentence summary}
+
+### Timeline
+| Time | Event |
+|------|-------|
+
+### Root Cause Analysis
+[5 Whys / Fishbone / Timeline analysis]
+
+### Action Items
+| # | Action | Owner | Due | Status |
+|---|--------|-------|-----|--------|
+
+### Lessons Learned
+1. [Key takeaway]
+2. [Key takeaway]
+```

package/departments/dev/skills/mcp/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: arka-dev-mcp
+description: >
+  MCP (Model Context Protocol) management for projects. Apply pre-configured MCP profiles,
+  add or remove individual MCP servers, list all available MCPs from the registry, and check
+  which MCPs are active in a project. Generates .mcp.json and .claude/settings.local.json.
+  Use when user says "mcp", "apply mcp", "add mcp", "mcp status", "mcp list", "remove mcp",
+  "model context protocol", "mcp profile", or wants to configure Claude Code integrations.
+---
+
+# MCP Management — ARKA OS Dev Department
+
+Manage Model Context Protocol (MCP) servers for projects. MCPs extend Claude Code with external tool integrations.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/dev mcp apply <profile> [--project <path>]` | Apply MCP profile to a project |
+| `/dev mcp add <name> [--project <path>]` | Add a single MCP to a project |
+| `/dev mcp list` | Show all available MCPs from the registry |
+| `/dev mcp status [--project <path>]` | Show active MCPs in a project |
+| `/dev mcp remove <name> [--project <path>]` | Remove an MCP from a project |
+
+## Profiles
+
+| Profile | MCPs Included | Use For |
+|---------|---------------|---------|
+| `base` | obsidian, context7, playwright, memory-bank, sentry, gh-grep, clickup, firecrawl, supabase | All projects |
+| `laravel` | base + laravel-boost, serena | Laravel backends |
+| `nuxt` | base + nuxt, nuxt-ui | Nuxt 3/4 apps |
+| `vue` | base + nuxt-ui | Vue 3 SPAs |
+| `react` | base + next-devtools | React SPAs |
+| `nextjs` | base + next-devtools, supabase | Next.js apps |
+| `ecommerce` | base + laravel-boost, serena, mirakl, shopify-dev | E-commerce projects |
+| `full-stack` | base + laravel-boost, serena, nuxt, nuxt-ui | Laravel + Nuxt apps |
+| `comms` | base + slack, discord, whatsapp, teams | Messaging platforms |
+
+## How It Works
+
+### /dev mcp apply <profile>
+
+1. Read the MCP registry at `mcps/registry.json`
+2. Read the profile file at `mcps/profiles/<profile>.json`
+3. Resolve base + profile MCPs (profiles extend base automatically)
+4. Run the apply script:
+   ```bash
+   bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" <profile> --project <path>
+   ```
+5. This generates:
+   - `.mcp.json` in the project root (MCP server definitions)
+   - `.claude/settings.local.json` (enables MCPs + base permissions)
+6. Report what was installed
+
+### /dev mcp add <name>
+
+Add a single MCP without applying a full profile:
+```bash
+bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" --add <name> --project <path>
+```
+This merges the new MCP into the existing `.mcp.json`.
+
+### /dev mcp list
+
+```bash
+bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" --list
+```
+
+Shows all MCPs from the registry with their category and description.
+
+### /dev mcp status
+
+```bash
+bash "$ARKA_OS/mcps/scripts/apply-mcps.sh" --status --project <path>
+```
+
+Shows which MCPs are currently active in the project's `.mcp.json`.
+
+### /dev mcp remove <name>
+
+1. Read project's `.mcp.json`
+2. Remove the specified MCP entry
+3. Update `.claude/settings.local.json` to remove from `enabledMcpjsonServers`
+4. Report the change
+
+## Registry
+
+The central MCP registry lives at `mcps/registry.json`. Each entry contains:
+- `command` + `args` (for local MCPs) OR `type` + `url` (for HTTP MCPs)
+- `category` — which profile group it belongs to
+- `description` — what the MCP does
+- `env` — required environment variables (if any)
+- `required_env` — list of env var names that must be set
+
+## Environment Variables
+
+Some MCPs require API keys or configuration. These are defined in the registry's `env` field.
+When applying MCPs that need env vars, the script will warn which ones need to be set.
+
+The user should set these in their shell profile or project `.env`, or run `bash env-setup.sh`:
+- `CLICKUP_API_KEY` / `CLICKUP_TEAM_ID` — ClickUp integration
+- `FIRECRAWL_API_KEY` — Firecrawl web scraping
+- `PG_HOST` / `PG_PORT` / `PG_USER` / `PG_PASSWORD` / `PG_DATABASE` — PostgreSQL direct access
+- `DISCORD_TOKEN` — Discord bot integration
+- `WHATSAPP_API_TOKEN` / `WHATSAPP_PHONE_ID` — WhatsApp Business API
+- `TEAMS_APP_ID` / `TEAMS_APP_SECRET` — Microsoft Teams