sqlrooms 0.1.0__tar.gz

sqlrooms-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+sqlrooms_uploads/
+sqlrooms.db
+sqlrooms.db.wal
+sqlrooms/web/static/

sqlrooms-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright 2025 SQLRooms Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sqlrooms-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: sqlrooms
+Version: 0.1.0
+Summary: Local-first SQLRooms project launcher for DuckDB worksheets and Mosaic dashboards.
+Project-URL: homepage, https://sqlrooms.com
+Project-URL: repository, https://github.com/sqlrooms/sqlrooms
+Author: SQLRooms Contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: duckdb<1.6.0,>=1.5.3
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyarrow>=17.0.0
+Requires-Dist: python-multipart>=0.0.27
+Requires-Dist: sqlrooms-server>=0.1.1
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: tomlkit>=0.13.0
+Requires-Dist: typer>=0.12.5
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: connectors
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'connectors'
+Requires-Dist: snowflake-connector-python>=4.3.0; extra == 'connectors'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2.0; extra == 'postgres'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=4.3.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# sqlrooms CLI
+
+Launch a local SQLRooms DuckDB project for adding data, authoring worksheets, and building Mosaic charts and dashboards.
+
+## Quick start
+
+```bash
+# From the repo root
+uvx sqlrooms \
+  ./sqlrooms.db
+```
+
+What happens:
+
+- Starts the DuckDB websocket backend (from `sqlrooms-server`) on a free local port.
+- Serves the SQLRooms worksheet UI on `http://localhost:4173`, or the next free port, and opens your browser (disable with `--no-open-browser`).
+- Drag-and-drop CSV, TSV, JSON, Parquet, and DuckDB files to load them into DuckDB; files are uploaded to a local `sqlrooms_uploads` folder and referenced by path.
+- UI state is stored in the SQLRooms meta namespace (default `__sqlrooms`) of the selected DuckDB file.
+
+## CLI flags
+
+- `DB_PATH` (positional): DuckDB project file to load/create (e.g. `sqlrooms ./my.db`). Required unless `--db-path` is provided.
+- `--db-path`: DuckDB database to use as a flag alternative. Pass a filepath to persist, or `:memory:` for an explicit temporary in-memory session.
+- `--host` / `--port`: HTTP host/port for the UI. The default bind address is `127.0.0.1`. If `--port` is omitted, `4173` or the next free port is chosen automatically.
+- `--ws-port`: WebSocket port for DuckDB queries. If omitted, a free port is chosen automatically.
+- `--experimental`: Enable experimental artifacts, blocks, commands, and agent tools.
+- `--experimental-sync`: Enable experimental sync (CRDT) over WebSocket (Loro). Requires `--experimental`.
+- `--ai-devtools`: Enable the AI session devtools button in the UI, including production-built UI bundles. Can also be set with `SQLROOMS_AI_DEVTOOLS=1`.
+- `--meta-db`: Optional path to a dedicated DuckDB file for SQLRooms meta tables (UI state + CRDT snapshots). If omitted, meta tables are stored in the main DB.
+- `--meta-namespace` (default `__sqlrooms`): Namespace for SQLRooms meta tables. If `--meta-db` is provided, used as ATTACH alias; otherwise used as a schema in the main DB.
+- `--no-open-browser`: Skip automatically opening the browser tab.
+- `--ui`: Optional path to a custom UI bundle directory (a Vite `dist/`). If omitted, uses the bundled default UI.
+- `--no-ui`: Start only the HTTP API server and DuckDB websocket backend; do not serve the bundled/static UI.
+- `--config`: Path to a SQLRooms TOML config file. Defaults to `~/.config/sqlrooms/config.toml` (`%APPDATA%\sqlrooms\config.toml` on Windows).
+- `--no-config`: Disable config file loading.
+
+`--host 0.0.0.0` is an advanced local-network mode. Only use it on trusted
+networks; it exposes the SQLRooms UI/API bind address beyond your loopback
+interface. The DuckDB websocket backend still enforces local-only connections
+unless you explicitly use external proxy settings.
+
+There is intentionally no `sqlrooms add`, `sqlrooms import`, or
+`sqlrooms doctor` command in the first public CLI. Drag-and-drop import is the
+supported first-launch path, and the release smoke checklist below covers the
+doctor-style checks for now.
+
+## Data persistence
+
+Tables created in the selected DuckDB file (or attached meta DB if `--meta-db` is provided):
+
+- `__sqlrooms.ui_state` (one row: `key='default'`)
+- `__sqlrooms.sync_rooms` (only used when `--experimental --experimental-sync` is enabled)
+
+Uploads go to `/api/upload`. Runtime config for the UI is exposed at `/api/config` / `/config.json`.
+
+## Manual smoke test
+
+Use this before release candidates to prove the first-launch path:
+
+```bash
+uv run --project python --package sqlrooms sqlrooms \
+  --no-open-browser \
+  ./smoke.duckdb
+```
+
+Then open the printed UI URL and verify:
+
+- The app starts without a database connection error.
+- Dragging `python/sqlrooms/tests/fixtures/cars.csv` into the data panel creates a `cars` table.
+- The uploaded CSV lands next to `smoke.duckdb` under `sqlrooms_uploads/`.
+- The data sidebar shows `main.cars` and does not show SQLRooms internal metadata.
+- A worksheet is created or selected automatically and contains a `cars` data-table explorer block.
+- Users can create worksheet and dashboard artifacts from the `New` menu without enabling `--experimental`.
+- Map, notebook, canvas, app, HTML app, pivot, and SQL query surfaces stay hidden unless `--experimental` is provided.
+- Restarting the same command with `./smoke.duckdb` restores the imported table and persisted workspace state.
+
+## Config file
+
+`sqlrooms` reads AI provider and connector settings from a TOML config file.
+AI settings changed in the CLI UI are saved back to this file automatically
+when config loading is enabled and the config file is writable:
+
+- macOS / Linux: `~/.config/sqlrooms/config.toml`
+- Windows: `%APPDATA%\sqlrooms\config.toml`
+
+Override with `--config <path>`, or disable with `--no-config`.
+
+Example config file:
+
+```toml
+[ai]
+default_provider = "openai"
+default_model = "gpt-5"
+
+[[ai.providers]]
+id = "openai"
+base_url = "https://api.openai.com/v1"
+api_key_env = "OPENAI_API_KEY"
+models = ["gpt-5", "gpt-4.1"]
+
+[[ai.providers]]
+id = "anthropic"
+base_url = "https://api.anthropic.com"
+api_key_env = "ANTHROPIC_API_KEY"
+models = ["claude-4-sonnet"]
+
+[[ai.custom_models]]
+model_name = "local-qwen"
+base_url = "http://localhost:11434/v1"
+api_key = "local-key"
+
+[ai.model_parameters]
+max_steps = 12
+additional_instruction = "Prefer short answers."
+
+[[db.connectors]]
+id = "postgres-local"
+engine = "postgres"
+title = "Postgres Local"
+host = "localhost"
+port = "5432"
+database = "postgres"
+user = "postgres"
+password = "postgres"
+
+[[db.connectors]]
+id = "snowflake-prod"
+engine = "snowflake"
+title = "Snowflake Prod"
+account = "your-account"
+user = "your-user"
+password = "your-password"
+warehouse = "your-warehouse"
+database = "your-database"
+schema = "your-schema"
+role = "your-role"
+authenticator = "externalbrowser"
+
+[[db.connectors]]
+id = "snowflake-dev"
+engine = "snowflake"
+title = "Snowflake Dev"
+account = "your-dev-account"
+user = "your-dev-user"
+warehouse = "your-dev-warehouse"
+```
+
+## Server-only mode (no UI)
+
+If you only want the DuckDB websocket server (no HTTP UI server), install/run `sqlrooms-server`:
+
+```bash
+uvx sqlrooms-server --db-path ./sqlrooms.db --port 4000
+```
+
+`sqlrooms-server` is also available as an alias console script.
+
+## Backend connectors (DbSlice bridge)
+
+Use these modes to run remote queries through backend connectors and materialize
+results into core DuckDB for downstream notebook cells.
+
+Install optional connector dependencies first:
+
+```bash
+# From python/sqlrooms
+uv sync --extra connectors
+# or install just one connector:
+uv sync --extra postgres
+uv sync --extra snowflake
+```
+
+### Postgres
+
+```bash
+uvx sqlrooms \
+  ./sqlrooms.db \
+  --ws-port 4000 \
+  --port 4173
+```
+
+### Snowflake
+
+```bash
+uvx sqlrooms \
+  ./sqlrooms.db \
+  --ws-port 4000 \
+  --port 4173
+```
+
+What this enables:
+
+- `sqlrooms` exposes connector bridge endpoints under `/api/db/*`.
+- Runtime connector metadata is exposed via `/api/config`, so frontend `DbSlice` auto-registers available backend connections.
+- Notebook SQL cells can select Postgres/Snowflake connectors from the connector dropdown.
+- Arrow payloads are materialized into DuckDB and can be queried downstream in the same session.
+
+Notes:
+
+- Configure connectors in `sqlrooms.toml` using `[[db.connectors]]` entries.
+- Connector libraries are optional extras (`postgres`, `snowflake`, or `connectors`).
+
+## Developer setup
+
+Local dev loop for the CLI and UI:
+
+1. Install deps and build the dedicated UI (from repo root):
+
+```bash
+pnpm install
+pnpm --filter sqlrooms-python build:ui
+# build outputs directly to python/sqlrooms/sqlrooms/web/static
+```
+
+2. Dev the Python CLI app from the repo root:
+
+```bash
+pnpm dev cli
+```
+
+This starts the Python API server on `http://127.0.0.1:4273` with `--no-ui`
+and the Vite UI on `http://localhost:4174`. If those ports are busy, the dev
+script selects the next free API and UI ports from separate ranges and points
+the Vite proxy at the selected API port. The auto-created dev database is named
+after the selected UI port, for example `sqlrooms-4174.db`.
+
+3. Run the Python API server on its own (optional):
+
+```bash
+cd python/sqlrooms
+pnpm dev
+```
+
+Tips:
+
+- Use `--no-open-browser` if you don’t want the static bundle auto-opened.
+- Use `--no-ui` when pairing the Python API server with the Vite UI dev server.
+- Rebuild the UI (`pnpm --filter sqlrooms-python build:ui`) when you want the Python server to serve new static assets.
+- `/api/config` reflects runtime config (AI providers/default model, DB bridge metadata, WS URL).

