@jaguilar87/gaia 5.0.11 → 5.1.0-rc.2

package/.claude-plugin/marketplace.json

@@ -1,33 +1,24 @@
 {
-  "name": "gaia-ops-marketplace",
+  "name": "gaia-marketplace",
   "owner": {
     "name": "jaguilar87",
     "email": "jorge.aguilar87@gmail.com"
   },
   "plugins": [
     {
-      "name": "gaia-ops",
-      "description": "Full DevOps orchestration for Claude Code. Eight specialized agents handle the complete development lifecycle — analysis, planning, execution, and deployment. Gaia-Ops scans your codebase to understand it and injects the right context into each sub-agent. Every command is classified by risk: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
-      "version": "5.0.11",
+      "name": "gaia",
+      "description": "Security-first multi-agent orchestration for Claude Code. Specialized agents cover the full development lifecycle — analysis, planning, execution, deployment — with codebase-aware context injection. Every command is risk-classified: read-only runs freely, state changes pause for your approval, and irreversible operations are permanently blocked.",
+      "version": "5.1.0-rc.2",
       "category": "devops",
       "author": {
         "name": "jaguilar87",
         "email": "jorge.aguilar87@gmail.com"
       },
       "homepage": "https://github.com/metraton/gaia#readme",
-      "source": "./dist/gaia-ops"
-    },
-    {
-      "name": "gaia-security",
-      "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
-      "version": "5.0.11",
-      "category": "security",
-      "author": {
-        "name": "jaguilar87",
-        "email": "jorge.aguilar87@gmail.com"
-      },
-      "homepage": "https://github.com/metraton/gaia#gaia-security",
-      "source": "./dist/gaia-security"
+      "source": {
+        "source": "npm",
+        "package": "@jaguilar87/gaia"
+      }
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
-  "name": "gaia-ops",
-  "version": "5.0.11",
-  "description": "Security-first orchestrator with specialized agents, hooks, and governance for AI coding",
+  "name": "gaia",
+  "version": "5.1.0-rc.2",
+  "description": "Security-first multi-agent orchestration for Claude Code. Agents span the full lifecycle; commands are risk-classified \u2014 reads run free, state changes need approval, irreversible ops blocked.",
   "author": {
     "name": "jaguilar87",
     "email": "jorge.aguilar87@gmail.com"
@@ -11,9 +11,7 @@
   "license": "MIT",
   "keywords": [
     "security",
-    "devops",
-    "orchestrator",
-    "governance"
+    "devops"
   ],
   "engines": {
     "claude-code": ">=2.1.0"
@@ -22,5 +20,177 @@
     "devops",
     "security",
     "orchestration"
-  ]
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      },
+      {
+        "matcher": "SendMessage",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Edit|Write|Glob|Grep|WebSearch|WebFetch|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/subagent_stop.py"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session_start.py"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session_end_hook.py"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pre_compact.py"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/post_compact.py"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/stop_hook.py"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/task_completed.py"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/subagent_start.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/user_prompt_submit.py"
+          }
+        ]
+      }
+    ],
+    "ElicitationResult": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/elicitation_result.py"
+          }
+        ]
+      }
+    ]
+  }
 }

package/ARCHITECTURE.md

@@ -4,7 +4,7 @@
 
 Gaia is an orchestration system for Claude Code agents. It turns a single Claude Code session into a coordinated multi-agent system with security enforcement, context injection, surface-based routing, episodic memory, and deterministic response contracts.
 
-The package is published as `@jaguilar87/gaia` on npm and installed into a project's `.claude/` directory via symlinks. Gaia ships two sub-plugins: `gaia-ops` (full orchestrator with all agents) and `gaia-security` (security hooks only).
+The package is published as `@jaguilar87/gaia` on npm and installed into a project's `.claude/` directory via symlinks. Gaia ships as a **single, unified plugin** named `gaia` — one artifact carrying the full orchestrator, all agents, all skills, all hooks, all tools, and all config. Every install runs the full orchestrator surface, and the T3 mutation-safety floor for the main session is unconditional (see `skills/gaia-patterns/reference.md` → "Plugin Packaging").
 
 ## Core Concepts
 
