Add AI setup. (#93) (#102)

Author: zantvoort

docs/ai-setup.md docs/ai.mddocs/ai-setup.md renamed to docs/ai.md

@@ -128,7 +128,6 @@ Storm's design principles align naturally with how AI coding tools operate:
 | Design Choice | Why it helps AI |
 |---------------|-----------------|
 | **Immutable entities** | No hidden state transitions for the AI to track or miss |
-| **Explicit SQL** | The generated SQL is visible and predictable; the AI can reason about queries directly |
 | **No proxies** | The entity class *is* the entity; no invisible bytecode transformations to account for |
 | **No persistence context** | No session scope, flush ordering, or detachment rules that require deep framework knowledge |
 | **Convention over configuration** | Fewer annotations and config files for the AI to keep consistent |

docs/index.md

@@ -8,8 +8,8 @@ import TabItem from '@theme/TabItem';
 
 # ST/ORM
 
-:::info Built for the AI Era
-Storm's immutable design, skills, and secure MCP schema access make it the ORM that AI coding tools get right consistently. Install with `npm install -g @storm-orm/cli`, then run `storm init` in your project. See [AI-Assisted Development](ai-setup.md).
+:::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).
 :::
 
 **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.

storm-cli/storm.mjs

@@ -316,7 +316,7 @@ async function checkbox({ message, choices }) {
         const label  = atCursor  ? boltYellow(choices[i].name) : choices[i].name;
         out += `\x1b[2K  ${prefix} ${check} ${label}\n`;
       }
-      out += `\x1b[2K${dimText('  Space to toggle, Enter to confirm')}`;
+      out += `\x1b[2K${dimText('  Space to toggle, Enter to confirm')}\n`;
       linesWritten = choices.length + 2;
       stdout.write(out);
     }
@@ -558,19 +558,10 @@ async function fetchRules() {
   }
 }
 
-async function fetchSchemaRules() {
-  try {
-    const res = await fetch(`${SKILLS_BASE_URL}/storm-schema-rules.md`);
-    if (!res.ok) throw new Error(`${res.status}`);
-    return await res.text();
-  } catch {
-    return null;
-  }
-}
 