sqlrooms-0.1.0/README.md

@@ -0,0 +1,239 @@
+# sqlrooms CLI
+
+Launch a local SQLRooms DuckDB project for adding data, authoring worksheets, and building Mosaic charts and dashboards.
+
+## Quick start
+
+```bash
+# From the repo root
+uvx sqlrooms \
+  ./sqlrooms.db
+```
+
+What happens:
+
+- Starts the DuckDB websocket backend (from `sqlrooms-server`) on a free local port.
+- Serves the SQLRooms worksheet UI on `http://localhost:4173`, or the next free port, and opens your browser (disable with `--no-open-browser`).
+- Drag-and-drop CSV, TSV, JSON, Parquet, and DuckDB files to load them into DuckDB; files are uploaded to a local `sqlrooms_uploads` folder and referenced by path.
+- UI state is stored in the SQLRooms meta namespace (default `__sqlrooms`) of the selected DuckDB file.
+
+## CLI flags
+
+- `DB_PATH` (positional): DuckDB project file to load/create (e.g. `sqlrooms ./my.db`). Required unless `--db-path` is provided.
+- `--db-path`: DuckDB database to use as a flag alternative. Pass a filepath to persist, or `:memory:` for an explicit temporary in-memory session.
+- `--host` / `--port`: HTTP host/port for the UI. The default bind address is `127.0.0.1`. If `--port` is omitted, `4173` or the next free port is chosen automatically.
+- `--ws-port`: WebSocket port for DuckDB queries. If omitted, a free port is chosen automatically.
+- `--experimental`: Enable experimental artifacts, blocks, commands, and agent tools.
+- `--experimental-sync`: Enable experimental sync (CRDT) over WebSocket (Loro). Requires `--experimental`.
+- `--ai-devtools`: Enable the AI session devtools button in the UI, including production-built UI bundles. Can also be set with `SQLROOMS_AI_DEVTOOLS=1`.
+- `--meta-db`: Optional path to a dedicated DuckDB file for SQLRooms meta tables (UI state + CRDT snapshots). If omitted, meta tables are stored in the main DB.
+- `--meta-namespace` (default `__sqlrooms`): Namespace for SQLRooms meta tables. If `--meta-db` is provided, used as ATTACH alias; otherwise used as a schema in the main DB.
+- `--no-open-browser`: Skip automatically opening the browser tab.
+- `--ui`: Optional path to a custom UI bundle directory (a Vite `dist/`). If omitted, uses the bundled default UI.
+- `--no-ui`: Start only the HTTP API server and DuckDB websocket backend; do not serve the bundled/static UI.
+- `--config`: Path to a SQLRooms TOML config file. Defaults to `~/.config/sqlrooms/config.toml` (`%APPDATA%\sqlrooms\config.toml` on Windows).
+- `--no-config`: Disable config file loading.
+
+`--host 0.0.0.0` is an advanced local-network mode. Only use it on trusted
+networks; it exposes the SQLRooms UI/API bind address beyond your loopback
+interface. The DuckDB websocket backend still enforces local-only connections
+unless you explicitly use external proxy settings.
+
+There is intentionally no `sqlrooms add`, `sqlrooms import`, or
+`sqlrooms doctor` command in the first public CLI. Drag-and-drop import is the
+supported first-launch path, and the release smoke checklist below covers the
+doctor-style checks for now.
+
+## Data persistence
+
+Tables created in the selected DuckDB file (or attached meta DB if `--meta-db` is provided):
+
+- `__sqlrooms.ui_state` (one row: `key='default'`)
+- `__sqlrooms.sync_rooms` (only used when `--experimental --experimental-sync` is enabled)
+
+Uploads go to `/api/upload`. Runtime config for the UI is exposed at `/api/config` / `/config.json`.
+
+## Manual smoke test
+
+Use this before release candidates to prove the first-launch path:
+
+```bash
+uv run --project python --package sqlrooms sqlrooms \
+  --no-open-browser \
+  ./smoke.duckdb
+```
+
+Then open the printed UI URL and verify:
+
+- The app starts without a database connection error.
+- Dragging `python/sqlrooms/tests/fixtures/cars.csv` into the data panel creates a `cars` table.
+- The uploaded CSV lands next to `smoke.duckdb` under `sqlrooms_uploads/`.
+- The data sidebar shows `main.cars` and does not show SQLRooms internal metadata.
+- A worksheet is created or selected automatically and contains a `cars` data-table explorer block.
+- Users can create worksheet and dashboard artifacts from the `New` menu without enabling `--experimental`.
+- Map, notebook, canvas, app, HTML app, pivot, and SQL query surfaces stay hidden unless `--experimental` is provided.
+- Restarting the same command with `./smoke.duckdb` restores the imported table and persisted workspace state.
+
+## Config file
+
+`sqlrooms` reads AI provider and connector settings from a TOML config file.
+AI settings changed in the CLI UI are saved back to this file automatically
+when config loading is enabled and the config file is writable:
+
+- macOS / Linux: `~/.config/sqlrooms/config.toml`
+- Windows: `%APPDATA%\sqlrooms\config.toml`
+
+Override with `--config <path>`, or disable with `--no-config`.
+
+Example config file:
+
+```toml
+[ai]
+default_provider = "openai"
+default_model = "gpt-5"
+
+[[ai.providers]]
+id = "openai"
+base_url = "https://api.openai.com/v1"
+api_key_env = "OPENAI_API_KEY"
+models = ["gpt-5", "gpt-4.1"]
+
+[[ai.providers]]
+id = "anthropic"
+base_url = "https://api.anthropic.com"
+api_key_env = "ANTHROPIC_API_KEY"
+models = ["claude-4-sonnet"]
+
+[[ai.custom_models]]
+model_name = "local-qwen"
+base_url = "http://localhost:11434/v1"
+api_key = "local-key"
+
+[ai.model_parameters]
+max_steps = 12
+additional_instruction = "Prefer short answers."
+
+[[db.connectors]]
+id = "postgres-local"
+engine = "postgres"
+title = "Postgres Local"
+host = "localhost"
+port = "5432"
+database = "postgres"
+user = "postgres"
+password = "postgres"
+
+[[db.connectors]]
+id = "snowflake-prod"
+engine = "snowflake"
+title = "Snowflake Prod"
+account = "your-account"
+user = "your-user"
+password = "your-password"
+warehouse = "your-warehouse"
+database = "your-database"
+schema = "your-schema"
+role = "your-role"
+authenticator = "externalbrowser"
+
+[[db.connectors]]
+id = "snowflake-dev"
+engine = "snowflake"
+title = "Snowflake Dev"
+account = "your-dev-account"
+user = "your-dev-user"
+warehouse = "your-dev-warehouse"
+```
+
+## Server-only mode (no UI)
+
+If you only want the DuckDB websocket server (no HTTP UI server), install/run `sqlrooms-server`:
+
+```bash
+uvx sqlrooms-server --db-path ./sqlrooms.db --port 4000
+```
+
+`sqlrooms-server` is also available as an alias console script.
+
+## Backend connectors (DbSlice bridge)
+
+Use these modes to run remote queries through backend connectors and materialize
+results into core DuckDB for downstream notebook cells.
+
+Install optional connector dependencies first:
+
+```bash
+# From python/sqlrooms
+uv sync --extra connectors
+# or install just one connector:
+uv sync --extra postgres
+uv sync --extra snowflake
+```
+
+### Postgres
+
+```bash
+uvx sqlrooms \
+  ./sqlrooms.db \
+  --ws-port 4000 \
+  --port 4173
+```
+
+### Snowflake
+
+```bash
+uvx sqlrooms \
+  ./sqlrooms.db \
+  --ws-port 4000 \
+  --port 4173
+```
+
+What this enables:
+
+- `sqlrooms` exposes connector bridge endpoints under `/api/db/*`.
+- Runtime connector metadata is exposed via `/api/config`, so frontend `DbSlice` auto-registers available backend connections.
+- Notebook SQL cells can select Postgres/Snowflake connectors from the connector dropdown.
+- Arrow payloads are materialized into DuckDB and can be queried downstream in the same session.
+
+Notes:
+
+- Configure connectors in `sqlrooms.toml` using `[[db.connectors]]` entries.
+- Connector libraries are optional extras (`postgres`, `snowflake`, or `connectors`).
+
+## Developer setup
+
+Local dev loop for the CLI and UI:
+
+1. Install deps and build the dedicated UI (from repo root):
+
+```bash
+pnpm install
+pnpm --filter sqlrooms-python build:ui
+# build outputs directly to python/sqlrooms/sqlrooms/web/static
+```
+
+2. Dev the Python CLI app from the repo root:
+
+```bash
+pnpm dev cli
+```
+
+This starts the Python API server on `http://127.0.0.1:4273` with `--no-ui`
+and the Vite UI on `http://localhost:4174`. If those ports are busy, the dev
+script selects the next free API and UI ports from separate ranges and points
+the Vite proxy at the selected API port. The auto-created dev database is named
+after the selected UI port, for example `sqlrooms-4174.db`.
+
+3. Run the Python API server on its own (optional):
+
+```bash
+cd python/sqlrooms
+pnpm dev
+```
+
+Tips:
+
+- Use `--no-open-browser` if you don’t want the static bundle auto-opened.
+- Use `--no-ui` when pairing the Python API server with the Vite UI dev server.
+- Rebuild the UI (`pnpm --filter sqlrooms-python build:ui`) when you want the Python server to serve new static assets.
+- `/api/config` reflects runtime config (AI providers/default model, DB bridge metadata, WS URL).

