sqlew 5.1.0 → 5.2.1

package/docs/DATABASE_AUTH.md

@@ -1,135 +1,135 @@
-# Database Authentication Configuration
-
-This document describes the authentication configuration for multi-database support in sqlew v4.0.0+.
-
-## Supported Authentication
-
-| Method | Status | Description |
-|--------|--------|-------------|
-| **Direct (Password)** | ✅ Supported | Standard username/password authentication |
-| **SSH Tunnel** | ✅ Manual | User-managed SSH port forwarding |
-
-## Configuration Structure
-
-All configuration is defined in `.sqlew/config.toml`.
-
-### SQLite (Default)
-
-```toml
-[database]
-path = ".sqlew/sqlew.db"
-```
-
-### PostgreSQL
-
-```toml
-[database]
-type = "postgres"
-
-[database.connection]
-host = "localhost"
-port = 5432
-database = "sqlew_db"
-
-[database.auth]
-type = "direct"
-user = "postgres"
-password = "your-password"
-```
-
-### MySQL/MariaDB
-
-```toml
-[database]
-type = "mysql"
-
-[database.connection]
-host = "localhost"
-port = 3306
-database = "sqlew_db"
-
-[database.auth]
-type = "direct"
-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 `~/.config/sqlew/.sqlew.env`:
-   ```bash
-   echo 'SQLEW_API_KEY=sk-your-api-key' >> ~/.config/sqlew/.sqlew.env
-   chmod 600 ~/.config/sqlew/.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.
-
-```bash
-# Example: Forward local port 5433 to remote database
-ssh -L 5433:db.internal.example.com:5432 user@bastion.example.com
-```
-
-Then configure sqlew to connect to localhost:
-
-```toml
-[database]
-type = "postgres"
-
-[database.connection]
-host = "localhost"    # Tunnel endpoint
-port = 5433           # Forwarded port
-database = "sqlew_db"
-
-[database.auth]
-type = "direct"
-user = "postgres"
-password = "db-password"
-```
-
-**Useful SSH options:**
-- `-N`: Don't execute remote command (tunnel only)
-- `-f`: Run in background
-- `-o ServerAliveInterval=60`: Keep connection alive
-
-## Validation Rules
-
-### Connection
-- `host`: Required for PostgreSQL/MySQL
-- `port`: 1-65535
-- `database`: Required for PostgreSQL/MySQL
-
-### Authentication
-- `type`: Must be `direct`
-- `user`: Required
-- `password`: Required
-
-## Security Best Practices
-
-1. **Never commit passwords** - Don't commit config.toml with passwords to git
-2. **Use SSH tunnels** - For databases behind firewalls
-3. **Restrict access** - Limit database user permissions
-
----
-
-## Related Documentation
-
-- [Configuration Guide](./CONFIGURATION.md)
-- [Cross Database Guide](./CROSS_DATABASE.md)
+# Database Authentication Configuration
+
+This document describes the authentication configuration for multi-database support in sqlew v4.0.0+.
+
+## Supported Authentication
+
+| Method | Status | Description |
+|--------|--------|-------------|
+| **Direct (Password)** | ✅ Supported | Standard username/password authentication |
+| **SSH Tunnel** | ✅ Manual | User-managed SSH port forwarding |
+
+## Configuration Structure
+
+All configuration is defined in `.sqlew/config.toml`.
+
+### SQLite (Default)
+
+```toml
+[database]
+path = ".sqlew/sqlew.db"
+```
+
+### PostgreSQL
+
+```toml
+[database]
+type = "postgres"
+
+[database.connection]
+host = "localhost"
+port = 5432
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+user = "postgres"
+password = "your-password"
+```
+
+### MySQL/MariaDB
+
+```toml
+[database]
+type = "mysql"
+
+[database.connection]
+host = "localhost"
+port = 3306
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+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 `~/.config/sqlew/.sqlew.env`:
+   ```bash
+   echo 'SQLEW_API_KEY=sk-your-api-key' >> ~/.config/sqlew/.sqlew.env
+   chmod 600 ~/.config/sqlew/.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.
+
+```bash
+# Example: Forward local port 5433 to remote database
+ssh -L 5433:db.internal.example.com:5432 user@bastion.example.com
+```
+
+Then configure sqlew to connect to localhost:
+
+```toml
+[database]
+type = "postgres"
+
+[database.connection]
+host = "localhost"    # Tunnel endpoint
+port = 5433           # Forwarded port
+database = "sqlew_db"
+
+[database.auth]
+type = "direct"
+user = "postgres"
+password = "db-password"
+```
+
+**Useful SSH options:**
+- `-N`: Don't execute remote command (tunnel only)
+- `-f`: Run in background
+- `-o ServerAliveInterval=60`: Keep connection alive
+
+## Validation Rules
+
+### Connection
+- `host`: Required for PostgreSQL/MySQL
+- `port`: 1-65535
+- `database`: Required for PostgreSQL/MySQL
+
+### Authentication
+- `type`: Must be `direct`
+- `user`: Required
+- `password`: Required
+
+## Security Best Practices
+
+1. **Never commit passwords** - Don't commit config.toml with passwords to git
+2. **Use SSH tunnels** - For databases behind firewalls
+3. **Restrict access** - Limit database user permissions
+
+---
+
+## Related Documentation
+
+- [Configuration Guide](./CONFIGURATION.md)
+- [Cross Database Guide](./CROSS_DATABASE.md)

package/docs/HOOKS_GUIDE.md

