sqlew 4.3.0 → 5.0.0

package/docs/HOOKS_GUIDE.md

@@ -33,15 +33,24 @@ This architecture ensures zero latency on code edits.
 
 ## Installation
 
+As of v5.0.0, hooks are managed by the **sqlew-plugin** (Claude Code Plugin).
+
 ```bash
-# Initialize hooks in your project
-sqlew init --hooks
+# 1. Add the marketplace
+/plugin marketplace add sqlew-io/sqlew-plugin
+
+# 2. Install the plugin (user-level recommended)
+/plugin install sqlew-plugin
 
-# Without Git hooks (MCP hooks only)
-sqlew init --hooks --no-git
+# 3. Restart Claude Code to apply changes
 ```
 
-This creates `.claude/settings.local.json` with hook configuration.
+The plugin automatically configures:
+- ✅ MCP server settings (`.mcp.json`)
+- ✅ Claude Code Hooks (PreToolUse/PostToolUse)
+- ✅ Claude Code Skills (Plan Mode guidance)
+
+> **Note:** Global Rules are automatically created at `~/.claude/rules/sqlew/` when the MCP server starts.
 
 ## Hook Commands
 
@@ -67,48 +76,6 @@ This creates `.claude/settings.local.json` with hook configuration.
 | post-merge | `sqlew mark-done` | Mark decisions as complete after merge |
 | post-rewrite | `sqlew mark-done` | Mark decisions as complete after rebase |
 