@@ -206,11 +206,19 @@ ClaudeCodeAdapter.format_validation_response() -> Claude Code stdout JSON
 ```
 
 ### Plugin Distribution
-Gaia ships the `gaia-ops` sub-plugin as a Claude Code plugin via `.claude-plugin/plugin.json`.
-The plugin is auto-discovered by Claude Code -- agents, skills, commands, and hooks
-are loaded from their respective directories.
-
-See `.claude-plugin/marketplace.json` for the self-hosted marketplace with sub-plugins.
+Gaia ships as the single unified `gaia` plugin. There is **no `dist/` bundle** --
+the npm package root (`@jaguilar87/gaia`) IS the plugin. The root
+`.claude-plugin/plugin.json` (with hooks embedded inline) and `hooks/hooks.json`
+are generated from `build/gaia.manifest.json` at pack time
+(`prepack` -> `generate:plugin-root`) and tracked in git. Claude Code
+auto-discovers agents, skills, commands, and hooks from their respective
+directories at the package root.
+
+See `.claude-plugin/marketplace.json` for the self-hosted marketplace, which
+advertises the one `gaia` plugin with a `source: npm` object
+(`{"source": "npm", "package": "@jaguilar87/gaia"}`) -- Claude Code installs the
+package into its plugin cache and reads the inline-hooks `plugin.json` from the
+package root.
 
 ## Adapter Coupling Points
 

package/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.1.0-rc.2] - 2026-07-02
+
+## [5.1.0-rc.1] - 2026-07-02
+
 ## [5.0.11] - 2026-06-30
 
 ### Changed

package/INSTALL.md

@@ -1,30 +1,60 @@
 # Gaia Installation Guide
 
-This guide will help you install and configure Gaia in your project. The process is automatic and takes less than 5 minutes.
+This guide will help you install and configure Gaia in your project. The process is non-invasive and takes less than 5 minutes.
 
 ## 🎯 What is Gaia?
 
 Gaia is a system of specialized AI agents that automate DevOps tasks. Think of it as having a team of experts (Terraform, Kubernetes, GCP, AWS) working together, coordinated by an intelligent orchestrator.
 
-The `gaia-ops` sub-plugin ships the full orchestrator and all agents; `gaia-security` ships security hooks only. Both are distributed via the `@jaguilar87/gaia` npm package.
+Gaia ships as a **single, unified plugin** named `gaia` — one artifact carrying the full orchestrator, all agents, all skills, all hooks, all tools, and all config. It is distributed as the `@jaguilar87/gaia` npm package; that same package root IS the Claude Code plugin (`source: npm`), so there is no separate `dist/` bundle.
 
 ---
 
-## 🚀 Quick Installation (Recommended)
+## 🚀 Installation
 
-### Option 1: npm install (standard)
+Gaia reaches a workspace through **two surfaces**. Pick the one that matches how you run Claude Code.
 
-The npm `postinstall` hook does everything automatically -- bootstraps the DB, creates `.claude/`, writes symlinks, registers the plugin, and merges hook config:
+### Surface 1: npm / pnpm
+
+Install the package, then wire the workspace with `gaia install`:
 
 ```bash
 npm install @jaguilar87/gaia