-async function fetchSkillIndex() {
+async function fetchSkillIndex(language) {
   try {
-    const res = await fetch(`${SKILLS_BASE_URL}/index.json`);
+    const res = await fetch(`${SKILLS_BASE_URL}/index-${language}.json`);
     if (!res.ok) throw new Error(`${res.status}`);
     return await res.json();
   } catch {
@@ -1107,16 +1098,6 @@ function registerMcp(toolConfig, stormDir, created, appended) {
   (isNew ? created : appended).push(toolConfig.mcpFile);
 }
 
-async function installSchemaRules(toolConfig, created, appended) {
-  const schemaRules = await fetchSchemaRules();
-  if (!schemaRules) return;
-
-  // Install as a skill file so all tools learn about the MCP tools.
-  if (toolConfig.skillPath) {
-    const content = `${STORM_SKILL_MARKER} storm-schema-rules -->\n${schemaRules}`;
-    installSkill('storm-schema-rules', content, toolConfig, created);
-  }
-}
 
 // ─── Database setup ──────────────────────────────────────────────────────────
 
@@ -1225,8 +1206,11 @@ async function setup() {
   await printWelcome();
 
   // Step 1: Select AI tools.
+  console.log('  Storm installs rules and skills for your AI coding tools.');
+  console.log('  Select the tools you use in this project.');
+  console.log();
   const tools = await checkbox({
-    message: 'Select AI tools to configure',
+    message: 'Which AI tools do you use?',
     choices: [
       { name: 'Claude Code',     value: 'claude',   checked: true },
       { name: 'Cursor',          value: 'cursor' },
@@ -1241,6 +1225,24 @@ async function setup() {
     return;
   }
 
+  // Step 1b: Select language(s).
+  console.log();
+  console.log('  Storm provides language-specific skills for entity creation,');
+  console.log('  repositories, queries, and SQL templates.');
+  console.log();
+  const languages = await checkbox({
+    message: 'Which language(s) does this project use?',
+    choices: [
+      { name: 'Kotlin',                                  value: 'kotlin', checked: true },
+      { name: 'Java (requires --enable-preview on JDK 21)', value: 'java' },
+    ],
+  });
+
+  if (languages.length === 0) {
+    console.log(boltYellow('\nNo language selected. Run again when ready.'));
+    return;
+  }
+
   console.log();
 
   // Step 2: Fetch and install rules.
@@ -1249,13 +1251,16 @@ async function setup() {
   const skipped  = [];
 
   console.log(dimText('  Fetching content from https://orm.st...'));
-  const [stormRules, skillIndex] = await Promise.all([fetchRules(), fetchSkillIndex()]);
+  const fetchPromises = [fetchRules(), ...languages.map(l => fetchSkillIndex(l))];
+  const [stormRules, ...skillIndexes] = await Promise.all(fetchPromises);
   if (!stormRules) {
     console.log(boltYellow('\n  Could not fetch Storm rules from https://orm.st. Check your connection.'));
     return;
   }
-  const skillNames = skillIndex?.skills ?? [];
-  const schemaSkillNames = skillIndex?.schemaSkills ?? [];
+
+  // Merge skill lists from all selected languages (deduplicated).
+  const skillNames = [...new Set(skillIndexes.flatMap(idx => idx?.skills ?? []))];
+  const schemaSkillNames = [...new Set(skillIndexes.flatMap(idx => idx?.schemaSkills ?? []))];
 
   for (const toolId of tools) {
     const config = TOOL_CONFIGS[toolId];
@@ -1291,10 +1296,15 @@ async function setup() {
   let stormDir = null;
 
   if (mcpTools.length > 0) {
+    console.log();
+    console.log('  Storm can connect to your local development database so AI tools');
+    console.log('  can read your schema (tables, columns, foreign keys) and generate');
+    console.log('  entities automatically. Credentials are stored locally and never');
+    console.log('  exposed to the AI.');
     console.log();
     const connectDb = await confirm({
-      message: 'Connect to a local database for schema-aware assistance?',
-      defaultValue: false,
+      message: 'Connect to a local database?',
+      defaultValue: true,
     });
 
     if (connectDb) {
@@ -1304,12 +1314,28 @@ async function setup() {
     }
   }
 
-  // Step 5: Register MCP and install schema skills for each tool.
+  // Step 5: Register MCP, append schema rules, and install schema skills.
   if (dbConfigured) {
+    // Fetch schema rules and append to each tool's rules block.
+    const schemaRules = await fetchSkill('storm-schema-rules');
     for (const toolId of tools) {
       const config = TOOL_CONFIGS[toolId];
       registerMcp(config, stormDir, created, appended);
-      await installSchemaRules(config, created, appended);
+      if (config.rulesFile && schemaRules) {
+        const rulesPath = join(process.cwd(), config.rulesFile);
+        if (existsSync(rulesPath)) {
+          const existing = readFileSync(rulesPath, 'utf-8');
+          // Insert schema rules inside the STORM block if not already present.
+          if (!existing.includes('Database Schema Access')) {
+            const endMarker = existing.indexOf(MARKER_END);
+            if (endMarker !== -1) {
+              const updated = existing.substring(0, endMarker) + '\n' + schemaRules.replace(/^<!-- storm-managed: \S+ -->\n/, '') + '\n' + existing.substring(endMarker);
+              writeFileSync(rulesPath, updated);
+              appended.push(config.rulesFile);
+            }
+          }
+        }
+      }
     }
 
     // Fetch and install schema-dependent skills.
@@ -1359,7 +1385,7 @@ async function setup() {
   } else {
     console.log(`  ${boltYellow('Quick start:')} Your AI tools now know Storm's patterns and conventions.`);
   }
-  console.log(`  ${dimText('Learn more:')}   https://orm.st/ai-setup`);
+  console.log(`  ${dimText('Learn more:')}   https://orm.st/ai`);
   console.log();
 }
 
@@ -1381,7 +1407,7 @@ async function run() {
     --help, -h               Show this help message
     --version, -v            Show version
 
-  ${dimText('Learn more:')}  https://orm.st/ai-setup
+  ${dimText('Learn more:')}  https://orm.st/ai
 `);
     return;
   }

website/scripts/generate-llms-full.sh

@@ -64,7 +64,7 @@ DOCS=(
   faq.md
   migration-from-jpa.md
   glossary.md
-  ai-setup.md
+  ai.md
   # API Reference
   api-kotlin.md
   api-java.md

website/static/llms-full.txt

@@ -14,7 +14,7 @@
 > GitHub: https://github.com/storm-orm/storm-framework
 > License: Apache 2.0
 
-# Generated: 2026-03-22T21:20:08Z
+# Generated: 2026-03-23T08:27:40Z
 
 ========================================
 ## Source: index.md
@@ -23,7 +23,7 @@
 # ST/ORM
 
 > **Info:**
-Storm's immutable design, skills, and secure MCP schema access make it the ORM that AI coding tools get right consistently. Install with `npm install -g @storm-orm/cli`, then run `storm init` in your project. See [AI-Assisted Development](ai-setup.md).
+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).
 
 **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.
 
@@ -18449,7 +18449,7 @@ A window of query results from a scrolling operation. A `Window<R>` contains the
 
 
 ========================================
-## Source: ai-setup.md
+## Source: ai.md
 ========================================
 
 # AI-Assisted Development
@@ -18571,7 +18571,6 @@ Storm's design principles align naturally with how AI coding tools operate:
 | Design Choice | Why it helps AI |
 |---------------|-----------------|
 | **Immutable entities** | No hidden state transitions for the AI to track or miss |
-| **Explicit SQL** | The generated SQL is visible and predictable; the AI can reason about queries directly |
 | **No proxies** | The entity class *is* the entity; no invisible bytecode transformations to account for |
 | **No persistence context** | No session scope, flush ordering, or detachment rules that require deep framework knowledge |
 | **Convention over configuration** | Fewer annotations and config files for the AI to keep consistent |

website/static/skills/index-java.json

@@ -0,0 +1,16 @@
+{
+  "skills": [
+    "storm-setup",
+    "storm-docs",
+    "storm-entity-java",
+    "storm-repository-java",
+    "storm-query-java",
+    "storm-sql-java",
+    "storm-migration"
+  ],
+  "schemaSkills": [
+    "storm-schema",
+    "storm-validate",
+    "storm-entity-from-schema"
+  ]
+}

website/static/skills/index.json website/static/skills/index-kotlin.jsonwebsite/static/skills/index.json renamed to website/static/skills/index-kotlin.json

@@ -1,14 +1,11 @@
 {
   "skills": [
+    "storm-setup",
     "storm-docs",
     "storm-entity-kotlin",
-    "storm-entity-java",
     "storm-repository-kotlin",
-    "storm-repository-java",
     "storm-query-kotlin",
-    "storm-query-java",
     "storm-sql-kotlin",
-    "storm-sql-java",
     "storm-migration"
   ],
   "schemaSkills": [

website/static/skills/storm-rules.md

@@ -4,7 +4,21 @@ This project uses the [Storm ORM framework](https://orm.st) for database access.
 Storm is a modern SQL Template and ORM for Kotlin 2.0+ and Java 21+, built around
 immutable data classes and records instead of proxied entities.
 
-Use the Storm skills for detailed guidance on entities, repositories, queries, and more.
+If the project does not yet have Storm dependencies in its build file (pom.xml,
+build.gradle.kts), use /storm-setup to help the user configure their project.
+Detect the project's Kotlin or Java version from the build file to recommend the
+correct dependencies and compiler plugin version.
+
+Available Storm skills:
+- /storm-setup - Help configure Maven/Gradle dependencies
+- /storm-docs - Load full Storm documentation
+- /storm-entity-kotlin or /storm-entity-java - Create entities
+- /storm-repository-kotlin or /storm-repository-java - Write repositories
+- /storm-query-kotlin or /storm-query-java - Write queries with the QueryBuilder
+- /storm-sql-kotlin or /storm-sql-java - Write SQL Templates
+- /storm-migration - Write Flyway/Liquibase migration SQL
+
+When the user asks about Storm topics, suggest the relevant skill if they need detailed guidance.
 
 Quick reference: https://orm.st/llms.txt
 Full documentation: https://orm.st/llms-full.txt

website/static/skills/storm-setup.md

@@ -0,0 +1,47 @@
+Help the user set up Storm ORM in their project.
+
+Fetch https://orm.st/llms-full.txt for complete reference (see the Installation section).
+
+Before suggesting dependencies, read the project's build file (pom.xml, build.gradle.kts, or build.gradle) to detect:
+- Build tool (Maven or Gradle)
+- Language and version (Kotlin version from kotlin plugin, Java version from sourceCompatibility/release)
+- Existing dependencies (Spring Boot, database driver, etc.)
+- Fetch the latest Storm version from https://repo1.maven.org/maven2/st/orm/storm-bom/maven-metadata.xml
+
+Core dependencies:
+
+Kotlin (Gradle):
+- `implementation(platform("st.orm:storm-bom:<version>"))`
+- `implementation("st.orm:storm-kotlin")`
+- `runtimeOnly("st.orm:storm-core")`
+- `ksp("st.orm:storm-metamodel-ksp")`
+- `kotlinCompilerPluginClasspath("st.orm:storm-compiler-plugin-<kotlin-major.minor>")`
+  Match the suffix to the project's Kotlin version: 2.0.x uses storm-compiler-plugin-2.0, 2.1.x uses storm-compiler-plugin-2.1, etc.
+
+Java (Maven):
+- Import `st.orm:storm-bom` in dependencyManagement
+- `st.orm:storm-java21`
+- `st.orm:storm-core` (runtime scope)
+- `st.orm:storm-metamodel-processor` (provided scope)
+- Requires `--enable-preview` in maven-compiler-plugin and maven-surefire-plugin
+
+Spring Boot:
+- Kotlin: `st.orm:storm-kotlin-spring-boot-starter`
+- Java: `st.orm:storm-spring-boot-starter`
+- These replace the core module and include auto-configuration
+
+Serialization (pick one if needed):
+- `st.orm:storm-kotlinx-serialization` for kotlinx-serialization
+- `st.orm:storm-jackson2` for Jackson 2 (Spring Boot 3.x)
+- `st.orm:storm-jackson3` for Jackson 3 (Spring Boot 4+)
+
+Database dialects (add as runtime dependency):
+- `st.orm:storm-postgresql`
+- `st.orm:storm-mysql`
+- `st.orm:storm-mariadb`
+- `st.orm:storm-oracle`
+- `st.orm:storm-mssqlserver`
+
+After configuring dependencies, remind the user to rebuild so the metamodel classes are generated.
+
+Do not hardcode versions. Always fetch the latest from Maven Central or use the version already in the project's BOM.