sqlew 5.0.7 → 5.0.8

package/docs/CROSS_DATABASE.md

@@ -55,96 +55,9 @@ user = "sqlew_user"
 password = "your_password"
 ```
 
-## Database-Specific Differences
-
-### String Aggregation
-
-| Database | Function |
-|----------|----------|
-| SQLite | `GROUP_CONCAT(column)` |
-| MySQL | `GROUP_CONCAT(column)` |
-| MariaDB | `GROUP_CONCAT(column)` |
-| PostgreSQL | `string_agg(column, ',')` |
-
-sqlew automatically detects the database type and uses the appropriate function.
-
-### GROUP BY Strictness
-
-PostgreSQL enforces strict GROUP BY rules:
-- All non-aggregated SELECT columns must appear in GROUP BY
-- MySQL/MariaDB/SQLite are more lenient
-
-sqlew includes all necessary columns in GROUP BY for cross-database compatibility.
-
-### Example Query Difference
-
-**MySQL/SQLite:**
-```sql
-SELECT d.key_id, ck.key_name, GROUP_CONCAT(t.name) as tags
-FROM v4_decisions d
-JOIN v4_context_keys ck ON d.key_id = ck.id
-GROUP BY d.key_id
-```
-
-**PostgreSQL:**
-```sql
-SELECT d.key_id, ck.key_name, string_agg(t.name, ',') as tags
-FROM v4_decisions d
-JOIN v4_context_keys ck ON d.key_id = ck.id
-GROUP BY d.key_id, ck.key_name
-```
-
 ## Data Migration
 
-### Cross-Database Migration
-
-Use JSON export/import for migrating between database types:
-
-```bash
-# Export from source database
-sqlew db:export backup.json
-
-# Import to target database (after changing config)
-sqlew db:import backup.json
-```
-
-**Note:** SQL dump (`db:dump`) is for same-database-type operations only.
-
-### Export Options
-
-```bash
-# Export all data
-sqlew db:export full-backup.json
-
-# Export with version tracking
-sqlew db:export --version 4.1.0 backup.json
-```
-
-## Adapter Implementation
-
-Database adapters are located in `src/adapters/`:
-
-| File | Purpose |
-|------|---------|
-| `sqlite-adapter.ts` | SQLite (better-sqlite3) |
-| `mysql-adapter.ts` | MySQL/MariaDB (mysql2) |
-| `postgresql-adapter.ts` | PostgreSQL (pg) |
-
-Each adapter implements the `DatabaseAdapter` interface with database-specific:
-- Connection handling
-- Transaction management
-- String aggregation
-- Type conversions
-
-## Testing Cross-Database Compatibility
-
-```bash
-# Run tests on all configured databases
-npm run test:cross-db
-
-# Run tests on specific database
-DB_TYPE=postgres npm test
-```
+See [CLI Usage Guide](CLI_USAGE.md#cross-database-migration) for export/import commands and step-by-step migration procedures.
 
 ## Version History
 

package/docs/DATABASE_AUTH.md

@@ -8,9 +8,6 @@ This document describes the authentication configuration for multi-database supp
 |--------|--------|-------------|
 | **Direct (Password)** | ✅ Supported | Standard username/password authentication |
 | **SSH Tunnel** | ✅ Manual | User-managed SSH port forwarding |
-| SSL/TLS Certificates | 🔮 Planned | Client certificate authentication |
-| AWS RDS IAM | 🔮 Planned | Token-based authentication for AWS RDS |
-| GCP Cloud SQL IAM | 🔮 Planned | Token-based authentication for GCP Cloud SQL |
 
 ## Configuration Structure
 
@@ -57,6 +54,30 @@ user = "mysql_user"
 password = "your-password"
 ```
 