+# or: pnpm add @jaguilar87/gaia
+
+gaia install
 ```
 
-After install, `gaia doctor` verifies the result. If postinstall fails, `~/.gaia/last-install-error.json` is written with the diagnostic.
+**There is no `postinstall` hook.** The install is deliberately non-invasive (npm and pnpm both handle it identically — pnpm ignores lifecycle scripts by default, so relying on `postinstall` would have been fragile). Two things bootstrap on demand instead:
+
+- The database `~/.gaia/gaia.db` is created **lazily on the first `gaia` CLI use** (`_ensure_db_bootstrapped` in `bin/gaia`). You do not have to run anything special — the first `gaia` command you run seeds it.
+- The workspace `.claude/` structure (symlinks + `settings.local.json` + registry) is written by running `gaia install` explicitly, or by the SessionStart hook.
+
+After install, `gaia doctor` verifies the result. If a bootstrap or wire-up step fails, `~/.gaia/last-install-error.json` is written with the diagnostic.
+
+### Surface 2: Claude Code plugin
 
-### Option 2: Project Scanner (on-demand)
+Claude Code consumes the npm package directly (`source: npm`) — it runs `npm install @jaguilar87/gaia` into its plugin cache. Add the marketplace and install the single plugin:
 
-To detect or refresh your project context (stack, GitOps directory, Terraform layout, GCP project, etc.) -- this is **not** the installer, it writes scan results to `~/.gaia/gaia.db`:
+```bash
+# Add the marketplace
+/plugin marketplace add metraton/gaia
+
+# Install the unified plugin
+/plugin install gaia
+```
+
+For a pre-release dry-run of the plugin surface without publishing, pack the exact tarball and validate the extracted root headless:
+
+```bash
+npm run gaia:plugin-dryrun   # pack -> temp extract -> structural asserts + `claude plugin validate`
+```
+
+On the plugin surface, Claude Code reads hooks from the package root's inline `.claude-plugin/plugin.json` / `hooks/hooks.json` (generated from `build/gaia.manifest.json` at pack time) — **not** from `settings.local.json`.
+
+### Project Scanner (on-demand, separate from install)
+
+To detect or refresh your project context (stack, GitOps directory, Terraform layout, GCP project, etc.), run the scanner. This is **not** the installer — it writes scan results to `~/.gaia/gaia.db`:
 
 ```bash
 gaia scan
@@ -41,7 +71,7 @@ gaia scan --non-interactive \
   --cluster my-gke-cluster
 ```
 
-**Important:** `gaia scan` and `gaia install` are separate flows. `gaia install` (run automatically by `npm install` postinstall) bootstraps the database and `.claude/` structure. `gaia scan` detects your project stack and writes the results to the DB. Running `gaia scan` never installs or creates symlinks; running `gaia install` never scans. To bootstrap from scratch, use `gaia install` (or `npm install @jaguilar87/gaia`), not `gaia scan`.
+**Important:** `gaia scan` and `gaia install` are separate flows. `gaia install` bootstraps the database and `.claude/` structure. `gaia scan` detects your project stack and writes the results to the DB. Running `gaia scan` never installs or creates symlinks; running `gaia install` never scans.
 
 ---
 
@@ -50,27 +80,29 @@ gaia scan --non-interactive \
 ### Installation Flow
 
 ```
-User runs: npm install @jaguilar87/gaia
+User runs: npm install @jaguilar87/gaia   (or: pnpm add @jaguilar87/gaia)
+        ↓
+(no postinstall — nothing runs automatically)
         ↓
-postinstall script → gaia install --postinstall
+User runs: gaia install    (or the SessionStart hook wires the workspace)
         ↓
-[Bootstrap] runs scripts/bootstrap_database.sh
-   - Seeds ~/.gaia/gaia.db with current schema (v17)
+[Bootstrap] first `gaia` use runs scripts/bootstrap_database.sh (lazy)
+   - Seeds ~/.gaia/gaia.db with current schema
    - Seeds agent rows and permissions
         ↓
 [Install] creates .claude/ structure
-   Creates symlinks to gaia package:
-     .claude/agents    → node_modules/.../agents
-     .claude/tools     → node_modules/.../tools
-     .claude/hooks     → node_modules/.../hooks
-     .claude/commands  → node_modules/.../commands
-     .claude/config    → node_modules/.../config
-     .claude/skills    → node_modules/.../skills
-     .claude/templates → node_modules/.../templates
+   Creates 5 directory symlinks to the gaia package:
+     .claude/agents  → node_modules/.../agents
+     .claude/tools   → node_modules/.../tools
+     .claude/hooks   → node_modules/.../hooks
+     .claude/config  → node_modules/.../config
+     .claude/skills  → node_modules/.../skills
+   Plus a file link:
+     .claude/CHANGELOG.md → node_modules/.../CHANGELOG.md
         ↓
 [Install] merges config files:
    - settings.local.json (hooks + permissions, union merge)
