feat(seed): embedded LibreDB sample connection on first standalone startup (#97)

On first standalone startup, Studio auto-provisions an editable, dismissable 'Sample (LibreDB)' connection seeded with example data across all three lenses (relational table, document collection, raw key-value). Gated by LIBREDB_EMBEDDED_SAMPLE (default on); never appears in embedded/platform mode. Includes a general dismissed-seeds mechanism so a deleted sample stays gone.

Author: cevheri

.env.example

@@ -152,6 +152,14 @@ LLM_MODEL=gemini-2.5-flash
 # LLM_MODEL=local-model
 # LLM_API_URL=http://localhost:1234/v1
 
+# ─── LibreDB Embedded Sample ─────────────────────────────────────────────────
+# LibreDB embedded sample: on first standalone startup, auto-provide an editable
+# "Sample (LibreDB)" connection seeded with example data (one per lens). Default on.
+# Set to "false" to disable. Has no effect when embedded in libredb-platform.
+# LIBREDB_EMBEDDED_SAMPLE=true
+# Optional file path override (default: <data dir>/sample.libredb):
+# LIBREDB_EMBEDDED_SAMPLE_PATH=/app/data/sample.libredb
+
 # ─── Seed Connections (pre-configured databases) ─────────────────────────────
 # SEED_CONFIG_PATH=/app/config/seed-connections.yaml  # Path to seed config file
 # SEED_CACHE_TTL_MS=60000                              # Cache TTL in ms (default: 60s)

.gitignore

@@ -105,3 +105,9 @@ npmjs-token
 .token
 .sonar-token
 data/
+# Local Docker test volumes and any stray embedded-db files
+.docker-data*/
+*.libredb
+
+docs/superpowers/
+

docs/providers/libredb.md

@@ -252,6 +252,24 @@ file does not exist at `connect()` time, the `@libredb/libredb` package will cre
 ordered-KV store). If the path is missing entirely, `connect()` throws `DatabaseConfigError`
 before attempting to open anything.
 
+### 4.3 Sample connection (standalone mode)
+
+On the first startup of a **standalone** Studio instance (i.e. not embedded inside
+libredb-platform), Studio automatically creates a connection named **"Sample (LibreDB)"** seeded
+with example data covering each lens (relational table, document collection, raw kv). This gives
+new users a working LibreDB file to explore immediately.
+
+The sample connection is fully editable and deletable. Once deleted it stays gone — Studio tracks
+dismissed seeds and will not recreate it. It is never injected when Studio runs as an embedded
+package inside libredb-platform.
+
+**Env vars:**
+
+| Variable | Default | Notes |
+|----------|---------|-------|
+| `LIBREDB_EMBEDDED_SAMPLE` | `true` | Set to `"false"` to disable the sample connection entirely. |
+| `LIBREDB_EMBEDDED_SAMPLE_PATH` | `<data dir>/sample.libredb` | Optional override for the path of the generated sample file. |
+
 ---
 
 ## 5. Query interface