sqlew 5.2.0 → 5.2.2

package/docs/MIGRATION_TO_SAAS.md

@@ -1,176 +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 backup-all.json project=all
-
-# Or export specific project
-npx sqlew db:export backup.json project=my-project
-```
-
-### 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
-
+# 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 backup-all.json project=all
+
+# Or export specific project
+npx sqlew db:export backup.json project=my-project
+```
+
+### 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
+

package/docs/SHARED_DATABASE.md

@@ -1,108 +1,108 @@
-# Shared Database (v5.1.0+)
-
-As of v5.1.0, sqlew uses a **global shared database** by default instead of a per-project local database. This resolves the issue where git worktrees created isolated databases that couldn't share decisions.
-
-## Default Paths
-
-| Purpose | Path |
-|---------|------|
-| Database | `~/.config/sqlew/sqlew-shared.db` |
-| Config | `~/.config/sqlew/config.toml` |
-| Session cache | `~/.config/sqlew/session-cache/` |
-
-These paths are the same on all platforms (Windows, macOS, Linux).
-
-## Automatic Migration
-
-When the MCP server starts, it automatically migrates local databases to the global shared database under these conditions:
-
-- **SQLite only** — MySQL/PostgreSQL/Cloud users are not affected
-- **No explicit `database.path` in config** — If you set a custom path in `.sqlew/config.toml`, auto-migration is skipped
-- **`.sqlew/sqlew.db` exists** — Only the standard local DB location is migrated
-
-### What happens during auto-migration
-
-1. If the global DB **doesn't exist yet** → the local DB is copied directly (fastest path)
-2. If the global DB **already exists** → data is exported as JSON and imported (skip-if-exists per project)
-3. The local DB is renamed to `.sqlew/sqlew.db.migrated` (not deleted)
-
-### Safety net for merge path
-
-When merging into an existing global DB (case 2), if the import is skipped due to a project name conflict, a `pre-migration-export.json` file is saved in `.sqlew/`. This file is automatically deleted on successful import. If it remains, you can manually import it later:
-
-```bash
-sqlew db:import .sqlew/pre-migration-export.json
-```
-
-## Manual Migration
-
-If your project uses a custom database path (set via `database.path` in `.sqlew/config.toml`), auto-migration does not apply. You can manually migrate to the global shared database:
-
-### Step 1: Export from your current database
-
-```bash
-# Export current project (auto-detected from .sqlew/config.toml [project].name)
-sqlew db:export export.json
-
-# Or export all projects from the database
-sqlew db:export export.json project=all
-
-# Or specify the database path explicitly
-sqlew db:export export.json db-path=.claude/docs/sqlew.db project=all
-```
-
-### Step 2: Switch to global database
-
-Remove or comment out the `database.path` line in `.sqlew/config.toml`:
-
-```toml
-[database]
-# path = ".claude/docs/sqlew.db"    # commented out → uses global default
-```
-
-### Step 3: Import into global database
-
-```bash
-sqlew db:import export.json
-```
-
-The global database at `~/.config/sqlew/sqlew-shared.db` will be created automatically on the next MCP server startup if it doesn't exist yet.
-
-## Per-Project Database Override
-
-If you want to keep a project-specific database instead of using the global shared one, set `database.path` in that project's `.sqlew/config.toml`:
-
-```toml
-[database]
-path = ".sqlew/sqlew.db"    # project-local database
-```
-
-### Config priority
-
-```
-1. CLI --db-path argument          (highest)
-2. Project .sqlew/config.toml
-3. Worktree parent config
-4. Global ~/.config/sqlew/config.toml
-5. Default: ~/.config/sqlew/sqlew-shared.db  (lowest)
-```
-
-Project-level config always overrides global config, so you can use the global shared database by default and opt specific projects out as needed.
-
-## FAQ
-
-### Can I still use project-local databases?
-
-Yes. Set `database.path` in your project's `.sqlew/config.toml` and the global default is bypassed entirely.
-
-### What happens to my old `.sqlew/sqlew.db`?
-
-It's renamed to `.sqlew/sqlew.db.migrated` after successful migration. You can safely delete it once you've confirmed the global DB has your data.
-
-### What about MySQL/PostgreSQL users?
-
-No change. External database connections configured in `config.toml` work exactly as before.
-
-### Is data shared between projects?
-
-Yes, all projects using the default global database share the same `sqlew-shared.db` file. Each project's data is scoped by `project_id`, so there's no data mixing. This is the same model used when multiple projects connect to a shared MySQL/PostgreSQL instance.
+# Shared Database (v5.1.0+)
+
+As of v5.1.0, sqlew uses a **global shared database** by default instead of a per-project local database. This resolves the issue where git worktrees created isolated databases that couldn't share decisions.
+
+## Default Paths
+
+| Purpose | Path |
+|---------|------|
+| Database | `~/.config/sqlew/sqlew-shared.db` |
+| Config | `~/.config/sqlew/config.toml` |
+| Session cache | `~/.config/sqlew/session-cache/` |
+
+These paths are the same on all platforms (Windows, macOS, Linux).
+
+## Automatic Migration
+
+When the MCP server starts, it automatically migrates local databases to the global shared database under these conditions:
+
+- **SQLite only** — MySQL/PostgreSQL/Cloud users are not affected
+- **No explicit `database.path` in config** — If you set a custom path in `.sqlew/config.toml`, auto-migration is skipped
+- **`.sqlew/sqlew.db` exists** — Only the standard local DB location is migrated
+
+### What happens during auto-migration
+
+1. If the global DB **doesn't exist yet** → the local DB is copied directly (fastest path)
+2. If the global DB **already exists** → data is exported as JSON and imported (skip-if-exists per project)
+3. The local DB is renamed to `.sqlew/sqlew.db.migrated` (not deleted)
+
+### Safety net for merge path
+
+When merging into an existing global DB (case 2), if the import is skipped due to a project name conflict, a `pre-migration-export.json` file is saved in `.sqlew/`. This file is automatically deleted on successful import. If it remains, you can manually import it later:
+
+```bash
+sqlew db:import .sqlew/pre-migration-export.json
+```
+
+## Manual Migration
+
+If your project uses a custom database path (set via `database.path` in `.sqlew/config.toml`), auto-migration does not apply. You can manually migrate to the global shared database:
+
+### Step 1: Export from your current database
+
+```bash
+# Export current project (auto-detected from .sqlew/config.toml [project].name)
+sqlew db:export export.json
+
+# Or export all projects from the database
+sqlew db:export export.json project=all
+
+# Or specify the database path explicitly
+sqlew db:export export.json db-path=.claude/docs/sqlew.db project=all
+```
+
+### Step 2: Switch to global database
+
+Remove or comment out the `database.path` line in `.sqlew/config.toml`:
+
+```toml
+[database]
+# path = ".claude/docs/sqlew.db"    # commented out → uses global default
+```
+
+### Step 3: Import into global database
+
+```bash
+sqlew db:import export.json
+```
+
+The global database at `~/.config/sqlew/sqlew-shared.db` will be created automatically on the next MCP server startup if it doesn't exist yet.
+
+## Per-Project Database Override
+
+If you want to keep a project-specific database instead of using the global shared one, set `database.path` in that project's `.sqlew/config.toml`:
+
+```toml
+[database]
+path = ".sqlew/sqlew.db"    # project-local database
+```
+
+### Config priority
+
+```
+1. CLI --db-path argument          (highest)
+2. Project .sqlew/config.toml
+3. Worktree parent config
+4. Global ~/.config/sqlew/config.toml
+5. Default: ~/.config/sqlew/sqlew-shared.db  (lowest)
+```
+
+Project-level config always overrides global config, so you can use the global shared database by default and opt specific projects out as needed.
+
+## FAQ
+
+### Can I still use project-local databases?
+
+Yes. Set `database.path` in your project's `.sqlew/config.toml` and the global default is bypassed entirely.
+
+### What happens to my old `.sqlew/sqlew.db`?
+
+It's renamed to `.sqlew/sqlew.db.migrated` after successful migration. You can safely delete it once you've confirmed the global DB has your data.
+
+### What about MySQL/PostgreSQL users?
+
+No change. External database connections configured in `config.toml` work exactly as before.
+
+### Is data shared between projects?
+
+Yes, all projects using the default global database share the same `sqlew-shared.db` file. Each project's data is scoped by `project_id`, so there's no data mixing. This is the same model used when multiple projects connect to a shared MySQL/PostgreSQL instance.