+## Managed Database (Recommended)
+
+For environments that require SSL/TLS encryption, IAM authentication, or managed scaling, use the sqlew cloud backend instead of configuring these locally.
+
+The cloud backend handles authentication, encryption, and scaling — no local database administration needed.
+
+### Setup
+
+1. Obtain an API key from the [sqlew dashboard](https://sqlew.io)
+
+2. Save the key to `~/.sqlew.env`:
+   ```bash
+   echo 'SQLEW_API_KEY=sk-your-api-key' >> ~/.sqlew.env
+   chmod 600 ~/.sqlew.env   # Unix only
+   ```
+
+3. Set database type in `.sqlew/config.toml`:
+   ```toml
+   [database]
+   type = "cloud"
+   ```
+
+See [Configuration Guide](./CONFIGURATION.md) for full environment variable details.
+
 ## SSH Tunnel (Manual Setup)
 
 **SSH tunneling is NOT built into sqlew.** Set up tunnels manually before connecting.
@@ -100,15 +121,6 @@ password = "db-password"
 - `user`: Required
 - `password`: Required
 
-## Error Handling
-
-```
-⚠️  Configuration validation failed: .sqlew/config.toml
-   - database.connection.host is required
-   - database.auth.user is required for direct authentication
-   Using default configuration
-```
-
 ## Security Best Practices
 
 1. **Never commit passwords** - Don't commit config.toml with passwords to git
@@ -117,41 +129,6 @@ password = "db-password"
 
 ---
 
-## Future Authentication Methods
-
-> **Status**: Planned for future releases. If you need these features, please [open an issue](https://github.com/sqlew-io/sqlew/issues) - we'll prioritize based on demand!
-
-### SSL/TLS Client Certificates
-
-```toml
-# PLANNED - Not yet implemented
-[database.auth.ssl]
-ca = "/path/to/ca-cert.pem"
-cert = "/path/to/client-cert.pem"
-key = "/path/to/client-key.pem"
-rejectUnauthorized = true
-```
-
-### AWS RDS IAM Authentication
-
-```toml
-# PLANNED - Not yet implemented
-[database.auth]
-type = "aws-iam"
-region = "us-east-1"
-```
-
-### GCP Cloud SQL IAM Authentication
-
-```toml
-# PLANNED - Not yet implemented
-[database.auth]
-type = "gcp-iam"
-project = "my-project"
-```
-
----
-
 ## Related Documentation
 
 - [Configuration Guide](./CONFIGURATION.md)

package/docs/HOOKS_GUIDE.md

@@ -1,139 +1,67 @@
-# Claude Code Hooks Guide
+# Plugin Installation
 
-Integration guide for sqlew with Claude Code hooks.
+sqlew integrates with AI coding assistants through plugins.
 
-## Overview
+## Prerequisites
 
-sqlew integrates with Claude Code through PreToolUse and PostToolUse hooks, enabling **Plan-to-ADR** (v4.3.0+): automatic Architecture Decision Record generation during AI-assisted development.
+Install the sqlew MCP server globally:
 
-## Architecture
-
-```
-Claude Code                    sqlew
-    │                            │
-    ├─ PreToolUse ──────────────►│ suggest (related decisions)
-    │                            │
-    ├─ Tool Execution            │
-    │                            │
-    ├─ PostToolUse ─────────────►│ track-plan, save, check-completion
-    │                            │
-    └─ (Git hooks) ─────────────►│ mark-done (post-merge, post-rewrite)
+```bash
+npm i -g sqlew
 ```
 
-## File Queue Architecture
-
-Hooks use a file-based queue for async operations:
-
-1. **Hook writes to queue** (fast, <100ms)
-   - Location: `.sqlew/queue/pending.json`
-2. **QueueWatcher detects change** (MCP server)
-3. **Decisions registered in DB** (async)
+## Claude Code
 
-This architecture ensures zero latency on code edits.
-
-## Installation
-
-As of v5.0.0, hooks are managed by the **sqlew-plugin** (Claude Code Plugin).
+Two commands to install:
 
 ```bash
-# 1. Add the marketplace
-/plugin marketplace add sqlew-io/sqlew-plugin
-
-# 2. Install the plugin (user-level recommended)
-/plugin install sqlew-plugin
-
-# 3. Restart Claude Code to apply changes
+claude plugin marketplace add sqlew-io/sqlew-plugin
+claude plugin install sqlew
 ```
 
 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
-
-### PreToolUse Hooks
-
-| Trigger | Command | Purpose |
-|---------|---------|---------|
-| Task | `sqlew suggest` | Suggest related decisions before Task creation |
-| Write | `sqlew track-plan` | Track plan ID during planning |
-
-### PostToolUse Hooks
-
-| Trigger | Command | Purpose |
-|---------|---------|---------|
-| Edit, Write | `sqlew save` | Enqueue decision updates |
-| TodoWrite | `sqlew check-completion` | Check task completion status |
-| ExitPlanMode | `sqlew save` | Save plan state on exit |
-
-### Git Hooks
-
-| Trigger | Command | Purpose |
-|---------|---------|---------|
-| post-merge | `sqlew mark-done` | Mark decisions as complete after merge |
-| post-rewrite | `sqlew mark-done` | Mark decisions as complete after rebase |
-
-## Queue File Format
-
-`.sqlew/queue/pending.json`:
-
-```json
-{
-  "items": [
-    {
-      "type": "decision",
-      "action": "update",
-      "key": "plan/my-feature",
-      "timestamp": 1703404800000,
-      "data": {
-        "value": "in_progress",
-        "layer": "planning"
-      }
-    }
-  ]
-}
-```
+- MCP server settings (`.mcp.json`)
+- Claude Code Hooks (plan tracking, decision extraction)
+- Claude Code Skills (plan mode guidance, PR enrichment)
 
-## Troubleshooting
+To uninstall:
 
-### Hooks not triggering
-
-1. Verify plugin is installed: `/plugin list`
-2. Check plugin status for errors
-3. Restart Claude Code to reload hooks
+```bash
+claude plugin remove sqlew
+```
 
-### Queue not processing
+Source: https://github.com/sqlew-io/sqlew-plugin
 
-1. Ensure MCP server is running
-2. Use `queue { action: "list" }` to check pending items
-3. Verify QueueWatcher is active (check debug logs)
+## Codex
 
-### Items stuck in queue (High Similarity)
+```bash
+git clone https://github.com/sqlew-io/sqlew-codex.git
+cp -r sqlew-codex/copy_to_codex_dir/* ~/.codex/
+```
 
-Items may remain in queue if they have 60%+ similarity to existing decisions:
+Then add to `~/.codex/config.toml`:
 
-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" }`
+```toml
+[mcp_servers.sqlew]
+command = "sqlew"
+args = []
+```
 
-See `~/.claude/rules/sqlew/queue-monitoring.md` for details.
+To uninstall, remove the copied skill directories and config entries.
 
-### Debug logging
+Source: https://github.com/sqlew-io/sqlew-codex
 
-Enable debug logging in `.sqlew/config.toml`:
+## What Gets Configured
 
-```toml
-[debug]
-log_path = ".sqlew/debug.log"
-log_level = "debug"
-```
+| Feature | Claude Code | Codex |
+|---------|-------------|-------|
+| MCP server | Auto-configured | Manual (config.toml) |
+| Plan-to-ADR | Skills + Hooks | Skills + System prompt |
+| PR enrichment | Skill (sqlew-pr-adr) | Skill (sqlew-pr-adr) |
+| Decision format guidance | Skill (sqlew-decision-format) | Skill (sqlew-decision-format) |
 
 ## Version History
 
-- **v5.0.0**: Hooks managed by sqlew-plugin (Claude Code Plugin)
+- **v5.0.0**: Plugin-first architecture (sqlew-plugin for Claude Code, sqlew-codex for Codex)
 - **v4.3.0**: Plan-to-ADR - Automatic ADR from Plan Mode
-- **v4.1.0**: Initial Claude Code Hooks integration with File Queue Architecture
+- **v4.1.0**: Initial Claude Code Hooks integration

package/docs/MIGRATION_TO_SAAS.md

@@ -173,4 +173,4 @@ There's a known limitation where constraint-to-tag relationships may not be full
 
 - [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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlew",
   "description": "Automated ADR (Architecture Decision Records) for Claude Code - MCP server with SQL-backed decision repository",
-  "version": "5.0.7",
+  "version": "5.0.8",
   "main": "dist/index.js",
   "type": "module",
   "bin": {

package/docs/HOW_TO_UNINSTALL.md

@@ -1,199 +0,0 @@
-# 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.