-   - plugin-registry.json (installed[].name = "gaia-ops")
+   - plugin-registry.json (installed[].name = "gaia")
         ↓
 Validates installation:
   ✅ Symlinks correct
@@ -86,14 +118,15 @@ Then optionally scan your project stack: gaia scan
 ```
 Example: Install + scan in a project with GitOps and Terraform
 
-1. User: npm install @jaguilar87/gaia
+1. User: pnpm add @jaguilar87/gaia   (no postinstall runs)
    ↓
-2. postinstall runs gaia install --postinstall:
-   ✅ ~/.gaia/gaia.db bootstrapped (schema v17)
+2. User: gaia install
+   ✅ ~/.gaia/gaia.db bootstrapped (lazy, on first `gaia` use)
    ✅ .claude/ created
-   ✅ 7 symlinks created (agents, tools, hooks, commands, templates, config, skills)
+   ✅ 5 directory symlinks + CHANGELOG.md link created
+      (agents, tools, hooks, config, skills)
    ✅ settings.local.json merged
-   ✅ plugin-registry.json written (name: gaia-ops)
+   ✅ plugin-registry.json written (name: gaia)
    ↓
 3. User: gaia scan (optional -- detects project stack)
    ↓
@@ -109,7 +142,7 @@ Example: Install + scan in a project with GitOps and Terraform
 6. Result:
    ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
    ✅ Gaia installed and project scanned!
-   
+
    Next steps:
    1. Run: gaia doctor
    2. Run: claude
@@ -143,7 +176,7 @@ gaia scan --non-interactive
 ### Complete CLI Options
 
 ```
-gaia install [options]          # Bootstrap DB + .claude/ structure (also: npm postinstall)
+gaia install [options]          # Bootstrap DB + .claude/ structure (run manually; no postinstall)
 
 gaia scan [options]             # Detect project stack, write to ~/.gaia/gaia.db
 
@@ -165,27 +198,29 @@ gaia scan options:
 
 ```
 your-project/
-├── .claude/                       ← Created by gaia install (npm postinstall)
+├── .claude/                       ← Created by gaia install
 │   ├── agents/ (symlink)          → Agent definitions
 │   ├── skills/ (symlink)          → Skill modules
 │   ├── tools/ (symlink)           → Orchestration tools
 │   ├── hooks/ (symlink)           → Security validations
-│   ├── commands/ (symlink)        → Slash commands
 │   ├── config/ (symlink)          → Configuration (contracts, rules)
+│   ├── CHANGELOG.md (file link)    → Package changelog
 │   ├── logs/                      ← Audit logs
 │   ├── approvals/                 ← Pending T3 approval files
-│   ├── plugin-registry.json       ← installed[].name = "gaia-ops"
+│   ├── plugin-registry.json       ← installed[].name = "gaia"
 │   └── settings.local.json        ← Merged hooks + permissions + env
 └── node_modules/
-    └── @jaguilar87/gaia/          ← npm package
+    └── @jaguilar87/gaia/          ← npm package (single unified plugin)
 
 ~/.gaia/
-└── gaia.db                        ← Canonical context + memory store (SQLite, schema v17)
+└── gaia.db                        ← Canonical context + memory store (SQLite)
 ```
 
+Five directory symlinks (`agents`, `tools`, `hooks`, `config`, `skills`) plus one `CHANGELOG.md` file link — the canonical list is `_SYMLINK_NAMES` + `_SYMLINK_FILES` in `bin/cli/_install_helpers.py`.
+
 Project context (stack, GitOps layout, Terraform layout, etc.) lives in `~/.gaia/gaia.db`, not in `.claude/project-context/`. Run `gaia scan` to populate it and `gaia context show` to inspect it.
 
-**Wire-up verification:** after install, the same checklist applies to every install mode (live, dry-run, RC, stable). See `skills/gaia-release/SKILL.md` -> "Wire-up Verification Checklist".
+**Wire-up verification:** after install, the same checklist applies to every install mode (live, npm-sandbox, plugin, registry). See `skills/gaia-verify/SKILL.md` → "Wire-up checklist".
 
 ---
 
