Improve documentation. (#119)

.github/workflows/release.yml

@@ -75,7 +75,7 @@ jobs:
 
       - name: Set package version from tag
         run: |
-          npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version
+          npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version --allow-same-version
           sed -i "s/const VERSION = '.*'/const VERSION = '${{ steps.version.outputs.VERSION }}'/" storm.mjs
         working-directory: storm-cli
 

docs/database-and-mcp.md

@@ -1,6 +1,6 @@
 # Database Connections & MCP
 
-The Storm CLI manages database connections and exposes them as MCP (Model Context Protocol) servers. This gives your AI tools direct access to your database schema — table definitions, column types, constraints, and foreign keys — without exposing credentials or actual data. The AI can use this structural knowledge to generate entities that match your schema, validate entities it just created, or understand relationships between tables before writing a query.
+The Storm CLI manages database connections and exposes them as MCP (Model Context Protocol) servers. This gives your AI tools direct access to your database schema (table definitions, column types, constraints, and foreign keys) without exposing credentials or actual data. The AI can use this structural knowledge to generate entities that match your schema, validate entities it just created, or understand relationships between tables before writing a query.
 
 ---
 
@@ -21,7 +21,7 @@ Database configuration in Storm has two layers: a **global connection library**
 
 Global connections store the actual credentials and connection details. Projects reference them by name through aliases. This separation means you configure a database once and reuse it across as many projects as you need. Changing a password or hostname in the global connection updates every project that references it.
 
-Each project alias becomes an MCP server that your AI tool can query. The alias `default` becomes `storm-schema`; any other alias like `reporting` becomes `storm-schema-reporting`. The Storm MCP server handles all supported dialects — PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2 — and the necessary drivers are installed automatically.
+Each project alias becomes an MCP server that your AI tool can query. The alias `default` becomes `storm-schema`; any other alias like `reporting` becomes `storm-schema-reporting`. The Storm MCP server handles all supported dialects — PostgreSQL, MySQL, MariaDB, Oracle, SQL Server, SQLite, and H2. The necessary drivers are installed automatically.
 
 ---
 
@@ -62,7 +62,7 @@ Use `storm db list` to see all global connections:
   localhost-legacy    (mysql://localhost:3306/legacy)
 ```
 
-To remove a connection, run `storm db remove localhost-legacy` (or just `storm db remove` for an interactive picker). Removing a global connection does not affect any project that already references it — the project alias simply becomes unresolvable until you point it at a different connection.
+To remove a connection, run `storm db remove localhost-legacy` (or just `storm db remove` for an interactive picker). Removing a global connection does not affect any project that already references it. The project alias simply becomes unresolvable until you point it at a different connection.
 
 ---
 
@@ -89,7 +89,7 @@ The alias determines the MCP server name. The convention is straightforward:
 | `reporting` | `storm-schema-reporting` |
 | `legacy` | `storm-schema-legacy` |
 
-You can add multiple connections to a single project by running `storm mcp add` repeatedly. Each one registers a separate MCP server, so your AI tool can query each database independently. This is useful when your application talks to more than one database — for example, a primary PostgreSQL for transactional data and an Oracle database for reporting.
+You can add multiple connections to a single project by running `storm mcp add` repeatedly. Each one registers a separate MCP server, so your AI tool can query each database independently. This is useful when your application talks to more than one database, for example a primary PostgreSQL for transactional data and an Oracle database for reporting.
 
 ### Listing project connections
 
@@ -125,7 +125,7 @@ When you run `storm init`, database configuration is part of the interactive set
 ? Connect to a local database? Yes
 ```
 
-If you say yes, it walks you through the same flow as `storm db add` (or lets you pick an existing global connection), including whether to enable data access. It then asks for an alias. After the first connection, it offers to add more. This lets you set up your full database configuration in a single `storm init` run — or you can skip it and add connections later with `storm mcp add`.
+If you say yes, it walks you through the same flow as `storm db add` (or lets you pick an existing global connection), including whether to enable data access. It then asks for an alias. After the first connection, it offers to add more. This lets you set up your full database configuration in a single `storm init` run, or you can skip it and add connections later with `storm mcp add`.
 
 ---
 
@@ -136,9 +136,9 @@ Real-world applications often work with more than one database. A project might
 ```
   .storm/databases.json              .mcp.json
   ┌───────────────────────────┐      ┌─────────────────────────────────┐
-  │  "default"  : "local-pg"  │ ───▶ │  storm-schema           (PG)   │
-  │  "reporting": "oracle-rpt"│ ───▶ │  storm-schema-reporting (ORA)  │
-  │  "legacy"   : "local-my"  │ ───▶ │  storm-schema-legacy    (MySQL)│
+  │  "default"  : "local-pg"  │ ───▶ │  storm-schema           (PG)    │
+  │  "reporting": "oracle-rpt"│ ───▶ │  storm-schema-reporting (ORA)   │
+  │  "legacy"   : "local-my"  │ ───▶ │  storm-schema-legacy    (MySQL) │
   └───────────────────────────┘      └─────────────────────────────────┘
 ```
 
@@ -182,27 +182,7 @@ Project-local connections are stored in `.storm/connections/` inside the project
 
 ## Directory Structure
 
-After setup, the file layout looks like this:
-
-```
-~/.storm/                          # global (machine-wide)
-├── package.json                   # npm package for driver installs
-├── node_modules/                  # database drivers (pg, mysql2, oracledb, etc.)
-├── server.mjs                     # MCP server script (shared by all connections)
-└── connections/
-    ├── localhost-shopdb.json       # { dialect, host, port, database, username, password, selectAccess }
-    └── staging-analytics.json
-
-<project>/
-├── .storm/                        # project-level (gitignored)
-│   ├── databases.json             # { "default": "localhost-shopdb", ... }
-│   └── connections/               # optional project-local connections
-│       └── test-h2.json
-├── .mcp.json                      # MCP server registrations (gitignored)
-└── CLAUDE.md                      # Storm rules (committed)
-```
-
-The `.storm/` directory and `.mcp.json` are gitignored because they contain machine-specific paths and credentials. The Storm rules and skills files are committed and shared with the team.
+Global connections are stored in `~/.storm/connections/`. Project-level configuration lives in `.storm/` inside your project directory. Both `.storm/` and `.mcp.json` are gitignored because they contain machine-specific paths and credentials.
 
 ---
 
@@ -221,7 +201,7 @@ This walks you through:
 3. Optionally enabling read-only data access
 4. Registering the MCP server with your AI tools
 
-No Storm rules, skills, or language-specific configuration is installed — just the database MCP server. Your AI tool gets `list_tables`, `describe_table`, and optionally `select_data`, regardless of what language or framework your project uses.
+No Storm rules, skills, or language-specific configuration is installed. Just the database MCP server. Your AI tool gets `list_tables`, `describe_table`, and optionally `select_data`, regardless of what language or framework your project uses.
 
 After setup, you can manage connections with `storm db` and `storm mcp` commands as described above.
 
@@ -258,7 +238,7 @@ When you enable data access for a connection, a third tool becomes available:
 
 If you answer No (the default), the MCP server exposes only `list_tables` and `describe_table`. The AI has full visibility into your database structure but cannot see any data.
 
-If you answer Yes, the AI can also query individual records using `select_data`. This is useful when sample data helps the AI make better decisions — for example, recognizing that a `status` column contains enum-like values, or that a `TEXT` column stores JSON. But it means **actual data from your database flows through the AI's context**. It is your responsibility to decide whether this is acceptable given the nature of your data.
+If you answer Yes, the AI can also query individual records using `select_data`. This is useful when sample data helps the AI make better decisions, for example recognizing that a `status` column contains enum-like values, or that a `TEXT` column stores JSON. But it means **actual data from your database flows through the AI's context**. It is your responsibility to decide whether this is acceptable given the nature of your data.
 
 The `selectAccess` setting is stored per connection in the connection JSON file. You can change it at any time by running `storm db config`.
 
@@ -285,7 +265,7 @@ Enabling data access does not give the AI the ability to write, modify, or delet
 
 **1. Structured queries, not SQL.** The AI never writes SQL. The `select_data` tool accepts a structured request — table name, column names, filter conditions, sort order, and row limit — and the MCP server builds the SQL internally. There is no code path that produces anything other than a `SELECT` statement. This is read-only by construction: the server cannot generate `INSERT`, `UPDATE`, `DELETE`, `DROP`, or any other write operation because it simply does not contain the code to do so.
 
-**2. Schema validation.** Every table and column name in a `select_data` request is validated against the actual database schema before any query is executed (case-insensitive — the server resolves the correct casing automatically). Unknown tables and columns are rejected. Filter operators are restricted to a fixed whitelist (`=`, `!=`, `<`, `>`, `<=`, `>=`, `LIKE`, `IN`, `IS NULL`, `IS NOT NULL`). Values are always parameterized — they never appear in the SQL string.
+**2. Schema validation.** Every table and column name in a `select_data` request is validated against the actual database schema before any query is executed (case-insensitive; the server resolves the correct casing automatically). Unknown tables and columns are rejected. Filter operators are restricted to a fixed whitelist (`=`, `!=`, `<`, `>`, `<=`, `>=`, `LIKE`, `IN`, `IS NULL`, `IS NOT NULL`). Values are always parameterized — they never appear in the SQL string.
 
 **3. Read-only database connections.** Independent of the query builder, the database connection itself is configured to reject writes at the driver or protocol level:
 
@@ -319,33 +299,59 @@ Even if the structured query builder had a bug that somehow produced a write sta
 
 ### `storm db` — Global connection library
 
-| Command | Description |
-|---------|-------------|
-| `storm db` | List all global connections |
-| `storm db add [name]` | Add a global database connection |
-| `storm db remove [name]` | Remove a global database connection |
-| `storm db config [name]` | Configure data access and table exclusions |
+#### `storm db`
+
+List all global connections with their dialect and host. Same as `storm db list`.
+
+#### `storm db add [name]`
+
+Add a new database connection to your global library. Walks you through dialect, host, port, database, credentials, and data access settings interactively. If `name` is provided, it is used as the connection name; otherwise Storm suggests one based on the host and database.
+
+Database drivers are installed automatically when you add your first connection of a given dialect. For example, adding a PostgreSQL connection installs the `pg` driver, and adding a MySQL connection later installs `mysql2` alongside it.
+
+#### `storm db remove [name]`
+
+Remove a connection from the global library. If `name` is omitted, shows an interactive picker. Does not affect project aliases that reference the connection; those aliases simply become unresolvable until you point them at a different connection.
+
+#### `storm db config [name]`
+
+Configure data access settings for a connection. This lets you:
+
+- Toggle read-only SELECT access on or off.
+- Exclude specific tables from data queries. Storm connects to the database, lists all tables, and presents a searchable checkbox list. You can type to filter, use Page Up/Down for large schemas, and press Space to toggle individual tables.
+
+Excluded tables still appear in `list_tables` and can be described with `describe_table`. Only `select_data` is restricted.
 
 ### `storm mcp` — Project MCP servers
 
-| Command | Description |
-|---------|-------------|
-| `storm mcp init` | Set up MCP database server (no Storm ORM required) |
-| `storm mcp` | Re-register MCP servers for all project connections |
-| `storm mcp add [alias]` | Add a database connection to this project |
-| `storm mcp list` | List project database connections with MCP server names |
-| `storm mcp remove [alias]` | Remove a database connection from this project |
+#### `storm mcp init`
+
+Standalone setup for the MCP database server, intended for projects that do not use Storm ORM. Walks you through AI tool selection, database connections, data access, and MCP registration. No Storm rules or language-specific configuration is installed.
+
+#### `storm mcp`
+
+Re-register all MCP servers defined in `.storm/databases.json` with your AI tools. Useful after switching branches, resetting editor config files, or when MCP registrations get out of sync.
+
+#### `storm mcp add [alias]`
+
+Add a database connection to this project by picking a global connection and assigning it an alias. The alias determines the MCP server name: `default` becomes `storm-schema`, anything else becomes `storm-schema-<alias>`. Run this command multiple times to add multiple databases to a single project.
+
+#### `storm mcp list`
+
+List all project database connections, showing each alias, the global connection it resolves to, the connection URL, and the corresponding MCP server name.
+
+#### `storm mcp remove [alias]`
+
+Remove a database connection from this project and unregister its MCP server from your AI tool's configuration. The global connection is not affected.
 
 ### Supported Databases
 
 The MCP server is a lightweight Node.js process that reads schema metadata. It uses native Node.js database drivers (not JDBC) to connect to the same databases your Storm application uses.
 
-| Database | Connection | Default Port |
-|----------|-----------|-------------|
-| PostgreSQL | TCP | 5432 |
-| MySQL | TCP | 3306 |
-| MariaDB | TCP | 3306 |
-| Oracle | TCP (thin mode) | 1521 |
-| SQL Server | TCP | 1433 |
-| SQLite | Direct file access (read-only) | — |
-| H2 | TCP (PG wire protocol, requires `-pgPort`) | 5435 |
+- **PostgreSQL** -- TCP on port 5432.
+- **MySQL** -- TCP on port 3306.
+- **MariaDB** -- TCP on port 3306. Uses the MySQL driver.
+- **Oracle** -- TCP in thin mode on port 1521. Does not require the Oracle Instant Client.
+- **SQL Server** -- TCP on port 1433.
+- **SQLite** -- Direct file access, opened read-only. No network connection needed.
+- **H2** -- TCP using the PG wire protocol on port 5435. Requires H2 to be started with the `-pgPort` flag.

docs/index.md

@@ -8,12 +8,8 @@ import TabItem from '@theme/TabItem';
 
 # ST/ORM
 
-:::info Built for AI
-Storm's concise API, strict conventions, and absence of hidden complexity make it optimized for AI-assisted development. Combined with AI skills and secure schema access via MCP, AI coding tools generate correct Storm code consistently. Install with `npm install -g @storm-orm/cli` and run `storm init` in your project. See [AI-Assisted Development](ai.md).
-:::
-
-:::tip Looking for a database MCP server for Python, Go, Ruby, or any other language?
-Storm's schema-aware MCP server works standalone — no Storm ORM required. Run `npx @storm-orm/cli mcp init` to give your AI tool access to your database schema and (optionally) read-only data, regardless of your tech stack. See [Using Without Storm ORM](database-and-mcp.md#using-without-storm-orm).
+:::tip Give your AI tool access to your database schema
+Storm includes a schema-aware MCP server that exposes your table definitions, column types, and foreign keys to AI coding tools like Claude Code, Cursor, Copilot and Codex. Run `npx @storm-orm/cli` for full Storm ORM support including AI skills, conventions, and schema access. Using Python, Go, Ruby, or another language? Run `npx @storm-orm/cli mcp init` to set up the MCP server standalone.
 :::
 
 **Storm** is a modern, high-performance ORM for Kotlin 2.0+ and Java 21+, built around a powerful SQL template engine. It focuses on simplicity, type safety, and predictable performance through immutable models and compile-time metadata.