@@ -1,67 +1,116 @@
-# Plugin Installation
-
-sqlew integrates with AI coding assistants through plugins.
-
-## Prerequisites
-
-Install the sqlew MCP server globally:
-
-```bash
-npm i -g sqlew
-```
-
-## Claude Code
-
-Two commands to install:
-
-```bash
-claude plugin marketplace add sqlew-io/sqlew-plugin
-claude plugin install sqlew
-```
-
-The plugin automatically configures:
-- MCP server settings (`.mcp.json`)
-- Claude Code Hooks (plan tracking, decision extraction)
-- Claude Code Skills (plan mode guidance, PR enrichment)
-
-To uninstall:
-
-```bash
-claude plugin remove sqlew
-```
-
-Source: https://github.com/sqlew-io/sqlew-plugin
-
-## Codex
-
-```bash
-git clone https://github.com/sqlew-io/sqlew-codex.git
-cp -r sqlew-codex/copy_to_codex_dir/* ~/.codex/
-```
-
-Then add to `~/.codex/config.toml`:
-
-```toml
-[mcp_servers.sqlew]
-command = "sqlew"
-args = []
-```
-
-To uninstall, remove the copied skill directories and config entries.
-
-Source: https://github.com/sqlew-io/sqlew-codex
-
-## What Gets Configured
-
-| 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**: 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
+# Plugin Installation
+
+sqlew integrates with AI coding assistants through plugins.
+
+## Prerequisites
+
+Install the sqlew MCP server globally:
+
+```bash
+npm i -g sqlew
+```
+
+## Claude Code
+
+Two commands to install:
+
+```bash
+claude plugin marketplace add sqlew-io/sqlew-plugin
+claude plugin install sqlew
+```
+
+The plugin automatically configures:
+- MCP server settings (`.mcp.json`)
+- Claude Code Hooks (plan tracking, decision extraction)
+- Claude Code Skills (plan mode guidance, PR enrichment)
+
+To uninstall:
+
+```bash
+claude plugin remove sqlew
+```
+
+Source: https://github.com/sqlew-io/sqlew-plugin
+
+## Codex
+
+```bash
+npm i -g sqlew
+codex plugin marketplace add sqlew-io/sqlew-plugin
+codex plugin install sqlew --source sqlew-plugin
+```
+
+After install, trust bundled hooks via `/hooks` in Codex.
+
+Enable Plan mode when needed:
+
+```toml
+[features]
+collaboration_modes = true
+```
+
+The plugin automatically configures:
+- MCP server settings (`.mcp.json`)
+- Skills (plan mode guidance, decision format, PR ADR)
+- Hooks (plan enforcement, PR ADR guard, decision extraction)
+
+To uninstall:
+
+```bash
+codex plugin remove sqlew
+```
+
+**Legacy manual install** (deprecated): see [sqlew-codex-skills](https://github.com/sqlew-io/sqlew-codex-skills).
+
+Source: https://github.com/sqlew-io/sqlew-plugin
+
+## Grok Build
+
+sqlew-plugin provides unified support for Claude Code and Grok Build (v5.2+).
+No separate adapter is required.
+
+```bash
+npm i -g sqlew
+grok plugin install sqlew-io/sqlew-plugin --trust
+grok plugin update
+```
+
+For local development, install from a cloned directory instead:
+
+```bash
+git clone https://github.com/sqlew-io/sqlew-plugin.git
+grok plugin install ./sqlew-plugin --trust
+```
+
+Verify installation:
+
+```bash
+grok plugin list          # sqlew enabled + trusted
+grok inspect              # hooks, MCP, skills visible
+```
+
+**Important**:
+- Do NOT register sqlew hooks in `~/.grok/hooks/` (causes double-firing with plugin hooks)
+- Do NOT add `[mcp_servers.sqlew]` to `~/.grok/config.toml` (plugin `.mcp.json` handles MCP)
+- Plan mode guidance uses plugin skills (`sqlew-plan-guidance`, `sqlew-decision-format`), not hook injection
+- Plan-to-ADR extracts `### 📌 Decision:` / `### 🚫 Constraint:` from `plan.md` on `exit_plan_mode`
+
+Source: https://github.com/sqlew-io/sqlew-plugin
+
+## What Gets Configured
+
+| Feature | Claude Code | Codex | Grok Build |
+|---------|-------------|-------|------------|
+| Install | `claude plugin install` | `codex plugin install` | `grok plugin install` |
+| MCP server | Plugin `.mcp.json` | Plugin `.mcp.json` | Plugin `.mcp.json` |
+| Plan-to-ADR | Skills + Hooks | Skills + Hooks | Skills + Hooks |
+| PR enrichment | Skill + Hook | Skill + Hook | Skill + Hook |
+| Decision format guidance | Skill (sqlew-decision-format) | Skill (sqlew-decision-format) | Skill (sqlew-decision-format) |
+
+## Version History
+
+- **v5.2.1**: Codex plugin support via sqlew-plugin (`.codex-plugin`, marketplace, hook normalization, transcript-based plan extraction)
+- **v5.2.0**: Grok Build support via sqlew-plugin (hook normalization, Grok plan path, skills-based plan guidance)
+- **v5.0.0**: Plugin-first architecture (sqlew-plugin for Claude Code; manual sqlew-codex-skills for Codex — now deprecated)
+- **v4.3.0**: Plan-to-ADR - Automatic ADR from Plan Mode
+- **v4.1.0**: Initial Claude Code Hooks integration