docs: document libSQL CLI connection crash issue

Add detailed documentation for the libSQL CLI crash that blocks interactive
setup flows on libSQL deployments (ironclaw tool setup, ironclaw secret set,
ironclaw mcp auth).

- Add known issue comment to src/db/mod.rs create_secrets_store() documenting
  the "invalid connection string" crash on libSQL CLI subcommands
- Add related comments to src/cli/tool.rs init_secrets_store() and
  src/cli/mcp.rs get_secrets_store() functions
- Add to CLAUDE.md Current Limitations section as priority item #1
- Include workaround: manually read master key from /proc/PID/environ,
  encrypt secrets with AES-256-GCM, write directly to secrets table
- Root cause unknown: libSQL works fine in main process but fails when
  called from CLI subcommands (possibly path resolution, file permissions,
  or WAL mode conflicts)
- Related: #655 (libSQL backend gaps)

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

CLAUDE.md

@@ -647,14 +647,15 @@ Key test patterns:
 
 ## Current Limitations / TODOs
 
-1. **Domain-specific tools** - `marketplace.rs`, `restaurant.rs`, `taskrabbit.rs`, `ecommerce.rs` return placeholder responses; need real API integrations
-2. **Integration tests** - Need testcontainers setup for PostgreSQL
-3. **MCP stdio transport** - Only HTTP transport implemented
-4. **WIT bindgen integration** - Auto-extract tool description/schema from WASM modules (stubbed)
-5. **Capability granting after tool build** - Built tools get empty capabilities; need UX for granting HTTP/secrets access
-6. **Tool versioning workflow** - No version tracking or rollback for dynamically built tools
-7. **Full channel status view** - Gateway status widget exists, but no per-channel connection dashboard
-8. **Observability backends** - Only `log` and `noop` implemented; OpenTelemetry/Prometheus not yet supported
+1. **libSQL CLI connection crash** - `ironclaw tool setup` and `ironclaw secret set` crash with "invalid connection string" error on libSQL deployments. Blocks all interactive setup flows. Workaround: manually encrypt secrets via Python. See `src/db/mod.rs` `create_secrets_store()` doc comment. Related: #655 (libSQL backend gaps).
+2. **Domain-specific tools** - `marketplace.rs`, `restaurant.rs`, `taskrabbit.rs`, `ecommerce.rs` return placeholder responses; need real API integrations
+3. **Integration tests** - Need testcontainers setup for PostgreSQL
+4. **MCP stdio transport** - Only HTTP transport implemented
+5. **WIT bindgen integration** - Auto-extract tool description/schema from WASM modules (stubbed)
+6. **Capability granting after tool build** - Built tools get empty capabilities; need UX for granting HTTP/secrets access
+7. **Tool versioning workflow** - No version tracking or rollback for dynamically built tools
+8. **Full channel status view** - Gateway status widget exists, but no per-channel connection dashboard
+9. **Observability backends** - Only `log` and `noop` implemented; OpenTelemetry/Prometheus not yet supported
 
 ## Tool Architecture
 

src/cli/mcp.rs

@@ -627,6 +627,11 @@ async fn save_servers(
 }
 
 /// Initialize and return the secrets store.
+/// Get the secrets store for MCP authentication operations.
+///
+/// **Known Issue:** This function crashes with "invalid connection string" on libSQL deployments
+/// when called from `mcp auth` subcommands. See `src/db/mod.rs` `create_secrets_store()`
+/// documentation for details and workaround.
 async fn get_secrets_store() -> anyhow::Result<Arc<dyn SecretsStore + Send + Sync>> {
     let config = Config::from_env().await?;
 

src/cli/tool.rs

@@ -551,6 +551,10 @@ fn validate_tool_name(name: &str) -> anyhow::Result<()> {
 }
 
 /// Initialize the secrets store from environment config.
+///
+/// **Known Issue:** This function crashes with "invalid connection string" on libSQL deployments
+/// when called from `tool setup` or `secret set` subcommands. See `src/db/mod.rs` `create_secrets_store()`
+/// documentation for details and workaround.
 async fn init_secrets_store() -> anyhow::Result<Arc<dyn SecretsStore + Send + Sync>> {
     let config = Config::from_env().await?;
     let master_key = config.secrets.master_key().ok_or_else(|| {

src/db/mod.rs

@@ -96,6 +96,24 @@ pub async fn connect_from_config(
 /// This is the shared factory for CLI commands and other call sites that need
 /// a `SecretsStore` without going through the full `AppBuilder`. Mirrors the
 /// pattern of [`connect_from_config`] but returns a secrets-specific store.
+///
+/// ## Known Issue: libSQL CLI Connection Crash
+///
+/// Running `ironclaw tool setup` or `ironclaw secret set` crashes with an
+/// "invalid connection string" error when DATABASE_BACKEND=libsql. This blocks
+/// all interactive setup flows on libSQL deployments (the default for hosted agents).
+///
+/// **Workaround:** Manually read the master key from `/proc/PID/environ`, encrypt
+/// secrets with AES-256-GCM via Python ctypes, and write directly to the secrets table.
+///
+/// **Related Issue:** #655 (libSQL backend gaps)
+///
+/// **Root Cause:** Unclear; the local libSQL database opens fine for the main process,
+/// but CLI subcommands fail when calling `LibSqlBackend::new_local(path)`. Likely
+/// relates to path resolution, file permissions, or WAL mode conflicts in concurrent
+/// connection scenarios.
+///
+/// **TODO:** Debug why libSQL connection fails in CLI context while working in main.rs.
 pub async fn create_secrets_store(
     config: &crate::config::DatabaseConfig,
     crypto: Arc<crate::secrets::SecretsCrypto>,