@@ -197,11 +232,10 @@ Once installed, you have access to **complete documentation** in each directory:
 
 ```
 .claude/
-├── agents/               6 agents (platform-architect, gitops-operator, etc.)
-├── skills/README.md      20 skill modules
-├── commands/README.md    Slash commands (gaia-plan, scan-project)
+├── agents/               8 agents (platform-architect, gitops-operator, etc.)
+├── skills/README.md      32 skill modules
 ├── config/README.md      Contracts, git standards, surface routing
-├── hooks/README.md       8 hook scripts (4 primary + 4 event handlers)
+├── hooks/README.md       Hook scripts (primary + event handlers)
 ├── tools/                Context, memory, validation, review
 └── bin/README.md         CLI utilities
 ```
@@ -269,11 +303,11 @@ Orchestrator identity lives in `agents/gaia-orchestrator.md` and is activated vi
 
 ```bash
 # 1. Update package
-npm install @jaguilar87/gaia@latest
+npm install @jaguilar87/gaia@latest   # or: pnpm add @jaguilar87/gaia@latest
 
-# 2. Postinstall hook automatically:
-#    - Replaces settings.json from template
-#    - Fixes broken symlinks
+# 2. Re-sync the workspace (no postinstall does this for you):
+gaia update
+#    - Refreshes DB schema, config, and symlinks after the version bump
 ```
 
 ---
@@ -357,14 +391,15 @@ echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
 # Check the diagnostic marker first
 cat ~/.gaia/last-install-error.json
 
-# Re-run install (postinstall is re-entrant)
-npm install @jaguilar87/gaia
-
-# Or repair without a fresh tarball
+# Re-run install (idempotent, re-entrant)
 gaia install
+
+# Or, if the DB itself is missing, just run any gaia command
+# (lazy bootstrap re-creates it):
+gaia doctor
 ```
 
-For the full symptom -> cause -> fix table, see `skills/gaia-release/reference.md` -> "Diagnostic Guide".
+For the full symptom → cause → fix table, see `skills/gaia-release/reference.md` → "Diagnostic guide".
 
 ---
 
@@ -398,7 +433,7 @@ Gaia is designed with these principles:
 
 ✅ **Minimal** - Only creates what's needed, no duplicates  
 ✅ **Adaptive** - Auto-detects existing installations  
-✅ **Non-invasive** - Works from any directory  
+✅ **Non-invasive** - No postinstall; bootstrap is lazy, works under npm and pnpm alike  
 ✅ **Safe** - Validates paths and skips reinstalls  
 ✅ **Clear** - Explicit feedback on each step  
 ✅ **Documented** - Complete documentation in each directory  
@@ -422,11 +457,10 @@ A: Yes. Each project is a separate workspace in `~/.gaia/gaia.db`. Run `gaia sca
 A: Yes, but you need to enable developer mode or run as administrator.
 
 **Q: How do I update only documentation without changing code?**
-A: `npm update @jaguilar87/gaia` - symlinks point to the new version automatically.
+A: `npm update @jaguilar87/gaia` then `gaia update` - symlinks point to the new version automatically.
 
 ---
 
-**Version:** 5.0.0-rc.7
-**Last updated:** 2026-05-22
+**Version:** 5.0.11
+**Last updated:** 2026-07-01
 **Maintained by:** Jorge Aguilar + Gaia (meta-agent)
-

package/README.md

@@ -25,7 +25,7 @@ That pipeline is the spine. Everything else in this repo is either a component o
 
 ## Overview
 
-**Gaia** is a multi-agent orchestration system for DevOps automation. It ships two sub-plugins — `gaia-ops` (full orchestrator) and `gaia-security` (security-only) — with security-first command classification, specialized AI agents, and plugin-based distribution. Currently integrates with Claude Code.
+**Gaia** is a multi-agent orchestration system for DevOps automation. It ships as a **single, unified plugin** named `gaia` — one artifact carrying the full orchestrator, all agents, all skills, all hooks, all tools, and all config — with security-first command classification, specialized AI agents, and plugin-based distribution. Currently integrates with Claude Code.
 
 ### Features
 
