diff --git a/CLAUDE.md b/CLAUDE.md
index e51177cb..a77575ea 100644
--- a/CLAUDE.md
+++ b/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
 
diff --git a/src/cli/mcp.rs b/src/cli/mcp.rs
index b13bf598..7e32b470 100644
--- a/src/cli/mcp.rs
+++ b/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?;
 
diff --git a/src/cli/tool.rs b/src/cli/tool.rs
index 752f4263..19f8f4d3 100644
--- a/src/cli/tool.rs
+++ b/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(|| {
diff --git a/src/db/mod.rs b/src/db/mod.rs
index d7e11c12..08475d1b 100644
--- a/src/db/mod.rs
+++ b/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>,