sqlrooms-0.1.0/node_modules/sqlrooms-cli-app/README.md

@@ -0,0 +1,166 @@
+# SQLRooms CLI UI
+
+This package is the **Vite/React UI** that powers the Python `sqlrooms` CLI (`python/sqlrooms`).
+
+In development it runs as a separate dev server (default `http://localhost:4174`) and **proxies API calls** to the Python server.
+
+In production (published `sqlrooms` wheel), the UI is served as **static assets** bundled into the Python package at:
+
+- `python/sqlrooms/sqlrooms/web/static/`
+
+## Local CLI smoke test
+
+For local pre-publish testing, run the workspace package directly rather than
+assuming `sqlrooms` is installed globally:
+
+```bash
+cd /Users/ilya/Workspace/sqlrooms
+
+pnpm --dir python/sqlrooms build
+
+uv run --project python --package sqlrooms sqlrooms \
+  ./smoke.duckdb \
+  --no-open-browser
+```
+
+Open the UI URL printed in the terminal. It should be
+`http://127.0.0.1:4173` or the next free port.
+
+The bare CLI command works only after installing the CLI somewhere on your
+`PATH`:
+
+```bash
+uv tool install /Users/ilya/Workspace/sqlrooms/python/sqlrooms
+sqlrooms ./smoke.duckdb --no-open-browser
+```
+
+For release smoke testing, verify both local execution paths:
+
+```bash
+uv run --project python --package sqlrooms sqlrooms ./smoke.duckdb --no-open-browser
+uv tool install --reinstall /Users/ilya/Workspace/sqlrooms/python/sqlrooms
+sqlrooms ./smoke.duckdb --no-open-browser
+```
+
+In the UI, drag in:
+
+```text
+/Users/ilya/Workspace/sqlrooms/python/sqlrooms/tests/fixtures/cars.csv
+```
+
+Verify `cars` appears, create a worksheet/Mosaic chart/dashboard, stop the
+server, restart the same command, and confirm the state comes back.
+
+## Dev mode (UI + Python server together)
+
+From the repo root:
+
+```bash
+pnpm dev cli
+```
+
+This starts:
+
+- the Python API server on `http://127.0.0.1:4273` without serving static UI, or the next free port
+- the Vite UI on `http://localhost:4174`, or the next free port, proxying `/api` and `/config.json` to the selected Python API port
+- a per-session dev database named after the selected UI port, for example `sqlrooms-4174.db`
+
+If you want fixed ports, pass them to the Python server:
+
+```bash
+pnpm dev cli -- --port 4176 --ws-port 4002
+```
+
+## Dev mode (separate terminals)
+
+Terminal A (Python server):
+
+```bash
+cd python/sqlrooms
+pnpm dev -- --no-ui
+```
+
+Terminal B (UI):
+
+```bash
+pnpm --filter sqlrooms-cli-app dev -- --host --port 4174
+```
+
+The Python package dev helper uses API port `4173` by default to match the
+Vite proxy. If you pass a different Python API port, also set
+`SQLROOMS_CLI_API_PROXY_TARGET` when starting Vite.
+
+## Build the bundled UI (for the Python wheel)
+
+From the repo root:
+
+```bash
+pnpm --filter sqlrooms-cli-app build
+```
+
+This builds the UI into `apps/sqlrooms-cli-ui/dist`.
+
+To copy it into the Python package bundle directory (so the published `sqlrooms` wheel can serve it), run:
+
+```bash
+cd python/sqlrooms
+pnpm build:ui
+```
+
+## Dashboard Layouts
+
+Dashboard artifacts are created with either a `dock` or `grid` Mosaic dashboard
+layout. Explicit dashboard creation commands and AI tools require `layoutType`
+so the choice is made once at creation time; auto-created dashboards from chart
+or Data Table Explorer flows use `grid`.
+
+## Worksheet Artifacts
+
+Worksheet artifacts are block-composed documents for active analytical work.
+They can contain editable text, images, standalone Mosaic/vgplot chart blocks, and
+direct stateful blocks such as dashboards, pivot tables, Data Table Explorers,
+SQL queries, and Markdown documents.
+
+Standalone chart blocks reuse the same Mosaic chart view and settings panel as
+dashboard charts. Charts with the same `selectionGroupId` in one Worksheet share
+a crossfilter selection; charts without a group are independent.
+Agent-created blocks can persist an `intent` string describing the purpose they
+were created to serve, which helps later edits distinguish durable intent from
+raw model input.
+
+Hosted dashboards are stored as direct stateful blocks keyed by their block
+instance id. Each hosted dashboard keeps its own Mosaic dashboard state and
+selection scope, so multiple dashboards in one Worksheet crossfilter
+independently.
+
+Hosted SQL queries reuse the `@sqlrooms/sql-editor` single-query block surface.
+The same query block can also be opened as a top-level SQL Query artifact tab.
+
+## HTML App Revision History
+
+Generated `html-app` artifacts and worksheet HTML app blocks store source
+revisions in `@sqlrooms/app-runtime` state. The CLI registers these room
+commands for palette and AI surfaces:
+
+- `html-app.restore-revision`
+- `html-app.undo-revision`
+- `html-app.redo-revision`
+
+Commands accept an optional `appId`. If omitted, the CLI resolves only a clearly
+selected top-level `html-app` artifact or a single known HTML app runtime.
+Ambiguous worksheet cases fail with a clear message so the caller can ask the
+user to select the target block. Chat undo/redo should execute these commands
+instead of mutating app state through hidden paths or rewriting chat messages.
+
+## AI Artifact Context
+
+The assistant captures selected artifact context at run start. The first
+selected item is the primary context artifact unless the run context carries an
+explicit `primaryItemId`.
+
+Direct AI tools can list and read context artifacts with
+`list_context_artifacts` and `read_context_artifact`. Mutating tools should pass
+an explicit `artifactId`; if omitted, dashboard chart tools only use an
+unambiguous primary dashboard. Reference artifacts are not implicit mutation
+targets. `set_primary_context_artifact` updates the current run and session
+context when the assistant creates or switches to a new primary artifact.