@hienlh/ppm 0.23.12 → 0.23.13

package/docs/architecture/data-and-storage.md

@@ -25,212 +25,148 @@ the loop seeded from the bus (windowed + rolling summary).
 
 ---
 
-## Database Management (v2.0+)
+## Database Management
 
-### Architecture Overview
+PPM manages external databases — SQLite files, PostgreSQL, MySQL and MariaDB — with a DBGate-style UI: a connection tree, a data grid (filter row, multi-column sort, editing saved as one script), Form view / Cell data / References, a Structure editor, Import/Export jobs and a multi-statement Query tab.
 
-PPM now supports managing external databases (SQLite & PostgreSQL) through a unified adapter pattern:
+### Layers
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Web UI (React)                               │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │ Database Sidebar                                         │   │
-│  │ • Connection List (with color badges)                    │   │
-│  │ • Create/Edit Connection Form                            │   │
-│  │ • Color Picker (WCAG contrast-aware)                     │   │
-│  │ • Query Execution UI                                     │   │
-│  └──────────────────────────────────────────────────────────┘   │
-└─────────────────┬───────────────────────────────────────────────┘
-                  │ HTTP REST / WebSocket
-┌─────────────────┴───────────────────────────────────────────────┐
-│                    PPM Server (Hono)                            │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │ /api/db Routes                                           │   │
-│  │ • GET  /connections        → List all connections        │   │
-│  │ • POST /connections        → Create connection           │   │
-│  │ • GET  /connections/:id    → Get connection (sanitized)  │   │
-│  │ • PUT  /connections/:id    → Update (readonly toggle)    │   │
-│  │ • DELETE /connections/:id  → Remove connection           │   │
-│  │ • GET  /connections/:id/tables      → List + sync tables │   │
-│  │ • GET  /connections/:id/tables/:tbl → Schema + data      │   │
-│  │ • POST /connections/:id/query       → Execute query      │   │
-│  │ • PATCH /connections/:id/cell       → Update cell        │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │ Service Layer                                            │   │
-│  │ • DbService (connection CRUD, caching)                   │   │
-│  │ • TableCacheService (metadata cache, search)             │   │
-│  │ • DatabaseAdapterRegistry (extensible)                   │   │
-│  └──────────────────────────────────────────────────────────┘   │
-│  ┌──────────────────────────────────────────────────────────┐   │
-│  │ Adapters (Pluggable Pattern)                             │   │
-│  │ • SQLiteAdapter → Uses `bun:sqlite` for local files      │   │
-│  │ • PostgresAdapter → Uses postgres driver for servers     │   │
-│  │ • isReadOnlyQuery() → Safety check (CTE-safe regex)      │   │
-│  │ • readonly=1 by default (safe-by-default)               │   │
-│  └──────────────────────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────────────────────┘
-        ↓↑
-   ┌────────────────────────────────────────────┐
-   │  External Databases                         │
-   │  • SQLite files (path: /path/to/db.db)      │
-   │  • PostgreSQL servers (connStr: postgres://)│
-   └────────────────────────────────────────────┘
+Browser — src/web/components/database/
+  connections-section/, explorer/, object-tree/   CONNECTIONS + TABLES, VIEWS, FUNCTIONS sidebar
+  table/, grid/                                   Glide data grid, filter row, Form view, Cell data, References
+  structure/, table-editor/, sql-object/          Structure tab, table editor, CREATE script tab
+  impexp/                                         Import/Export tab
+  query/                                          Query tab (Monaco, Messages + Result N, History)
+  connection-form/, db-login/                     connection tab, Database Log In dialog
+        │  REST under /api/db (PPM auth); the Query tab's runs stream NDJSON
+Routes — src/server/routes/database*.ts
+        │
+Services — src/services/database/
+  adapter-registry → sqlite-adapter / postgres-adapter / mysql-adapter
+  dialect-*.ts + grid-query-builder.ts            every grid SELECT is built on the server
+  changeset.service.ts, structure-edit.service.ts, ddl/   writes and DDL, one transaction each
+  impexp/                                         export and import jobs
+  query-script-runner.ts                          Query tab runs
+  drivers/                                        drivers installed from Settings
+        │
+postgres.service.ts (postgres.js) · mysql.service.ts (mysql2, installed on demand) · sqlite.service.ts (bun:sqlite)
 ```
 
-### DatabaseAdapter Pattern (Extensible)
+### Routes (`/api/db`)
 
-**Interface** (`src/types/database.ts`):
-```typescript
-interface DatabaseAdapter {
-  testConnection(config: DbConnectionConfig): Promise<{ ok: boolean; error?: string }>;
-  getTables(config: DbConnectionConfig): Promise<DbTableInfo[]>;
-  getTableSchema(config: DbConnectionConfig, table: string, schema?: string): Promise<DbColumnInfo[]>;
-  getTableData(config: DbConnectionConfig, table: string, opts: {...}): Promise<DbPagedData>;
-  executeQuery(config: DbConnectionConfig, sql: string): Promise<DbQueryResult>;
-  updateCell(config: DbConnectionConfig, table: string, opts: {...}): Promise<void>;
-}
-```
+| Area | Routes |
+|---|---|
+| Connections | `GET`/`POST /connections`, `GET`/`PUT`/`DELETE /connections/:id`, `GET /connections/:id/config`, `POST /connections/:id/duplicate`, `POST /connections/folder`, `GET /connections/export`, `POST /connections/import`, `POST /test`, `POST /connections/:id/test` |
+| Login | `POST /connections/:id/login`, `POST /connections/:id/disconnect` |
+| Tree | `GET /connections/:id/databases`, `/objects`, `/columns`, `/structure`, `/object-sql`, `/tables` (`?cached=1` reads PPM's own cache) |
+| Grid | `POST /connections/:id/grid`, `/grid/count`, `/grid/values`, `/grid/export`, `/grid/cell`; the export's file is `GET /grid-export/:ticket` |
+| Writes | `POST /connections/:id/changeset/preview`, `/changeset/apply` |
+| Structure | `POST /connections/:id/structure/preview`, `/structure/apply` |
+| Import/Export | `POST /connections/:id/impexp/export`, `/impexp/import`; `PUT /impexp/uploads`, `POST /impexp/uploads/:id/preview`, `DELETE /impexp/uploads/:id`, `GET /impexp/jobs/:id`, `POST /impexp/jobs/:id/stop`, `POST /impexp/jobs/:id/download` |
+| Query tab | `POST /connections/:id/query/script` (NDJSON), `POST /connections/:id/query/cancel`, `GET /connections/:id/history` |
+| Kept for the CLI, agents and SQL completion | `POST /connections/:id/query`, `GET /connections/:id/schema`, `/data`, `/export`, `PUT /connections/:id/cell`, the `/row` routes, `GET /search` |
+| Drivers | `GET /drivers`, `POST /drivers/:id/install`, `DELETE /drivers/:id`, `GET /ssh/agent` |
 
-**Implementations:**
-1. **SQLiteAdapter** — Local file-based SQLite via `bun:sqlite`
-   - testConnection: Opens file, runs pragma check
-   - Supports: SELECT, INSERT, UPDATE, DELETE (if writable), CREATE TABLE
+- `?database=` targets another database on the same server (the tree's database nodes). It is refused with 400 for a connection that uses only its own database, and for a database not in the connection's **Allowed databases** list (ignoring case; the connection's own database is always allowed). The allowed-databases regular expression only filters the tree: the server never runs a pattern the user typed. None of this is a permission: SQL typed in a Query tab, or a MySQL table named with its database, reaches whatever the login can.
+- A database **file** that is not a saved connection is served at `/connections/file/…?path=&project=`: the data routes only, with the path checked again on every request. Typed SQL on such a file returns at most 1,000 rows.
+- Before a route runs, a middleware answers **424** when the engine's driver is not installed and **428** when the connection asks for its password and no login is held.
 
-2. **PostgresAdapter** — Remote PostgreSQL servers via postgres driver
-   - testConnection: Attempts connection with credentials
-   - Supports: Full SQL except DDL on readonly connections
+### Dialects and the grid
 
-**Registry Pattern** (`src/services/database/adapter-registry.ts`):
-```typescript
-registerAdapter("sqlite", new SQLiteAdapter());
-registerAdapter("postgres", new PostgresAdapter());
-// Can be extended: registerAdapter("mysql", new MysqlAdapter());
-```
+- `dialect-*.ts` quote identifiers, page, cast and compare per engine. `grid-query-builder.ts` turns the grid's request — columns, DBGate filter syntax per column, multi-column sort, page — into one parameterised `SELECT`. The browser never sends SQL for the grid.
+- Rows come 100 at a time and **Fetch all** asks for the rest. `/grid/count` shows the engine's own estimate first and an exact `COUNT(*)` only if it finishes within 10 s (5 minutes when the user asks for an exact count), so a large table opens without waiting on a count.
+- Dates and times travel as text, as the database prints them — no conversion to ISO / UTC on the way.
+- Columns come from the driver's result metadata, never from `Object.keys` of a row, so `SELECT 1 a, 2 a` shows both columns.
 
-### Security Design
+### Writes: one changeset, one transaction
 
-**Readonly by Default:**
-- All connections created with `readonly = true` in database
-- Default: read-only query execution (safe-by-default)
-- Web UI toggle: Switch to writable (admin decision only)
-- CLI: Cannot disable readonly via command-line (browser only)
+- The grid collects edited cells, new rows and deleted rows into one changeset (with undo/redo). **Save** shows the script (`/changeset/preview`) and `/changeset/apply` runs every statement in **one transaction**. Rows are addressed by the table's whole primary key, multi-column keys included.
+- Deleting a row that other rows still reference offers **Delete references CASCADE**: the server walks the foreign keys (`listForeignKeys`) and deletes the referencing rows first, in the same transaction.
 
-**Readonly Query Detection:**
-```typescript
-// isReadOnlyQuery() in src/services/database/readonly-check.ts
-// Checks for: SELECT, PRAGMA, EXPLAIN, WITH (CTE)
-// Rejects: INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, etc.
-// CTE-safe: Handles "WITH AS SELECT" (wraps CTE result check)
-```
+### Readonly, enforced by the database
 
-**Credential Handling:**
-- Connection credentials stored in SQLite `connections` table as `connection_config` JSON
-- **NEVER** returned in API responses (stripped by `sanitizeConn()` in routes)
-- Only used internally by adapters when executing queries
-- Frontend never sees passwords/connection strings
+A connection is readonly by default (`connections.readonly = 1`). Two layers:
 
-**API Security:**
-- All `/api/db` requests require valid auth token (middleware checked)
-- Connection IDs are numeric (no enumeration risk)
-- Connection color is user-specific (cosmetic only, not sensitive)
+1. `isReadOnlyQuery()` refuses an obvious write before it is sent, and the audit log records it as `blocked`.
+2. The database refuses whatever gets past that check. PostgreSQL runs each statement inside `BEGIN READ ONLY`, always rolled back. MySQL / MariaDB sessions start with `SET SESSION TRANSACTION READ ONLY` and run statements inside `START TRANSACTION READ ONLY`. SQLite opens a `readonly` handle.
 
-### Data Flow: Query Execution
+The second layer is what stops writes hidden in a function call — `nextval`, `setval`, a function that writes — on every path, `ppm db query` included.
 
-```
-User opens Database tab
-    ↓
-DatabaseSidebar fetches: GET /api/db/connections
-    ↓
-ConnectionList displays (sanitized, no credentials)
-    ↓
-User clicks connection → GET /api/db/connections/:id/tables
-    ↓
-DbService.getConnections() reads from SQLite
-    ↓
-TableCacheService.syncTables() calls adapter.getTables()
-    ↓
-SQLiteAdapter/PostgresAdapter queries database
-    ↓
-Results cached in table_metadata table
-    ↓
-UI displays table list + schema
-    ↓
-User selects table → GET /api/db/connections/:id/tables/:table
-    ↓
-Adapter.getTableData() executes paginated query
-    ↓
-Results returned: { columns, rows, total, page, limit }
-    ↓
-UI renders table grid with pagination
-    ↓
-User executes custom query → POST /api/db/connections/:id/query
-    ↓
-isReadOnlyQuery() checks SQL (rejects writes if readonly=true)
-    ↓
-Adapter.executeQuery() runs SQL
-    ↓
-Results returned: { columns, rows, rowsAffected, changeType }
-    ↓
-UI displays results (read-only highlight if mutation was blocked)
-```
+### Structure editing
 
-### Connection Storage
+The Structure tab edits a table model. `ddl/table-diff.ts` compares it with the catalog, and `ddl/ddl-<engine>.ts` turns the difference into a plan that is previewed (`/structure/preview`) and applied (`/structure/apply`). SQLite can `ALTER` very little, so `ddl/sqlite-recreate.ts` follows SQLite's documented 12-step rebuild (new table, copy, drop, rename, indexes and triggers again, `foreign_key_check`) inside one transaction. New tables go through the same path. The SQL object tab shows an object's `CREATE` script (`/object-sql`).
 
-**SQLite Schema** (in `~/.ppm/ppm.db`):
-```sql
-CREATE TABLE accounts (
-  id TEXT PRIMARY KEY,
-  account_name TEXT NOT NULL,
-  encrypted_api_key TEXT NOT NULL,
-  priority INTEGER DEFAULT 0,
-  is_active INTEGER DEFAULT 0, -- 1 = active, 0 = inactive
-  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-  updated_at TEXT DEFAULT CURRENT_TIMESTAMP
-);
+### Import and Export
 
+- The grid's **Export ▾** streams the current view, filters and sort applied, as CSV, TSV, JSON, NDJSON, SQL `INSERT`s, XML or XLSX. A browser can only save a download it navigated to, and such a request carries no auth header, so the authenticated `POST /grid/export` answers with a ticket and the browser fetches `GET /grid-export/:ticket` — once, within 30 s.
+- The Import/Export tab runs **jobs** (`impexp/`): several tables at a time, per-format options, column mapping, then one file per table or, with **Create single file**, one XLSX workbook with a sheet per table — optionally zipped. Import reads uploaded CSV, JSON or JSON-lines files into new or existing tables. An export reads inside a READ ONLY transaction. A job is polled by id, can be stopped, and its file is fetched once.
+
+### Query tab
+
+- `POST /query/script` splits the script with `splitSqlScript` (it understands MySQL's `DELIMITER`) and runs it one statement at a time in a session of its own, so `SET`, temporary tables and `BEGIN` carry from one statement to the next. Each statement's result is sent as soon as it ends, as one NDJSON line (`start`, `running`, `statement`, `message`, `done`).
+- **Stop** (`/query/cancel` with the `runId` the browser chose) cancels only the running statement: postgres.js `cancel()` on PostgreSQL, `KILL QUERY` from another connection on MySQL / MariaDB. `bun:sqlite` cannot be interrupted mid-statement, so the runner yields between statements and Stop keeps the next one from starting.
+- A transaction the script leaves open is rolled back and reported. Results are cut at the tab's row limit on the server (closing the cursor, `sql_select_limit`, or `LIMIT N+1`), so the rest are never read.
+- History is read from the query audit log (`source = "editor"`); there is no separate store.
+
+### Connections and secrets
+
+```sql
+-- ~/.ppm/ppm.db (schema v56)
 CREATE TABLE connections (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
-  type TEXT NOT NULL, -- 'sqlite' | 'postgres'
-  name TEXT NOT NULL,
-  connection_config TEXT NOT NULL, -- JSON: { path, connectionString, ... }
-  readonly INTEGER DEFAULT 1, -- 1 = readonly, 0 = writable (UI-only toggle)
-  group_name TEXT,
-  color TEXT, -- Optional hex color (#3b82f6)
-  created_at TEXT DEFAULT CURRENT_TIMESTAMP,
-  updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+  type TEXT NOT NULL CHECK(type IN ('sqlite', 'postgres', 'mysql', 'mariadb')),
+  name TEXT NOT NULL UNIQUE,
+  connection_config TEXT NOT NULL,       -- encrypted StoredConnectionConfig
+  group_name TEXT,                       -- folder in the CONNECTIONS tree
+  color TEXT,
+  sort_order INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT, updated_at TEXT,
+  readonly INTEGER NOT NULL DEFAULT 1,
+  ai_access INTEGER NOT NULL DEFAULT 1   -- 0: `ppm db` run from an AI chat does not see it
 );
 
-CREATE TABLE table_metadata (
+CREATE TABLE connection_table_cache (
   id INTEGER PRIMARY KEY AUTOINCREMENT,
   connection_id INTEGER NOT NULL REFERENCES connections(id) ON DELETE CASCADE,
   table_name TEXT NOT NULL,
-  schema_name TEXT DEFAULT 'public',
-  row_count INTEGER,
-  last_synced TEXT,
-  UNIQUE(connection_id, table_name, schema_name)
+  schema_name TEXT NOT NULL DEFAULT 'public',
+  row_count INTEGER NOT NULL DEFAULT 0,
+  cached_at TEXT,
+  UNIQUE(connection_id, schema_name, table_name)
 );
 ```
 
-### CLI Support (ppm db)
+- `connection_config` is encrypted at rest and never sent to the browser, with one deliberate exception: **Export** (`GET /connections/export`) hands out every connection's config in plain text — database, SSH and SSL key passwords included — because Import recreates the connections from that file, and its menu says so. `GET /connections/:id/config` returns the form's fields with each secret replaced by a `has…` flag.
+- `StoredConnectionConfig` (`src/shared/db-connection-config.ts`) holds the URL or the host / port / user fields, `passwordMode` (`saved` or `ask`), `singleDatabase`, `allowedDatabases` (+ regex), `isolationLevel`, `queryTimeoutSec`, `ssh` and `ssl`.
+- **Ask for password**: the password is never stored. Database Log In holds the login in memory until **Disconnect**, which also closes the connection's pools.
+- **SSH tunnel**: password, key file or SSH agent. A host key is pinned on first use in PPM's own `known_hosts`. **SSL**: CA, client certificate and key files; `verify-full` checks the host name, an IP address included.
+- Migration 55 rebuilt `connections` to accept `mysql` / `mariadb`. Dropping the old table would have cascade-deleted `connection_table_cache`, so it runs with `PRAGMA foreign_keys = OFF` — set outside the transaction, where that pragma takes effect.
+
+### Drivers installed on demand
+
+MySQL / MariaDB (`mysql2`) and SSH tunnels (`ssh2`) are not bundled. **Settings → Database Drivers** (or `ppm db driver install <id>`) installs the pinned version with its pinned lockfile (`db-driver-locks.generated.json`) into `<ppm dir>/db-drivers/<id>`, and `db-driver-loader.ts` imports it from there.
+
+### Query audit
+
+Every statement PPM runs on a user database is logged in `<ppm dir>/query-audit.db`, with its source (`editor`, `grid`, `cli`, `filter`, `structure`, `export`, `import`), actor (human or agent), operation and status (`ok`, `error`, `blocked`). How long it is kept follows Settings (`query_audit.retention_days`, `max_size_mb`).
+
+### CLI (`ppm db`)
 
-**Commands** (`src/cli/commands/db-cmd.ts`):
 ```bash
-ppm db connections           # List all connections
-ppm db connect               # Add new connection (interactive)
-ppm db remove <name>         # Delete connection
-ppm db query <name> <sql>    # Execute query (respects readonly)
-ppm db run <name> <file>     # Execute SQL file (multi-statement, transactions)
-ppm db tables <name>         # List tables
-ppm db schema <name> <table> # Show table schema
-ppm db data <name> <table>   # Show table data (paginated)
+ppm db list                           # connections (hides ai_access = 0 inside an AI chat)
+ppm db add -n <name> -t <type> -c <url> | -f <file>
+ppm db remove <name>
+ppm db test <name>
+ppm db tables <name>
+ppm db schema <name> <table>
+ppm db data <name> <table>
+ppm db query <name> <sql>             # readonly enforced by the database
+ppm db run <name> <file>              # a multi-statement file
+ppm db driver list | install <id> | remove <id>
 ```
 
-**CLI Safety:**
-- Always respects readonly flag (cannot override via CLI)
-- Uses same adapter/validation as web UI
-- Table formatting for terminal output
+The CLI goes through the same adapters as the web UI, so readonly, the audit log and "ask for password" (a hidden prompt on the terminal) behave the same.
 
 ---
 

package/docs/architecture/integrations.md

@@ -97,9 +97,10 @@ ppm bot restart                                                   # Restart serv
 ppm bot help                                                      # Help
 ```
 
-**Settings UI (ppmbot-settings-section.tsx):**
-- Enable/disable PPMBot
-- Paired Telegram chats (approval management)
+**Settings UI (ppmbot-settings-section.tsx, Telegram part in ppmbot-telegram-section.tsx):**
+- PPMBot's own Telegram bot: token with the @BotFather steps, checked with Telegram (`getMe`) before it is kept
+- Turn on PPMBot (saved at once, `PUT /api/settings/clawbot { enabled }`), with whether it is running
+- Chats that can use PPMBot (Disconnect), Connect Telegram (single-use link + QR). The link is the only way in: PPMBot hands out no pairing codes, and a chat that writes to the bot without being connected is told once to connect it from Settings
 - Default project selection
 - System prompt customization
 - Task auto-refresh (poll interval, max history)
@@ -108,7 +109,14 @@ ppm bot help                                                      # Help
 **Legacy `clawbot` naming:** PPMBot replaced an earlier bot called ClawBot, but the config key and
 its REST surface were never renamed. `config.clawbot` (typed `PPMBotConfig`) and
 `GET|PUT /api/settings/clawbot` configure **PPMBot** — toggling `enabled` there starts or stops
-`ppmbotService`. The old `ClawBotService` / `ClawBotSessionService` / `ClawBotMemoryService` /
+`ppmbotService`. Its Telegram bot is `GET|PUT /api/settings/clawbot/telegram` (status, token) and
+`POST|DELETE /api/settings/clawbot/telegram/connect` (the one-time link).
+
+**Its own bot, not the notifications one:** PPMBot reads the bot in the `ppmbot_telegram` config row
+and answers the chats approved in `clawbot_paired_chats`; notifications send through `config.telegram`
+to the `telegram_notify_chats` row (`src/services/telegram-bots.ts`). They used to share both, so a
+chat connected for alerts could command PPMBot. An install that shared them is split once, on first
+read: alert chats are copied, and PPMBot keeps the shared token only if it was enabled. The old `ClawBotService` / `ClawBotSessionService` / `ClawBotMemoryService` /
 `ClawBotStreamerService` no longer exist; the implementation is `src/services/ppmbot/*`. Treat
 `clawbot` purely as a backward-compatible key name, not as a separate subsystem.
 

package/docs/architecture/workspace-and-ui.md

@@ -277,7 +277,7 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 
 **The design session** is an ordinary chat session whose `session_metadata.design_slug` is fixed at creation (`POST /chat/sessions` with `designSlug`, accepted only on a provider with `supportsDesignInstructions` — Claude and Codex). `chatService.prepareSendOptions` rebuilds the instruction block from the stored slug on every turn, whoever sends it (WebSocket, `ppm chat send`, scheduler, bots): Claude gets it appended to the `claude_code` preset, Codex as `developerInstructions` (`design-instructions.ts`). The permission mode defaults exactly as for a new chat (the provider's configured default, normally `bypassPermissions`), because a design agent reads and searches the project constantly and a stricter default asked on every file. A user who picks `acceptEdits` for a design session gets the tighter design policy: project file reads and writes are approved, shell and every other tool ask (`design-tool-policy.ts` for Claude, `workspace-write` + `untrusted` for Codex). Every `done`, and every terminal background task, schedules a `turn` snapshot 2 s later (`design-turn-snapshot.ts`). The tab keeps the session in design mode: a fork is swapped in place, `/clear` starts the next session in the same tab, the embedded history lists only this design's sessions, and opening a design session from anywhere focuses its design tab (`openSessionInItsTab`, `tabSessionId()` in `src/web/lib/tab-session-id.ts`).
 
-**The user's design instructions** (Settings → Design, `design-settings-section.tsx`; `GET/PUT /api/settings/design`, `src/server/routes/design-settings.ts`) are one global text (config row `design.instructions`, 8 KB UTF-8 cap, `design-settings.service.ts`). `design-user-section.ts` appends them after PPM's block, quoted in a `<user_design_instructions>` block under a statement that PPM's rules win. `/name` and `$name` mentions (`src/shared/design-skill-mentions.ts`) are resolved per session against the skills that provider can load (`design-skill-sources.ts`: Claude's slash discovery for the project narrowed to `.claude`, `CLAUDE_CONFIG_DIR` and plugins, since the Skill tool cannot run a `.codex`/`.ppm` skill the composer also lists; Codex's `skills/list` for the session's cwd and account): Claude is told to invoke the canonical name with the Skill tool, Codex to use `$name` (Codex's own mention syntax, the same rewrite `provider-skill-sigil.ts` does in chat). A name found nowhere is "not a skill, read it as text", any mention adds the ask-before-installing rule, and an unreadable list (an empty codex answer counts) marks the names unchecked; listing has a 5 s timeout and a 60 s back-off after a failure so a broken codex cannot spawn an app-server per turn. The editor reuses the composer's `SlashCommandPicker` and `slash-trigger.ts`. When nothing named resolves and no `ui-ux-pro-max` is installed, the pane (and a hint in New Design) shows the upstream install commands (`design-skill-suggestion.ts`); PPM never installs a skill. Claude snapshots its system prompt at a session's first request and Codex reads developer instructions on connect, so a change reaches new design chats; the section is cached per session and text. e2e `tests/e2e/design-settings-e2e.mjs`.
+**The user's design instructions** (Settings → Design, `design-settings-section.tsx`; `GET/PUT /api/settings/design`, `src/server/routes/design-settings.ts`) are one global text (config row `design.instructions`, 8 KB UTF-8 cap, `design-settings.service.ts`). `design-user-section.ts` appends them after PPM's block, quoted in a `<user_design_instructions>` block under a statement that PPM's rules win. `/name` and `$name` mentions (`src/shared/design-skill-mentions.ts`) are resolved per session against the skills that provider can load (`design-skill-sources.ts`: Claude's slash discovery for the project narrowed to `.claude`, `CLAUDE_CONFIG_DIR` and plugins, since the Skill tool cannot run a `.codex`/`.ppm` skill the composer also lists; Codex's `skills/list` for the session's cwd and account): Claude is told to invoke the canonical name with the Skill tool, Codex to use `$name` (Codex's own mention syntax, the same rewrite `provider-skill-sigil.ts` does in chat). A name found nowhere is "not a skill, read it as text", any mention adds the ask-before-installing rule, and an unreadable list (an empty codex answer counts) marks the names unchecked; listing has a 5 s timeout and a 60 s back-off after a failure so a broken codex cannot spawn an app-server per turn. The editor reuses the composer's `SlashCommandPicker` and `slash-trigger.ts`. When nothing named resolves and no `ui-ux-pro-max` is installed, the pane offers to install it (a hint in New Design points there): `POST /api/settings/design/skill` runs `design-skill-install.service.ts`, which downloads the `ui-ux-pro-max-cli` tarball pinned by version (`design-skill-suggestion.ts`) and SHA-256 (`DESIGN_SKILL_PACKAGE`) and writes exactly what upstream's `uipro init --ai <claude|codex> --global` writes, for each configured design provider — Claude's skills folder (`$CLAUDE_CONFIG_DIR/skills`, else `~/.claude/skills`), Codex's `~/.agents/skills` — never replacing a folder that is already there. The pane then names `/ui-ux-pro-max` in the instructions, saved at once unless the draft has unsaved edits. The upstream commands stay behind "Install it yourself instead"; the skill's scripts need Python 3, which PPM reports and does not install. `tests/e2e/design-skill-install-e2e.ts` compares the result with upstream's file for file. Claude snapshots its system prompt at a session's first request and Codex reads developer instructions on connect, so a change reaches new design chats; the section is cached per session and text. e2e `tests/e2e/design-settings-e2e.mjs`.
 
 **The canvas** (`src/server/routes/design-preview.ts`):
 - `POST /api/design-preview` (authenticated) mints a token for one design and one purpose. A canvas token lives 30 min idle and 8 h at most, and is extended only by authenticated refreshes; within the last hour a refresh rotates it. Print and standalone tokens last 10 min and cannot be refreshed. Unauthenticated content reads never extend a token (`design-preview-tokens.ts`).
@@ -358,6 +358,32 @@ Shell (bash/zsh) receives SIGWINCH signal
 Terminal state updated
 ```
 
+A terminal with no layout is never fitted. That covers the dock's active tab while the dock is hidden, which on a phone is every restore because the dock comes back collapsed, and any tab parked off-screen. FitAddon would propose its 2x1 floor for such a terminal, and zsh with a themed prompt aborts on the next keystroke after being redrawn that narrow. The server also drops any size below 20x2 (`src/shared/terminal-size.ts`). Until the terminal is shown, the shell keeps its last real size, or 80x24.
+
+### Terminal selection to chat
+
+A selection in the terminal offers the editor's two actions, Add to current chat and Add to new
+chat, in a small bar under the selection's last row (over its first row when there is no room
+under it), as Cursor shows its Add to Chat. `terminal-selection-chat.tsx` draws it; `useTerminal`
+hands it the xterm instance. Either action adds the selection as a context chip
+(`sendToChat({ asContext })`, label "Terminal selection") and clears it, which takes the bar away.
+On a phone the selection is made in select mode and the buttons are 44px tall.
+
+Four details are load-bearing:
+
+- xterm reports a selection on mouseup, never during the drag, so the bar does not chase the
+  pointer. But it says nothing about a selection identical to the last one it reported, and its
+  `clearSelection()` — which it also runs when the user types with something selected — does
+  not forget that one, so selecting the same text again showed no bar. The component therefore
+  also reads the selection on the mouseup that ends a press in the terminal, in the document the
+  terminal is in at that moment (a tab can move into a picture-in-picture window).
+- `getSelectionPosition()` is documented as 1-based and returns 0-based columns and buffer rows,
+  the end column exclusive; the e2e measures the bar against the rows it selected.
+- The bar is a sibling of xterm's container, not a child: in select mode that container turns
+  every touch into a selection gesture, which would swallow a tap on the buttons.
+- It is positioned by hand on xterm's `onRender`, which a scroll, a resize and new output all end
+  in, and hidden while none of the selection is in view.
+
 ---
 
 ## Git Integration Flow
@@ -392,6 +418,71 @@ GitService.status() returns:
 UI updates: "src/index.ts" moves from "Unstaged" to "Staged"
 ```
 
+### Source Control, Review changes and Git Graph — one flow
+
+The three are views of one thing, the working tree and the commit about to be made, and they read
+and write it through the same routes, so they cannot disagree about a rename, a conflict or the
+message being written.
+
+- **What is changed**: `GET /git/changes` (`src/services/git-changes/git-changes.service.ts`)
+  answers the branch (upstream, ahead/behind), the operation stopped part way (`git-operation.ts`
+  reads the rebase/merge/cherry-pick/revert markers in `--absolute-git-dir`, which in a linked
+  worktree is `.git/worktrees/<name>`), and one row per file with its blocks on both sides —
+  staged (HEAD → index) and open (index → working tree) — without their lines. One
+  `git status --porcelain=v2` names the files (`porcelain-v2.ts`), then at most one `git diff` per
+  side covers all of them, cut back into files while it streams (`diff-sections.ts`); untracked
+  files go through a throwaway index, at most 400 of them and 4 MB each, beyond which a file is one
+  whole-file block. Every diff uses `PATCH_DIFF_ARGS`, so a block's id is the fingerprint the hunk
+  routes (`src/services/git-hunks/`) resolve a request by. It runs with `GIT_OPTIONAL_LOCKS=0`: it
+  runs on a poll, and a refreshed index would take the lock from under the user's own
+  `git commit`. `GET /git/changes/file?path=` adds the lines of one file. Shapes in
+  `src/shared/git-changes.ts`.
+- **Writes**: blocks and lines are staged, unstaged and discarded through the hunk routes. Undo
+  last commit, publish, pull and the stash are `src/services/git-workflow/git-workflow.service.ts`
+  (pull adds `--no-rebase` only when the repository configures no strategy; stash apply/pop use
+  `--index` and first check the hash of `stash@{n}`). After every POST on the git router a
+  middleware emits `git:changed` (`git-events.ts`), relayed on `/ws/global`, failed commands
+  included; Source Control, the Review tab, the Git Graph and the status bar's poller
+  (`useGitChangesPoller`) read again about 300 ms later.
+- **Discard Undo**: `src/services/git-discard-journal/` keeps what a discard threw away in
+  `<ppm dir>/git-discards/<repo key>/` — the reversed patch for a block (Undo only while the file
+  is still exactly what the discard left), the bytes for a whole file, written before the discard
+  runs (Undo only while every file is still what the discard left) — for a day, 100 per
+  repository, nothing over 20 MB.
+- **One commit message per repository**: `src/services/git-commit-draft.service.ts` keeps it in
+  `chat_drafts` (session id `git-commit`, keyed by the repository's real path, left alone by
+  `deleteOrphaned`), behind `GET/PUT /git/commit-draft`; a change goes out as `git:commit-draft`
+  with the sender's client id, so the sender ignores its own echo. Browser side
+  `src/web/stores/commit-draft-store.ts` (saved 300 ms after the last keystroke) and
+  `src/web/hooks/use-commit-draft.ts`.
+- **Source Control**: `src/web/components/git/git-status-panel.tsx` with `git-branch-row.tsx`,
+  `git-commit-composer.tsx`, `git-change-row.tsx` / `git-change-tree.tsx`,
+  `git-operation-banner.tsx`, `git-stash-section.tsx` and `git-confirm.tsx`; data from
+  `src/web/hooks/use-git-changes.ts`, and the decisions (checkbox state, sync button, hints) as
+  pure functions in `src/web/lib/git-changes-view.ts`.
+- **Review changes**: the `git-review` tab type, one per project and repository
+  (`src/web/components/git-review/`, `src/web/hooks/use-git-review.ts`, opened through
+  `src/web/lib/open-git-review.ts`). `src/web/lib/git-review-model.ts` puts staged blocks, open
+  blocks and the tab's own discards in one list by the one coordinate they share, the line in the
+  index version of the file. Code lines reuse the session review's `review-tokens.tsx`.
+- **Git Graph** (`packages/ext-git-graph/`): the working tree, the blocks and the draft come from
+  PPM's routes (`ppm-git.ts`), and so do the writes of the inspector and the toolbar: stage,
+  unstage, discard and its Undo, commit and Undo last commit, Fetch, Pull, Push, Sync and Publish,
+  stash save, apply, pop and drop, and Abort/Continue. The rest still runs git itself (`spawnGit` in
+  `extension.ts`, `reflog-view.ts`, `rebase-view.ts`) and sends no `git:changed`: the commit,
+  branch, tag and stash menus (checkout, merge, rebase and its Skip, cherry-pick, revert, reset,
+  creating, renaming and deleting branches and tags, a branch from a stash, deleting a remote
+  branch), the Reflog and Rebase views, worktrees, submodule updates, remotes and the user name.
+  Source Control and the Review tab see those when the file watcher reports a change to the working
+  tree, or at their next 5 s poll; the status bar at its next 10 s one. A write that bypasses the
+  routes is heard by nobody until then — the toolbar's Fetch once ran `git fetch` itself and left
+  the status bar on "synced" for up to 10 s. The webview's script is built from the
+  `webview-script-*.ts` modules into one `<script>`. Its file icons are the app's: the panel posts
+  `__ppm.fileIcons` with file names and `src/web/components/extensions/webview-file-icons.ts`
+  answers with each name's class and only the drawings those classes need, the light-theme ones
+  rewritten to `:root[data-ppm-theme="light"]`. Its 5 s poll also reads `for-each-ref` and
+  `stash list`, so a ref moved outside PPM triggers a full re-read.
+
 ---
 
 ## Frontend Performance Optimization (v0.9.86+)
@@ -410,7 +501,6 @@ UI updates: "src/index.ts" moves from "Unstaged" to "Staged"
 
 **3. Lazy Loading**
 - MarkdownRenderer lazy-loaded from 3 sites (reduces initial bundle)
-- CodeMirror on-demand in postgres-viewer
 - Mermaid diagram support loaded dynamically only when diagram syntax detected
 
 **4. Code Splitting (vite.config.ts)**
@@ -440,8 +530,8 @@ the **whole host filesystem** — not just registered project directories — th
 
 ### FS scope = auth boundary
 
-Every `/api/fs` route — including `docx-html`, `read`, `raw`, both SQLite doors — passes through
-one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching disk:
+Every `/api/fs` route — including `docx-html`, `read`, `raw` — and the database file door
+(`/api/db/connections/file/*`) pass through one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching disk:
 
 | Protection | Mechanism |
 |---|---|
@@ -449,7 +539,7 @@ one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching
 | Protected roots | `/`, drive roots (`C:\`), `$HOME` and the PPM dir itself refuse delete/rename/move as a source |
 | Download tokens | `/api/fs/download/token` issues a single-use, path-bound token; `/api/fs/raw` spends it on first use, rejects replay and any path mismatch |
 | Symlink safety | every op `lstat`s the entry itself (never follows to the target) so a link *to* a protected path can itself still be deleted, but nothing can read/write *through* one into the PPM dir |
-| SQL injection surface | the external-DB doors (`/api/fs/sqlite/*`) block `ATTACH`/`DETACH` by keyword scan (after stripping comments/string literals) before executing any query — the same class of guard the project-scoped `/sqlite` route also needed |
+| SQL injection surface | the database file door (`/api/db/connections/file/*`, a `.db` opened by its path) refuses `ATTACH`/`DETACH` by keyword scan (after stripping comments/string literals) before executing any query, for a file inside a project and one reached by absolute path alike |
 | No event-loop blocking | every op is `fs.promises`-based with bounded concurrency and a per-entry timeout — a dead network mount or sleeping USB drive cannot stall unrelated requests, which matters once scope is the whole disk instead of one project |
 
 ### API surface
@@ -462,7 +552,7 @@ one shared guard chain (`src/services/fs-path-guard.service.ts`) before touching
 | POST | `/api/fs/copy` \| `/move` \| `/rename` \| `/touch` \| `/mkdir` | Mutations, collision (`EEXIST`)/self-nesting (`EINVAL`) reported for the client to resolve |
 | DELETE | `/api/fs/delete` \| `/rmdir` | `{permanent?}` — OS trash (Recycle Bin / Trash / gio) by default, permanent on request |
 | POST/GET | `/api/fs/download/token` / `/api/fs/raw` | Single-use, path-bound download |
-| GET/POST | `/api/fs/sqlite/{tables,schema,data,query}` | External `.db` viewer — same shape as the project-scoped `/sqlite` route, `path` absolute, PPM dir refused |
+| GET/POST | `/api/db/connections/file/*?path=&project=` | A `.db` opened from a file tree or the editor — the saved-connection routes under the id `file`, the file named and checked on every request. A path relative to `project` must stay inside it; an absolute one returns at most 1,000 rows of typed SQL; the PPM dir is refused, symlinks followed (`src/services/database/file-database.ts`) |
 
 `host-info.service.ts` orchestrates three OS-specific provider sets (`src/services/host-info/`)
 behind a 60s cache with in-flight de-duplication (concurrent `?refresh=true` calls share one
@@ -583,3 +673,75 @@ restored on reload (see Persistence below).
   tab-host window's titlebar keeps the tab title captured at pop-out time.
 - **Mobile.** Pop-out and PiP are hidden entirely below `md` (`useIsMobile()`) — never a scaled-down
   window.
+
+### Selected editor code as chat context
+
+`editor-selection-context.tsx` draws nothing. It registers a code-action provider for every
+language (`"*"`) that answers only for its own editor's model and, when the selection holds
+non-whitespace text, offers Add to current chat and Add to new chat. Monaco draws the lightbulb and
+the menu, so the two actions sit beside whatever a language server offers — under "More Actions…",
+Monaco's group for an action with no kind — and Ctrl+. reaches them too. Where the bulb goes is
+Monaco's decision: on the line at column 1 when its indentation has room, else on an empty or
+indented neighbouring line, else in the glyph margin left of the line numbers. Standalone Monaco
+turns the glyph margin off (`editor.api2.js`), and the gutter bulb is then drawn nowhere, which is
+why `code-editor.tsx` sets `glyphMargin: true`.
+
+That margin is one line height per glyph lane in use, so with the bulb as the only glyph it is a
+single 19px lane and the bulb fills it flush against the editor's edge. `monaco-lightbulb-gutter.ts`
+holds a second lane open with two empty glyph-margin widgets on line 1 (the width follows the line
+using the most lanes), and `globals.css` moves the bulb to the middle of the two. Moving it with CSS
+alone does not work: Monaco hit-tests the gutter by x, so a bulb drawn over the line-number column
+opens its menu and the same click selects that whole line, replacing the selection. Three details
+are load-bearing. The widgets sit at zIndex -1, because Monaco draws one glyph per lane and line,
+highest first, widgets winning ties — at 0 the left one hides the bulb on line 1. They are widgets,
+not `persistLane` decorations: a glyph decoration on the bulb's line makes Monaco give up the gutter
+and draw the bulb over the text. And `lineNumbersMinChars: 3` gives back the width of the extra lane,
+so the code starts where it did.
+
+The action's arguments are a snapshot taken when the bulb is shown: file path, line range and the
+model's text in that range, unsaved edits included. Markdown fences are sized past the longest
+backtick run. Every mounted editor registers the same command id (`ppm.selection.addToChat`);
+Monaco's registry stacks registrations, so closing one editor leaves the command to the others.
+`sendToChat` adds the snapshot to the last selected chat of the file's project as an attachment
+without replacing its draft (never to another project's chat: with none of its own open, it opens
+one), or opens a new chat with a context chip. Lazy-mounted chats receive `pendingContexts` in tab
+metadata; their composer consumes those once without replacing the existing draft. Neither action
+sends a turn.
+
+Monaco's own rules apply: the bulb waits for every code-action provider, so a slow language server
+delays it; any provider registering resets it until the cursor moves; and code actions are off in a
+read-only editor, so a database-cell preview has no bulb.
+
+### Fix with AI and Explain with AI on editor problems
+
+`editor-fix-with-ai.tsx` is built the same way: a code-action provider for `"*"` that answers only
+for its own editor's model and draws nothing. Monaco hands every provider the markers touching the
+range it asks about (`context.markers`); when one of them is an error or a warning, the provider
+offers two quick fixes, Fix with AI and Explain with AI, both flagged `isAI`. That flag is all
+Monaco needs for the rest:
+
+- a sparkle beside each in its menu, under Quick Fix after the language server's own fixes
+  (Monaco sorts AI actions last, and keeps the provider's order among them);
+- the first AI action as a one-click link in the problem's hover. Monaco shows one there, which is
+  why Fix is listed before Explain, and asks providers for quick fixes only — hence
+  `kind: "quickfix"` rather than no kind;
+- a sparkle for the bulb: `lightbulbSparkle` beside other fixes, `sparkleFilled` when every fix on
+  offer is AI. Monaco runs a *lone* AI action straight from the bulb instead of opening its menu;
+  with Explain beside Fix there is never a lone one, so the bulb always opens the menu, as VS Code's
+  does with Copilot's pair. Dropping either action brings that auto-run back.
+
+The requests are a snapshot taken when the actions are offered: each problem as
+`line:column severity: message source(code)` in file order, then the model's text from three lines
+above the first to three below the last, under "Fix this problem in …:" or "Explain this problem in
+…, without changing any files:" — said outright because the chat it lands in may edit files. Both
+go through one command (`ppm.problems.askAi`) carrying the text, to a new chat, sent from there
+(`sendToChat({ newTab, autoSend })`). The new tab has not rendered when the command runs, so
+`sendOnceMounted` keeps addressing it until its composer acks — idle and empty, the composer sends
+the text itself — and leaves the text as the draft after 10 s, so a slow first load costs a
+keypress rather than the request.
+
+Markers come from the language server (`ppm-lsp`) and from Monaco's own JSON and CSS validators.
+Monaco's TypeScript diagnostics are always off (`monaco-builtin-typescript.ts`), so a TypeScript
+file has problems to fix only with LSP on. The LSP code-action request carries the server's own
+diagnostics for the range (`LspDocument.diagnostics`, as published, `data` included): servers find
+their fixes from that list, and typescript-language-server answers an empty one with none.