Refactor Capabilities structure and enforce read-only mode

- Removed write and DDL capability flags from Capabilities struct.
- Updated methods to create capabilities to focus solely on read-only operations.
- Adjusted tests and integration points to reflect the new capabilities structure.
- Modified error messages to clarify that Plenum is strictly read-only.
- Ensured all database engines reject write and DDL operations uniformly.
- Cleaned up main.rs and MCP tool documentation to remove references to write/DDL capabilities.

Author: therecluse26

.plenum/config.json

@@ -1,9 +1,9 @@
 {
   "connections": {
-    "test-sqlite": {
+    "default": {
       "engine": "sqlite",
       "file": "/tmp/test.db"
     }
   },
-  "default": "test-sqlite"
+  "default": "default"
 }

CLAUDE.md

@@ -200,38 +200,43 @@ Stdout MUST NOT include logs or diagnostic text.
 
 ---
 
-## Capability Model
+## Read-Only Mode
 
-Read-only is the default mode (SELECT queries only).
+**Plenum is strictly read-only.** All write and DDL operations are prohibited.
 
-Operations requiring higher privileges are gated by explicit capability flags:
-- allow_write (enables INSERT, UPDATE, DELETE)
-- allow_ddl (enables CREATE, DROP, ALTER, etc.)
-- max_rows (limits result set size)
-- timeout_ms (limits execution time)
+Permitted operations:
+- `SELECT` queries
+- `SHOW`, `DESCRIBE`, `PRAGMA` statements (database-specific introspection)
+- `EXPLAIN` and `EXPLAIN ANALYZE`
+- Transaction control statements (BEGIN, COMMIT, ROLLBACK, SAVEPOINT, RELEASE)
 
-Violations MUST fail before query execution.
+Rejected operations:
+- `INSERT`, `UPDATE`, `DELETE` (write operations)
+- `CREATE`, `DROP`, `ALTER`, `TRUNCATE` (DDL operations)
+- Any other statement that modifies data or schema
 
-Capabilities are NEVER inferred.
+### Safety Constraints
 
-### Capability Hierarchy
+While Plenum does not allow write operations, it provides safety constraints for read operations:
+- `max_rows` (limits result set size to prevent overwhelming MCP token limits)
+- `timeout_ms` (limits execution time to prevent long-running queries)
 
-Capabilities follow a strict hierarchy:
-- **Read-only** (default): No flags needed, SELECT queries only
-- **Write**: Requires `--allow-write` flag, enables INSERT, UPDATE, DELETE
-- **DDL**: Requires `--allow-ddl` flag, enables DDL operations AND write operations
+**Examples:**
+- `plenum query --sql "SELECT * FROM users" --max-rows 100` → allowed
+- `plenum query --sql "INSERT INTO users ..." ` → DENIED (Plenum is read-only)
+- `plenum query --sql "CREATE TABLE ..." ` → DENIED (Plenum is read-only)
+- `plenum query --sql "SHOW TABLES"` → allowed
+- `plenum query --sql "EXPLAIN SELECT * FROM users"` → allowed
 
-**Important rules:**
-- `--allow-ddl` implicitly grants write permissions (DDL is a superset of write)
-- `--allow-write` does NOT enable DDL operations (DDL requires explicit flag)
-- Agents must explicitly request `--allow-ddl` even if write is already enabled
+### Agent Workflow for Write Operations
 
-**Examples:**
-- `plenum query --sql "SELECT ..."` → allowed (read-only default)
-- `plenum query --sql "INSERT ..." --allow-write` → allowed
-- `plenum query --sql "CREATE TABLE ..." --allow-write` → DENIED (needs --allow-ddl)
-- `plenum query --sql "CREATE TABLE ..." --allow-ddl` → allowed (DDL implies write)
-- `plenum query --sql "INSERT ..." --allow-ddl` → allowed (DDL implies write)
+When an agent determines that a write or DDL operation is needed:
+1. Use `plenum introspect` to understand the schema
+2. Use `plenum query` to read current data if needed
+3. Construct the appropriate SQL statement
+4. **Present the SQL to the user** in the response for manual execution
+
+Plenum will never execute write operations - this ensures all data modifications remain under human control.
 
 ---
 
@@ -288,25 +293,27 @@ Engine quirks stay inside engine modules.
 
 ## Security Model
 
-Plenum's security boundary is **capability enforcement**, not SQL validation.
+Plenum's security boundary is **read-only enforcement**, not SQL validation.
 
 ### Plenum Enforces:
-- Operation type restrictions (read-only, write, DDL)
-- Row limits and timeouts
+- Strict read-only operation (rejects all write/DDL operations)
+- Row limits and timeouts (for safety constraints)
 - Credential security (no logging/persistence in error messages or logs)
 
 ### Plenum Does NOT Enforce:
 - SQL injection prevention
 - Query semantic correctness
 - Business logic constraints
+- Row-level security or access control
 
 ### Agent Responsibility:
 The calling agent MUST:
 - Sanitize user inputs before constructing SQL
 - Validate queries for safety before passing to Plenum
 - Implement application-level security controls
+- Present write operations to users instead of attempting to execute them
 
-**Plenum assumes SQL passed to it is safe.** It provides capability constraints, not query validation.
+**Plenum assumes SQL passed to it is safe for reading.** It provides read-only enforcement and safety constraints, not query validation.
 
 ---
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plenum"
-version = "1.0.2"
+version = "1.5.0"
 edition = "2021"
 authors = ["Plenum Contributors"]
 license = "MIT OR Apache-2.0"

EXAMPLES.md

@@ -321,98 +321,57 @@ plenum query \
 
 Sets a 5-second timeout for query execution.
 
-### Write Query (INSERT)
+### Attempted Write Query (REJECTED)
+
+Plenum is strictly read-only. Write operations are rejected:
 
 ```bash
 plenum query \
   --name prod-db \
-  --sql "INSERT INTO logs (level, message) VALUES ('INFO', 'Application started')" \
-  --allow-write
+  --sql "INSERT INTO logs (level, message) VALUES ('INFO', 'Application started')"
 ```
 
-**Success Output:**
+**Error Output:**
 ```json
 {
-  "ok": true,
+  "ok": false,
   "engine": "postgres",
   "command": "query",
-  "data": {
-    "columns": [],
-    "rows": [],
-    "rows_affected": 1
-  },
-  "meta": {
-    "execution_ms": 45,
-    "rows_returned": 0
+  "error": {
+    "code": "CAPABILITY_VIOLATION",
+    "message": "Plenum is read-only and cannot execute this query. Please run this query manually:\n\nINSERT INTO logs (level, message) VALUES ('INFO', 'Application started')"
   }
 }
 ```
 
-### Write Query (UPDATE)
+**Agent Workflow:** When a write operation is needed:
+1. Use Plenum to introspect schema and read current data
+2. Construct the SQL statement
+3. Present it to the user for manual execution
+
+### Attempted DDL Query (REJECTED)
+
+DDL operations are also rejected:
 
 ```bash
 plenum query \
   --name prod-db \
-  --sql "UPDATE users SET last_login = CURRENT_TIMESTAMP WHERE id = 42" \
-  --allow-write
+  --sql "CREATE TABLE temp_results (id SERIAL PRIMARY KEY, value TEXT)"
 ```
 
-**Success Output:**
+**Error Output:**
 ```json
 {
-  "ok": true,
+  "ok": false,
   "engine": "postgres",
   "command": "query",
-  "data": {
-    "columns": [],
-    "rows": [],
-    "rows_affected": 1
-  },
-  "meta": {
-    "execution_ms": 52,
-    "rows_returned": 0
+  "error": {
+    "code": "CAPABILITY_VIOLATION",
+    "message": "Plenum is read-only and cannot execute this query. Please run this query manually:\n\nCREATE TABLE temp_results (id SERIAL PRIMARY KEY, value TEXT)"
   }
 }
 ```
 
-### Write Query (DELETE)
-
-```bash
-plenum query \
-  --name prod-db \
-  --sql "DELETE FROM temp_cache WHERE created_at < NOW() - INTERVAL '1 hour'" \
-  --allow-write
-```
-
-### DDL Query (CREATE TABLE)
-
-```bash
-plenum query \
-  --name prod-db \
-  --sql "CREATE TABLE temp_results (id SERIAL PRIMARY KEY, value TEXT)" \
-  --allow-ddl
-```
-
-**Note:** `--allow-ddl` implicitly grants write permissions.
-
-### DDL Query (CREATE INDEX)
-
-```bash
-plenum query \
-  --name prod-db \
-  --sql "CREATE INDEX idx_users_created_at ON users(created_at)" \
-  --allow-ddl
-```
-
-### DDL Query (DROP TABLE)
-
-```bash
-plenum query \
-  --name prod-db \
-  --sql "DROP TABLE IF EXISTS temp_results" \
-  --allow-ddl
-```
-
 ### Query from File
 
 ```bash
@@ -493,24 +452,21 @@ plenum query --name dest-db \
   --sql "SELECT id, email FROM users WHERE id NOT IN (SELECT id FROM source_users)"
 ```
 
-### Workflow 4: Temporary Table Workflow
+### Workflow 4: Read-Only Analysis
 
 ```bash
-# Create temporary table
-plenum query --name work-db \
-  --sql "CREATE TEMPORARY TABLE analysis_tmp (id INT, score REAL)" \
-  --allow-ddl
+# Plenum is read-only - complex queries should be constructed and run manually
+# Use Plenum to understand the schema first
+plenum introspect --name work-db > schema.json
 
-# Populate it
-plenum query --name work-db \
-  --sql "INSERT INTO analysis_tmp SELECT user_id, AVG(rating) FROM reviews GROUP BY user_id" \
-  --allow-write
+# Then construct your analysis query
+# Present this to the user for manual execution:
+# CREATE TEMPORARY TABLE analysis_tmp (id INT, score REAL);
+# INSERT INTO analysis_tmp SELECT user_id, AVG(rating) FROM reviews GROUP BY user_id;
 
-# Query results
+# After the user runs it manually, use Plenum to query results
 plenum query --name work-db \
   --sql "SELECT * FROM analysis_tmp WHERE score > 4.5"
-
-# No cleanup needed - temporary table drops when connection closes
 ```
 
 ### Workflow 5: Database Discovery (Wildcard Mode)
@@ -682,7 +638,9 @@ plenum introspect --name mysql-discovery
 
 ## Error Handling
 
-### Capability Violation (Missing --allow-write)
+### Read-Only Violation (Write Operation)
+
+Plenum rejects all write operations:
 
 ```bash
 plenum query --name prod-db \
@@ -697,17 +655,18 @@ plenum query --name prod-db \
   "command": "query",
   "error": {
     "code": "CAPABILITY_VIOLATION",
-    "message": "Write operations require --allow-write flag"
+    "message": "Plenum is read-only and cannot execute this query. Please run this query manually:\n\nUPDATE users SET email = 'test@example.com' WHERE id = 1"
   }
 }
 ```
 
-### Capability Violation (Missing --allow-ddl)
+### Read-Only Violation (DDL Operation)
+
+Plenum rejects all DDL operations:
 
 ```bash
 plenum query --name prod-db \
-  --sql "DROP TABLE users" \
-  --allow-write
+  --sql "DROP TABLE users"
 ```
 
 **Error Output:**
@@ -718,7 +677,7 @@ plenum query --name prod-db \
   "command": "query",
   "error": {
     "code": "CAPABILITY_VIOLATION",
-    "message": "DDL operations require --allow-ddl flag"
+    "message": "Plenum is read-only and cannot execute this query. Please run this query manually:\n\nDROP TABLE users"
   }
 }
 ```
@@ -880,7 +839,7 @@ diff source-schema.json dest-schema.json
 3. **Parse JSON output** - All Plenum output is valid JSON
 4. **Sanitize user inputs** - Plenum passes SQL verbatim to the database
 5. **Use named connections** - Avoid repeating connection parameters
-6. **Start read-only** - Only add `--allow-write` or `--allow-ddl` when necessary
+6. **Plenum is read-only** - Use it to introspect and query, then present write/DDL SQL to users for manual execution
 7. **Set max-rows for unknown queries** - Prevent accidentally fetching millions of rows
 8. **Use timeouts for expensive queries** - Protect against long-running operations