@@ -45,45 +45,45 @@ That pipeline is the spine. Everything else in this repo is either a component o
 
 ## Installation
 
+Gaia is one plugin reaching a workspace through two surfaces. Pick the one that matches how you run Claude Code.
+
 ### Via Claude Code Plugin (recommended)
 ```bash
 # Add the marketplace
 /plugin marketplace add metraton/gaia
 
-# Install the full system (includes security)
-/plugin install gaia-ops
-
-# Or install security only
-/plugin install gaia-security    # Security hooks only
+# Install the unified plugin
+/plugin install gaia
 ```
 
-### Via npm (advanced setup)
+### Via npm / pnpm (advanced setup)
 ```bash
-npm install @jaguilar87/gaia
+npm install @jaguilar87/gaia    # or: pnpm add @jaguilar87/gaia
+gaia install                    # wires the workspace
 ```
 
-The `npm install` postinstall script bootstraps the database, creates `.claude/`, writes symlinks, and registers the plugin. Run `gaia doctor` afterward to verify.
+**There is no `postinstall` hook.** The install is non-invasive and works identically under npm and pnpm. The DB is bootstrapped **lazily on the first `gaia` CLI use** (`_ensure_db_bootstrapped` in `bin/gaia`); the workspace `.claude/` structure is written by running `gaia install` explicitly, or by the SessionStart hook. Run `gaia doctor` afterward to verify.
 
-### Quick Start (npm)
+### Quick Start (npm / pnpm)
 
 ```bash
-# Install and bootstrap (postinstall does the rest)
-npm install @jaguilar87/gaia
+# Install the package
+npm install @jaguilar87/gaia        # or: pnpm add @jaguilar87/gaia
 
-# Or install globally
-npm install -g @jaguilar87/gaia
+# Wire the workspace (no postinstall does this for you)
+gaia install
 ```
 
-The postinstall hook does everything automatically. To scan your project stack after install:
+To scan your project stack after install:
 ```bash
 gaia scan
 ```
 
-`gaia install` (run by postinstall) will:
-1. Bootstrap the DB (`~/.gaia/gaia.db`) with the current schema
-2. Create `.claude/` directory with symlinks to this package
+`gaia install` will:
+1. Bootstrap the DB (`~/.gaia/gaia.db`) with the current schema (lazy on first use, or here explicitly)
+2. Create `.claude/` directory with 5 symlinks + a `CHANGELOG.md` link to this package
 3. Merge hooks and permissions into `settings.local.json` (preserves existing user config)
-4. Write `plugin-registry.json`
+4. Write `plugin-registry.json` with `installed[].name == "gaia"`
 
 `gaia scan` (run separately, on-demand) will:
 1. Auto-detect your project structure (GitOps, Terraform, AppServices, stack)
@@ -104,21 +104,22 @@ This ensures your personal customizations (MCP servers, extra permissions) survi
 
 ### Manual Installation
 
+`gaia install` writes these for you; the manual equivalent is:
+
 ```bash
 npm install @jaguilar87/gaia
 ```
 
-Then create symlinks:
+Then create the 5 directory symlinks plus the CHANGELOG file link:
 
 ```bash
 mkdir -p .claude && cd .claude
 ln -s ../node_modules/@jaguilar87/gaia/agents agents
 ln -s ../node_modules/@jaguilar87/gaia/tools tools
 ln -s ../node_modules/@jaguilar87/gaia/hooks hooks
-ln -s ../node_modules/@jaguilar87/gaia/commands commands
 ln -s ../node_modules/@jaguilar87/gaia/config config
-ln -s ../node_modules/@jaguilar87/gaia/templates templates
 ln -s ../node_modules/@jaguilar87/gaia/skills skills
+ln -s ../node_modules/@jaguilar87/gaia/CHANGELOG.md CHANGELOG.md
 ```
 
 ## Usage