-## Configuration
-
-Generated configuration in `.claude/settings.local.json`:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Task",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "sqlew suggest"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "sqlew save"
-          }
-        ]
-      },
-      {
-        "matcher": "TodoWrite",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "sqlew check-completion"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
 ## Queue File Format
 
 `.sqlew/queue/pending.json`:
@@ -134,16 +101,27 @@ Generated configuration in `.claude/settings.local.json`:
 
 ### Hooks not triggering
 
-1. Check `.claude/settings.local.json` exists
-2. Verify hook configuration format
+1. Verify plugin is installed: `/plugin list`
+2. Check plugin status for errors
 3. Restart Claude Code to reload hooks
 
 ### Queue not processing
 
 1. Ensure MCP server is running
-2. Check `.sqlew/queue/pending.json` for items
+2. Use `queue { action: "list" }` to check pending items
 3. Verify QueueWatcher is active (check debug logs)
 
+### Items stuck in queue (High Similarity)
+
+Items may remain in queue if they have 60%+ similarity to existing decisions:
+
+1. **Check queue**: `queue { action: "list" }`
+2. **Search existing**: `/sqlew search for <topic>`
+3. **Remove if duplicate**: `queue { action: "remove", index: N }`
+4. **Or clear all**: `queue { action: "clear" }`
+
+See `~/.claude/rules/sqlew/queue-monitoring.md` for details.
+
 ### Debug logging
 
 Enable debug logging in `.sqlew/config.toml`:
@@ -156,4 +134,6 @@ log_level = "debug"
 
 ## Version History
 
+- **v5.0.0**: Hooks managed by sqlew-plugin (Claude Code Plugin)
+- **v4.3.0**: Plan-to-ADR - Automatic ADR from Plan Mode
 - **v4.1.0**: Initial Claude Code Hooks integration with File Queue Architecture

package/docs/HOW_TO_UNINSTALL.md

@@ -0,0 +1,199 @@
+# How to Uninstall sqlew
+
+This guide explains how to completely remove sqlew from your system.
+
+---
+
+## All Clients (Common Steps)
+
+These steps apply to all MCP clients (Claude Code, Codex, Gemini CLI, etc.).
+
+### 1. Remove SaaS Configuration (if using cloud mode)
+
+If you configured sqlew for SaaS/cloud mode, remove the environment file:
+
+```bash
+# Windows
+del %USERPROFILE%\.sqlew.env
+
+# macOS / Linux
+rm ~/.sqlew.env
+```
+
+### 2. Remove Project-Local Data
+
+Each project may have a `.sqlew/` directory containing:
+- `sqlew.db` - Local SQLite database
+- `config.toml` - Project configuration
+- `queue/` - Hook queue files (pending.json, failed.json)
+
+```bash
+# In each project directory
+rm -rf .sqlew/
+```
+
+---
+
+## Claude Code
+
+### 1. Remove sqlew-plugin (if installed)
+
+```bash
+# List installed plugins
+/plugin list
+
+# Remove sqlew plugin
+/plugin remove sqlew
+
+# Remove from marketplace (if added)
+/plugin marketplace remove sqlew-io/sqlew-plugin
+```
+
+### 2. Remove Plugin Repository (if cloned)
+
+If you cloned the plugin repository locally:
+
+```bash
+# Windows
+rmdir /s /q %USERPROFILE%\.claude\plugins\sqlew-plugin
+
+# macOS / Linux
+rm -rf ~/.claude/plugins/sqlew-plugin
+```
+
+### 3. Remove MCP Server Configuration
+
+Edit your Claude Code MCP settings file:
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Remove the sqlew entry from `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "sqlew": { ... }  // ← Delete this entire block
+  }
+}
+```
+
+### 4. Remove Injected CLAUDE.md Section
+
+sqlew automatically injects a section into `~/.claude/CLAUDE.md`. Remove it manually:
+
+1. Open `~/.claude/CLAUDE.md` in your editor
+2. Find and delete the section between these markers:
+
+```markdown
+<!-- sqlew:auto-injected:start -->
+...
+<!-- sqlew:auto-injected:end -->
+```
+
+**Quick removal (Unix/macOS/WSL):**
+
+```bash
+# Backup first
+cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE.md.bak
+
+# Remove injected section using sed
+sed -i '/<!-- sqlew:auto-injected:start -->/,/<!-- sqlew:auto-injected:end -->/d' ~/.claude/CLAUDE.md
+```
+
+**Quick removal (Windows PowerShell):**
+
+```powershell
+# Backup first
+Copy-Item "$env:USERPROFILE\.claude\CLAUDE.md" "$env:USERPROFILE\.claude\CLAUDE.md.bak"
+
+# Remove injected section
+$content = Get-Content "$env:USERPROFILE\.claude\CLAUDE.md" -Raw
+$content = $content -replace '(?s)<!-- sqlew:auto-injected:start -->.*?<!-- sqlew:auto-injected:end -->\r?\n?', ''
+Set-Content "$env:USERPROFILE\.claude\CLAUDE.md" $content
+```
+
+### 5. Remove Global Rules (Legacy v5.0.0)
+
+If you used sqlew v5.0.0 (before v5.0.0), rules were copied to `~/.claude/rules/sqlew/`:
+
+```bash
+# Windows
+rmdir /s /q %USERPROFILE%\.claude\rules\sqlew
+
+# macOS / Linux
+rm -rf ~/.claude/rules/sqlew
+```
+
+---
+
+## Codex / Gemini CLI / Other Clients
+
+### 1. Remove MCP Server Configuration
+
+Remove sqlew from your client's MCP configuration file. The location varies by client:
+
+- **Codex**: Check Codex documentation for MCP config location
+- **Gemini CLI**: Check Gemini CLI documentation for MCP config location
+
+### 2. Remove Client-Specific Injections (if any)
+
+Future versions may inject into client-specific configuration files. Check for sqlew markers:
+
+```
+<!-- sqlew:auto-injected:start -->
+...
+<!-- sqlew:auto-injected:end -->
+```
+
+---
+
+## npm Package Removal
+
+### Uninstall Global Package
+
+If installed globally:
+
+```bash
+npm uninstall -g sqlew
+# or
+npm uninstall -g mcp-sqlew
+```
+
+### Remove npm link (Development)
+
+If you used `npm link` for local development:
+
+```bash
+# In the mcp-sqlew project directory
+npm unlink
+
+# Remove global symlink
+npm unlink -g sqlew
+```
+
+---
+
+## Verification
+
+After uninstalling, verify removal:
+
+```bash
+# Check if sqlew command is available (should fail)
+sqlew --version
+
+# Check if MCP server is removed
+# Restart your MCP client and verify no sqlew tools appear
+```
+
+---
+
+## Reinstallation
+
+To reinstall sqlew:
+
+1. **Recommended (Plugin)**: `/plugin marketplace add sqlew-io/sqlew-plugin`
+2. **Manual (MCP)**: Add sqlew to your MCP configuration
+
+See [README.md](../README.md) for installation instructions.

package/docs/MIGRATION_CLEANUP_GUIDE.md

@@ -0,0 +1,212 @@
+# v4 to v5 Migration Cleanup Guide
+
+This guide lists the **specific files** that were auto-generated by sqlew v4 (`sqlew --init`, `sqlew --hooks`). Delete only these files - other files in the same directories may have been created by you or other tools.
+
+## What Changed in v5
+
+| Feature | v4 (Legacy) | v5 (Plugin) |
+|---------|-------------|-------------|
+| Installation | `sqlew --init` per project | `sqlew-plugin` via Claude Plugin marketplace |
+| Skills/Hooks | `.claude/hooks/`, `.claude/skills/` | Managed by plugin |
+| Agents | `.claude/agents/` | Removed (Agent system deprecated) |
+| Rules | `.claude/rules/` | Global `~/.claude/rules/sqlew/` |
+| Commands | `.claude/commands/` | Global `~/.claude/commands/` |
+
+---
+
+## Files to Delete (v4 Auto-Generated)
+
+### Agents (Added by sqlew v3.x, deprecated in v4.0.0)
+
+These agent definition files were created by early sqlew versions:
+
+| File | Description |
+|------|-------------|
+| `.claude/agents/parallel-orchestrator.md` | Parallel task orchestration agent |
+| `.claude/agents/sqlew-architect.md` | Architecture decision agent |
+| `.claude/agents/sqlew-researcher.md` | Context research agent |
+| `.claude/agents/sqlew-scrum-master.md` | Task management agent |
+
+### Commands (Added by `sqlew --init`)
+
+| File | Description |
+|------|-------------|
+| `.claude/commands/sqlew.md` | `/sqlew` slash command definition |
+
+**Note**: Now managed globally at `~/.claude/commands/sqlew.md` by the plugin.
+
+### Hooks (Added by `sqlew --hooks`)
+
+| File | Description |
+|------|-------------|
+| `.claude/hooks/check-ast-grep.mjs` | AST pattern validation hook |
+| `.claude/hooks/check-db-path.mjs` | Database path guardrail hook |
+| `.claude/hooks/check-migration.mjs` | Migration file protection hook |
+| `.claude/hooks/check-prod-db.mjs` | Production DB protection hook |
+
+**Note**: Now managed by sqlew-plugin.
+
+### Rules (Added by `sqlew --init`)
+
+| File | Description |
+|------|-------------|
+| `.claude/rules/plan-mode-integration.md` | Plan mode decision format guide |
+
+**Note**: Now managed globally at `~/.claude/rules/sqlew/plan-mode-integration.md`.
+
+### Skills (Added by `sqlew --init`)
+
+| Directory | Description |
+|-----------|-------------|
+| `.claude/skills/sqlew-plan-guidance/` | Plan mode quick reference |
+| `.claude/skills/sqlew-decision-format/` | Decision format guide |
+
+**Note**: Now managed globally:
+- `~/.claude/skills/sqlew-plan-guidance/`
+- `~/.claude/skills/plan-decision-format/`
+
+---
+
+## settings.json Modification
+
+Remove hook entries that reference the deleted `.claude/hooks/*.mjs` files.
+
+**Before (v4):**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "command": "node .claude/hooks/check-migration.mjs" },
+          { "command": "node .claude/hooks/check-ast-grep.mjs" }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "command": "node .claude/hooks/check-db-path.mjs" },
+          { "command": "node .claude/hooks/check-prod-db.mjs" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**After (v5):**
+Remove the PreToolUse entries that reference `.claude/hooks/`. The plugin handles these automatically.
+
+---
+
+## Complete File List
+
+Copy-paste ready deletion commands for v4 auto-generated files:
+
+```bash
+# Windows (PowerShell)
+Remove-Item .claude\agents\parallel-orchestrator.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-architect.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-researcher.md -ErrorAction SilentlyContinue
+Remove-Item .claude\agents\sqlew-scrum-master.md -ErrorAction SilentlyContinue
+Remove-Item .claude\commands\sqlew.md -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-ast-grep.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-db-path.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-migration.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\hooks\check-prod-db.mjs -ErrorAction SilentlyContinue
+Remove-Item .claude\rules\plan-mode-integration.md -ErrorAction SilentlyContinue
+Remove-Item -Recurse .claude\skills\sqlew-plan-guidance -ErrorAction SilentlyContinue
+Remove-Item -Recurse .claude\skills\sqlew-decision-format -ErrorAction SilentlyContinue
+```
+
+```bash
+# Unix/macOS/Linux
+rm -f .claude/agents/parallel-orchestrator.md
+rm -f .claude/agents/sqlew-architect.md
+rm -f .claude/agents/sqlew-researcher.md
+rm -f .claude/agents/sqlew-scrum-master.md
+rm -f .claude/commands/sqlew.md
+rm -f .claude/hooks/check-ast-grep.mjs
+rm -f .claude/hooks/check-db-path.mjs
+rm -f .claude/hooks/check-migration.mjs
+rm -f .claude/hooks/check-prod-db.mjs
+rm -f .claude/rules/plan-mode-integration.md
+rm -rf .claude/skills/sqlew-plan-guidance
+rm -rf .claude/skills/sqlew-decision-format
+```
+
+---
+
+## Verification
+
+After cleanup, verify your setup:
+
+1. **Check plugin is installed:**
+   ```bash
+   # In Claude Code
+   /plugin list
+   # Should show: sqlew-plugin@sqlew-plugin
+   ```
+
+2. **Check global rules exist:**
+   ```bash
+   # Windows
+   dir %USERPROFILE%\.claude\rules\sqlew\
+
+   # Unix/macOS
+   ls ~/.claude/rules/sqlew/
+   ```
+
+3. **Test /sqlew command:**
+   ```bash
+   # In Claude Code
+   /sqlew
+   # Should show status without errors
+   ```
+
+4. **Verify no duplicate hooks:**
+   - Open `.claude/settings.json`
+   - Ensure no references to `.claude/hooks/*.mjs`
+
+---
+
+## Troubleshooting
+
+### Error: "Cannot find module '.claude/hooks/check-*.mjs'"
+
+**Cause**: `settings.json` still references deleted hook files.
+
+**Solution**: Remove the PreToolUse hooks section from `.claude/settings.json`.
+
+### /sqlew command not found
+
+**Cause**: Plugin not installed or global command not registered.
+
+**Solution**:
+```bash
+/plugin install sqlew-plugin
+# Restart Claude Code
+```
+
+### Decisions not being captured automatically
+
+**Cause**: Plugin hooks not active.
+
+**Solution**:
+1. Ensure plugin is installed at user level (not project level)
+2. Restart Claude Code
+3. Check `~/.claude/settings.json` for `enabledPlugins`
+
+---
+
+## Summary
+
+| Category | Files to Delete |
+|----------|-----------------|
+| **Agents** | `parallel-orchestrator.md`, `sqlew-architect.md`, `sqlew-researcher.md`, `sqlew-scrum-master.md` |
+| **Commands** | `sqlew.md` |
+| **Hooks** | `check-ast-grep.mjs`, `check-db-path.mjs`, `check-migration.mjs`, `check-prod-db.mjs` |
+| **Rules** | `plan-mode-integration.md` |
+| **Skills** | `sqlew-plan-guidance/`, `sqlew-decision-format/` |
+| **settings.json** | Remove PreToolUse entries referencing `.claude/hooks/` |

package/docs/MIGRATION_TO_SAAS.md

@@ -0,0 +1,176 @@
+# Migrating Local Data to SaaS
+
+This guide explains how to migrate your existing local sqlew data to [sqlew.io](https://sqlew.io) cloud backend.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────┐
+│  Migration Flow                                 │
+├─────────────────────────────────────────────────┤
+│                                                 │
+│  [Local v3.x/v4.x DB]                          │
+│       │                                         │
+│       ▼ npm install -g sqlew@latest            │
+│       │                                         │
+│       ▼ sqlew (auto-migration to v5.0+)        │
+│       │                                         │
+│  [Local v5.0+ DB]                              │
+│       │                                         │
+│       ▼ npm run db:export -- backup.json       │
+│       │                                         │
+│  [JSON file]                                    │
+│       │                                         │
+│       ▼ Upload to sqlew.io                     │
+│       │                                         │
+│  [SaaS v5.0+]                                  │
+│                                                 │
+└─────────────────────────────────────────────────┘
+```
+
+## Step-by-Step Guide
+
+### 1. Update to v5.0+
+
+If you're on an older version (v3.x or v4.x), update first:
+
+```bash
+npm install -g sqlew@latest
+```
+
+### 2. Run Auto-Migration
+
+Start the MCP server once. This automatically migrates your database schema:
+
+```bash
+sqlew
+```
+
+The migration system:
+- Detects your current schema version
+- Applies all necessary migrations (v3→v4→v5)
+- Preserves your decisions and constraints
+
+### 3. Export Your Data
+
+Export your local database to JSON format:
+
+```bash
+# From your project directory
+cd your-project
+
+# Export to JSON
+npx sqlew db:export backup.json
+```
+
+The exported JSON includes:
+- All decisions with full metadata
+- Decision history (version tracking)
+- Decision context (rationale, alternatives, tradeoffs)
+- Constraints with categories and priorities
+- Tags and scopes
+
+### 4. Import to SaaS
+
+Upload your JSON file via the sqlew.io dashboard:
+
+1. Go to [sqlew.io/dashboard/import](https://sqlew.io/dashboard/import)
+2. Select your project (or create a new one)
+3. Upload `backup.json`
+4. Review and confirm the import
+
+## Version Compatibility
+
+| Source Version | Support | Notes |
+|----------------|---------|-------|
+| **v5.0+** | ✅ Full | Direct export/import |
+| **v4.x** | ✅ Full | Auto-migrated on startup |
+| **v3.7+** | ✅ Full | Auto-migrated on startup |
+| **v3.0-v3.6** | ⚠️ Untested | May work, but not guaranteed |
+
+## What Gets Migrated
+
+### Preserved Data
+
+| Data Type | Migrated | Notes |
+|-----------|----------|-------|
+| Decisions | ✅ Yes | All metadata preserved |
+| Decision History | ✅ Yes | Full version tracking |
+| Decision Context | ✅ Yes | Rationale, alternatives, tradeoffs |
+| Constraints | ✅ Yes | Categories, priorities |
+| Tags | ✅ Yes | Project-scoped |
+| Scopes | ✅ Yes | Project-scoped |
+| Layers | ✅ Yes | 9 predefined layers |
+
+### Not Migrated (Removed Features)
+
+| Data Type | Version Removed | Reason |
+|-----------|-----------------|--------|
+| Agent references | v4.0 | Agent system simplified |
+| Tasks | v5.0 | Replaced by Claude Code TodoWrite |
+| Task dependencies | v5.0 | Replaced by Claude Code TodoWrite |
+| Files/File changes | v5.0 | No longer tracked |
+
+> **Note:** These features were removed from sqlew itself. The data is not lost during migration—these systems simply no longer exist in v5.0+.
+
+## Troubleshooting
+
+### Migration Fails
+
+If auto-migration fails:
+
+1. Check your Node.js version (requires 20.0.0+)
+2. Ensure `.sqlew/sqlew.db` exists and is readable
+3. Check for disk space issues
+
+### Export Fails
+
+If export fails:
+
+1. Verify the database was migrated successfully
+2. Check write permissions for the output directory
+3. Try with absolute path: `npx sqlew db:export /full/path/to/backup.json`
+
+### Import Fails on SaaS
+
+If SaaS import fails:
+
+1. Verify JSON file is valid (not corrupted)
+2. Check schema_version in JSON metadata is 5.0+
+3. Contact support if the issue persists
+
+## FAQ
+
+### Can I migrate v3.0-v3.6 data?
+
+These versions are untested. The migration may work, but we recommend:
+
+1. Backup your database first
+2. Try the migration
+3. Report any issues to [GitHub Issues](https://github.com/sqlew-io/sqlew/issues)
+
+### Will I lose any decisions?
+
+No. All decisions and constraints are fully preserved. Only deprecated features (agents, tasks, files) are not migrated because they no longer exist in v5.0+.
+
+### Can I migrate multiple projects?
+
+Yes. Export each project separately:
+
+```bash
+# Export all projects
+npx sqlew db:export --all backup-all.json
+
+# Or export specific project
+npx sqlew db:export --project my-project backup.json
+```
+
+### What about constraint tags?
+
+There's a known limitation where constraint-to-tag relationships may not be fully preserved. After import, you may need to re-tag some constraints manually.
+
+## See Also
+
+- [Configuration Guide](CONFIGURATION.md) - SaaS connection setup
+- [CLI Reference](cli/README.md) - All export/import commands
+- [Upgrade from v4 to v5](MIGRATION_CLEANUP_GUIDE.md) - Plugin migration guide

package/docs/SLASH_COMMANDS.md

@@ -326,4 +326,4 @@ The `/sqlew` command is designed for token efficiency:
 ## Contributing
 
 Found a bug or have a suggestion? Please report at:
-https://github.com/sin5ddd/mcp-sqlew/issues
+https://github.com/sqlew-io/sqlew/issues