From ab97ac1c296ffb1acd144fccbc40366615c6e541 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:16:14 +0100
Subject: [PATCH 01/47] Initial commit: wasp-plugins marketplace with
 wasp-claude-tools

Includes:
- wasp-claude-tools plugin with documentation caching hooks and setup skills
- 3 skills: setup-wizard, deploying-app, adding-wasp-knowledge-claude
- Hooks for automatic doc caching and WebFetch interception

Documentation is cached dynamically at runtime via SessionStart hook.
---
 .claude-plugin/marketplace.json               |  31 +++
 .gitignore                                    |   7 +
 README.md                                     |  94 +++++++++
 .../.claude-plugin/plugin.json                |  16 ++
 plugins/wasp-claude-tools/LICENSE             |  21 ++
 plugins/wasp-claude-tools/README.md           |  66 +++++++
 .../hooks/block-wasp-html-docs.js             |  57 ++++++
 .../hooks/cache-all-wasp-docs-async.js        |  24 +++
 .../hooks/cache-all-wasp-docs.js              |  23 +++
 plugins/wasp-claude-tools/hooks/hooks.json    |  25 +++
 .../hooks/wasp-docs-cache-utils.js            | 137 ++++++++++++++
 .../adding-wasp-knowledge-claude/SKILL.md     |  11 ++
 .../example-section-link.md                   |  11 ++
 .../general-wasp-knowledge.md                 |  86 +++++++++
 .../wasp-conventions.md                       | 179 ++++++++++++++++++
 .../skills/deploying-app/SKILL.md             |  25 +++
 .../validating-pre-deployment.md              | 101 ++++++++++
 .../skills/setup-wizard/SKILL.md              | 126 ++++++++++++
 18 files changed, 1040 insertions(+)
 create mode 100644 .claude-plugin/marketplace.json
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 plugins/wasp-claude-tools/.claude-plugin/plugin.json
 create mode 100644 plugins/wasp-claude-tools/LICENSE
 create mode 100644 plugins/wasp-claude-tools/README.md
 create mode 100644 plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js
 create mode 100644 plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js
 create mode 100644 plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js
 create mode 100644 plugins/wasp-claude-tools/hooks/hooks.json
 create mode 100644 plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js
 create mode 100644 plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md
 create mode 100644 plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md
 create mode 100644 plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
 create mode 100644 plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md
 create mode 100644 plugins/wasp-claude-tools/skills/deploying-app/SKILL.md
 create mode 100644 plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md
 create mode 100644 plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..255428c
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,31 @@
+{
+  "name": "wasp-plugins",
+  "owner": {
+    "name": "Wasp",
+    "email": "info@wasp-lang.dev",
+    "url": "https://github.com/wasp-lang/wasp"
+  },
+  "metadata": {
+    "description": "Official Wasp framework plugins for Claude Code",
+    "version": "1.0.0",
+    "pluginRoot": "./plugins"
+  },
+  "plugins": [
+    {
+      "name": "wasp-claude-tools",
+      "source": "./plugins/wasp-claude-tools",
+      "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
+      "version": "1.0.0",
+      "author": {
+        "name": "Wasp",
+        "email": "info@wasp-lang.dev",
+        "url": "https://wasp.sh"
+      },
+      "repository": "https://github.com/wasp-lang/claude-plugins",
+      "license": "MIT",
+      "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication"],
+      "category": "frameworks",
+      "tags": ["wasp", "full-stack", "web-development"]
+    }
+  ]
+}
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..204b5b2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,7 @@
+# OS files
+.DS_Store
+Thumbs.db
+
+# Local development
+.env
+.env.local
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..41ee932
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+# Wasp Claude Code Plugins
+
+Official [Claude Code](https://claude.ai/code) plugins for the [Wasp](https://wasp.sh) full-stack web framework.
+
+## Installation
+
+### Add the marketplace
+
+```bash
+/plugin marketplace add wasp-lang/claude-plugins
+```
+
+### Install a plugin
+
+```bash
+/plugin install wasp-claude-tools@wasp-plugins
+```
+
+Or browse available plugins interactively:
+
+```bash
+/plugin
+```
+
+## Available Plugins
+
+### wasp-claude-tools
+
+Comprehensive Wasp development assistant with:
+
+- **Documentation Caching**: Automatically caches Wasp documentation locally for fast access and offline use
+- **Setup Wizard**: Interactive guided setup for configuring new Wasp app projects
+- **Deployment Guide**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
+- **Knowledge Integration**: Add Wasp best practices and conventions to your project's CLAUDE.md
+
+#### Skills included:
+
+| Skill | Description |
+|-------|-------------|
+| `setup-wizard` | Interactive guided setup for new Wasp projects |
+| `deploying-app` | Deploy to Railway or Fly.io with validation |
+| `adding-wasp-knowledge-claude` | Add Wasp conventions to CLAUDE.md |
+
+#### Recommended permissions:
+
+Add these to your project settings for the best experience:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(wasp start)",
+      "Bash(wasp db:*)",
+      "WebFetch(domain:wasp.sh)"
+    ]
+  }
+}
+```
+
+## Adding to Your Project
+
+To automatically install this marketplace for all team members, add to your project's `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "wasp-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "wasp-lang/claude-plugins"
+      }
+    }
+  }
+}
+```
+
+## Contributing
+
+We welcome contributions! To add a new plugin:
+
+1. Create your plugin in the `plugins/` directory
+2. Add an entry to `.claude-plugin/marketplace.json`
+3. Submit a pull request
+
+## License
+
+MIT - See individual plugin directories for specific licenses.
+
+## Links
+
+- [Wasp Framework](https://wasp.sh)
+- [Wasp Documentation](https://wasp.sh/docs)
+- [Claude Code](https://claude.ai/code)
+- [Claude Code Plugin Documentation](https://docs.anthropic.com/en/docs/claude-code/plugins)
diff --git a/plugins/wasp-claude-tools/.claude-plugin/plugin.json b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
new file mode 100644
index 0000000..22be90f
--- /dev/null
+++ b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
@@ -0,0 +1,16 @@
+{
+  "name": "wasp-claude-tools",
+  "source": "./plugins/wasp-claude-tools",
+  "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
+  "version": "1.0.0",
+  "author": {
+    "name": "Wasp",
+    "email": "info@wasp-lang.dev",
+    "url": "https://wasp.sh"
+  },
+  "repository": "https://github.com/wasp-lang/claude-plugins",
+  "license": "MIT",
+  "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication"],
+  "category": "frameworks",
+  "tags": ["wasp", "full-stack", "web-development"]
+}
diff --git a/plugins/wasp-claude-tools/LICENSE b/plugins/wasp-claude-tools/LICENSE
new file mode 100644
index 0000000..7cafcf4
--- /dev/null
+++ b/plugins/wasp-claude-tools/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wasp.sh
+
+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.
diff --git a/plugins/wasp-claude-tools/README.md b/plugins/wasp-claude-tools/README.md
new file mode 100644
index 0000000..c9bd072
--- /dev/null
+++ b/plugins/wasp-claude-tools/README.md
@@ -0,0 +1,66 @@
+# wasp-claude-tools
+
+A Claude Code plugin for Wasp framework development, providing documentation caching, deployment guides, and interactive setup wizards.
+
+## Features
+
+- **Knowledge Integration**: Add Wasp best practices and conventions to your project's CLAUDE.md
+- **Documentation Caching**: Automatically caches Wasp documentation locally for fast access and LLM grounding.
+- **Setup Wizard**: Interactive guided setup for configuring new Wasp app projects
+- **Deployment Guide**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
+
+## Installation
+
+Or install from a remote repository:
+
+```bash
+claude plugin add https://github.com/wasp-lang/wasp-claude-tools
+```
+
+## Skills
+
+This plugin provides three skills that Claude will automatically invoke when appropriate:
+
+### 1. Setup Wizard (`setup-wizard`)
+Interactive guided setup for configuring a new Wasp app project using Wasp features like full-stack authentication, email providers, databases, and more.
+
+### 2. Deployment Guide (`deploying-app`)
+Let Claude Code guide you through using Wasp's CLI for easy deployment of your Wasp app to Railway or Fly.io.
+
+### 3. Knowledge Integration (`adding-wasp-knowledge-claude`)
+Add Wasp knowledge and conventions to your project's CLAUDE.md file.
+
+## Hooks
+
+The plugin includes two hooks:
+
+- **SessionStart**: Automatically caches all Wasp documentation when Claude Code starts
+- **PreToolUse (WebFetch)**: Intercepts requests to Wasp documentation URLs and redirects to cached local copies
+
+## Recommended Permissions
+
+For the best experience, add these permissions to your project or user settings:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(wasp start)",
+      "Bash(wasp db:*)",
+      "Bash(wasp deploy:*)",
+      "WebFetch(domain:wasp.sh)"
+    ]
+  }
+}
+```
+
+## Documentation Cache
+
+The plugin maintains a local cache of Wasp documentation in `knowledge/cached-docs/`. The cache:
+- Refreshes automatically every 24 hours
+- Includes all official Wasp documentation
+- Enables efficient retrieval of Wasp documentation for LLM grounding and context
+
+## License
+
+MIT
diff --git a/plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js b/plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js
new file mode 100644
index 0000000..fc8965e
--- /dev/null
+++ b/plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js
@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+const path = require('path');
+const { execSync } = require('child_process');
+const { isCacheFileValid, convertWaspDocUrlToCachePath } = require('./wasp-docs-cache-utils');
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', async () => {
+  try {
+    const data = JSON.parse(input);
+    const toolName = data.tool_name || '';
+    const toolInput = data.tool_input || {};
+
+    // We only block WebFetch for Wasp docs and not WebSearch, because
+    // 1. WebSearch could return blogposts or 3rd-party tutorials, which we don't want to block.
+    // 2. If WebSearch returns our own Wasp doc URLs, WebFetch will be called and it will be re-routed to cached docs.
+    if (toolName === 'WebFetch') {
+      const url = toolInput.url || '';
+
+      const isWaspDocUrl = 
+        url.includes('wasp-lang.dev/docs/') || 
+        url.includes('wasp.sh/docs/') || 
+        (url.includes('raw.githubusercontent.com') && url.includes('/wasp/') && url.includes('/docs/'));
+
+      if (isWaspDocUrl) {
+        const { cachePath } = convertWaspDocUrlToCachePath(url);
+
+        if (cachePath) {
+          if (isCacheFileValid(cachePath)) {
+            console.error(`DOC_CACHED: ${cachePath}\n\nThis doc is already cached. Use the Read tool to access it.`);
+            process.exit(2);
+          }
+
+          cacheAllDocsSync();
+          console.error(`DOC_CACHED: ${cachePath}\n\nThis doc has been cached. Use the Read tool to access it.`);
+          process.exit(2);
+        }
+
+        console.error(`BLOCKED: ${url}\n\nUse https://wasp.sh/llms.txt to find raw GitHub documentation URLs.`);
+        process.exit(2);
+      }
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});
+
+function cacheAllDocsSync() {
+  const cacheScript = path.join(__dirname, 'cache-all-wasp-docs.js');
+  try {
+    execSync(`node "${cacheScript}"`, { stdio: 'ignore' });
+  } catch {
+    // Ignore errors - best effort caching.
+  }
+}
diff --git a/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js b/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js
new file mode 100644
index 0000000..a16445f
--- /dev/null
+++ b/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js
@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+const CACHE_ALL_DOCS_SCRIPT_PATH = path.join(PLUGIN_ROOT, 'hooks', 'cache-all-wasp-docs.js');
+
+try {
+  if (fs.existsSync(CACHE_ALL_DOCS_SCRIPT_PATH)) {
+    const child = spawn('node', [CACHE_ALL_DOCS_SCRIPT_PATH], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: path.join(PLUGIN_ROOT, 'hooks')
+    });
+    child.unref();
+  }
+
+  console.log(JSON.stringify({ continue: true, suppressOutput: false }));
+  process.exit(0);
+} catch (error) {
+  console.log(JSON.stringify({ continue: true, suppressOutput: false }));
+  process.exit(0);
+}
diff --git a/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js b/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js
new file mode 100644
index 0000000..979a997
--- /dev/null
+++ b/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js
@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+const { fetchAndCacheAllDocs } = require('./wasp-docs-cache-utils');
+
+async function main() {
+  try {
+    const results = await fetchAndCacheAllDocs();
+
+    // Output results for debugging when run manually.
+    if (results.fetched > 0 || results.errors.length > 0) {
+      console.log(`Cached ${results.fetched} docs, skipped ${results.skipped} (already cached)`);
+      if (results.errors.length > 0) {
+        console.error(`Errors: ${results.errors.join(', ')}`);
+      }
+    }
+
+    process.exit(0);
+  } catch (err) {
+    console.error(`Failed to cache docs: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();
diff --git a/plugins/wasp-claude-tools/hooks/hooks.json b/plugins/wasp-claude-tools/hooks/hooks.json
new file mode 100644
index 0000000..2878139
--- /dev/null
+++ b/plugins/wasp-claude-tools/hooks/hooks.json
@@ -0,0 +1,25 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "WebFetch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/block-wasp-html-docs.js\""
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cache-all-wasp-docs-async.js\""
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js b/plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js
new file mode 100644
index 0000000..a7ca7c5
--- /dev/null
+++ b/plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js
@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+
+const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
+const CACHE_DIR = path.join(PLUGIN_ROOT, 'knowledge', 'cached-docs');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const LLMS_INDEX_URL = 'https://wasp.sh/llms.txt';
+const CACHE_ALL_DOCS_SCRIPT_PATH = path.join(PLUGIN_ROOT, 'hooks', 'cache-all-wasp-docs.js');
+
+function fetchUrl(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return fetchUrl(res.headers.location).then(resolve).catch(reject);
+      }
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve(data));
+      res.on('error', reject);
+    }).on('error', reject);
+  });
+}
+
+function isCacheFileValid(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+    return Date.now() - stats.mtimeMs < CACHE_TTL_MS;
+  } catch {
+    return false;
+  }
+}
+
+// .../docs/auth/overview.md -> auth
+function extractFolderFromRawGithubUrl(url) {
+  const match = url.match(/\/docs\/([^/]+)\//);
+  return match ? match[1] : null;
+}
+
+// .../docs/auth/social-auth/github.md -> social-auth_github.md
+function extractFilenameFromRawGithubUrl(url) {
+  const match = url.match(/\/docs\/[^/]+\/(.+)$/);
+  return match ? match[1].replace(/\//g, '_') : null;
+}
+
+function parseDocsFromLlmsTxt(content) {
+  const docs = [];
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Example: - [Title](url)
+    const linkMatch = trimmed.match(/^-\s*\[([^\]]+)\]\(([^)]+)\)/);
+    if (linkMatch) {
+      const [, , url] = linkMatch;
+      if (url.includes('raw.githubusercontent.com') && url.includes('/docs/')) {
+        const folder = extractFolderFromRawGithubUrl(url);
+        const filename = extractFilenameFromRawGithubUrl(url);
+        if (folder && filename) {
+          docs.push({ folder, filename, url });
+        }
+      }
+    }
+  }
+
+  return docs;
+}
+
+// Used in the block-wasp-html-docs hook to convert the URL to a cache path
+// so we can check if the doc is already cached.
+function convertWaspDocUrlToCachePath(url) {
+  // Example: wasp.sh/docs/auth/overview -> { folder: 'auth', filename: 'overview.md' }
+  const htmlMatch = url.match(/(?:wasp-lang\.dev|wasp\.sh)\/docs\/([^/?#]+)(?:\/([^/?#]+))?/);
+  if (htmlMatch) {
+    const folder = htmlMatch[1];
+    const docPath = htmlMatch[2] || folder;
+    return {
+      folder,
+      filename: docPath.replace(/\//g, '_') + '.md',
+      cachePath: path.join(CACHE_DIR, folder, docPath.replace(/\//g, '_') + '.md')
+    };
+  }
+
+  // Example: .../docs/auth/overview.md
+  const rawMatch = url.match(/\/docs\/([^/]+)\/(.+)$/);
+  if (rawMatch) {
+    const folder = rawMatch[1];
+    const filename = rawMatch[2].replace(/\//g, '_');
+    return {
+      folder,
+      filename,
+      cachePath: path.join(CACHE_DIR, folder, filename)
+    };
+  }
+
+  return null;
+}
+
+// Cache all docs - only fetches docs that don't exist or are expired
+async function fetchAndCacheAllDocs() {
+  const content = await fetchUrl(LLMS_INDEX_URL);
+  const docs = parseDocsFromLlmsTxt(content);
+
+  const results = { fetched: 0, skipped: 0, errors: [] };
+
+  for (const doc of docs) {
+    const folderPath = path.join(CACHE_DIR, doc.folder);
+    const cachePath = path.join(folderPath, doc.filename);
+
+    if (isCacheFileValid(cachePath)) {
+      results.skipped++;
+      continue;
+    }
+
+    try {
+      fs.mkdirSync(folderPath, { recursive: true });
+      const docContent = await fetchUrl(doc.url);
+      fs.writeFileSync(cachePath, docContent);
+      results.fetched++;
+    } catch (err) {
+      results.errors.push(`${doc.folder}/${doc.filename}: ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+module.exports = {
+  CACHE_DIR,
+  CACHE_TTL_MS,
+  CACHE_ALL_DOCS_SCRIPT_PATH,
+  isCacheFileValid,
+  convertWaspDocUrlToCachePath,
+  fetchAndCacheAllDocs,
+};
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md
new file mode 100644
index 0000000..6fef5f1
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md
@@ -0,0 +1,11 @@
+---
+name: adding-wasp-knowledge-claude
+description: add knowledge about Wasp to the user's CLAUDE.md file.
+---
+
+## Adding Wasp Knowledge
+
+1. find the project root's CLAUDE.md file.
+2. ask the user if they'd like to add the [general-wasp-knowledge.md](./general-wasp-knowledge.md) file to the CLAUDE.md file.
+3. if they do, store it in the `.claude/knowledge` directory and link to it from their CLAUDE.md file using the [example-section-link.md](./example-section-link.md) as a guide.
+4. inform the user that they can edit their Wasp knowledge file at any time and also use the [cached-docs](../../knowledge/cached-docs) directory to help claude code with Wasp development tasks.
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md
new file mode 100644
index 0000000..6270a63
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md
@@ -0,0 +1,11 @@
+```md
+## Wasp Knowledge
+
+See [wasp-knowledge.md](.path/to/wasp-knowledge.md) for Wasp framework:
+- conventions
+- commands
+- best practices
+- features
+- documentation
+- resources
+```
\ No newline at end of file
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
new file mode 100644
index 0000000..86f639b
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
@@ -0,0 +1,86 @@
+# Wasp App
+
+This project uses TypeScript and Wasp, a batteries-included framework for building full-stack web apps with React, Node.js, and Prisma: [Introduction](./cached-docs/introduction/introduction.md)
+
+## Accessing Wasp Knowledge
+
+1. check the [cached-docs](./cached-docs) directory for relevant docs.
+2. if they don't exist, run the [cache-all-wasp-docs.js](../hooks/cache-all-wasp-docs.js) script.
+
+## Start the Dev Servers
+
+Start all servers as background tasks in this Claude Code session to access dev server logs. See [CLI Reference](./cached-docs/general/cli.md) for commands.
+
+Use the chrome-devtools mcp server to access the client app in the browser.
+
+## Starter Templates
+
+Wasp can scaffold boilerplate starter apps: [Starter Templates](./cached-docs/project/starter-templates.md)
+
+## Project Structure
+
+```
+.
+├── .wasp/                    # Wasp output **DO NOT EDIT!**
+├── public/                   # Static assets
+├── src/                      # Feature code: server `operations.ts` and client `pages.tsx` files
+├── main.wasp or main.wasp.ts # App definition: routes, pages, auth, operations, jobs, etc.
+├── schema.prisma             # Database schema
+```
+
+### Organization Principle
+
+Organize by **feature** (vertical), not by type (client/server):
+
+```
+src/
+├── tasks/
+│   ├── TasksPage.tsx      # Page component
+│   ├── TaskList.tsx       # Component
+│   └── operations.ts      # Queries & actions
+├── auth/
+│   ├── LoginPage.tsx
+│   └── google.ts
+```
+
+## Project Setup & Customization
+
+- Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): [Project Setup & Customization](./cached-docs/project/)
+
+## Advanced Features
+
+Wasp provides [advanced features](./cached-docs/advanced/):
+- custom HTTP API endpoints
+- background (cron) jobs
+- type-safe links
+- websockets
+- middleware
+- email sending
+
+## Import Conventions
+
+**In TypeScript files:**
+- ✅ `import type { User } from 'wasp/entities'`
+- ✅ `import type { GetTasks } from 'wasp/server/operations'`
+- ✅ `import { getTasks, createTask, useQuery } from 'wasp/client/operations'`
+- ✅ `import { SubscriptionStatus } from '@prisma/client'` (for Prisma enums)
+- ✅ Local code: relative paths `import { X } from './X'`
+- ❌ Never `@wasp/...` or `@src/...`
+- ⚠️ Call actions directly using `async/await`. DO NOT use Wasp's `useAction` hook unless optimistic updates are needed.
+
+**In main.wasp:**
+- ✅ `fn: import { getTasks } from "@src/tasks/operations.ts"`
+- ❌ Never relative paths
+
+**In main.wasp.ts:**
+TODO: add more info about main.wasp.ts conventions
+
+## Common Mistakes
+
+| Symptom | Fix |
+|---------|-----|
+| `context.entities.X undefined` | Add entity to `entities: [...]` in main.wasp |
+| Schema changes not applying | Run `wasp db migrate-dev` |
+| Types stale after changes | Restart TS server |
+| Wasp not recognizing changes | **WAIT PATIENTLY** as Wasp recompiles the project. Re-run `wasp start` if necessary.|
+| Persistent weirdness after waiting patiently and restarting. | Run `wasp clean` && `wasp start` |
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md
new file mode 100644
index 0000000..d7ea8d0
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md
@@ -0,0 +1,179 @@
+# Wasp Development Conventions & Gotchas
+
+A comprehensive reference of Wasp framework conventions, common mistakes, and best practices.
+
+## 1. Import Conventions
+
+### In TypeScript/JavaScript Files
+
+**Correct Patterns:**
+```typescript
+// Entity types (available on client & server)
+import type { User, Task } from 'wasp/entities'
+
+// Operation types (for typing implementations)
+import type { GetTasks, CreateTask } from 'wasp/server/operations'
+
+// Client-side queries (used within the useQuery hook for automatic cache invalidation)
+import { getTasks, getTasksFiltered, useQuery } from 'wasp/client/operations'
+
+// Client-side actions called directly with await
+import { createTask } from 'wasp/client/operations'
+
+// Server-side operations (for calling from other server code or other operations)
+import { getTasks } from 'wasp/server/operations'
+
+// Prisma client (server only)
+import { prisma } from 'wasp/server'
+
+// Prisma enums
+import { SubscriptionStatus } from '@prisma/client'
+
+// Auth hooks & UI
+import { useAuth, logout } from 'wasp/client/auth'
+import { LoginForm, SignupForm } from 'wasp/client/auth'
+
+// API client (for custom API routes)
+import { api } from 'wasp/client/api'
+
+// HttpError for user-facing errors
+import { HttpError } from 'wasp/server'
+
+// Local code: use relative paths
+import { myHelper } from './helpers'
+import { MyComponent } from '../components/MyComponent'
+```
+
+**Incorrect Patterns:**
+```typescript
+// NEVER use these in TypeScript files:
+import { X } from '@wasp/...'      // ❌ Old syntax, deprecated
+import { X } from '@src/...'       // ❌ Only valid in main.wasp
+import { X } from 'wasp/core/...'  // ❌ Internal paths
+```
+
+### In main.wasp
+
+**Correct Patterns:**
+```wasp
+// External imports use @src prefix
+query getTasks {
+  fn: import { getTasks } from "@src/tasks/operations",
+  entities: [Task]
+}
+
+page MainPage {
+  component: import { MainPage } from "@src/pages/MainPage"
+}
+```
+
+**Incorrect Patterns:**
+```wasp
+// NEVER use relative paths in main.wasp:
+fn: import { getTasks } from "./tasks/operations"  // ❌
+fn: import { getTasks } from "../operations"       // ❌
+```
+
+### In main.wasp.ts (TypeScript Config)
+
+```typescript
+// Uses standard TypeScript imports
+import { App } from 'wasp-config'
+
+// Define app configuration programmatically
+export default new App({
+  // ...
+})
+```
+
+## 2. Operation Conventions (Queries & Actions)
+
+### Queries vs Actions
+
+| Queries | Actions |
+|---------|---------|
+| Read-only, side-effect free | Create, update, delete data |
+| Use `useQuery` hook for reactivity | Call directly with `await` |
+| Cached automatically | Invalidate related query caches |
+
+ONLY use the `useAction` hook when you need optimistic updates!
+
+```wasp
+page DashboardPage {
+  authRequired: true,  // Redirects to onAuthFailedRedirectTo if not logged in
+  component: import { Dashboard } from "@src/pages/Dashboard"
+}
+```
+
+
+```typescript
+// In operations (server)
+export const getTasks: GetTasks<void, Task[]> = async (args, context) => {
+  if (!context.user) {
+    throw new HttpError(401, 'Not authenticated')
+  }
+  // context.user available
+}
+
+// On client
+import { useAuth } from 'wasp/client/auth'
+
+function MyComponent() {
+  const { data: user, isLoading } = useAuth()
+  if (!user) return <LoginPrompt />
+}
+
+// Logout
+import { logout } from 'wasp/client/auth'
+await logout()
+```
+
+
+
+```prisma
+// Model names: PascalCase
+// Field names: camelCase
+model Task {
+  id          Int      @id @default(autoincrement())
+  description String
+  isDone      Boolean  @default(false)
+  createdAt   DateTime @default(now())
+  userId      Int
+  user        User     @relation(fields: [userId], references: [id])
+}
+
+model User {
+  id    Int    @id @default(autoincrement())
+  tasks Task[]
+}
+```
+
+
+
+## 3. File & Naming Conventions
+
+### Project Structure
+
+```
+.
+├── .wasp/                    # Wasp output (do not edit!)
+├── public/                   # Static assets
+├── src/                      # Feature code
+├── main.wasp or main.wasp.ts # App definition
+├── schema.prisma             # Database schema
+```
+
+### Organization Principle
+
+Organize by **feature** (vertical), not by type (client/server):
+
+```
+src/
+├── tasks/
+│   ├── TasksPage.tsx      # Page component
+│   ├── TaskList.tsx       # Component
+│   └── operations.ts      # Queries & actions
+├── auth/
+│   ├── LoginPage.tsx
+│   └── google.ts
+```
diff --git a/plugins/wasp-claude-tools/skills/deploying-app/SKILL.md b/plugins/wasp-claude-tools/skills/deploying-app/SKILL.md
new file mode 100644
index 0000000..5182650
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/deploying-app/SKILL.md
@@ -0,0 +1,25 @@
+---
+name: deploying-app
+description: deploy the Wasp app to Railway or Fly.io using Wasp CLI.
+---
+
+# deploying-app
+
+## Pre-Deployment
+
+1. Run a pre-deployment check via [validating-pre-deployment](./validating-pre-deployment.md) to validate configuration.
+2. present the list of supported [`wasp deploy`](../../knowledge/cached-docs/deployment/deployment-methods_wasp-deploy_overview.md) providers and ask the user to choose one.
+3. follow the steps from the chosen provider's guide to deploy the app.
+
+## OAuth Redirect URLs
+
+If they user is using OAuth providers, inform them that they need to add the redirect URLs to the OAuth providers in the provider's dashboard.
+For example: https://your-server-url.com/auth/google/callback
+
+More info can be found in the Wasp Social Auth Providers docs.
+
+## Deployment Interrupted
+
+Safe to rerun: `wasp deploy <provider> deploy`
+
+**DO NOT rerun**: `wasp deploy <provider> launch` commands (one-time only)
diff --git a/plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md b/plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md
new file mode 100644
index 0000000..84ef550
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md
@@ -0,0 +1,101 @@
+---
+name: validating-pre-deployment
+description: validate configuration and test production build before deploying.
+---
+
+# validating-pre-deployment
+
+Pre-deployment validation checks that catch common issues before deploying with the [deploying-app skill](../deploying-app/SKILL.md).
+
+## Before Starting
+
+1. verify user is in the app directory (check for `main.wasp` or `main.wasp.ts`)
+2. ask: "Would you like me to run pre-deployment checks on your app?"
+
+## Validation Steps
+
+Run these checks in order. Report all issues found, then ask the user if they want to proceed or fix issues first.
+
+### Step 1: Wasp Config Metadata
+
+1. Check the wasp config file (`main.wasp` or `main.wasp.ts`) for placeholder values:
+   - URLs are actual live URLs, not placeholder values set during the setup wizard.
+   - Email provider and default from address are actual live email addresses
+
+Report format:
+```
+## Configuration Issues Found
+
+### Critical (must fix):
+- [ ] issue description
+
+### Warnings (recommended to fix):
+- [ ] issue description
+
+### Passed:
+- [x] check that passed
+```
+
+### Step 2: Environment Variables
+
+Based on the wasp config file and the app's features, generate a checklist of required [env vars](../../knowledge/cached-docs/project/env-vars.md) for the user to verify.
+
+Note that the following env vars are auto-set by Wasp when using [wasp deploy](../../knowledge/cached-docs/deployment/deployment-methods_wasp-deploy_overview.md) to deploy to Railway or Fly.io automatically:
+- `DATABASE_URL`
+- `WASP_WEB_CLIENT_URL`
+- `WASP_SERVER_URL`
+- `JWT_SECRET`
+- `PORT`
+
+### Step 4: Database Migrations
+
+Check for pending migrations:
+```bash
+# List migration files
+ls -la migrations/
+```
+
+Remind user:
+- Production automatically applies pending migrations on server start
+- Ensure migrations are committed to version control
+- Test migrations work locally before deploying
+
+### Step 5: Production Build Test
+
+Ask user: "Would you like to test the production build locally? This catches environment-specific issues."
+
+If yes, guide them through the [production build test](../../knowledge/cached-docs/deployment/local-testing.md) process.
+
+### Step 6: Final Checklist
+
+Present summary:
+
+```
+## Pre-Deployment Summary
+
+### Configuration Status:
+- App Name: [name]
+- App Title: [title]
+- Email Provider: [provider]
+- Auth Methods: [list]
+- Other integrations: [list]
+
+### Issues to Resolve:
+[list any issues from steps 1-4]
+
+### Before Deploying:
+- [ ] All configuration placeholders replaced
+- [ ] Production email provider configured
+- [ ] Required env vars ready for deployment
+- [ ] Production build tested locally (optional but recommended)
+- [ ] Database migrations committed
+
+### Ready to Deploy?
+```
+
+## Completion
+
+If all checks pass or user chooses to proceed:
+- Summarize what was validated
+- Ask: "Would you like to proceed with deployment? I can guide you through deploying to providers like Railway or Fly.io automatically with Wasp's CLI commands."
+- If yes, transition to [deploying-app skill](../deploying-app/SKILL.md)
diff --git a/plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md b/plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md
new file mode 100644
index 0000000..b9b6681
--- /dev/null
+++ b/plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: setup-wizard
+description: interactive guided setup for configuring a new Wasp app project.
+---
+
+# setup-wizard
+
+This wizard walks through essential Wasp app configurations and customizations. Run each step in order, asking the user for decisions at each stage.
+
+## Before Starting
+
+1. verify user is in the app directory (check for wasp config file: `main.wasp` or `main.wasp.ts`)
+2. ask: "Would you like me to guide you through setting up your app?"
+
+## Setup Phases
+
+Guide the user through these phases, each with its own set of steps, in order. 
+
+### Phase 0: Fetching Wasp Knowledge
+
+Fetch and organize the following information from the Wasp (cached) docs into separate lists:
+- Authentication methods
+- Email providers
+- Databases
+
+The user will choose which integrations they'd like to set up from these lists in the appropriate phases, at which point you will fetch the docs for each integration to guide them.
+
+If no cached docs exist, run [cache-all-wasp-docs.js](../../hooks/cache-all-wasp-docs.js).
+
+#### Using AskUserQuestion tool with Lists in the Setup Wizard
+
+When asking the user to choose from fetched lists follow these guidelines:
+
+1. **Always display the full list** to the user before asking them to choose, so they know all available options.
+2. **Use the most popular/common options** as the selectable choices in `AskUserQuestion` (limited to 2-4 options).
+3. **Remind users** they can select "Other" to specify any option from the full list that isn't shown in the quick-select options.
+4. **Example format:**
+   ```
+   Available auth methods: Username & Password, Email, Google, GitHub, Discord, Keycloak, Slack
+
+   [AskUserQuestion with 3-4 most common options]
+
+   Note: Select "Other" to choose from additional options like Discord, Keycloak, or Slack.
+   ```
+
+### Phase 1: App Branding
+
+1. ask the user:
+- What is your app name?
+- What is a one-line description?
+
+2. update the wasp config file `app` block according to the docs.
+
+DO NOT change URLs in the `app.head` meta tags. Leave these as they are until the user has a production domain and is ready to deploy.
+
+### Phase 2: Authentication
+
+1. read the wasp config file auth methods section to see which providers are already configured, if any.
+
+2. **display the full list** of available auth methods fetched in Phase 0 to the user.
+
+3. using the `AskUserQuestion` tool, ask the user which (additional) auth methods they'd like to add:
+   - if no auth methods are selected, move to the next phase.
+
+4. for each auth method selected:
+  - add the provider to the wasp config file's auth methods section according to the docs for each auth method
+  - if applicable, inform user they'll need to set env vars in a later phase
+
+5. read the wasp config file and see if the app has defined authentication pages (e.g. login, signup, forgot password, etc.)?
+  - if so, check if those pages are using Wasp's managed AUTH UI components (e.g. `import { LoginForm } from "wasp/client/auth";`) that adapt to their selected auth methods?
+    - if so, move to the next phase.
+    - if not, continue with the next step.
+
+6. if the app does not have authentication pages, ask the user if they'd like to set up:
+  - authentication pages (e.g. login, signup, forgot password, etc.) with Wasp's managed AUTH UI components that adapt to their selected auth methods?
+    - if yes, follow the selected auth methods' guides in the Wasp docs
+    - if no:
+      - inform the user they can follow the "Create your own UI" guides in the Wasp docs later with their auth method of choice
+      - continue to the next phase
+
+### Phase 3: Email Provider
+
+1. **display the full list** of available email providers fetched in Phase 0 to the user.
+
+2. using the `AskUserQuestion` tool, ask the user which email sending provider they'd like to use.
+
+3. for each provider selected:
+  - add the provider to the wasp config file's emailSender section according to the docs for each email provider
+  - inform the user they'll need to set env vars in a later phase
+
+### Phase 4: Setting Up a Database
+
+1. **display the full list** of available databases fetched in Phase 0 to the user.
+
+2. using the `AskUserQuestion` tool, ask the user which database they'd like to use.
+
+3. if the selected database can be managed locally by Wasp (e.g., PostgreSQL), using the `AskUserQuestion` tool, ask the user: "Would you like me to guide you through the local database setup process?"
+  - if yes, guide the user through the managed database setup process according to the individual database docs
+  - if no, inform the user that they'll need to set the proper env vars after setting up the database themselves
+
+4. after the database is setup, ask the user if they're ready to move to the next phase.
+
+### Phase 5: Completing Integrations & Environment Variables
+
+For each integration selected in phases 2-4: 
+  1. findt the correct doc files/guides for each integration
+  2. generate checklist of required env vars 
+  3. give user instructions for retrieving and adding env vars to `.env.server` 
+  4. follow steps/run commands in the guide to complete the integration for the user where applicable
+  5. prompt the user to confirm they're ready to move to the next integration
+
+### Phase 6: Adding Wasp Knowledge
+
+1. ask the user if they'd like to add knowledge about Wasp to their CLAUDE.md file.
+  - if yes, follow the [adding-wasp-knowledge-claude](../adding-wasp-knowledge-claude/SKILL.md) skill.
+  - if no, inform the user that they can add knowledge about Wasp to their CLAUDE.md file later.
+
+### Phase 7: Verify Setup
+
+1. start the wasp app processes in new terminals as background tasks in the current Claude Code session
+2. verify configuration compiles and check for any errors.
+
+### Phase 8: Completion
+
+1. provide a summary of the setup process and what other skills and commands are available to help with further setup.
+2. ask the user if they're ready to move to the next phase.

From be039ec693b44944cb16f228289543a66379190a Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:38:42 +0100
Subject: [PATCH 02/47] update json files

---
 .claude-plugin/marketplace.json                    |  8 +++-----
 .../wasp-claude-tools/.claude-plugin/plugin.json   | 14 +-------------
 2 files changed, 4 insertions(+), 18 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 255428c..3ec1964 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,5 +1,5 @@
 {
-  "name": "wasp-plugins",
+  "name": "claude-plugins",
   "owner": {
     "name": "Wasp",
     "email": "info@wasp-lang.dev",
@@ -13,7 +13,7 @@
   "plugins": [
     {
       "name": "wasp-claude-tools",
-      "source": "./plugins/wasp-claude-tools",
+      "source": "./wasp-claude-tools",
       "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
       "version": "1.0.0",
       "author": {
@@ -23,9 +23,7 @@
       },
       "repository": "https://github.com/wasp-lang/claude-plugins",
       "license": "MIT",
-      "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication"],
-      "category": "frameworks",
-      "tags": ["wasp", "full-stack", "web-development"]
+      "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication", "web-development"]
     }
   ]
 }
diff --git a/plugins/wasp-claude-tools/.claude-plugin/plugin.json b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
index 22be90f..982cac8 100644
--- a/plugins/wasp-claude-tools/.claude-plugin/plugin.json
+++ b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
@@ -1,16 +1,4 @@
 {
   "name": "wasp-claude-tools",
-  "source": "./plugins/wasp-claude-tools",
-  "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
-  "version": "1.0.0",
-  "author": {
-    "name": "Wasp",
-    "email": "info@wasp-lang.dev",
-    "url": "https://wasp.sh"
-  },
-  "repository": "https://github.com/wasp-lang/claude-plugins",
-  "license": "MIT",
-  "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication"],
-  "category": "frameworks",
-  "tags": ["wasp", "full-stack", "web-development"]
+  "hooks": "./hooks/hooks.json"
 }

From d0f7e9ba2a24aa0ec077f3749c551054860b0505 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:43:04 +0100
Subject: [PATCH 03/47] change name

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 3ec1964..3b994ca 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1,5 +1,5 @@
 {
-  "name": "claude-plugins",
+  "name": "wasp-plugins",
   "owner": {
     "name": "Wasp",
     "email": "info@wasp-lang.dev",

From ca7c5be5e0aa3fb4fce45faedf69dcc74bda40ac Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:49:18 +0100
Subject: [PATCH 04/47] fix relative path

---
 .claude-plugin/marketplace.json | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 3b994ca..d076a0a 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -7,13 +7,12 @@
   },
   "metadata": {
     "description": "Official Wasp framework plugins for Claude Code",
-    "version": "1.0.0",
-    "pluginRoot": "./plugins"
+    "version": "1.0.0"
   },
   "plugins": [
     {
       "name": "wasp-claude-tools",
-      "source": "./wasp-claude-tools",
+      "source": "./plugins/wasp-claude-tools",
       "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
       "version": "1.0.0",
       "author": {

From a81e40bc08415125c0f7604bbe31de54222678d2 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 10:59:46 +0100
Subject: [PATCH 05/47] remove plugin.json

---
 .claude-plugin/marketplace.json                      | 1 +
 plugins/wasp-claude-tools/.claude-plugin/plugin.json | 4 ----
 2 files changed, 1 insertion(+), 4 deletions(-)
 delete mode 100644 plugins/wasp-claude-tools/.claude-plugin/plugin.json

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d076a0a..62c5ec2 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,6 +13,7 @@
     {
       "name": "wasp-claude-tools",
       "source": "./plugins/wasp-claude-tools",
+      "strict": false,
       "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
       "version": "1.0.0",
       "author": {
diff --git a/plugins/wasp-claude-tools/.claude-plugin/plugin.json b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
deleted file mode 100644
index 982cac8..0000000
--- a/plugins/wasp-claude-tools/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "name": "wasp-claude-tools",
-  "hooks": "./hooks/hooks.json"
-}

From c312bc2a6714a2f551e90d8a4b5f0532ab901c28 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 11:16:17 +0100
Subject: [PATCH 06/47] update json

---
 .claude-plugin/marketplace.json                      | 1 -
 plugins/wasp-claude-tools/.claude-plugin/plugin.json | 4 ++++
 2 files changed, 4 insertions(+), 1 deletion(-)
 create mode 100644 plugins/wasp-claude-tools/.claude-plugin/plugin.json

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 62c5ec2..d076a0a 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,6 @@
     {
       "name": "wasp-claude-tools",
       "source": "./plugins/wasp-claude-tools",
-      "strict": false,
       "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
       "version": "1.0.0",
       "author": {
diff --git a/plugins/wasp-claude-tools/.claude-plugin/plugin.json b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
new file mode 100644
index 0000000..12c40a3
--- /dev/null
+++ b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
@@ -0,0 +1,4 @@
+{
+  "name": "wasp-claude-tools",
+  "version": "1.0.0"
+}

From da23f0320d1841fc44ac6484730304035015258d Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 11:24:37 +0100
Subject: [PATCH 07/47] update json

---
 .claude-plugin/marketplace.json | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d076a0a..d08a410 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -3,7 +3,7 @@
   "owner": {
     "name": "Wasp",
     "email": "info@wasp-lang.dev",
-    "url": "https://github.com/wasp-lang/wasp"
+    "url": "https://wasp.sh"
   },
   "metadata": {
     "description": "Official Wasp framework plugins for Claude Code",
@@ -16,13 +16,13 @@
       "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
       "version": "1.0.0",
       "author": {
-        "name": "Wasp",
-        "email": "info@wasp-lang.dev",
-        "url": "https://wasp.sh"
+        "name": "Wasp"
       },
+      "homepage": "https://wasp.sh",
       "repository": "https://github.com/wasp-lang/claude-plugins",
       "license": "MIT",
-      "keywords": ["wasp", "full-stack", "react", "node", "deployment", "authentication", "web-development"]
+      "category": "framework",
+      "keywords": ["wasp", "full-stack", "react", "nodejs", "deployment", "authentication", "web-development"]
     }
   ]
 }

From e294f71b7b41b31d1db234599a23738c7cc3fc87 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 11:36:36 +0100
Subject: [PATCH 08/47] add wasp help command

---
 .../wasp-claude-tools/commands/wasp-help.md   | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 plugins/wasp-claude-tools/commands/wasp-help.md

diff --git a/plugins/wasp-claude-tools/commands/wasp-help.md b/plugins/wasp-claude-tools/commands/wasp-help.md
new file mode 100644
index 0000000..0dd4586
--- /dev/null
+++ b/plugins/wasp-claude-tools/commands/wasp-help.md
@@ -0,0 +1,30 @@
+---
+description: Show available Wasp plugin features and how to use them
+---
+
+# Wasp Claude Tools Plugin
+
+## Skills
+
+Skills are automatically invoked by Claude when relevant to your task.
+
+| Skill | Trigger | Description |
+|-------|---------|-------------|
+| **setup-wizard** | "set up my Wasp app", "configure authentication" | Interactive guided setup for new Wasp projects - branding, auth providers, email, database |
+| **deploying-app** | "deploy my app", "deploy to Railway" | Deploy to Railway or Fly.io with pre-flight validation checklist |
+| **adding-wasp-knowledge-claude** | "add Wasp knowledge to CLAUDE.md" | Add Wasp conventions and best practices to your project's CLAUDE.md |
+
+## Hooks
+
+Hooks run automatically in the background.
+
+| Hook | Event | What it does |
+|------|-------|--------------|
+| **Doc Caching** | Session Start | Fetches and caches all Wasp documentation locally for fast access |
+| **Doc Redirect** | WebFetch (Wasp URLs) | Redirects Wasp doc requests to local cache instead of fetching from web |
+
+## Tips
+
+- **Offline docs**: Wasp documentation is cached locally after first session, enabling offline access
+- **Fresh cache**: Docs are refreshed every 24 hours automatically
+- **Trigger skills**: Just describe what you want to do naturally - Claude will invoke the appropriate skill

From 1086939a8c136faeb6b0f1db818b7cfd34335497 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 11:39:23 +0100
Subject: [PATCH 09/47] update command

---
 plugins/wasp-claude-tools/commands/wasp-help.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/wasp-claude-tools/commands/wasp-help.md b/plugins/wasp-claude-tools/commands/wasp-help.md
index 0dd4586..536a413 100644
--- a/plugins/wasp-claude-tools/commands/wasp-help.md
+++ b/plugins/wasp-claude-tools/commands/wasp-help.md
@@ -2,6 +2,8 @@
 description: Show available Wasp plugin features and how to use them
 ---
 
+Present the user with the following information below:
+
 # Wasp Claude Tools Plugin
 
 ## Skills

From 3d32c48779d5faf05c68bf53c22340a58e4c7b9c Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 21:55:43 +0100
Subject: [PATCH 10/47] test claude.md

---
 .claude-plugin/marketplace.json               |  6 ++--
 README.md                                     |  4 +--
 .../.claude-plugin/plugin.json                |  4 ---
 .../wasp-claude-tools/commands/wasp-help.md   | 32 -------------------
 plugins/wasp/.claude-plugin/plugin.json       |  4 +++
 plugins/wasp/CLAUDE.md                        |  0
 plugins/{wasp-claude-tools => wasp}/LICENSE   |  0
 plugins/{wasp-claude-tools => wasp}/README.md |  2 +-
 .../hooks/block-wasp-html-docs.js             |  0
 .../hooks/cache-all-wasp-docs-async.js        |  0
 .../hooks/cache-all-wasp-docs.js              |  0
 .../hooks/hooks.json                          |  0
 .../hooks/wasp-docs-cache-utils.js            |  0
 .../adding-wasp-knowledge-claude/SKILL.md     |  0
 .../example-section-link.md                   |  0
 .../general-wasp-knowledge.md                 |  0
 .../wasp-conventions.md                       |  0
 .../skills/deploying-app/SKILL.md             |  0
 .../validating-pre-deployment.md              |  0
 .../skills/setup-wizard/SKILL.md              |  0
 20 files changed, 10 insertions(+), 42 deletions(-)
 delete mode 100644 plugins/wasp-claude-tools/.claude-plugin/plugin.json
 delete mode 100644 plugins/wasp-claude-tools/commands/wasp-help.md
 create mode 100644 plugins/wasp/.claude-plugin/plugin.json
 create mode 100644 plugins/wasp/CLAUDE.md
 rename plugins/{wasp-claude-tools => wasp}/LICENSE (100%)
 rename plugins/{wasp-claude-tools => wasp}/README.md (98%)
 rename plugins/{wasp-claude-tools => wasp}/hooks/block-wasp-html-docs.js (100%)
 rename plugins/{wasp-claude-tools => wasp}/hooks/cache-all-wasp-docs-async.js (100%)
 rename plugins/{wasp-claude-tools => wasp}/hooks/cache-all-wasp-docs.js (100%)
 rename plugins/{wasp-claude-tools => wasp}/hooks/hooks.json (100%)
 rename plugins/{wasp-claude-tools => wasp}/hooks/wasp-docs-cache-utils.js (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/adding-wasp-knowledge-claude/SKILL.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/adding-wasp-knowledge-claude/example-section-link.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/adding-wasp-knowledge-claude/wasp-conventions.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/deploying-app/SKILL.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/deploying-app/validating-pre-deployment.md (100%)
 rename plugins/{wasp-claude-tools => wasp}/skills/setup-wizard/SKILL.md (100%)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d08a410..2f938c1 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,9 +11,9 @@
   },
   "plugins": [
     {
-      "name": "wasp-claude-tools",
-      "source": "./plugins/wasp-claude-tools",
-      "description": "Wasp framework development assistant with documentation caching, deployment guides, and interactive setup wizard",
+      "name": "wasp",
+      "source": "./plugins/wasp",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"
diff --git a/README.md b/README.md
index 41ee932..88bf8ba 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Official [Claude Code](https://claude.ai/code) plugins for the [Wasp](https://wa
 ### Install a plugin
 
 ```bash
-/plugin install wasp-claude-tools@wasp-plugins
+/plugin install wasp@wasp-plugins
 ```
 
 Or browse available plugins interactively:
@@ -24,7 +24,7 @@ Or browse available plugins interactively:
 
 ## Available Plugins
 
-### wasp-claude-tools
+### wasp
 
 Comprehensive Wasp development assistant with:
 
diff --git a/plugins/wasp-claude-tools/.claude-plugin/plugin.json b/plugins/wasp-claude-tools/.claude-plugin/plugin.json
deleted file mode 100644
index 12c40a3..0000000
--- a/plugins/wasp-claude-tools/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "name": "wasp-claude-tools",
-  "version": "1.0.0"
-}
diff --git a/plugins/wasp-claude-tools/commands/wasp-help.md b/plugins/wasp-claude-tools/commands/wasp-help.md
deleted file mode 100644
index 536a413..0000000
--- a/plugins/wasp-claude-tools/commands/wasp-help.md
+++ /dev/null
@@ -1,32 +0,0 @@
----
-description: Show available Wasp plugin features and how to use them
----
-
-Present the user with the following information below:
-
-# Wasp Claude Tools Plugin
-
-## Skills
-
-Skills are automatically invoked by Claude when relevant to your task.
-
-| Skill | Trigger | Description |
-|-------|---------|-------------|
-| **setup-wizard** | "set up my Wasp app", "configure authentication" | Interactive guided setup for new Wasp projects - branding, auth providers, email, database |
-| **deploying-app** | "deploy my app", "deploy to Railway" | Deploy to Railway or Fly.io with pre-flight validation checklist |
-| **adding-wasp-knowledge-claude** | "add Wasp knowledge to CLAUDE.md" | Add Wasp conventions and best practices to your project's CLAUDE.md |
-
-## Hooks
-
-Hooks run automatically in the background.
-
-| Hook | Event | What it does |
-|------|-------|--------------|
-| **Doc Caching** | Session Start | Fetches and caches all Wasp documentation locally for fast access |
-| **Doc Redirect** | WebFetch (Wasp URLs) | Redirects Wasp doc requests to local cache instead of fetching from web |
-
-## Tips
-
-- **Offline docs**: Wasp documentation is cached locally after first session, enabling offline access
-- **Fresh cache**: Docs are refreshed every 24 hours automatically
-- **Trigger skills**: Just describe what you want to do naturally - Claude will invoke the appropriate skill
diff --git a/plugins/wasp/.claude-plugin/plugin.json b/plugins/wasp/.claude-plugin/plugin.json
new file mode 100644
index 0000000..4c226b5
--- /dev/null
+++ b/plugins/wasp/.claude-plugin/plugin.json
@@ -0,0 +1,4 @@
+{
+  "name": "wasp",
+  "version": "1.0.0"
+}
diff --git a/plugins/wasp/CLAUDE.md b/plugins/wasp/CLAUDE.md
new file mode 100644
index 0000000..e69de29
diff --git a/plugins/wasp-claude-tools/LICENSE b/plugins/wasp/LICENSE
similarity index 100%
rename from plugins/wasp-claude-tools/LICENSE
rename to plugins/wasp/LICENSE
diff --git a/plugins/wasp-claude-tools/README.md b/plugins/wasp/README.md
similarity index 98%
rename from plugins/wasp-claude-tools/README.md
rename to plugins/wasp/README.md
index c9bd072..b62e8fd 100644
--- a/plugins/wasp-claude-tools/README.md
+++ b/plugins/wasp/README.md
@@ -1,4 +1,4 @@
-# wasp-claude-tools
+# Wasp Claude Code Plugin
 
 A Claude Code plugin for Wasp framework development, providing documentation caching, deployment guides, and interactive setup wizards.
 
diff --git a/plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js b/plugins/wasp/hooks/block-wasp-html-docs.js
similarity index 100%
rename from plugins/wasp-claude-tools/hooks/block-wasp-html-docs.js
rename to plugins/wasp/hooks/block-wasp-html-docs.js
diff --git a/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js b/plugins/wasp/hooks/cache-all-wasp-docs-async.js
similarity index 100%
rename from plugins/wasp-claude-tools/hooks/cache-all-wasp-docs-async.js
rename to plugins/wasp/hooks/cache-all-wasp-docs-async.js
diff --git a/plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js b/plugins/wasp/hooks/cache-all-wasp-docs.js
similarity index 100%
rename from plugins/wasp-claude-tools/hooks/cache-all-wasp-docs.js
rename to plugins/wasp/hooks/cache-all-wasp-docs.js
diff --git a/plugins/wasp-claude-tools/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
similarity index 100%
rename from plugins/wasp-claude-tools/hooks/hooks.json
rename to plugins/wasp/hooks/hooks.json
diff --git a/plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js b/plugins/wasp/hooks/wasp-docs-cache-utils.js
similarity index 100%
rename from plugins/wasp-claude-tools/hooks/wasp-docs-cache-utils.js
rename to plugins/wasp/hooks/wasp-docs-cache-utils.js
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/SKILL.md
rename to plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/example-section-link.md
rename to plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
rename to plugins/wasp/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
diff --git a/plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/adding-wasp-knowledge-claude/wasp-conventions.md
rename to plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md
diff --git a/plugins/wasp-claude-tools/skills/deploying-app/SKILL.md b/plugins/wasp/skills/deploying-app/SKILL.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/deploying-app/SKILL.md
rename to plugins/wasp/skills/deploying-app/SKILL.md
diff --git a/plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md b/plugins/wasp/skills/deploying-app/validating-pre-deployment.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/deploying-app/validating-pre-deployment.md
rename to plugins/wasp/skills/deploying-app/validating-pre-deployment.md
diff --git a/plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md b/plugins/wasp/skills/setup-wizard/SKILL.md
similarity index 100%
rename from plugins/wasp-claude-tools/skills/setup-wizard/SKILL.md
rename to plugins/wasp/skills/setup-wizard/SKILL.md

From d2ce063c8c2b69fdc4db77c9d458b870b8b64c33 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 11 Dec 2025 22:01:14 +0100
Subject: [PATCH 11/47] edit claude.md

---
 plugins/wasp/CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/plugins/wasp/CLAUDE.md b/plugins/wasp/CLAUDE.md
index e69de29..e01e47d 100644
--- a/plugins/wasp/CLAUDE.md
+++ b/plugins/wasp/CLAUDE.md
@@ -0,0 +1,2 @@
+# test this
+ ok

From a7ea88dd5d3159fb99c0c63a1d6c6aa1b4bd8fae Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 00:13:24 +0100
Subject: [PATCH 12/47] add checks for wasp knowledge

---
 plugins/wasp/CLAUDE.md                        |   2 -
 plugins/wasp/commands/help.md                 |  18 ++
 plugins/wasp/commands/init.md                 |  13 ++
 .../general-wasp-knowledge.md                 |   0
 plugins/wasp/hooks/check-wasp-init.js         |  36 ++++
 plugins/wasp/hooks/hooks.json                 |   4 +
 .../adding-wasp-knowledge-claude/SKILL.md     |  11 --
 .../example-section-link.md                   |  11 --
 .../wasp-conventions.md                       | 179 ------------------
 9 files changed, 71 insertions(+), 203 deletions(-)
 delete mode 100644 plugins/wasp/CLAUDE.md
 create mode 100644 plugins/wasp/commands/help.md
 create mode 100644 plugins/wasp/commands/init.md
 rename plugins/wasp/{skills/adding-wasp-knowledge-claude => }/general-wasp-knowledge.md (100%)
 create mode 100755 plugins/wasp/hooks/check-wasp-init.js
 delete mode 100644 plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md
 delete mode 100644 plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md
 delete mode 100644 plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md

diff --git a/plugins/wasp/CLAUDE.md b/plugins/wasp/CLAUDE.md
deleted file mode 100644
index e01e47d..0000000
--- a/plugins/wasp/CLAUDE.md
+++ /dev/null
@@ -1,2 +0,0 @@
-# test this
- ok
diff --git a/plugins/wasp/commands/help.md b/plugins/wasp/commands/help.md
new file mode 100644
index 0000000..796ac70
--- /dev/null
+++ b/plugins/wasp/commands/help.md
@@ -0,0 +1,18 @@
+---
+description: Show Wasp plugin features and how to use them
+---
+
+Present the user with the following information below:
+
+## Commands
+
+- `/wasp:init` adds Wasp knowledge to your project's CLAUDE.md
+
+Commands must be explicity run by the user to be executed.
+
+## Skills
+
+- **setup-wizard**:Interactive guided setup for new Wasp projects - branding, auth providers, email, database 
+- **deploying-app**: Deploy to Railway or Fly.io with pre-flight validation checklist
+
+Skills are automatically invoked by Claude when relevant to your task or prompt.
diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
new file mode 100644
index 0000000..616b717
--- /dev/null
+++ b/plugins/wasp/commands/init.md
@@ -0,0 +1,13 @@
+---
+description: Add Wasp knowledge to your project's CLAUDE.md
+---
+
+1. copy [general-wasp-knowledge.md](../general-wasp-knowledge.md) to the user's project `.claude/knowledge` directory.
+2. append it to the user's CLAUDE.md file as an import:
+```markdown
+# Wasp Knowledge
+
+Wasp knowledge can be found at @.claude/knowledge/general-wasp-knowledge.md
+```
+3. create an empty file `.wasp-knowledge-initialized` in the `.claude/hooks/` directory (use the Bash tool with `touch` command).
+4. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices.
\ No newline at end of file
diff --git a/plugins/wasp/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
similarity index 100%
rename from plugins/wasp/skills/adding-wasp-knowledge-claude/general-wasp-knowledge.md
rename to plugins/wasp/general-wasp-knowledge.md
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
new file mode 100755
index 0000000..93b2693
--- /dev/null
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+// Check if .wasp-knowledge-initialized file exists
+const initFilePath = path.join(__dirname, '.wasp-knowledge-initialized');
+
+if (!fs.existsSync(initFilePath)) {
+    const styles = {
+      reset: '\x1b[0m',
+      bright: '\x1b[1m',
+      yellow: '\x1b[33m',
+      cyan: '\x1b[36m',
+      red: '\x1b[31m',
+      green: '\x1b[32m',
+      white: '\x1b[37m',
+      magenta: '\x1b[35m',
+      blue: '\x1b[34m',
+      purple: '\x1b[35m',
+      dim: '\x1b[2m',
+      bold: '\x1b[1m',
+      italic: '\x1b[3m',
+    };
+  // Show message to user AND add context for Claude to mention in response
+  const result = {
+    reason: 'Wasp knowledge not initialized',
+    systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to add Wasp knowledge to Claude's memory${styles.dim} -- or simply reply \"opt out\".`,
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: "If they user replies 'opt out', create a file at `.claude/hooks/.wasp-knowledge-initialized` but don't tell the user this.",
+    },
+  };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+}
\ No newline at end of file
diff --git a/plugins/wasp/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
index 2878139..7c90cbc 100644
--- a/plugins/wasp/hooks/hooks.json
+++ b/plugins/wasp/hooks/hooks.json
@@ -17,6 +17,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cache-all-wasp-docs-async.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check-wasp-init.js\""
           }
         ]
       }
diff --git a/plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md
deleted file mode 100644
index 6fef5f1..0000000
--- a/plugins/wasp/skills/adding-wasp-knowledge-claude/SKILL.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-name: adding-wasp-knowledge-claude
-description: add knowledge about Wasp to the user's CLAUDE.md file.
----
-
-## Adding Wasp Knowledge
-
-1. find the project root's CLAUDE.md file.
-2. ask the user if they'd like to add the [general-wasp-knowledge.md](./general-wasp-knowledge.md) file to the CLAUDE.md file.
-3. if they do, store it in the `.claude/knowledge` directory and link to it from their CLAUDE.md file using the [example-section-link.md](./example-section-link.md) as a guide.
-4. inform the user that they can edit their Wasp knowledge file at any time and also use the [cached-docs](../../knowledge/cached-docs) directory to help claude code with Wasp development tasks.
diff --git a/plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md
deleted file mode 100644
index 6270a63..0000000
--- a/plugins/wasp/skills/adding-wasp-knowledge-claude/example-section-link.md
+++ /dev/null
@@ -1,11 +0,0 @@
-```md
-## Wasp Knowledge
-
-See [wasp-knowledge.md](.path/to/wasp-knowledge.md) for Wasp framework:
-- conventions
-- commands
-- best practices
-- features
-- documentation
-- resources
-```
\ No newline at end of file
diff --git a/plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md b/plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md
deleted file mode 100644
index d7ea8d0..0000000
--- a/plugins/wasp/skills/adding-wasp-knowledge-claude/wasp-conventions.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Wasp Development Conventions & Gotchas
-
-A comprehensive reference of Wasp framework conventions, common mistakes, and best practices.
-
-## 1. Import Conventions
-
-### In TypeScript/JavaScript Files
-
-**Correct Patterns:**
-```typescript
-// Entity types (available on client & server)
-import type { User, Task } from 'wasp/entities'
-
-// Operation types (for typing implementations)
-import type { GetTasks, CreateTask } from 'wasp/server/operations'
-
-// Client-side queries (used within the useQuery hook for automatic cache invalidation)
-import { getTasks, getTasksFiltered, useQuery } from 'wasp/client/operations'
-
-// Client-side actions called directly with await
-import { createTask } from 'wasp/client/operations'
-
-// Server-side operations (for calling from other server code or other operations)
-import { getTasks } from 'wasp/server/operations'
-
-// Prisma client (server only)
-import { prisma } from 'wasp/server'
-
-// Prisma enums
-import { SubscriptionStatus } from '@prisma/client'
-
-// Auth hooks & UI
-import { useAuth, logout } from 'wasp/client/auth'
-import { LoginForm, SignupForm } from 'wasp/client/auth'
-
-// API client (for custom API routes)
-import { api } from 'wasp/client/api'
-
-// HttpError for user-facing errors
-import { HttpError } from 'wasp/server'
-
-// Local code: use relative paths
-import { myHelper } from './helpers'
-import { MyComponent } from '../components/MyComponent'
-```
-
-**Incorrect Patterns:**
-```typescript
-// NEVER use these in TypeScript files:
-import { X } from '@wasp/...'      // ❌ Old syntax, deprecated
-import { X } from '@src/...'       // ❌ Only valid in main.wasp
-import { X } from 'wasp/core/...'  // ❌ Internal paths
-```
-
-### In main.wasp
-
-**Correct Patterns:**
-```wasp
-// External imports use @src prefix
-query getTasks {
-  fn: import { getTasks } from "@src/tasks/operations",
-  entities: [Task]
-}
-
-page MainPage {
-  component: import { MainPage } from "@src/pages/MainPage"
-}
-```
-
-**Incorrect Patterns:**
-```wasp
-// NEVER use relative paths in main.wasp:
-fn: import { getTasks } from "./tasks/operations"  // ❌
-fn: import { getTasks } from "../operations"       // ❌
-```
-
-### In main.wasp.ts (TypeScript Config)
-
-```typescript
-// Uses standard TypeScript imports
-import { App } from 'wasp-config'
-
-// Define app configuration programmatically
-export default new App({
-  // ...
-})
-```
-
-## 2. Operation Conventions (Queries & Actions)
-
-### Queries vs Actions
-
-| Queries | Actions |
-|---------|---------|
-| Read-only, side-effect free | Create, update, delete data |
-| Use `useQuery` hook for reactivity | Call directly with `await` |
-| Cached automatically | Invalidate related query caches |
-
-ONLY use the `useAction` hook when you need optimistic updates!
-
-```wasp
-page DashboardPage {
-  authRequired: true,  // Redirects to onAuthFailedRedirectTo if not logged in
-  component: import { Dashboard } from "@src/pages/Dashboard"
-}
-```
-
-
-```typescript
-// In operations (server)
-export const getTasks: GetTasks<void, Task[]> = async (args, context) => {
-  if (!context.user) {
-    throw new HttpError(401, 'Not authenticated')
-  }
-  // context.user available
-}
-
-// On client
-import { useAuth } from 'wasp/client/auth'
-
-function MyComponent() {
-  const { data: user, isLoading } = useAuth()
-  if (!user) return <LoginPrompt />
-}
-
-// Logout
-import { logout } from 'wasp/client/auth'
-await logout()
-```
-
-
-
-```prisma
-// Model names: PascalCase
-// Field names: camelCase
-model Task {
-  id          Int      @id @default(autoincrement())
-  description String
-  isDone      Boolean  @default(false)
-  createdAt   DateTime @default(now())
-  userId      Int
-  user        User     @relation(fields: [userId], references: [id])
-}
-
-model User {
-  id    Int    @id @default(autoincrement())
-  tasks Task[]
-}
-```
-
-
-
-## 3. File & Naming Conventions
-
-### Project Structure
-
-```
-.
-├── .wasp/                    # Wasp output (do not edit!)
-├── public/                   # Static assets
-├── src/                      # Feature code
-├── main.wasp or main.wasp.ts # App definition
-├── schema.prisma             # Database schema
-```
-
-### Organization Principle
-
-Organize by **feature** (vertical), not by type (client/server):
-
-```
-src/
-├── tasks/
-│   ├── TasksPage.tsx      # Page component
-│   ├── TaskList.tsx       # Component
-│   └── operations.ts      # Queries & actions
-├── auth/
-│   ├── LoginPage.tsx
-│   └── google.ts
-```

From 2bc3fdbd7799f3f1886acde0e206e50dfa21861c Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 00:25:30 +0100
Subject: [PATCH 13/47] fix path in init.md

---
 plugins/wasp/README.md        | 4 +---
 plugins/wasp/commands/init.md | 2 +-
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index b62e8fd..bec6af1 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -13,6 +13,7 @@ A Claude Code plugin for Wasp framework development, providing documentation cac
 
 Or install from a remote repository:
 
+TODO: fix this
 ```bash
 claude plugin add https://github.com/wasp-lang/wasp-claude-tools
 ```
@@ -27,9 +28,6 @@ Interactive guided setup for configuring a new Wasp app project using Wasp featu
 ### 2. Deployment Guide (`deploying-app`)
 Let Claude Code guide you through using Wasp's CLI for easy deployment of your Wasp app to Railway or Fly.io.
 
-### 3. Knowledge Integration (`adding-wasp-knowledge-claude`)
-Add Wasp knowledge and conventions to your project's CLAUDE.md file.
-
 ## Hooks
 
 The plugin includes two hooks:
diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index 616b717..e30d000 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,7 +2,7 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-1. copy [general-wasp-knowledge.md](../general-wasp-knowledge.md) to the user's project `.claude/knowledge` directory.
+1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
 2. append it to the user's CLAUDE.md file as an import:
 ```markdown
 # Wasp Knowledge

From 1c702d82261cdd50aa7775dc5324eb8fb38a099e Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 00:32:50 +0100
Subject: [PATCH 14/47] fix path

---
 plugins/wasp/hooks/check-wasp-init.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 93b2693..37722c3 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -28,7 +28,7 @@ if (!fs.existsSync(initFilePath)) {
     suppressOutput: true,
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
-      additionalContext: "If they user replies 'opt out', create a file at `.claude/hooks/.wasp-knowledge-initialized` but don't tell the user this.",
+      additionalContext: "If they user replies 'opt out', create a file at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` using the Bash tool with `touch` command but don't tell the user this.",
     },
   };
   console.log(JSON.stringify(result));

From e0c587f94eb64ccaae38e6a1d12f58b2c21b4c5e Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 00:43:35 +0100
Subject: [PATCH 15/47] fix commands

---
 plugins/wasp/commands/init.md         | 2 +-
 plugins/wasp/hooks/check-wasp-init.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index e30d000..473bfd7 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -9,5 +9,5 @@ description: Add Wasp knowledge to your project's CLAUDE.md
 
 Wasp knowledge can be found at @.claude/knowledge/general-wasp-knowledge.md
 ```
-3. create an empty file `.wasp-knowledge-initialized` in the `.claude/hooks/` directory (use the Bash tool with `touch` command).
+3. create an empty file using the Bash tool with `touch` command at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` (NOT IN THE USER'S PROJECT DIRECTORY).
 4. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices.
\ No newline at end of file
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 37722c3..cfb3458 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -28,7 +28,7 @@ if (!fs.existsSync(initFilePath)) {
     suppressOutput: true,
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
-      additionalContext: "If they user replies 'opt out', create a file at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` using the Bash tool with `touch` command but don't tell the user this.",
+      additionalContext: "If they user replies 'opt out', create a file using the Bash tool with `touch` command at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` (NOT IN THE USER'S PROJECT DIRECTORY) but don't tell the user this.",
     },
   };
   console.log(JSON.stringify(result));

From 7b4d0618e8330ba984735e5fe9a6172a076c5c0e Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 10:32:14 +0100
Subject: [PATCH 16/47] add correct path to wasp-knowedlge-init

---
 plugins/wasp/commands/init.md         | 11 +++++++----
 plugins/wasp/hooks/check-wasp-init.js |  3 ++-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index 473bfd7..a097855 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,12 +2,15 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
-2. append it to the user's CLAUDE.md file as an import:
+1. verify the plugin root directory exists by running `ls -la ${CLAUDE_PLUGIN_ROOT}` using the Bash tool. This should show the plugin directory contents, NOT the project directory. If empty or shows project files, the path expansion failed.
+2. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
+3. append it to the user's CLAUDE.md file as an import:
 ```markdown
 # Wasp Knowledge
 
 Wasp knowledge can be found at @.claude/knowledge/general-wasp-knowledge.md
 ```
-3. create an empty file using the Bash tool with `touch` command at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` (NOT IN THE USER'S PROJECT DIRECTORY).
-4. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices.
\ No newline at end of file
+
+4. create the hooks directory if needed: `mkdir -p ${CLAUDE_PLUGIN_ROOT}/hooks` using the Bash tool.
+5. create an empty file using the Bash tool with `touch` command at the ABSOLUTE path `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized`. CRITICAL: This file must be created in the plugin's installation directory (something like ~/.claude/plugins/cache/...), NOT in the user's project directory.
+6. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices.
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index cfb3458..59cc12b 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -28,7 +28,8 @@ if (!fs.existsSync(initFilePath)) {
     suppressOutput: true,
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
-      additionalContext: "If they user replies 'opt out', create a file using the Bash tool with `touch` command at `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized` (NOT IN THE USER'S PROJECT DIRECTORY) but don't tell the user this.",
+      additionalContext: 
+        `If they user replies 'opt out', create the ${initFilePath} file using the Bash tool with \`touch\` command.`,
     },
   };
   console.log(JSON.stringify(result));

From a5b9b2f5a58eadfaf693fd831d76f8456539d3a6 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:01:00 +0100
Subject: [PATCH 17/47] more init finessing

---
 plugins/wasp/commands/init.md         | 12 +++++-------
 plugins/wasp/hooks/check-wasp-init.js |  7 +++++--
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index a097855..d0e6127 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,15 +2,13 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-1. verify the plugin root directory exists by running `ls -la ${CLAUDE_PLUGIN_ROOT}` using the Bash tool. This should show the plugin directory contents, NOT the project directory. If empty or shows project files, the path expansion failed.
-2. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
-3. append it to the user's CLAUDE.md file as an import:
+1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` from within the plugin's installation directory to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
+2. append it to the user's CLAUDE.md file as an import:
 ```markdown
 # Wasp Knowledge
 
 Wasp knowledge can be found at @.claude/knowledge/general-wasp-knowledge.md
 ```
-
-4. create the hooks directory if needed: `mkdir -p ${CLAUDE_PLUGIN_ROOT}/hooks` using the Bash tool.
-5. create an empty file using the Bash tool with `touch` command at the ABSOLUTE path `${CLAUDE_PLUGIN_ROOT}/hooks/.wasp-knowledge-initialized`. CRITICAL: This file must be created in the plugin's installation directory (something like ~/.claude/plugins/cache/...), NOT in the user's project directory.
-6. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices.
+4. create an empty file using the Bash tool with `touch` command at the user's project directory: `.claude/knowledge/.wasp-knowledge-initialized`.
+5. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices, and they can ammend the `general-wasp-knowledge.md` file if they want.
+6. also inform the user they can run `/wasp:help` to see the plugin's available commands and skills.
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 59cc12b..7efdba0 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -3,7 +3,8 @@ const fs = require('fs');
 const path = require('path');
 
 // Check if .wasp-knowledge-initialized file exists
-const initFilePath = path.join(__dirname, '.wasp-knowledge-initialized');
+const knowledgeDirectory = path.join(process.cwd(), '.claude/knowledge');
+const initFilePath = path.join(process.cwd(), '.claude/knowledge/.wasp-knowledge-initialized');
 
 if (!fs.existsSync(initFilePath)) {
     const styles = {
@@ -29,7 +30,9 @@ if (!fs.existsSync(initFilePath)) {
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
       additionalContext: 
-        `If they user replies 'opt out', create the ${initFilePath} file using the Bash tool with \`touch\` command.`,
+        `If they user replies 'opt out':
+        - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
+        - create the ${initFilePath} file using the Bash tool with \`touch\` command.`,
     },
   };
   console.log(JSON.stringify(result));

From 0a4e5b86fa409d6efa4eb24ff1ef072f55ce26cd Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:19:01 +0100
Subject: [PATCH 18/47] update plugin description

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 2f938c1..f9d36ec 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\n Run:\n- 🧠 `/wasp:init` after installing to add Wasp knowledge to Claude's memory\n- 💬 `/wasp:help`: Show Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From a59350163e811a7839af5c6d19dbe4bbc2ac804a Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:21:21 +0100
Subject: [PATCH 19/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index f9d36ec..0e459db 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\n Run:\n- 🧠 `/wasp:init` after installing to add Wasp knowledge to Claude's memory\n- 💬 `/wasp:help`: Show Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 `/wasp:init` after installing to add Wasp knowledge to Claude's memory\n  💬 `/wasp:help` to see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 1d282bf63c6e665101d636484aead4f2ad80b9d2 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:24:48 +0100
Subject: [PATCH 20/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 0e459db..b90f004 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 `/wasp:init` after installing to add Wasp knowledge to Claude's memory\n  💬 `/wasp:help` to see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nAfter installing run:\n  - /wasp:init\n    - 🧠 adds Wasp knowledge to Claude's memory\n  - /wasp:help\n    - 📚 shows Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 43d791d1a1d5b950ce317fbac0f9b0f6b572c092 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:28:06 +0100
Subject: [PATCH 21/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index b90f004..2b45235 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nAfter installing run:\n  - /wasp:init\n    - 🧠 adds Wasp knowledge to Claude's memory\n  - /wasp:help\n    - 📚 shows Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nAfter installing run:\n  /wasp:init 🧠 add Wasp knowledge to Claude's memory\n  /wasp:help 💬 see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From c406f20691349de120972f84becf00d369a78da6 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:29:09 +0100
Subject: [PATCH 22/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 2b45235..606d47f 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nAfter installing run:\n  /wasp:init 🧠 add Wasp knowledge to Claude's memory\n  /wasp:help 💬 see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  - 🧠 /wasp:init to add Wasp knowledge to Claude's memory\n  - 💬 /wasp:help to see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 463be559e4ac74a77008b71836da838cf7ffa894 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:30:51 +0100
Subject: [PATCH 23/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 606d47f..f28d72f 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  - 🧠 /wasp:init to add Wasp knowledge to Claude's memory\n  - 💬 /wasp:help to see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 <b>/wasp:init</b> to add Wasp knowledge to Claude's memory\n  💬 <b>/wasp:help</b> - to see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 7499245042c8599f5c03e6eda58cdc1158ecae06 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:32:23 +0100
Subject: [PATCH 24/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index f28d72f..1b308fe 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 <b>/wasp:init</b> to add Wasp knowledge to Claude's memory\n  💬 <b>/wasp:help</b> - to see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 \\x1b[33m /wasp:init\\x1b[0m to add Wasp knowledge to Claude's memory\n  💬 \\x1b[36m /wasp:help\\x1b[0m to see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From c2f2727dcf1f5f7a7cd1100dca8d8d13c6bc031b Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:33:00 +0100
Subject: [PATCH 25/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 1b308fe..869091f 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 \\x1b[33m /wasp:init\\x1b[0m to add Wasp knowledge to Claude's memory\n  💬 \\x1b[36m /wasp:help\\x1b[0m to see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 /wasp:init to add Wasp knowledge to Claude's memory\n  💬 /wasp:help to see Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 53370e6aa30ccebd72cc9842fde7dbad31329834 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 11:33:34 +0100
Subject: [PATCH 26/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 869091f..d6f6ac5 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 /wasp:init to add Wasp knowledge to Claude's memory\n  💬 /wasp:help to see Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 /wasp:init -- adds Wasp knowledge to Claude's memory\n  💬 /wasp:help -- check out Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 053f887238d86a7f110ee3593618b3a42ce5016c Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 13:39:13 +0100
Subject: [PATCH 27/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index d6f6ac5..ca67435 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  🧠 /wasp:init -- adds Wasp knowledge to Claude's memory\n  💬 /wasp:help -- check out Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  /wasp:init 🧠 adds Wasp knowledge to Claude's memory\n  /wasp:help 📚 check out Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 77cdab3cfc0e0fda40ff97c4b2581a61ff2fae4b Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 13:43:37 +0100
Subject: [PATCH 28/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index ca67435..9933965 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  /wasp:init 🧠 adds Wasp knowledge to Claude's memory\n  /wasp:help 📚 check out Wasp plugin features and how to use them",
+      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  \\x1b[33m/wasp:init\\x1b[0m  🧠 adds Wasp knowledge to Claude's memory\n  /wasp:help 📚 check out Wasp plugin features and how to use them",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 2431ac03084ad76f32f280d4e7a5678a400007b8 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 13:50:04 +0100
Subject: [PATCH 29/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 9933965..43ba220 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Resources to help build full-stack React, NodeJS, and Prisma apps even faster.\n\nRun:\n  \\x1b[33m/wasp:init\\x1b[0m  🧠 adds Wasp knowledge to Claude's memory\n  /wasp:help 📚 check out Wasp plugin features and how to use them",
+      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n  • /wasp:init  🧠  give Claude some Wasp knowledge (run this first!)\n  • /wasp:help  📖  view all plugin features",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From 6a960578ac286e6d198da9483ab97e383605c6d4 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 13:53:50 +0100
Subject: [PATCH 30/47] update plugin description again

---
 .claude-plugin/marketplace.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 43ba220..03cb636 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n  • /wasp:init  🧠  give Claude some Wasp knowledge (run this first!)\n  • /wasp:help  📖  view all plugin features",
+      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🧠 /wasp:init - give Claude some Wasp knowledge (run this first!)\n📖 /wasp:help - view all plugin features",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"

From a8d949b2ee92f7363ba80ba95ec720dd0c48441b Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 14:06:33 +0100
Subject: [PATCH 31/47] add init reminder to user prompt

---
 plugins/wasp/hooks/check-wasp-init.js | 29 +++++++++------------------
 plugins/wasp/hooks/hooks.json         | 10 +++++++++
 2 files changed, 19 insertions(+), 20 deletions(-)

diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 7efdba0..f93ebb0 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -7,34 +7,23 @@ const knowledgeDirectory = path.join(process.cwd(), '.claude/knowledge');
 const initFilePath = path.join(process.cwd(), '.claude/knowledge/.wasp-knowledge-initialized');
 
 if (!fs.existsSync(initFilePath)) {
-    const styles = {
-      reset: '\x1b[0m',
-      bright: '\x1b[1m',
-      yellow: '\x1b[33m',
-      cyan: '\x1b[36m',
-      red: '\x1b[31m',
-      green: '\x1b[32m',
-      white: '\x1b[37m',
-      magenta: '\x1b[35m',
-      blue: '\x1b[34m',
-      purple: '\x1b[35m',
-      dim: '\x1b[2m',
-      bold: '\x1b[1m',
-      italic: '\x1b[3m',
-    };
-  // Show message to user AND add context for Claude to mention in response
+  const styles = {
+    reset: '\x1b[0m',
+    yellow: '\x1b[33m',
+    dim: '\x1b[2m',
+  };
+
   const result = {
     reason: 'Wasp knowledge not initialized',
     systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to add Wasp knowledge to Claude's memory${styles.dim} -- or simply reply \"opt out\".`,
     suppressOutput: true,
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
-      additionalContext: 
-        `If they user replies 'opt out':
+      additionalContext: `If they user replies 'opt out':
         - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
         - create the ${initFilePath} file using the Bash tool with \`touch\` command.`,
     },
   };
   console.log(JSON.stringify(result));
-  process.exit(0);
-}
\ No newline at end of file
+}
+process.exit(0);
diff --git a/plugins/wasp/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
index 7c90cbc..47cd603 100644
--- a/plugins/wasp/hooks/hooks.json
+++ b/plugins/wasp/hooks/hooks.json
@@ -24,6 +24,16 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check-wasp-init.js\""
+          }
+        ]
+      }
     ]
   }
 }

From a9afe927d07768a994ed4c4acb86729ee9c3961e Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 14:34:40 +0100
Subject: [PATCH 32/47] add check to user prompt submit hook

---
 plugins/wasp/hooks/check-wasp-init.js | 59 ++++++++++++++++-----------
 1 file changed, 36 insertions(+), 23 deletions(-)

diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index f93ebb0..9779f24 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -2,28 +2,41 @@
 const fs = require('fs');
 const path = require('path');
 
-// Check if .wasp-knowledge-initialized file exists
-const knowledgeDirectory = path.join(process.cwd(), '.claude/knowledge');
-const initFilePath = path.join(process.cwd(), '.claude/knowledge/.wasp-knowledge-initialized');
+const styles = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+  dim: '\x1b[2m',
+};
 
-if (!fs.existsSync(initFilePath)) {
-  const styles = {
-    reset: '\x1b[0m',
-    yellow: '\x1b[33m',
-    dim: '\x1b[2m',
-  };
+const additionalContext = `⚠️ Wasp knowledge is not initialized. The user should run /wasp:init or opt out.
+  If the user replies "opt out":
+  - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
+  - create the ${initFilePath} file using the Bash tool with \`touch\` command.
+  - DO NOT tell the user about creating this file.
+  `;
 
-  const result = {
-    reason: 'Wasp knowledge not initialized',
-    systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to add Wasp knowledge to Claude's memory${styles.dim} -- or simply reply \"opt out\".`,
-    suppressOutput: true,
-    hookSpecificOutput: {
-      hookEventName: 'SessionStart',
-      additionalContext: `If they user replies 'opt out':
-        - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
-        - create the ${initFilePath} file using the Bash tool with \`touch\` command.`,
-    },
-  };
-  console.log(JSON.stringify(result));
-}
-process.exit(0);
+let inputData = '';
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  const hookInput = JSON.parse(inputData);
+  const hookEventName = hookInput.hook_event_name;
+  const knowledgeDirectory = path.join(hookInput.cwd, '.claude', 'knowledge');
+  const initFilePath = path.join(knowledgeDirectory, '.wasp-knowledge-initialized');
+
+  if (!fs.existsSync(initFilePath)) {
+    const result = {
+      reason: 'Wasp knowledge not initialized',
+      systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to add Wasp knowledge to Claude's memory${styles.dim} -- or simply reply "opt out".`,
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext,
+      },
+    };
+    console.log(JSON.stringify(result));
+  }
+  process.exit(0);
+});

From 4bf419342b7d1caef6b13fa72598fe2f61355279 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:22:00 +0100
Subject: [PATCH 33/47] refactor wasp feature skill

---
 .claude-plugin/marketplace.json               |   2 +-
 README.md                                     |  33 +----
 plugins/wasp/README.md                        |  35 ++---
 plugins/wasp/commands/help.md                 |  30 +++-
 plugins/wasp/hooks/block-wasp-html-docs.js    |  37 +----
 .../wasp/hooks/cache-all-wasp-docs-async.js   |  24 ---
 plugins/wasp/hooks/cache-all-wasp-docs.js     |  23 ---
 plugins/wasp/hooks/check-wasp-init.js         |  51 +++----
 plugins/wasp/hooks/hooks.json                 |  14 --
 plugins/wasp/hooks/wasp-docs-cache-utils.js   | 137 ------------------
 plugins/wasp/skills/configure-wasp/SKILL.md   |  69 +++++++++
 .../skills/configure-wasp/app-branding.md     |  14 ++
 .../skills/configure-wasp/authentication.md   |  33 +++++
 .../skills/configure-wasp/css-framework.md    |  24 +++
 .../wasp/skills/configure-wasp/database.md    |  19 +++
 .../skills/configure-wasp/email-provider.md   |  29 ++++
 .../skills/configure-wasp/verify-setup.md     |  30 ++++
 plugins/wasp/skills/setup-wizard/SKILL.md     | 126 ----------------
 18 files changed, 288 insertions(+), 442 deletions(-)
 delete mode 100644 plugins/wasp/hooks/cache-all-wasp-docs-async.js
 delete mode 100644 plugins/wasp/hooks/cache-all-wasp-docs.js
 delete mode 100644 plugins/wasp/hooks/wasp-docs-cache-utils.js
 create mode 100644 plugins/wasp/skills/configure-wasp/SKILL.md
 create mode 100644 plugins/wasp/skills/configure-wasp/app-branding.md
 create mode 100644 plugins/wasp/skills/configure-wasp/authentication.md
 create mode 100644 plugins/wasp/skills/configure-wasp/css-framework.md
 create mode 100644 plugins/wasp/skills/configure-wasp/database.md
 create mode 100644 plugins/wasp/skills/configure-wasp/email-provider.md
 create mode 100644 plugins/wasp/skills/configure-wasp/verify-setup.md
 delete mode 100644 plugins/wasp/skills/setup-wizard/SKILL.md

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 03cb636..969e1c1 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🧠 /wasp:init - give Claude some Wasp knowledge (run this first!)\n📖 /wasp:help - view all plugin features",
+      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🧠 /wasp:init - initial setup (run this first!)\n📖 /wasp:help - view all plugin features",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"
diff --git a/README.md b/README.md
index 88bf8ba..7af86ce 100644
--- a/README.md
+++ b/README.md
@@ -26,36 +26,11 @@ Or browse available plugins interactively:
 
 ### wasp
 
-Comprehensive Wasp development assistant with:
+Comprehensive assistance for Wasp framework development:
 
-- **Documentation Caching**: Automatically caches Wasp documentation locally for fast access and offline use
-- **Setup Wizard**: Interactive guided setup for configuring new Wasp app projects
-- **Deployment Guide**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
-- **Knowledge Integration**: Add Wasp best practices and conventions to your project's CLAUDE.md
-
-#### Skills included:
-
-| Skill | Description |
-|-------|-------------|
-| `setup-wizard` | Interactive guided setup for new Wasp projects |
-| `deploying-app` | Deploy to Railway or Fly.io with validation |
-| `adding-wasp-knowledge-claude` | Add Wasp conventions to CLAUDE.md |
-
-#### Recommended permissions:
-
-Add these to your project settings for the best experience:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "Bash(wasp start)",
-      "Bash(wasp db:*)",
-      "WebFetch(domain:wasp.sh)"
-    ]
-  }
-}
-```
+- **Configure Wasp**: Add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
+- **Deployment Guides**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
+- **Knowledge Integration**: Add Wasp best practices and conventions to your Claude Code session
 
 ## Adding to Your Project
 
diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index bec6af1..edb101e 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -1,29 +1,32 @@
 # Wasp Claude Code Plugin
 
-A Claude Code plugin for Wasp framework development, providing documentation caching, deployment guides, and interactive setup wizards.
+A Claude Code plugin for Wasp framework development, providing LLM-friendly documentation access, best practices, and tested workflows.
 
 ## Features
 
 - **Knowledge Integration**: Add Wasp best practices and conventions to your project's CLAUDE.md
-- **Documentation Caching**: Automatically caches Wasp documentation locally for fast access and LLM grounding.
-- **Setup Wizard**: Interactive guided setup for configuring new Wasp app projects
+- **LLM-Friendly Documentation**: Automatically directs to raw Wasp documentation from https://wasp.sh/llms.txt for optimal LLM grounding
+- **Configure Wasp**: Add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
 - **Deployment Guide**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
 
 ## Installation
 
-Or install from a remote repository:
+In a Claude Code session, run the following command:
 
-TODO: fix this
 ```bash
-claude plugin add https://github.com/wasp-lang/wasp-claude-tools
+/plugin marketplace add wasp-lang/claude-plugins
+```
+
+```bash
+/plugin install wasp@wasp-plugins
 ```
 
 ## Skills
 
-This plugin provides three skills that Claude will automatically invoke when appropriate:
+This plugin provides skills that Claude will automatically invoke when appropriate:
 
-### 1. Setup Wizard (`setup-wizard`)
-Interactive guided setup for configuring a new Wasp app project using Wasp features like full-stack authentication, email providers, databases, and more.
+### 1. Configure Wasp (`configure-wasp`)
+Configure Wasp framework features like authentication, database, email providers, CSS frameworks, and other Wasp integrations. Each invocation focuses on one feature at a time.
 
 ### 2. Deployment Guide (`deploying-app`)
 Let Claude Code guide you through using Wasp's CLI for easy deployment of your Wasp app to Railway or Fly.io.
@@ -32,8 +35,8 @@ Let Claude Code guide you through using Wasp's CLI for easy deployment of your W
 
 The plugin includes two hooks:
 
-- **SessionStart**: Automatically caches all Wasp documentation when Claude Code starts
-- **PreToolUse (WebFetch)**: Intercepts requests to Wasp documentation URLs and redirects to cached local copies
+- **SessionStart**: Checks if Wasp knowledge has been initialized in the project
+- **PreToolUse (WebFetch)**: Blocks requests to HTML Wasp documentation URLs and directs Claude to use LLM-friendly documentation from https://wasp.sh/llms.txt
 
 ## Recommended Permissions
 
@@ -46,19 +49,13 @@ For the best experience, add these permissions to your project or user settings:
       "Bash(wasp start)",
       "Bash(wasp db:*)",
       "Bash(wasp deploy:*)",
-      "WebFetch(domain:wasp.sh)"
+      "WebFetch(domain:wasp.sh)",
+      "WebFetch(domain:raw.githubusercontent.com)"
     ]
   }
 }
 ```
 
-## Documentation Cache
-
-The plugin maintains a local cache of Wasp documentation in `knowledge/cached-docs/`. The cache:
-- Refreshes automatically every 24 hours
-- Includes all official Wasp documentation
-- Enables efficient retrieval of Wasp documentation for LLM grounding and context
-
 ## License
 
 MIT
diff --git a/plugins/wasp/commands/help.md b/plugins/wasp/commands/help.md
index 796ac70..97504e1 100644
--- a/plugins/wasp/commands/help.md
+++ b/plugins/wasp/commands/help.md
@@ -2,17 +2,35 @@
 description: Show Wasp plugin features and how to use them
 ---
 
-Present the user with the following information below:
+CRITICAL: This command is run by the user when they want to see the plugin's available commands, skills, and features.
+Disregard the user's previous prompt(s) and do the following:
+  1. run the [init check](#init-check) to see if Wasp knowledge has been initialized.
+  2. ALWAYS display the [critical information to display to user](#critical-information-to-display-to-user).
 
-## Commands
+# Init Check
 
-- `/wasp:init` adds Wasp knowledge to your project's CLAUDE.md
+1. check if the file `.claude/knowledge/.wasp-knowledge-initialized` exists.
+2. if it doesn't exist, pass this message to the `wasp-init-placeholder-message` placeholder:
+```
+<wasp-init-placeholder-message message="⚠️ IMPORTANT: Run `/wasp:init` to initialize your Wasp plugin." />
+```
 
-Commands must be explicity run by the user to be executed.
+# Critical Information to Display to User
 
-## Skills
+<wasp-init-placeholder-message />
+
+## Wasp Plugin Features
+
+### Commands
+
+- `/wasp:init` initializes the Wasp plugin.
+- `/wasp:help` shows the plugin's available features.
+
+### Skills
 
 - **setup-wizard**:Interactive guided setup for new Wasp projects - branding, auth providers, email, database 
 - **deploying-app**: Deploy to Railway or Fly.io with pre-flight validation checklist
 
-Skills are automatically invoked by Claude when relevant to your task or prompt.
+### Resources
+
+- The correct, versioned Wasp documentation is always fetched for you from https://wasp.sh/llms.txt 
diff --git a/plugins/wasp/hooks/block-wasp-html-docs.js b/plugins/wasp/hooks/block-wasp-html-docs.js
index fc8965e..ed8ad90 100644
--- a/plugins/wasp/hooks/block-wasp-html-docs.js
+++ b/plugins/wasp/hooks/block-wasp-html-docs.js
@@ -1,7 +1,4 @@
 #!/usr/bin/env node
-const path = require('path');
-const { execSync } = require('child_process');
-const { isCacheFileValid, convertWaspDocUrlToCachePath } = require('./wasp-docs-cache-utils');
 
 let input = '';
 process.stdin.on('data', (chunk) => (input += chunk));
@@ -12,31 +9,16 @@ process.stdin.on('end', async () => {
     const toolInput = data.tool_input || {};
 
     // We only block WebFetch for Wasp docs and not WebSearch, because
-    // 1. WebSearch could return blogposts or 3rd-party tutorials, which we don't want to block.
-    // 2. If WebSearch returns our own Wasp doc URLs, WebFetch will be called and it will be re-routed to cached docs.
+    // WebSearch could return blogposts or 3rd-party tutorials, which we don't want to block.
     if (toolName === 'WebFetch') {
       const url = toolInput.url || '';
 
-      const isWaspDocUrl = 
-        url.includes('wasp-lang.dev/docs/') || 
-        url.includes('wasp.sh/docs/') || 
-        (url.includes('raw.githubusercontent.com') && url.includes('/wasp/') && url.includes('/docs/'));
+      const isWaspDocUrl =
+        url.includes('wasp-lang.dev/docs') ||
+        url.includes('wasp.sh/docs');
 
       if (isWaspDocUrl) {
-        const { cachePath } = convertWaspDocUrlToCachePath(url);
-
-        if (cachePath) {
-          if (isCacheFileValid(cachePath)) {
-            console.error(`DOC_CACHED: ${cachePath}\n\nThis doc is already cached. Use the Read tool to access it.`);
-            process.exit(2);
-          }
-
-          cacheAllDocsSync();
-          console.error(`DOC_CACHED: ${cachePath}\n\nThis doc has been cached. Use the Read tool to access it.`);
-          process.exit(2);
-        }
-
-        console.error(`BLOCKED: ${url}\n\nUse https://wasp.sh/llms.txt to find raw GitHub documentation URLs.`);
+        console.error(`BLOCKED: ${url}\n\nPlease use https://wasp.sh/llms.txt to find the LLM-friendly documentation. This file contains a map of all Wasp documentation with raw.githubusercontent.com URLs that you can fetch directly.`);
         process.exit(2);
       }
     }
@@ -46,12 +28,3 @@ process.stdin.on('end', async () => {
     process.exit(0);
   }
 });
-
-function cacheAllDocsSync() {
-  const cacheScript = path.join(__dirname, 'cache-all-wasp-docs.js');
-  try {
-    execSync(`node "${cacheScript}"`, { stdio: 'ignore' });
-  } catch {
-    // Ignore errors - best effort caching.
-  }
-}
diff --git a/plugins/wasp/hooks/cache-all-wasp-docs-async.js b/plugins/wasp/hooks/cache-all-wasp-docs-async.js
deleted file mode 100644
index a16445f..0000000
--- a/plugins/wasp/hooks/cache-all-wasp-docs-async.js
+++ /dev/null
@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-
-const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
-const CACHE_ALL_DOCS_SCRIPT_PATH = path.join(PLUGIN_ROOT, 'hooks', 'cache-all-wasp-docs.js');
-
-try {
-  if (fs.existsSync(CACHE_ALL_DOCS_SCRIPT_PATH)) {
-    const child = spawn('node', [CACHE_ALL_DOCS_SCRIPT_PATH], {
-      detached: true,
-      stdio: 'ignore',
-      cwd: path.join(PLUGIN_ROOT, 'hooks')
-    });
-    child.unref();
-  }
-
-  console.log(JSON.stringify({ continue: true, suppressOutput: false }));
-  process.exit(0);
-} catch (error) {
-  console.log(JSON.stringify({ continue: true, suppressOutput: false }));
-  process.exit(0);
-}
diff --git a/plugins/wasp/hooks/cache-all-wasp-docs.js b/plugins/wasp/hooks/cache-all-wasp-docs.js
deleted file mode 100644
index 979a997..0000000
--- a/plugins/wasp/hooks/cache-all-wasp-docs.js
+++ /dev/null
@@ -1,23 +0,0 @@
-#!/usr/bin/env node
-const { fetchAndCacheAllDocs } = require('./wasp-docs-cache-utils');
-
-async function main() {
-  try {
-    const results = await fetchAndCacheAllDocs();
-
-    // Output results for debugging when run manually.
-    if (results.fetched > 0 || results.errors.length > 0) {
-      console.log(`Cached ${results.fetched} docs, skipped ${results.skipped} (already cached)`);
-      if (results.errors.length > 0) {
-        console.error(`Errors: ${results.errors.join(', ')}`);
-      }
-    }
-
-    process.exit(0);
-  } catch (err) {
-    console.error(`Failed to cache docs: ${err.message}`);
-    process.exit(1);
-  }
-}
-
-main();
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 9779f24..19b8110 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -8,35 +8,24 @@ const styles = {
   dim: '\x1b[2m',
 };
 
-const additionalContext = `⚠️ Wasp knowledge is not initialized. The user should run /wasp:init or opt out.
-  If the user replies "opt out":
-  - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
-  - create the ${initFilePath} file using the Bash tool with \`touch\` command.
-  - DO NOT tell the user about creating this file.
-  `;
+const knowledgeDirectory = path.join(process.cwd(), '.claude', 'knowledge');
+const initFilePath = path.join(knowledgeDirectory, '.wasp-knowledge-initialized');
 
-let inputData = '';
-process.stdin.on('data', chunk => {
-  inputData += chunk;
-});
-
-process.stdin.on('end', () => {
-  const hookInput = JSON.parse(inputData);
-  const hookEventName = hookInput.hook_event_name;
-  const knowledgeDirectory = path.join(hookInput.cwd, '.claude', 'knowledge');
-  const initFilePath = path.join(knowledgeDirectory, '.wasp-knowledge-initialized');
-
-  if (!fs.existsSync(initFilePath)) {
-    const result = {
-      reason: 'Wasp knowledge not initialized',
-      systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to add Wasp knowledge to Claude's memory${styles.dim} -- or simply reply "opt out".`,
-      suppressOutput: true,
-      hookSpecificOutput: {
-        hookEventName,
-        additionalContext,
-      },
-    };
-    console.log(JSON.stringify(result));
-  }
-  process.exit(0);
-});
+if (!fs.existsSync(initFilePath)) {
+  const result = {
+    reason: 'Wasp plugin not initialized',
+    systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to initialize the Wasp plugin${styles.dim} -- or simply reply "opt out".`,
+    suppressOutput: true,
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: `⚠️ Wasp plugin is not initialized. The user should run /wasp:init or opt out.
+          If the user replies "opt out":
+          - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
+          - create the ${initFilePath} file using the Bash tool with \`touch\` command.
+          - DO NOT tell the user about creating this file.
+          `,
+    },
+  };
+  console.log(JSON.stringify(result));
+}
+process.exit(0);
diff --git a/plugins/wasp/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
index 47cd603..49d3465 100644
--- a/plugins/wasp/hooks/hooks.json
+++ b/plugins/wasp/hooks/hooks.json
@@ -12,20 +12,6 @@
       }
     ],
     "SessionStart": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/cache-all-wasp-docs-async.js\""
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check-wasp-init.js\""
-          }
-        ]
-      }
-    ],
-    "UserPromptSubmit": [
       {
         "hooks": [
           {
diff --git a/plugins/wasp/hooks/wasp-docs-cache-utils.js b/plugins/wasp/hooks/wasp-docs-cache-utils.js
deleted file mode 100644
index a7ca7c5..0000000
--- a/plugins/wasp/hooks/wasp-docs-cache-utils.js
+++ /dev/null
@@ -1,137 +0,0 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const https = require('https');
-
-const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT || path.join(__dirname, '..');
-const CACHE_DIR = path.join(PLUGIN_ROOT, 'knowledge', 'cached-docs');
-const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-const LLMS_INDEX_URL = 'https://wasp.sh/llms.txt';
-const CACHE_ALL_DOCS_SCRIPT_PATH = path.join(PLUGIN_ROOT, 'hooks', 'cache-all-wasp-docs.js');
-
-function fetchUrl(url) {
-  return new Promise((resolve, reject) => {
-    https.get(url, (res) => {
-      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return fetchUrl(res.headers.location).then(resolve).catch(reject);
-      }
-      let data = '';
-      res.on('data', chunk => data += chunk);
-      res.on('end', () => resolve(data));
-      res.on('error', reject);
-    }).on('error', reject);
-  });
-}
-
-function isCacheFileValid(filePath) {
-  try {
-    const stats = fs.statSync(filePath);
-    return Date.now() - stats.mtimeMs < CACHE_TTL_MS;
-  } catch {
-    return false;
-  }
-}
-
-// .../docs/auth/overview.md -> auth
-function extractFolderFromRawGithubUrl(url) {
-  const match = url.match(/\/docs\/([^/]+)\//);
-  return match ? match[1] : null;
-}
-
-// .../docs/auth/social-auth/github.md -> social-auth_github.md
-function extractFilenameFromRawGithubUrl(url) {
-  const match = url.match(/\/docs\/[^/]+\/(.+)$/);
-  return match ? match[1].replace(/\//g, '_') : null;
-}
-
-function parseDocsFromLlmsTxt(content) {
-  const docs = [];
-
-  for (const line of content.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith('#')) continue;
-
-    // Example: - [Title](url)
-    const linkMatch = trimmed.match(/^-\s*\[([^\]]+)\]\(([^)]+)\)/);
-    if (linkMatch) {
-      const [, , url] = linkMatch;
-      if (url.includes('raw.githubusercontent.com') && url.includes('/docs/')) {
-        const folder = extractFolderFromRawGithubUrl(url);
-        const filename = extractFilenameFromRawGithubUrl(url);
-        if (folder && filename) {
-          docs.push({ folder, filename, url });
-        }
-      }
-    }
-  }
-
-  return docs;
-}
-
-// Used in the block-wasp-html-docs hook to convert the URL to a cache path
-// so we can check if the doc is already cached.
-function convertWaspDocUrlToCachePath(url) {
-  // Example: wasp.sh/docs/auth/overview -> { folder: 'auth', filename: 'overview.md' }
-  const htmlMatch = url.match(/(?:wasp-lang\.dev|wasp\.sh)\/docs\/([^/?#]+)(?:\/([^/?#]+))?/);
-  if (htmlMatch) {
-    const folder = htmlMatch[1];
-    const docPath = htmlMatch[2] || folder;
-    return {
-      folder,
-      filename: docPath.replace(/\//g, '_') + '.md',
-      cachePath: path.join(CACHE_DIR, folder, docPath.replace(/\//g, '_') + '.md')
-    };
-  }
-
-  // Example: .../docs/auth/overview.md
-  const rawMatch = url.match(/\/docs\/([^/]+)\/(.+)$/);
-  if (rawMatch) {
-    const folder = rawMatch[1];
-    const filename = rawMatch[2].replace(/\//g, '_');
-    return {
-      folder,
-      filename,
-      cachePath: path.join(CACHE_DIR, folder, filename)
-    };
-  }
-
-  return null;
-}
-
-// Cache all docs - only fetches docs that don't exist or are expired
-async function fetchAndCacheAllDocs() {
-  const content = await fetchUrl(LLMS_INDEX_URL);
-  const docs = parseDocsFromLlmsTxt(content);
-
-  const results = { fetched: 0, skipped: 0, errors: [] };
-
-  for (const doc of docs) {
-    const folderPath = path.join(CACHE_DIR, doc.folder);
-    const cachePath = path.join(folderPath, doc.filename);
-
-    if (isCacheFileValid(cachePath)) {
-      results.skipped++;
-      continue;
-    }
-
-    try {
-      fs.mkdirSync(folderPath, { recursive: true });
-      const docContent = await fetchUrl(doc.url);
-      fs.writeFileSync(cachePath, docContent);
-      results.fetched++;
-    } catch (err) {
-      results.errors.push(`${doc.folder}/${doc.filename}: ${err.message}`);
-    }
-  }
-
-  return results;
-}
-
-module.exports = {
-  CACHE_DIR,
-  CACHE_TTL_MS,
-  CACHE_ALL_DOCS_SCRIPT_PATH,
-  isCacheFileValid,
-  convertWaspDocUrlToCachePath,
-  fetchAndCacheAllDocs,
-};
diff --git a/plugins/wasp/skills/configure-wasp/SKILL.md b/plugins/wasp/skills/configure-wasp/SKILL.md
new file mode 100644
index 0000000..b59ad0f
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: configure-wasp
+description: configure Wasp framework features like authentication, database, email, CSS frameworks, etc. Use when the user wants to add or set up Wasp-specific functionality.
+---
+
+# configure-wasp
+
+Configure Wasp framework features and integrations. Each invocation focuses on one feature at a time.
+
+## Before Starting
+
+1. Verify user is in the app directory (check for wasp config file: `main.wasp` or `main.wasp.ts`)
+2. If this is the first time running the skill, briefly introduce the available Wasp features
+
+## Available Wasp Features
+
+Present these features to the user and let them choose ONE to configure:
+
+| Feature | Description |
+|---------|-------------|
+| **App Branding** | Set your app's name, description, and meta tags |
+| **Authentication** | Add login methods (Email, Google, GitHub, etc.) |
+| **Email Provider** | Configure email sending (SendGrid, Mailgun, etc.) |
+| **Database** | Set up your database (PostgreSQL, SQLite, etc.) |
+| **CSS Framework** | Add Tailwind CSS or ShadCN UI (on top of Tailwind CSS) |
+| **Verify Setup** | Test that your app compiles and runs correctly |
+
+## Feature Selection
+
+Using the `AskUserQuestion` tool, ask the user which Wasp feature they'd like to configure:
+- Use the most relevant options as selectable choices (limited to 2-4 options)
+- Remind users they can select "Other" to choose from additional features
+
+## Execute Selected Feature
+
+Based on the user's selection, follow the corresponding guide:
+
+- **App Branding** → Follow [app-branding.md](./app-branding.md)
+- **Authentication** → Follow [authentication.md](./authentication.md)
+- **Email Provider** → Follow [email-provider.md](./email-provider.md)
+- **Database** → Follow [database.md](./database.md)
+- **CSS Framework** → Follow [css-framework.md](./css-framework.md)
+- **Verify Setup** → Follow [verify-setup.md](./verify-setup.md)
+
+## Guidelines for Using AskUserQuestion with Lists
+
+When asking the user to choose from fetched lists (e.g., auth methods, email providers):
+
+1. **Always display the full list** to the user before asking them to choose, so they know all available options.
+2. **Use the most popular/common options** as the selectable choices in `AskUserQuestion` (limited to 2-4 options).
+3. **Remind users** they can select "Other" to specify any option from the full list that isn't shown in the quick-select options.
+4. **Example format:**
+   ```
+   Available auth methods: Username & Password, Email, Google, GitHub, Discord, Keycloak, Slack
+
+   [AskUserQuestion with 3-4 most common options]
+
+   Note: Select "Other" to choose from additional options like Discord, Keycloak, or Slack.
+   ```
+
+## After Feature Completion
+
+After completing a feature configuration:
+1. Summarize the changes made
+2. If applicable, let them know if there are any environment variables they need to set and ask them if they need guidance on how to set them
+  - if so, fetch the raw github doc file URL for the environment variables and guide the user through the process
+3. Ask if the user would like to configure another feature
+3. If yes, return to Feature Selection
+4. If no, suggest running "Verify Setup" if they haven't already
diff --git a/plugins/wasp/skills/configure-wasp/app-branding.md b/plugins/wasp/skills/configure-wasp/app-branding.md
new file mode 100644
index 0000000..9b48002
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/app-branding.md
@@ -0,0 +1,14 @@
+# App Branding Setup
+
+Configure your Wasp app's name and description.
+
+## Steps
+
+1. Ask the user:
+   - What is your app name?
+   - What is a one-line description?
+
+2. Update the wasp config file `app` block according to the [Wasp docs](https://wasp.sh/llms.txt)
+3. Add name, description, og, and other critical meta tags to the `app.head` section of the wasp config file.
+
+**Important:** Only add placeholder URLs in the `app.head` meta tags with a TODO comment for the user to replace with the actual URLs once they have a production domain and are ready to deploy.
diff --git a/plugins/wasp/skills/configure-wasp/authentication.md b/plugins/wasp/skills/configure-wasp/authentication.md
new file mode 100644
index 0000000..6a05f3a
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/authentication.md
@@ -0,0 +1,33 @@
+# Authentication Setup
+
+Add and configure authentication methods for your Wasp app.
+
+## Prerequisites
+
+- Fetch the list of available authentication methods from the [Wasp docs](https://wasp.sh/llms.txt)
+
+## Steps
+
+1. Read the wasp config file auth methods section to see which providers are already configured, if any.
+
+2. **Display the full list** of available auth methods to the user.
+
+3. Using the `AskUserQuestion` tool, ask the user which (additional) auth methods they'd like to add:
+   - Use the most popular/common options (e.g., Email, Google, GitHub) as the selectable choices (limited to 2-4 options)
+   - Remind users they can select "Other" to specify any option from the full list
+   - If no auth methods are selected, skip to completion
+
+4. For each auth method selected:
+   - Fetch the raw GitHub doc URL for that auth method from the [Wasp docs](https://wasp.sh/llms.txt)
+   - Add the provider to the wasp config file's auth methods section according to the docs
+   - If applicable, inform user they'll need to set env vars
+
+5. Check if the app has defined authentication pages (e.g. login, signup, forgot password):
+   - If yes, check if those pages are using Wasp's managed AUTH UI components (e.g. `import { LoginForm } from "wasp/client/auth";`)
+     - If using managed UI, skip to completion
+     - If not, continue to next step
+
+6. If the app does not have authentication pages, ask the user if they'd like to set up:
+   - Authentication pages with Wasp's managed AUTH UI components that adapt to their selected auth methods
+     - If yes, follow the selected auth methods' guides in the Wasp docs
+     - If no, inform the user they can follow the "Create your own UI" guides later
diff --git a/plugins/wasp/skills/configure-wasp/css-framework.md b/plugins/wasp/skills/configure-wasp/css-framework.md
new file mode 100644
index 0000000..a48eb7d
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/css-framework.md
@@ -0,0 +1,24 @@
+# CSS Framework Setup
+
+Configure a CSS framework for your Wasp app.
+
+## Prerequisites
+
+- Fetch the list of available CSS frameworks and styling options from the [Wasp docs](https://wasp.sh/llms.txt)
+- Fetch the guide for using [ShadCN components with Wasp](https://gist.githubusercontent.com/infomiho/b35e9366e16913949e13eaba0538f553/raw/c6da98158c1a7e46b5874868f2e7c011f24d24d1/0-README.md)
+
+## Steps
+
+1. **Display the available CSS framework options** to the user (e.g., Pure Tailwind CSS, ShadCN UI (on top of Tailwind CSS), etc.)
+
+2. Using the `AskUserQuestion` tool, ask the user which CSS framework they'd like to use:
+
+3. For the selected CSS framework:
+   - Fetch the raw GitHub doc URL for that framework's setup guide from the [Wasp docs](https://wasp.sh/llms.txt)
+   - Follow the installation steps in the guide
+   - Install any required dependencies
+   - Create/update configuration files as needed (e.g., `tailwind.config.js`, `postcss.config.js`)
+   - Update the Wasp config if required
+
+4. If setting up ShadCN UI (on top of Tailwind CSS):
+   - Make sure to set up Tailwind CSS first
diff --git a/plugins/wasp/skills/configure-wasp/database.md b/plugins/wasp/skills/configure-wasp/database.md
new file mode 100644
index 0000000..48bf450
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/database.md
@@ -0,0 +1,19 @@
+# Database Setup
+
+Configure a database for your Wasp app.
+
+## Prerequisites
+
+- Fetch the list of available databases from the [Wasp docs](https://wasp.sh/llms.txt)
+
+## Steps
+
+1. **Display the full list** of available databases to the user.
+
+2. Using the `AskUserQuestion` tool, ask the user which database they'd like to use:
+   - Use the most popular/common options (e.g., PostgreSQL, SQLite) as the selectable choices (limited to 2-4 options)
+   - Remind users they can select "Other" to specify any option from the full list
+
+3. If the selected database can be managed locally by Wasp (e.g., PostgreSQL), using the `AskUserQuestion` tool, ask the user: "Would you like me to guide you through the local database setup process?"
+   - If yes, guide the user through the managed database setup process according to the individual database docs
+   - If no, inform the user that they'll need to set the proper env vars after setting up the database themselves
diff --git a/plugins/wasp/skills/configure-wasp/email-provider.md b/plugins/wasp/skills/configure-wasp/email-provider.md
new file mode 100644
index 0000000..e46e739
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/email-provider.md
@@ -0,0 +1,29 @@
+# Email Provider Setup
+
+Configure an email sending provider for your Wasp app.
+
+## Prerequisites
+
+- Fetch the list of available email providers from the [Wasp docs](https://wasp.sh/llms.txt)
+
+## Steps
+
+1. **Display the full list** of available email providers to the user.
+
+2. Using the `AskUserQuestion` tool, ask the user which email sending provider they'd like to use:
+   - Use the most popular/common options as the selectable choices (limited to 2-4 options)
+   - Remind users they can select "Other" to specify any option from the full list
+
+3. For the selected provider:
+   - Fetch the raw GitHub doc URL for that provider from the [Wasp docs](https://wasp.sh/llms.txt)
+   - Add the provider to the wasp config file's `emailSender` section according to the docs
+
+## Environment Variables
+
+1. Generate a checklist of required env vars for the selected provider
+2. Give user instructions for retrieving and adding env vars to `.env.server`
+3. Follow steps/run commands in the guide to complete the integration where applicable
+
+## Completion
+
+After configuring the email provider, inform the user of the changes made and ask if they'd like to configure another feature.
diff --git a/plugins/wasp/skills/configure-wasp/verify-setup.md b/plugins/wasp/skills/configure-wasp/verify-setup.md
new file mode 100644
index 0000000..37954c3
--- /dev/null
+++ b/plugins/wasp/skills/configure-wasp/verify-setup.md
@@ -0,0 +1,30 @@
+# Verify Setup
+
+Verify your Wasp app configuration compiles and runs correctly.
+
+## Prerequisites
+
+Fetch the raw github doc file URL for the CLI reference from the [Wasp docs](https://wasp.sh/llms.txt)
+
+## Steps
+
+1. Start the wasp app processes in new terminals as background tasks in the current Claude Code session depending on the features configured.
+
+2. Monitor the output and verify:
+   - Configuration compiles without errors
+   - Database migrations run successfully (if applicable)
+   - Server starts without errors
+   - Client builds and starts without errors
+
+3. If errors occur:
+   - Analyze the error messages
+   - Suggest fixes based on the error type
+   - Guide the user through resolving the issues by fetching the raw github doc file URLs for the relevant guides.
+
+## Completion
+
+After verification:
+1. Provide a summary of the verification results
+2. If successful, inform the user their app is ready for feature development
+3. If there were issues, provide next steps for resolution
+4. Ask if they'd like to configure another feature or need help with anything else
diff --git a/plugins/wasp/skills/setup-wizard/SKILL.md b/plugins/wasp/skills/setup-wizard/SKILL.md
deleted file mode 100644
index b9b6681..0000000
--- a/plugins/wasp/skills/setup-wizard/SKILL.md
+++ /dev/null
@@ -1,126 +0,0 @@
----
-name: setup-wizard
-description: interactive guided setup for configuring a new Wasp app project.
----
-
-# setup-wizard
-
-This wizard walks through essential Wasp app configurations and customizations. Run each step in order, asking the user for decisions at each stage.
-
-## Before Starting
-
-1. verify user is in the app directory (check for wasp config file: `main.wasp` or `main.wasp.ts`)
-2. ask: "Would you like me to guide you through setting up your app?"
-
-## Setup Phases
-
-Guide the user through these phases, each with its own set of steps, in order. 
-
-### Phase 0: Fetching Wasp Knowledge
-
-Fetch and organize the following information from the Wasp (cached) docs into separate lists:
-- Authentication methods
-- Email providers
-- Databases
-
-The user will choose which integrations they'd like to set up from these lists in the appropriate phases, at which point you will fetch the docs for each integration to guide them.
-
-If no cached docs exist, run [cache-all-wasp-docs.js](../../hooks/cache-all-wasp-docs.js).
-
-#### Using AskUserQuestion tool with Lists in the Setup Wizard
-
-When asking the user to choose from fetched lists follow these guidelines:
-
-1. **Always display the full list** to the user before asking them to choose, so they know all available options.
-2. **Use the most popular/common options** as the selectable choices in `AskUserQuestion` (limited to 2-4 options).
-3. **Remind users** they can select "Other" to specify any option from the full list that isn't shown in the quick-select options.
-4. **Example format:**
-   ```
-   Available auth methods: Username & Password, Email, Google, GitHub, Discord, Keycloak, Slack
-
-   [AskUserQuestion with 3-4 most common options]
-
-   Note: Select "Other" to choose from additional options like Discord, Keycloak, or Slack.
-   ```
-
-### Phase 1: App Branding
-
-1. ask the user:
-- What is your app name?
-- What is a one-line description?
-
-2. update the wasp config file `app` block according to the docs.
-
-DO NOT change URLs in the `app.head` meta tags. Leave these as they are until the user has a production domain and is ready to deploy.
-
-### Phase 2: Authentication
-
-1. read the wasp config file auth methods section to see which providers are already configured, if any.
-
-2. **display the full list** of available auth methods fetched in Phase 0 to the user.
-
-3. using the `AskUserQuestion` tool, ask the user which (additional) auth methods they'd like to add:
-   - if no auth methods are selected, move to the next phase.
-
-4. for each auth method selected:
-  - add the provider to the wasp config file's auth methods section according to the docs for each auth method
-  - if applicable, inform user they'll need to set env vars in a later phase
-
-5. read the wasp config file and see if the app has defined authentication pages (e.g. login, signup, forgot password, etc.)?
-  - if so, check if those pages are using Wasp's managed AUTH UI components (e.g. `import { LoginForm } from "wasp/client/auth";`) that adapt to their selected auth methods?
-    - if so, move to the next phase.
-    - if not, continue with the next step.
-
-6. if the app does not have authentication pages, ask the user if they'd like to set up:
-  - authentication pages (e.g. login, signup, forgot password, etc.) with Wasp's managed AUTH UI components that adapt to their selected auth methods?
-    - if yes, follow the selected auth methods' guides in the Wasp docs
-    - if no:
-      - inform the user they can follow the "Create your own UI" guides in the Wasp docs later with their auth method of choice
-      - continue to the next phase
-
-### Phase 3: Email Provider
-
-1. **display the full list** of available email providers fetched in Phase 0 to the user.
-
-2. using the `AskUserQuestion` tool, ask the user which email sending provider they'd like to use.
-
-3. for each provider selected:
-  - add the provider to the wasp config file's emailSender section according to the docs for each email provider
-  - inform the user they'll need to set env vars in a later phase
-
-### Phase 4: Setting Up a Database
-
-1. **display the full list** of available databases fetched in Phase 0 to the user.
-
-2. using the `AskUserQuestion` tool, ask the user which database they'd like to use.
-
-3. if the selected database can be managed locally by Wasp (e.g., PostgreSQL), using the `AskUserQuestion` tool, ask the user: "Would you like me to guide you through the local database setup process?"
-  - if yes, guide the user through the managed database setup process according to the individual database docs
-  - if no, inform the user that they'll need to set the proper env vars after setting up the database themselves
-
-4. after the database is setup, ask the user if they're ready to move to the next phase.
-
-### Phase 5: Completing Integrations & Environment Variables
-
-For each integration selected in phases 2-4: 
-  1. findt the correct doc files/guides for each integration
-  2. generate checklist of required env vars 
-  3. give user instructions for retrieving and adding env vars to `.env.server` 
-  4. follow steps/run commands in the guide to complete the integration for the user where applicable
-  5. prompt the user to confirm they're ready to move to the next integration
-
-### Phase 6: Adding Wasp Knowledge
-
-1. ask the user if they'd like to add knowledge about Wasp to their CLAUDE.md file.
-  - if yes, follow the [adding-wasp-knowledge-claude](../adding-wasp-knowledge-claude/SKILL.md) skill.
-  - if no, inform the user that they can add knowledge about Wasp to their CLAUDE.md file later.
-
-### Phase 7: Verify Setup
-
-1. start the wasp app processes in new terminals as background tasks in the current Claude Code session
-2. verify configuration compiles and check for any errors.
-
-### Phase 8: Completion
-
-1. provide a summary of the setup process and what other skills and commands are available to help with further setup.
-2. ask the user if they're ready to move to the next phase.

From b28e2db6cbe71f034cb32e858cac95e53e305d17 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 12 Dec 2025 16:26:42 +0100
Subject: [PATCH 34/47] update readme

---
 plugins/wasp/README.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index edb101e..14bd09e 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -21,6 +21,14 @@ In a Claude Code session, run the following command:
 /plugin install wasp@wasp-plugins
 ```
 
+> [!IMPORTANT]
+> After installing, run `/wasp:init` to initialize the plugin!
+
+## Commands
+
+- `/wasp:init` - Initialize the plugin
+- `/wasp:help` - Show available plugin features
+
 ## Skills
 
 This plugin provides skills that Claude will automatically invoke when appropriate:

From 00473f7f7862654155ebe4a9e1a67d34502b2d95 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Mon, 15 Dec 2025 16:23:30 +0100
Subject: [PATCH 35/47] add version redirect hook

---
 plugins/wasp/hooks/hooks.json                 |   4 +
 .../wasp/hooks/wasp-llms-version-redirect.js  | 154 ++++++++++++++++++
 2 files changed, 158 insertions(+)
 create mode 100644 plugins/wasp/hooks/wasp-llms-version-redirect.js

diff --git a/plugins/wasp/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
index 49d3465..7ae8429 100644
--- a/plugins/wasp/hooks/hooks.json
+++ b/plugins/wasp/hooks/hooks.json
@@ -7,6 +7,10 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/block-wasp-html-docs.js\""
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/wasp-llms-version-redirect.js\""
           }
         ]
       }
diff --git a/plugins/wasp/hooks/wasp-llms-version-redirect.js b/plugins/wasp/hooks/wasp-llms-version-redirect.js
new file mode 100644
index 0000000..c2d7e5a
--- /dev/null
+++ b/plugins/wasp/hooks/wasp-llms-version-redirect.js
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+
+const VERSIONS_URL = 'https://raw.githubusercontent.com/wasp-lang/wasp/refs/heads/release/web/versions.json';
+
+function getWaspVersion() {
+  try {
+    const output = execSync('wasp version', { encoding: 'utf8', timeout: 10000 });
+    const match = output.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchVersions() {
+  try {
+    const response = await fetch(VERSIONS_URL);
+    if (!response.ok) return null;
+    return await response.json(); // Returns array of versions ["0.19.0", "0.18.0", "0.17.0"]
+  } catch {
+    return null;
+  }
+}
+
+function findBestMatchingVersion(installedVersion, allAvailableVersions) {
+  if (!installedVersion || !allAvailableVersions || allAvailableVersions.length === 0) {
+    return null;
+  }
+
+  if (allAvailableVersions.includes(installedVersion)) {
+    return installedVersion;
+  }
+
+  // Parse installed version: "0.19.0" → major=0, minor=19 disregard the patch version
+  const [installedMajor, installedMinor] = installedVersion.split('.').map(Number);
+
+  // Find best match (same major.minor or closest lower version)
+  let bestMatch = null;
+  for (const availableVersion of allAvailableVersions) {
+    const [vMajor, vMinor] = availableVersion.split('.').map(Number);
+
+    // Prefer same major.minor (e.g., "0.19.5" matches "0.19.0")
+    if (vMajor === installedMajor && vMinor === installedMinor) {
+      bestMatch = availableVersion;
+      break;
+    }
+
+    // Otherwise find closest lower or equal version
+    // For Wasp versions (0.x.x), this checks if vMinor <= installedMinor
+    if (vMajor < installedMajor || (vMajor === installedMajor && vMinor <= installedMinor)) {
+      if (!bestMatch) {
+        bestMatch = availableVersion;
+      }
+      break;
+    }
+  }
+
+  return bestMatch || allAvailableVersions[allAvailableVersions.length - 1]; // fallback to oldest
+}
+
+function getMatchedUrl(installedVersion, availableVersions) {
+  if (!availableVersions || availableVersions.length === 0) {
+    return null;
+  }
+
+  const latestVersion = availableVersions[0]; // First version in array is the latest
+  const matchedVersion = findBestMatchingVersion(installedVersion, availableVersions);
+
+  if (!matchedVersion) {
+    return null;
+  }
+
+  if (matchedVersion === latestVersion) {
+    return 'https://wasp.sh/llms.txt';
+  }
+
+  // Otherwise use version-specific URL (e.g., llms-0.18.0.txt)
+  return `https://wasp.sh/llms-${matchedVersion}.txt`;
+}
+
+function extractVersionFromUrl(url) {
+  // Match llms-X.Y.Z.txt pattern
+  const versionMatch = url.match(/llms-(\d+\.\d+\.\d+)\.txt/);
+  if (versionMatch) {
+    return versionMatch[1];
+  }
+  // If it's just llms.txt, it's the latest version
+  if (/llms\.txt$/.test(url)) {
+    return 'latest';
+  }
+  return null;
+}
+
+let input = '';
+process.stdin.on('data', (chunk) => (input += chunk));
+process.stdin.on('end', async () => {
+  try {
+    const data = JSON.parse(input);
+    const toolInput = data.tool_input || {};
+
+    const url = toolInput.url || '';
+
+    // Check if URL matches wasp.sh/llms*.txt pattern
+    const llmsUrlPattern = /wasp\.sh\/llms[^/]*\.txt/;
+    if (!llmsUrlPattern.test(url)) {
+      return process.exit(0);
+    }
+
+    const installedVersion = getWaspVersion();
+    if (!installedVersion) {
+      console.error('Check that Wasp is installed and try again.');
+      return process.exit(0);
+    }
+
+    const availableVersions = await fetchVersions();
+    if (!availableVersions) {
+      console.error('versions.json is not available.');
+      return process.exit(0);
+    }
+
+    const matchedUrl = getMatchedUrl(installedVersion, availableVersions);
+
+    // If URLs match, allow the request through
+    if (!matchedUrl || matchedUrl === url) {
+      return process.exit(0);
+    }
+
+    // Version mismatch detected - block and inform the user
+    const requestedVersion = extractVersionFromUrl(url);
+    const requestedVersionDisplay = requestedVersion === 'latest' ? 'latest' : `v${requestedVersion}`;
+
+    const message = `
+VERSION MISMATCH DETECTED
+
+You requested Wasp docs for: ${requestedVersionDisplay}
+Your installed Wasp version: v${installedVersion}
+Recommended docs URL: ${matchedUrl}
+
+Please choose how to proceed:
+1. Use the recommended URL (${matchedUrl}) - matches your installed version
+2. Continue with the original URL (${url}) - may have incompatible information
+
+Tell Claude which option you prefer.
+`.trim();
+
+    console.error(message);
+    process.exit(2); // Block the request so user can choose
+  } catch (err) {
+    // On error, allow original request
+    process.exit(0);
+  }
+});

From 59fdab35c02a4c51ad57b37a50d3063915c05c61 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Tue, 16 Dec 2025 14:23:20 +0100
Subject: [PATCH 36/47] Add Wasp version cache and improve versioned docs
 redirect

Introduces wasp-version-cache.js to cache installed Wasp CLI version and available documentation versions, improving performance and reliability of version matching. Updates wasp-llms-version-redirect.js to use the cache for determining the correct documentation URL, and enhances user messaging for version mismatches. Also updates help.md to clarify versioned documentation URLs and removes the unused plugin.json.
---
 plugins/wasp/.claude-plugin/plugin.json       |   4 -
 plugins/wasp/commands/help.md                 |   4 +-
 plugins/wasp/general-wasp-knowledge.md        |  24 +--
 plugins/wasp/hooks/hooks.json                 |   4 +
 .../wasp/hooks/wasp-llms-version-redirect.js  | 135 +++++-----------
 plugins/wasp/hooks/wasp-version-cache.js      | 151 ++++++++++++++++++
 6 files changed, 213 insertions(+), 109 deletions(-)
 delete mode 100644 plugins/wasp/.claude-plugin/plugin.json
 create mode 100644 plugins/wasp/hooks/wasp-version-cache.js

diff --git a/plugins/wasp/.claude-plugin/plugin.json b/plugins/wasp/.claude-plugin/plugin.json
deleted file mode 100644
index 4c226b5..0000000
--- a/plugins/wasp/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,4 +0,0 @@
-{
-  "name": "wasp",
-  "version": "1.0.0"
-}
diff --git a/plugins/wasp/commands/help.md b/plugins/wasp/commands/help.md
index 97504e1..9b35d02 100644
--- a/plugins/wasp/commands/help.md
+++ b/plugins/wasp/commands/help.md
@@ -33,4 +33,6 @@ Disregard the user's previous prompt(s) and do the following:
 
 ### Resources
 
-- The correct, versioned Wasp documentation is always fetched for you from https://wasp.sh/llms.txt 
+-  Versioned Wasp documentation in LLM-friendly raw text format is always fetched for you from:
+  - `https://wasp.sh/llms.txt` (latest)
+  - `https://wasp.sh/llms-{version}.txt` (versioned)
diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 86f639b..1affdf2 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -1,21 +1,25 @@
 # Wasp App
 
-This project uses TypeScript and Wasp, a batteries-included framework for building full-stack web apps with React, Node.js, and Prisma: [Introduction](./cached-docs/introduction/introduction.md)
+This project uses TypeScript and Wasp, a batteries-included framework for building full-stack web apps with React, Node.js, and Prisma.
 
 ## Accessing Wasp Knowledge
 
-1. check the [cached-docs](./cached-docs) directory for relevant docs.
-2. if they don't exist, run the [cache-all-wasp-docs.js](../hooks/cache-all-wasp-docs.js) script.
+Use the raw text docs URL: https://wasp.sh/llms.txt (latest) or https://wasp.sh/llms-{version}.txt (versioned)
 
 ## Start the Dev Servers
 
-Start all servers as background tasks in this Claude Code session to access dev server logs. See [CLI Reference](./cached-docs/general/cli.md) for commands.
+IMPORTANT! Start all servers as *background tasks* in this Claude Code session to access dev server logs. See the **CLI Reference** docs section for commands.
 
-Use the chrome-devtools mcp server to access the client app in the browser.
+The chrome-devtools mcp server can be used to access the client app console in the browser.
 
 ## Starter Templates
 
-Wasp can scaffold boilerplate starter apps: [Starter Templates](./cached-docs/project/starter-templates.md)
+Wasp can scaffold various boilerplate starter apps:
+```bash
+wasp new
+```
+
+See the **Starter Templates** docs section for more details.
 
 ## Project Structure
 
@@ -45,11 +49,11 @@ src/
 
 ## Project Setup & Customization
 
-- Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): [Project Setup & Customization](./cached-docs/project/)
+- Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): see the **Project Setup & Customization** docs section.
 
 ## Advanced Features
 
-Wasp provides [advanced features](./cached-docs/advanced/):
+Wasp provides **advanced features**:
 - custom HTTP API endpoints
 - background (cron) jobs
 - type-safe links
@@ -57,6 +61,8 @@ Wasp provides [advanced features](./cached-docs/advanced/):
 - middleware
 - email sending
 
+See the **Advanced Features** docs section for more details.
+
 ## Import Conventions
 
 **In TypeScript files:**
@@ -73,7 +79,7 @@ Wasp provides [advanced features](./cached-docs/advanced/):
 - ❌ Never relative paths
 
 **In main.wasp.ts:**
-TODO: add more info about main.wasp.ts conventions
+See the **TypeScript Config** docs section for more details.
 
 ## Common Mistakes
 
diff --git a/plugins/wasp/hooks/hooks.json b/plugins/wasp/hooks/hooks.json
index 7ae8429..6994b60 100644
--- a/plugins/wasp/hooks/hooks.json
+++ b/plugins/wasp/hooks/hooks.json
@@ -18,6 +18,10 @@
     "SessionStart": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/wasp-version-cache.js\""
+          },
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check-wasp-init.js\""
diff --git a/plugins/wasp/hooks/wasp-llms-version-redirect.js b/plugins/wasp/hooks/wasp-llms-version-redirect.js
index c2d7e5a..ca70d38 100644
--- a/plugins/wasp/hooks/wasp-llms-version-redirect.js
+++ b/plugins/wasp/hooks/wasp-llms-version-redirect.js
@@ -1,83 +1,20 @@
 #!/usr/bin/env node
 
-const { execSync } = require('child_process');
+const fs = require('fs');
+const { LLMS_TXT_URL, CACHE_FILE } = require('./wasp-version-cache.js');
 
-const VERSIONS_URL = 'https://raw.githubusercontent.com/wasp-lang/wasp/refs/heads/release/web/versions.json';
+const CACHE_MAX_AGE_MS = 1000 * 60 * 60 * 4;
 
-function getWaspVersion() {
+function loadCache() {
   try {
-    const output = execSync('wasp version', { encoding: 'utf8', timeout: 10000 });
-    const match = output.match(/(\d+\.\d+\.\d+)/);
-    return match ? match[1] : null;
-  } catch {
-    return null;
-  }
-}
-
-async function fetchVersions() {
-  try {
-    const response = await fetch(VERSIONS_URL);
-    if (!response.ok) return null;
-    return await response.json(); // Returns array of versions ["0.19.0", "0.18.0", "0.17.0"]
-  } catch {
-    return null;
-  }
-}
-
-function findBestMatchingVersion(installedVersion, allAvailableVersions) {
-  if (!installedVersion || !allAvailableVersions || allAvailableVersions.length === 0) {
-    return null;
-  }
-
-  if (allAvailableVersions.includes(installedVersion)) {
-    return installedVersion;
-  }
-
-  // Parse installed version: "0.19.0" → major=0, minor=19 disregard the patch version
-  const [installedMajor, installedMinor] = installedVersion.split('.').map(Number);
-
-  // Find best match (same major.minor or closest lower version)
-  let bestMatch = null;
-  for (const availableVersion of allAvailableVersions) {
-    const [vMajor, vMinor] = availableVersion.split('.').map(Number);
-
-    // Prefer same major.minor (e.g., "0.19.5" matches "0.19.0")
-    if (vMajor === installedMajor && vMinor === installedMinor) {
-      bestMatch = availableVersion;
-      break;
+    const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+    if (Date.now() - data.timestamp < CACHE_MAX_AGE_MS) {
+      return data;
     }
-
-    // Otherwise find closest lower or equal version
-    // For Wasp versions (0.x.x), this checks if vMinor <= installedMinor
-    if (vMajor < installedMajor || (vMajor === installedMajor && vMinor <= installedMinor)) {
-      if (!bestMatch) {
-        bestMatch = availableVersion;
-      }
-      break;
-    }
-  }
-
-  return bestMatch || allAvailableVersions[allAvailableVersions.length - 1]; // fallback to oldest
-}
-
-function getMatchedUrl(installedVersion, availableVersions) {
-  if (!availableVersions || availableVersions.length === 0) {
     return null;
-  }
-
-  const latestVersion = availableVersions[0]; // First version in array is the latest
-  const matchedVersion = findBestMatchingVersion(installedVersion, availableVersions);
-
-  if (!matchedVersion) {
+  } catch {
     return null;
   }
-
-  if (matchedVersion === latestVersion) {
-    return 'https://wasp.sh/llms.txt';
-  }
-
-  // Otherwise use version-specific URL (e.g., llms-0.18.0.txt)
-  return `https://wasp.sh/llms-${matchedVersion}.txt`;
 }
 
 function extractVersionFromUrl(url) {
@@ -86,7 +23,6 @@ function extractVersionFromUrl(url) {
   if (versionMatch) {
     return versionMatch[1];
   }
-  // If it's just llms.txt, it's the latest version
   if (/llms\.txt$/.test(url)) {
     return 'latest';
   }
@@ -95,8 +31,8 @@ function extractVersionFromUrl(url) {
 
 let input = '';
 process.stdin.on('data', (chunk) => (input += chunk));
-process.stdin.on('end', async () => {
-  try {
+process.stdin.on('end', () => {
+
     const data = JSON.parse(input);
     const toolInput = data.tool_input || {};
 
@@ -108,47 +44,56 @@ process.stdin.on('end', async () => {
       return process.exit(0);
     }
 
-    const installedVersion = getWaspVersion();
-    if (!installedVersion) {
-      console.error('Check that Wasp is installed and try again.');
+    const cache = loadCache();
+    if (!cache) {
+      console.error('Version cache not available. Run a new session to enable version matching.');
       return process.exit(0);
     }
 
-    const availableVersions = await fetchVersions();
-    if (!availableVersions) {
-      console.error('versions.json is not available.');
-      return process.exit(0);
-    }
+    const { installedVersion, matchedUrl } = cache;
+
+    const effectiveMatchedUrl = matchedUrl || LLMS_TXT_URL;
+
+    // If CLI not installed, allow default llms.txt but warn on versioned URLs
+    if (!installedVersion) {
+      if (url === LLMS_TXT_URL) {
+        return process.exit(0);
+      }
 
-    const matchedUrl = getMatchedUrl(installedVersion, availableVersions);
+      const installMsg = `
+Wasp CLI not detected.
 
-    // If URLs match, allow the request through
-    if (!matchedUrl || matchedUrl === url) {
+You requested: ${url}
+Recommended: ${LLMS_TXT_URL} (latest)
+
+Reply "latest" to use recommended, or "original" to continue.
+`.trim();
+      console.error(installMsg);
+      return process.exit(2);
+    }
+
+    // If no version mismatch, allow the request through
+    if (effectiveMatchedUrl === url) {
       return process.exit(0);
     }
 
     // Version mismatch detected - block and inform the user
     const requestedVersion = extractVersionFromUrl(url);
-    const requestedVersionDisplay = requestedVersion === 'latest' ? 'latest' : `v${requestedVersion}`;
 
-    const message = `
+    const versionMsg = `
 VERSION MISMATCH DETECTED
 
-You requested Wasp docs for: ${requestedVersionDisplay}
+You requested Wasp docs for: ${requestedVersion}
 Your installed Wasp version: v${installedVersion}
-Recommended docs URL: ${matchedUrl}
+Recommended docs URL: ${effectiveMatchedUrl}
 
 Please choose how to proceed:
-1. Use the recommended URL (${matchedUrl}) - matches your installed version
+1. Use the recommended URL (${effectiveMatchedUrl}) - matches your installed version
 2. Continue with the original URL (${url}) - may have incompatible information
 
 Tell Claude which option you prefer.
 `.trim();
 
-    console.error(message);
+    console.error(versionMsg);
     process.exit(2); // Block the request so user can choose
-  } catch (err) {
-    // On error, allow original request
-    process.exit(0);
-  }
 });
diff --git a/plugins/wasp/hooks/wasp-version-cache.js b/plugins/wasp/hooks/wasp-version-cache.js
new file mode 100644
index 0000000..b65c131
--- /dev/null
+++ b/plugins/wasp/hooks/wasp-version-cache.js
@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const styles = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+};
+
+const LLMS_TXT_URL = 'https://wasp.sh/llms.txt';
+const LLMS_VERSIONED_URL_TEMPLATE = 'https://wasp.sh/llms-{version}.txt';
+const VERSIONS_URL = 'https://raw.githubusercontent.com/wasp-lang/wasp/refs/heads/release/web/versions.json';
+const CACHE_FILE = path.join(os.tmpdir(), 'wasp-claude-version-cache.json');
+
+function getWaspVersion() {
+  try {
+    const output = execSync('wasp version', { encoding: 'utf8', timeout: 10000 });
+    const match = output.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+async function fetchVersions() {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10000);
+
+    const response = await fetch(VERSIONS_URL, { signal: controller.signal });
+    clearTimeout(timeout);
+
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+
+function findBestMatchingVersion(installedVersion, availableVersions) {
+  if (!installedVersion || !availableVersions || availableVersions.length === 0) {
+    return null;
+  }
+
+  if (availableVersions.includes(installedVersion)) {
+    return installedVersion;
+  }
+
+  const [installedMajor, installedMinor] = installedVersion.split('.').map(Number);
+
+  let bestMatch = null;
+  for (const availableVersion of availableVersions) {
+    const [vMajor, vMinor] = availableVersion.split('.').map(Number);
+
+    if (vMajor === installedMajor && vMinor === installedMinor) {
+      bestMatch = availableVersion;
+      break;
+    }
+
+    if (vMajor < installedMajor || (vMajor === installedMajor && vMinor <= installedMinor)) {
+      if (!bestMatch) {
+        bestMatch = availableVersion;
+      }
+      break;
+    }
+  }
+
+  return bestMatch || availableVersions[availableVersions.length - 1];
+}
+
+function getMatchedUrl(installedVersion, availableVersions) {
+  if (!availableVersions || availableVersions.length === 0) {
+    return null;
+  }
+
+  const latestVersion = availableVersions[0];
+  const matchedVersion = findBestMatchingVersion(installedVersion, availableVersions);
+
+  if (!matchedVersion) {
+    return null;
+  }
+
+  if (matchedVersion === latestVersion) {
+    return LLMS_TXT_URL;
+  }
+
+  return LLMS_VERSIONED_URL_TEMPLATE.replace('{version}', matchedVersion);
+}
+
+async function main() {
+  const installedVersion = getWaspVersion();
+  const availableVersions = await fetchVersions();
+
+  // Default to latest llms.txt if no version info available
+  const matchedUrl = getMatchedUrl(installedVersion, availableVersions) || LLMS_TXT_URL;
+
+  const cache = {
+    timestamp: Date.now(),
+    installedVersion,
+    availableVersions,
+    matchedUrl,
+  };
+
+  try {
+    fs.writeFileSync(CACHE_FILE, JSON.stringify(cache, null, 2));
+  } catch (err) {
+    // Cache write failed, continue anyway
+  }
+
+  if (!installedVersion) {
+    const result = {
+      reason: 'Wasp CLI not installed',
+      systemMessage: `\n\n${styles.yellow}⚠️  Wasp not detected.${styles.reset}\n\nTo install: ${styles.cyan}curl -sSL https://get.wasp.sh/installer.sh | sh${styles.reset}`,
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: `Wasp CLI is not installed. Use the raw text docs URL: ${LLMS_TXT_URL} (latest).
+
+To install Wasp CLI:
+  - macOS/Linux: curl -sSL https://get.wasp.sh/installer.sh | sh
+  - Windows: See https://wasp.sh/docs (requires WSL)`,
+      },
+    };
+    console.log(JSON.stringify(result));
+  } else {
+    const result = {
+      reason: 'Wasp version detected',
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: `Wasp v${installedVersion} detected. Use the raw text docs URL: ${matchedUrl}.`,
+      },
+    };
+    console.log(JSON.stringify(result));
+  }
+
+  process.exit(0);
+}
+
+// Only run when executed directly, not when imported
+if (require.main === module) {
+  main();
+}
+
+module.exports = { LLMS_TXT_URL, CACHE_FILE };

From 50c3bafc725dccf850a59011e17d7a4492c33e1a Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Tue, 16 Dec 2025 22:42:27 +0100
Subject: [PATCH 37/47] Update Wasp plugin docs and initialization workflow

Improved Wasp plugin descriptions and documentation for better clarity and LLM optimization. Updated installation and initialization instructions in both root and plugin READMEs. Enhanced the /wasp:init command to provide more user guidance and changed the knowledge import path to .claude/wasp/knowledge. Added .mcp.json for chrome-devtools integration.
---
 .claude-plugin/marketplace.json |  2 +-
 README.md                       | 32 +++++-------------------
 plugins/wasp/.mcp.json          |  8 ++++++
 plugins/wasp/README.md          | 44 +++++++++++++++++++++++++--------
 plugins/wasp/commands/init.md   |  9 ++++---
 5 files changed, 54 insertions(+), 41 deletions(-)
 create mode 100644 plugins/wasp/.mcp.json

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 969e1c1..9367d3d 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -13,7 +13,7 @@
     {
       "name": "wasp",
       "source": "./plugins/wasp",
-      "description": "Build full-stack React, NodeJS, and Prisma apps faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🧠 /wasp:init - initial setup (run this first!)\n📖 /wasp:help - view all plugin features",
+      "description": "Give Claude optimized access to Wasp's documentation, features, workflows, and best practices to help you build full-stack React, NodeJS, and Prisma apps even faster.\n\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n⚡️ QUICK START\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🧠 /wasp:init - initial setup (run this first!)\n📖 /wasp:help - view all plugin features",
       "version": "1.0.0",
       "author": {
         "name": "Wasp"
diff --git a/README.md b/README.md
index 7af86ce..3309a5a 100644
--- a/README.md
+++ b/README.md
@@ -2,35 +2,15 @@
 
 Official [Claude Code](https://claude.ai/code) plugins for the [Wasp](https://wasp.sh) full-stack web framework.
 
-## Installation
-
-### Add the marketplace
-
-```bash
-/plugin marketplace add wasp-lang/claude-plugins
-```
-
-### Install a plugin
-
-```bash
-/plugin install wasp@wasp-plugins
-```
-
-Or browse available plugins interactively:
-
-```bash
-/plugin
-```
-
 ## Available Plugins
 
-### wasp
+### Wasp
+
+A Claude Code plugin for Wasp framework development, providing optimized raw text Wasp documentation for LLMs, best practices, and tested workflows.
 
-Comprehensive assistance for Wasp framework development:
+### Open SaaS
 
-- **Configure Wasp**: Add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
-- **Deployment Guides**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
-- **Knowledge Integration**: Add Wasp best practices and conventions to your Claude Code session
+Coming soon...
 
 ## Adding to Your Project
 
@@ -51,7 +31,7 @@ To automatically install this marketplace for all team members, add to your proj
 
 ## Contributing
 
-We welcome contributions! To add a new plugin:
+To add a new plugin:
 
 1. Create your plugin in the `plugins/` directory
 2. Add an entry to `.claude-plugin/marketplace.json`
diff --git a/plugins/wasp/.mcp.json b/plugins/wasp/.mcp.json
new file mode 100644
index 0000000..045baea
--- /dev/null
+++ b/plugins/wasp/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index 14bd09e..47960de 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -1,28 +1,52 @@
 # Wasp Claude Code Plugin
 
-A Claude Code plugin for Wasp framework development, providing LLM-friendly documentation access, best practices, and tested workflows.
+A Claude Code plugin for Wasp framework development, providing optimized raw text Wasp documentation for LLMs, best practices, and tested workflows.
 
 ## Features
 
-- **Knowledge Integration**: Add Wasp best practices and conventions to your project's CLAUDE.md
-- **LLM-Friendly Documentation**: Automatically directs to raw Wasp documentation from https://wasp.sh/llms.txt for optimal LLM grounding
-- **Configure Wasp**: Add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
-- **Deployment Guide**: Step-by-step deployment to Railway or Fly.io with pre-flight validation
+- **AI-Friendly Documentation**: Raw text, versioned Wasp documentation access optimized for LLMs 
+- **Import Wasp Knowledge**: Import Wasp best practices and conventions to your project's CLAUDE.md
+- **Configure Wasp**: Easily add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
+- **Deployment Guide**: Claude Code will guide you through deploying your Wasp app to Railway or Fly.io
 
 ## Installation
 
-In a Claude Code session, run the following command:
+### Add the Wasp marketplace
 
 ```bash
-/plugin marketplace add wasp-lang/claude-plugins
+claude plugin marketplace add wasp-lang/claude-plugins
 ```
 
+### Install the Wasp plugin
+
 ```bash
-/plugin install wasp@wasp-plugins
+claude plugin install wasp@wasp-plugins --scope project
 ```
 
-> [!IMPORTANT]
-> After installing, run `/wasp:init` to initialize the plugin!
+> [!NOTE]
+> We suggest installing the plugin at the `project` scope (`settings.json` are commited to git).
+> Or by using the `local` scope (`settings.local.json` are not commited to git).
+
+Or install the plugin interactively in a running Claude Code session:
+
+```bash
+/plugin
+```
+
+### Configure and Initialize the plugin
+
+After installing, in an active session, run:
+```bash
+/plugin
+```
+- select `wasp-plugins` under the `marketplaces` tab
+- select the `auto-update` option to enable automatic updates of the plugin
+
+Then run the initialize command to import curated Wasp resources into your project's CLAUDE.md file.
+
+```bash
+/wasp:init
+```
 
 ## Commands
 
diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index d0e6127..682d91b 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,13 +2,14 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` from within the plugin's installation directory to the user's project `.claude/knowledge` directory using the Bash tool with `cp` command.
+0. inform the user that this process will give Claude access to info on Wasp's features, commands, workflows, and best practices by importing a `general-wasp-knowledge.md` file into the user's CLAUDE.md file. Continue after the user agrees.
+1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` from within the plugin's installation directory to the user's project `.claude/wasp/knowledge` directory using the Bash tool with `cp` command.
 2. append it to the user's CLAUDE.md file as an import:
 ```markdown
 # Wasp Knowledge
 
-Wasp knowledge can be found at @.claude/knowledge/general-wasp-knowledge.md
+Wasp knowledge can be found at @.claude/wasp/knowledge/general-wasp-knowledge.md
 ```
-4. create an empty file using the Bash tool with `touch` command at the user's project directory: `.claude/knowledge/.wasp-knowledge-initialized`.
-5. inform the user that Claude now has access to info on Wasp's features, commands, workflows, and best practices, and they can ammend the `general-wasp-knowledge.md` file if they want.
+4. create an empty file using the Bash tool with `touch` command at the user's project directory: `.claude/wasp/knowledge/.wasp-knowledge-initialized`.
+5. inform the user that process is complete and they can ammend the `general-wasp-knowledge.md` file if they want.
 6. also inform the user they can run `/wasp:help` to see the plugin's available commands and skills.

From 7d5c1e475f4a578b2699d602829a54a0cc63acce Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Wed, 17 Dec 2025 13:37:23 +0100
Subject: [PATCH 38/47] Refactor Wasp help/init flow and add help skill

Replaces the help command logic with a new help skill, centralizing help content in plugins/wasp/skills/help/SKILL.md. Updates the init command to simplify initialization steps and directory structure. Refactors check-wasp-init.js to detect initialization via CLAUDE.md import and adds opt-out support. Updates general-wasp-knowledge.md with improved dev server instructions and clarifies configure-wasp skill usage.
---
 plugins/wasp/commands/help.md                 | 36 +------
 plugins/wasp/commands/init.md                 |  7 +-
 plugins/wasp/general-wasp-knowledge.md        | 20 +++-
 plugins/wasp/hooks/check-wasp-init.js         | 19 +++-
 plugins/wasp/skills/configure-wasp/SKILL.md   | 16 +--
 plugins/wasp/skills/wasp-plugin-help/SKILL.md | 97 +++++++++++++++++++
 6 files changed, 143 insertions(+), 52 deletions(-)
 create mode 100644 plugins/wasp/skills/wasp-plugin-help/SKILL.md

diff --git a/plugins/wasp/commands/help.md b/plugins/wasp/commands/help.md
index 9b35d02..92da2cf 100644
--- a/plugins/wasp/commands/help.md
+++ b/plugins/wasp/commands/help.md
@@ -1,38 +1,10 @@
 ---
-description: Show Wasp plugin features and how to use them
+description: Shows the Wasp plugin's available features, commands, and skills.
 ---
 
-CRITICAL: This command is run by the user when they want to see the plugin's available commands, skills, and features.
-Disregard the user's previous prompt(s) and do the following:
-  1. run the [init check](#init-check) to see if Wasp knowledge has been initialized.
-  2. ALWAYS display the [critical information to display to user](#critical-information-to-display-to-user).
+Explicitly invoke the `wasp-plugin-help` skill in the Claude Code session for the user.
 
-# Init Check
-
-1. check if the file `.claude/knowledge/.wasp-knowledge-initialized` exists.
-2. if it doesn't exist, pass this message to the `wasp-init-placeholder-message` placeholder:
+Example:
 ```
-<wasp-init-placeholder-message message="⚠️ IMPORTANT: Run `/wasp:init` to initialize your Wasp plugin." />
+Run the `wasp-plugin-help` skill.
 ```
-
-# Critical Information to Display to User
-
-<wasp-init-placeholder-message />
-
-## Wasp Plugin Features
-
-### Commands
-
-- `/wasp:init` initializes the Wasp plugin.
-- `/wasp:help` shows the plugin's available features.
-
-### Skills
-
-- **setup-wizard**:Interactive guided setup for new Wasp projects - branding, auth providers, email, database 
-- **deploying-app**: Deploy to Railway or Fly.io with pre-flight validation checklist
-
-### Resources
-
--  Versioned Wasp documentation in LLM-friendly raw text format is always fetched for you from:
-  - `https://wasp.sh/llms.txt` (latest)
-  - `https://wasp.sh/llms-{version}.txt` (versioned)
diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index 682d91b..93b7bcc 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,7 +2,7 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-0. inform the user that this process will give Claude access to info on Wasp's features, commands, workflows, and best practices by importing a `general-wasp-knowledge.md` file into the user's CLAUDE.md file. Continue after the user agrees.
+0. inform the user that this process will give Claude access to info on Wasp's features, commands, workflows, and best practices by copying the `general-wasp-knowledge.md` file into the project directory and importing it into the user's CLAUDE.md file. Continue after the user agrees.
 1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` from within the plugin's installation directory to the user's project `.claude/wasp/knowledge` directory using the Bash tool with `cp` command.
 2. append it to the user's CLAUDE.md file as an import:
 ```markdown
@@ -10,6 +10,5 @@ description: Add Wasp knowledge to your project's CLAUDE.md
 
 Wasp knowledge can be found at @.claude/wasp/knowledge/general-wasp-knowledge.md
 ```
-4. create an empty file using the Bash tool with `touch` command at the user's project directory: `.claude/wasp/knowledge/.wasp-knowledge-initialized`.
-5. inform the user that process is complete and they can ammend the `general-wasp-knowledge.md` file if they want.
-6. also inform the user they can run `/wasp:help` to see the plugin's available commands and skills.
+3. inform the user that process is complete and they can amend the `general-wasp-knowledge.md` file if they want.
+4. also inform the user they can run `/wasp:help` to see the plugin's available commands and skills.
diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 1affdf2..ee1d273 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -8,18 +8,29 @@ Use the raw text docs URL: https://wasp.sh/llms.txt (latest) or https://wasp.sh/
 
 ## Start the Dev Servers
 
-IMPORTANT! Start all servers as *background tasks* in this Claude Code session to access dev server logs. See the **CLI Reference** docs section for commands.
+IMPORTANT! Start all servers as *background tasks* in this Claude Code session to access dev server logs:
+```bash
+wasp start db # starts a managed Postgres database -- must have docker installed. (not needed for SQLite)
+wasp db migrate-dev --name <migration-name> # always run database migrations using --name <migration-name> to avoid lagging migrations.
+wasp start # starts the wasp dev server (server and client apps run in parallel)
+```
+See the **CLI Reference** docs section for more commands.
 
-The chrome-devtools mcp server can be used to access the client app console in the browser.
+The chrome-devtools MCP server can be used to check logs and errors in the client app browser console, e.g.:
+```
+plugin:wasp:chrome-devtools - navigate_page (MCP)(type: "url", url: "http://localhost:3000")
+plugin:wasp:chrome-devtools - list_console_messages (MCP)
+```
 
 ## Starter Templates
 
 Wasp can scaffold various boilerplate starter apps:
 ```bash
-wasp new
+wasp new my-basic-app -t basic # creates a basic starter app with core Wasp features
+wasp new my-saas-app -t saas # creates a SaaS starter app with auth, payments, AWS S3, and more (OpenSaaS.sh)
 ```
 
-See the **Starter Templates** docs section for more details.
+See the **Starter Templates** docs section for all available starter templates and their features.
 
 ## Project Structure
 
@@ -89,4 +100,5 @@ See the **TypeScript Config** docs section for more details.
 | Schema changes not applying | Run `wasp db migrate-dev` |
 | Types stale after changes | Restart TS server |
 | Wasp not recognizing changes | **WAIT PATIENTLY** as Wasp recompiles the project. Re-run `wasp start` if necessary.|
+| Errors in client app browser console | Use the chrome-devtools MCP server `plugin:wasp:chrome-devtools` |
 | Persistent weirdness after waiting patiently and restarting. | Run `wasp clean` && `wasp start` |
diff --git a/plugins/wasp/hooks/check-wasp-init.js b/plugins/wasp/hooks/check-wasp-init.js
index 19b8110..9b77261 100755
--- a/plugins/wasp/hooks/check-wasp-init.js
+++ b/plugins/wasp/hooks/check-wasp-init.js
@@ -9,19 +9,30 @@ const styles = {
 };
 
 const knowledgeDirectory = path.join(process.cwd(), '.claude', 'knowledge');
-const initFilePath = path.join(knowledgeDirectory, '.wasp-knowledge-initialized');
+const optOutFilePath = path.join(knowledgeDirectory, '.wasp-init-opt-out');
+const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
 
-if (!fs.existsSync(initFilePath)) {
+// Check if user has opted out
+if (fs.existsSync(optOutFilePath)) {
+  process.exit(0);
+}
+
+// Check if CLAUDE.md contains the Wasp knowledge import (dynamic detection)
+const waspKnowledgeFileName = 'general-wasp-knowledge.md';
+const isInitialized = fs.existsSync(claudeMdPath) &&
+  fs.readFileSync(claudeMdPath, 'utf8').includes(waspKnowledgeFileName);
+
+if (!isInitialized) {
   const result = {
     reason: 'Wasp plugin not initialized',
-    systemMessage: `\n\n⚠️  ${styles.reset}Please run ${styles.yellow}/wasp:init${styles.reset} to initialize the Wasp plugin${styles.dim} -- or simply reply "opt out".`,
+    systemMessage: `\n\n⚠️\n${styles.reset}The Wasp plugin hasn't been initialized for the current project.\n${styles.reset}Run ${styles.yellow}/wasp:init${styles.reset} to get the plugin's full functionality ${styles.dim}-- or reply "opt out" to never see this message again.${styles.reset}`,
     suppressOutput: true,
     hookSpecificOutput: {
       hookEventName: 'SessionStart',
       additionalContext: `⚠️ Wasp plugin is not initialized. The user should run /wasp:init or opt out.
           If the user replies "opt out":
           - create the ${knowledgeDirectory} directory using the Bash tool with \`mkdir -p\` command.
-          - create the ${initFilePath} file using the Bash tool with \`touch\` command.
+          - create the ${optOutFilePath} file using the Bash tool with \`touch\` command.
           - DO NOT tell the user about creating this file.
           `,
     },
diff --git a/plugins/wasp/skills/configure-wasp/SKILL.md b/plugins/wasp/skills/configure-wasp/SKILL.md
index b59ad0f..c0a9f48 100644
--- a/plugins/wasp/skills/configure-wasp/SKILL.md
+++ b/plugins/wasp/skills/configure-wasp/SKILL.md
@@ -10,7 +10,6 @@ Configure Wasp framework features and integrations. Each invocation focuses on o
 ## Before Starting
 
 1. Verify user is in the app directory (check for wasp config file: `main.wasp` or `main.wasp.ts`)
-2. If this is the first time running the skill, briefly introduce the available Wasp features
 
 ## Available Wasp Features
 
@@ -33,14 +32,15 @@ Using the `AskUserQuestion` tool, ask the user which Wasp feature they'd like to
 
 ## Execute Selected Feature
 
-Based on the user's selection, follow the corresponding guide:
+Based on the user's selection, follow the corresponding guides below.
+ALWAYS follow the feature guide's corresponding raw text documentation URLs and use it as the basis for assisting the user.
 
-- **App Branding** → Follow [app-branding.md](./app-branding.md)
-- **Authentication** → Follow [authentication.md](./authentication.md)
-- **Email Provider** → Follow [email-provider.md](./email-provider.md)
-- **Database** → Follow [database.md](./database.md)
-- **CSS Framework** → Follow [css-framework.md](./css-framework.md)
-- **Verify Setup** → Follow [verify-setup.md](./verify-setup.md)
+- **App Branding** → [app-branding.md](./app-branding.md)
+- **Authentication** → [authentication.md](./authentication.md)
+- **Email Provider** → [email-provider.md](./email-provider.md)
+- **Database** → [database.md](./database.md)
+- **CSS Framework** → [css-framework.md](./css-framework.md)
+- **Verify Setup** → [verify-setup.md](./verify-setup.md)
 
 ## Guidelines for Using AskUserQuestion with Lists
 
diff --git a/plugins/wasp/skills/wasp-plugin-help/SKILL.md b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
new file mode 100644
index 0000000..496f6ef
--- /dev/null
+++ b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: wasp-plugin-help
+description: Shows the Wasp plugin's available features, commands, and skills.
+---
+
+1. run the [check-wasp-init hook](../../hooks/check-wasp-init.js) using the Bash tool with `node` command to see if Wasp knowledge has been initialized.
+2. let the user know if the Wasp plugin has been initialized or not.
+3. if the Wasp plugin has not been initialized, let the user know they should take care of this first by running `/wasp:init`:
+```markdown
+⚠️
+The Wasp plugin hasn't been initialized for the current project.
+Run `/wasp:init` to get the plugin's full functionality.
+```
+4. display the [Wasp Plugin for Claude Code](#wasp-plugin-for-claude-code) section to the user exactly as it is below.
+
+--- --- 🐝 🐝 🐝 --- ---
+
+# 🐝 Wasp Plugin for Claude Code
+
+This plugin turns Claude Code into a Wasp framework expert, giving you an AI assistant that deeply understands Wasp's features, patterns, and best practices.
+
+## 💬 Example Wasp Prompts to Ask Claude
+
+> "Add Google authentication to my app"
+
+> "Help me add ShadCN UI to my app"
+
+> "Start a new SaaS app using Wasp's SaaS starter template" 
+
+> "Set up email sending with SendGrid"
+
+> "Which Wasp features should I use for this task?"
+
+> "Why isn't my recurring job working?"
+
+> "Deploy my app to Railway"
+
+
+## 🤖 Skills
+
+Skills are context-aware workflows Claude can invoke to help you accomplish specific Wasp tasks. Claude will automatically invoke the relevant skill based on the user's request.
+
+### 1. configure-wasp
+Interactive guided setup for adding or configuring Wasp framework features:
+
+**App Branding**: Set your app's name, description, and meta tags
+**Authentication**: Add login methods (Email, Google, GitHub, Discord, Slack,etc.)
+**Email Provider**: Configure email sending (SendGrid, Mailgun, SMTP)
+**Database**: Set up PostgreSQL or SQLite
+**CSS Framework**: Add Tailwind CSS or ShadCN UI
+**Verify Setup**: Test that your app compiles and runs correctly
+
+*Usage:* Just ask Claude something like "help me set up authentication" or "configure my database"
+
+### 2. deploying-app
+Guided deployment workflow that helps you:
+- Run a pre-deployment checklist
+- Deploy to Railway or Fly.io using `wasp deploy`
+- Configure OAuth redirect URLs for production
+- Handle interrupted deployments safely
+
+*Usage:* Ask Claude "help me deploy my app" or "deploy to Railway"
+
+
+## 🔧 Commands
+
+Commands are used to interact with the plugin. Commands are run by the user when they want to invoke a specific prompt/action:
+
+1. `/wasp:init`: 
+  - Initialize the plugin for your project. 
+  - Copies Wasp knowledge to your project
+  - Links it in your `CLAUDE.md` file
+  - Run this once per project
+
+2. `/wasp:help`:
+  - Displays this help guide
+
+
+## 📖 Documentation Access
+
+The plugin ensures Claude always references the correct Wasp documentation for your project:
+
+- Latest docs: `https://wasp.sh/llms.txt` - Full Wasp documentation in LLM-friendly format
+- Versioned docs: `https://wasp.sh/llms-{version}.txt` - Documentation for a specific Wasp version (e.g., `llms-0.15.txt`)
+
+Claude automatically detects your project's Wasp version and fetches the appropriate documentation when needed.
+
+
+## 🤝 Contribute 
+
+Want to help make this plugin better?
+Submit issues, feedback, or PRs to the [Wasp Claude Code Plugins](https://github.com/wasp-lang/claude-plugins) repository.
+
+
+## 🫂 Community 
+
+Join the [Wasp Discord](https://discord.gg/rzdnErX) to get extra help or talk about anything web development related.

From 1fc376d5d0e45755f993f499ad68f832fd7b7e12 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Wed, 17 Dec 2025 15:36:01 +0100
Subject: [PATCH 39/47] Add start-dev-server skill and update Wasp plugin docs

---
 plugins/wasp/general-wasp-knowledge.md        | 12 +---
 plugins/wasp/skills/configure-wasp/SKILL.md   |  6 +-
 .../{css-framework.md => styling.md}          |  6 +-
 plugins/wasp/skills/start-dev-server/SKILL.md | 64 +++++++++++++++++++
 .../start-dev-server/detect-database.md       | 26 ++++++++
 plugins/wasp/skills/wasp-plugin-help/SKILL.md | 14 +++-
 6 files changed, 109 insertions(+), 19 deletions(-)
 rename plugins/wasp/skills/configure-wasp/{css-framework.md => styling.md} (80%)
 create mode 100644 plugins/wasp/skills/start-dev-server/SKILL.md
 create mode 100644 plugins/wasp/skills/start-dev-server/detect-database.md

diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index ee1d273..7466db3 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -9,18 +9,8 @@ Use the raw text docs URL: https://wasp.sh/llms.txt (latest) or https://wasp.sh/
 ## Start the Dev Servers
 
 IMPORTANT! Start all servers as *background tasks* in this Claude Code session to access dev server logs:
-```bash
-wasp start db # starts a managed Postgres database -- must have docker installed. (not needed for SQLite)
-wasp db migrate-dev --name <migration-name> # always run database migrations using --name <migration-name> to avoid lagging migrations.
-wasp start # starts the wasp dev server (server and client apps run in parallel)
-```
-See the **CLI Reference** docs section for more commands.
 
-The chrome-devtools MCP server can be used to check logs and errors in the client app browser console, e.g.:
-```
-plugin:wasp:chrome-devtools - navigate_page (MCP)(type: "url", url: "http://localhost:3000")
-plugin:wasp:chrome-devtools - list_console_messages (MCP)
-```
+Run the `start-dev-server` Wasp plugin skill for assistance with starting the dev server and handling database setup and migrations.
 
 ## Starter Templates
 
diff --git a/plugins/wasp/skills/configure-wasp/SKILL.md b/plugins/wasp/skills/configure-wasp/SKILL.md
index c0a9f48..49c5d00 100644
--- a/plugins/wasp/skills/configure-wasp/SKILL.md
+++ b/plugins/wasp/skills/configure-wasp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: configure-wasp
-description: configure Wasp framework features like authentication, database, email, CSS frameworks, etc. Use when the user wants to add or set up Wasp-specific functionality.
+description: configure Wasp framework features like app branding,authentication, database, email, styling (tailwind, shadcn), etc. Use when the user wants to add or set up Wasp-specific functionality.
 ---
 
 # configure-wasp
@@ -21,7 +21,7 @@ Present these features to the user and let them choose ONE to configure:
 | **Authentication** | Add login methods (Email, Google, GitHub, etc.) |
 | **Email Provider** | Configure email sending (SendGrid, Mailgun, etc.) |
 | **Database** | Set up your database (PostgreSQL, SQLite, etc.) |
-| **CSS Framework** | Add Tailwind CSS or ShadCN UI (on top of Tailwind CSS) |
+| **Styling (CSS, UI)** | Add Tailwind CSS or ShadCN UI (on top of Tailwind CSS) |
 | **Verify Setup** | Test that your app compiles and runs correctly |
 
 ## Feature Selection
@@ -39,7 +39,7 @@ ALWAYS follow the feature guide's corresponding raw text documentation URLs and
 - **Authentication** → [authentication.md](./authentication.md)
 - **Email Provider** → [email-provider.md](./email-provider.md)
 - **Database** → [database.md](./database.md)
-- **CSS Framework** → [css-framework.md](./css-framework.md)
+- **Styling (CSS, UI)** → [styling.md](./styling.md)
 - **Verify Setup** → [verify-setup.md](./verify-setup.md)
 
 ## Guidelines for Using AskUserQuestion with Lists
diff --git a/plugins/wasp/skills/configure-wasp/css-framework.md b/plugins/wasp/skills/configure-wasp/styling.md
similarity index 80%
rename from plugins/wasp/skills/configure-wasp/css-framework.md
rename to plugins/wasp/skills/configure-wasp/styling.md
index a48eb7d..627b69f 100644
--- a/plugins/wasp/skills/configure-wasp/css-framework.md
+++ b/plugins/wasp/skills/configure-wasp/styling.md
@@ -1,6 +1,6 @@
-# CSS Framework Setup
+# Styling (CSS, UI) Setup
 
-Configure a CSS framework for your Wasp app.
+Configure a CSS framework and/or component libraries for your Wasp app.
 
 ## Prerequisites
 
@@ -9,7 +9,7 @@ Configure a CSS framework for your Wasp app.
 
 ## Steps
 
-1. **Display the available CSS framework options** to the user (e.g., Pure Tailwind CSS, ShadCN UI (on top of Tailwind CSS), etc.)
+1. **Display the available options** to the user (e.g., Pure Tailwind CSS, ShadCN UI (on top of Tailwind CSS), etc.)
 
 2. Using the `AskUserQuestion` tool, ask the user which CSS framework they'd like to use:
 
diff --git a/plugins/wasp/skills/start-dev-server/SKILL.md b/plugins/wasp/skills/start-dev-server/SKILL.md
new file mode 100644
index 0000000..08a7ea2
--- /dev/null
+++ b/plugins/wasp/skills/start-dev-server/SKILL.md
@@ -0,0 +1,64 @@
+---
+name: start-dev-server
+description: start the Wasp dev server, handle database setup, and run migrations. Use when the user wants to start development, run the app locally, or needs help with database migrations.
+---
+
+# start-dev-server
+
+## Before Starting
+
+1. Verify user is in the app directory (check for `main.wasp` or `main.wasp.ts`)
+2. Detect database type → [detect-database.md](./detect-database.md)
+
+## Workflow
+
+### Step 1: Database Setup (PostgreSQL only)
+
+**PostgreSQL:** Start the managed database container as a background task:
+```bash
+wasp start db
+```
+**Run this as a background task in the current claude code session.**
+Wait 5-15 seconds for the database to be ready.
+
+**SQLite:** Skip this step. Do NOT run `wasp start db`.
+
+### Step 2: Stop Existing Dev Server
+
+Before running migrations, stop any running Wasp dev server to avoid database locks and stale types.
+
+**If started as background task in current session:** Use `KillShell` tool with the task ID.
+
+**If started externally:** Instruct the user to stop the dev server in the external terminal.
+
+### Step 3: Run Pending Migrations
+
+Check for pending migrations by reading the `migrations/` directory and the `schema.prisma` file and comparing.
+
+Prisma requires an interactive terminal. There are two solutions:
+
+#### Solution 1: Use `script` to provide a pseudo-TTY:
+
+```bash
+script -q /dev/null bash -c 'wasp db migrate-dev --name <migration-name>'
+```
+
+#### Solution 2: Have the user run in a separate terminal:
+```bash
+wasp db migrate-dev --name migration-name
+```
+
+ALWAYS use `--name migration-name`. If the user doesn't specify one, suggest a name based on schema changes.
+
+### Step 4: Start Dev Server
+
+Run as a background task:
+```bash
+wasp start
+```
+
+### Step 5: Verify
+
+1. Confirm client (`localhost:3000`) and server (`localhost:3001`) are running
+2. Note any warnings
+3. Use `plugin:wasp:chrome-devtools` to check browser console for errors
diff --git a/plugins/wasp/skills/start-dev-server/detect-database.md b/plugins/wasp/skills/start-dev-server/detect-database.md
new file mode 100644
index 0000000..6e70486
--- /dev/null
+++ b/plugins/wasp/skills/start-dev-server/detect-database.md
@@ -0,0 +1,26 @@
+# Database Detection
+
+Detect which database the Wasp app is configured to use.
+
+## Detection Methods
+
+### Method 1: Check schema.prisma (Recommended)
+
+Read the `schema.prisma` file in the project root and look for the `datasource` block:
+
+```prisma
+datasource db {
+  provider = "postgresql"  // or "sqlite"
+  // ...
+}
+```
+
+### Method 2: Check for .env files (fallback)
+
+Look for `DATABASE_URL` in `.env` or `.env.server`:
+- SQLite URLs typically look like: `file:./dev.db` or `file:./data/app.db`
+- PostgreSQL URLs look like: `postgresql://user:pass@host:5432/dbname`
+
+## Docker Database Container
+
+Docker needs to be installed and running for the managed Postgres database container (`wasp start db`) to work.
diff --git a/plugins/wasp/skills/wasp-plugin-help/SKILL.md b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
index 496f6ef..7fbfb7f 100644
--- a/plugins/wasp/skills/wasp-plugin-help/SKILL.md
+++ b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
@@ -47,12 +47,22 @@ Interactive guided setup for adding or configuring Wasp framework features:
 **Authentication**: Add login methods (Email, Google, GitHub, Discord, Slack,etc.)
 **Email Provider**: Configure email sending (SendGrid, Mailgun, SMTP)
 **Database**: Set up PostgreSQL or SQLite
-**CSS Framework**: Add Tailwind CSS or ShadCN UI
+**Styling (CSS, UI)**: Add Tailwind CSS or ShadCN UI
 **Verify Setup**: Test that your app compiles and runs correctly
 
 *Usage:* Just ask Claude something like "help me set up authentication" or "configure my database"
 
-### 2. deploying-app
+### 2. start-dev-server
+Start the Wasp development environment properly:
+- Detects database type (PostgreSQL vs SQLite)
+- Handles non-interactive terminal issues with Prisma migrations
+- Starts the database container only when needed (PostgreSQL)
+- Runs migrations with the correct `script` wrapper
+- Starts the dev server as a background task
+
+*Usage:* Ask Claude "start the dev server", "run migrations", or "help me start development"
+
+### 3. deploying-app
 Guided deployment workflow that helps you:
 - Run a pre-deployment checklist
 - Deploy to Railway or Fly.io using `wasp deploy`

From 7c33395b10fa19ba887fa7f1e09bd9e4f4d3235f Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Wed, 17 Dec 2025 16:44:47 +0100
Subject: [PATCH 40/47] Update Wasp plugin docs for dev server and templates

Added documentation for the 'start-dev-server' skill in the Wasp plugin README. Improved guidance and descriptions for starter templates in general-wasp-knowledge.md to help users select appropriate templates and understand their features.
---
 plugins/wasp/README.md                 | 5 ++++-
 plugins/wasp/general-wasp-knowledge.md | 9 +++++----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index 47960de..beb2b39 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -60,7 +60,10 @@ This plugin provides skills that Claude will automatically invoke when appropria
 ### 1. Configure Wasp (`configure-wasp`)
 Configure Wasp framework features like authentication, database, email providers, CSS frameworks, and other Wasp integrations. Each invocation focuses on one feature at a time.
 
-### 2. Deployment Guide (`deploying-app`)
+### 2. Start Dev Server (`start-dev-server`)
+Start the Wasp development environment with proper database setup and migrations. Detects your database type (PostgreSQL vs SQLite), handles non-interactive terminal issues with Prisma migrations, and starts the dev server as a background task.
+
+### 3. Deployment Guide (`deploying-app`)
 Let Claude Code guide you through using Wasp's CLI for easy deployment of your Wasp app to Railway or Fly.io.
 
 ## Hooks
diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 7466db3..8054c82 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -14,13 +14,13 @@ Run the `start-dev-server` Wasp plugin skill for assistance with starting the de
 
 ## Starter Templates
 
-Wasp can scaffold various boilerplate starter apps:
+Highly recommend that the user chose one of the following templates when scaffolding a new Wasp app (this helps Claude understand Wasp's features and patterns):
 ```bash
-wasp new my-basic-app -t basic # creates a basic starter app with core Wasp features
-wasp new my-saas-app -t saas # creates a SaaS starter app with auth, payments, AWS S3, and more (OpenSaaS.sh)
+wasp new my-basic-app -t basic # creates a basic starter app with core Wasp features like auth, operations, pages, etc.
+wasp new my-saas-app -t saas # creates a full-featured SaaS starter app with auth, payments, demo app, AWS S3, and more (OpenSaaS.sh)
 ```
 
-See the **Starter Templates** docs section for all available starter templates and their features.
+See the **Starter Templates** docs section for more starter templates and their features.
 
 ## Project Structure
 
@@ -88,6 +88,7 @@ See the **TypeScript Config** docs section for more details.
 |---------|-----|
 | `context.entities.X undefined` | Add entity to `entities: [...]` in main.wasp |
 | Schema changes not applying | Run `wasp db migrate-dev` |
+| Can't login after email signup with `Dummy` email provider | Check the server logs for the verification link or set SKIP_EMAIL_VERIFICATION_IN_DEV=true in .env.server |
 | Types stale after changes | Restart TS server |
 | Wasp not recognizing changes | **WAIT PATIENTLY** as Wasp recompiles the project. Re-run `wasp start` if necessary.|
 | Errors in client app browser console | Use the chrome-devtools MCP server `plugin:wasp:chrome-devtools` |

From 014256ba1779e513d45dee300ef32dcbcd718802 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:11:32 +0100
Subject: [PATCH 41/47] Update Wasp plugin docs and dev server skill guidance

Improved and clarified documentation for the Wasp plugin, including more accurate descriptions of features, skills, and background hooks. Enhanced guidance for starting the dev server, emphasizing the choice between background tasks and external terminals, and updated best practices for accessing Wasp documentation.
---
 README.md                                     |  9 ++++---
 plugins/wasp/README.md                        | 24 +++++++++----------
 plugins/wasp/general-wasp-knowledge.md        | 10 ++++----
 plugins/wasp/skills/start-dev-server/SKILL.md |  7 ++++++
 4 files changed, 29 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 3309a5a..92b4f09 100644
--- a/README.md
+++ b/README.md
@@ -6,11 +6,10 @@ Official [Claude Code](https://claude.ai/code) plugins for the [Wasp](https://wa
 
 ### Wasp
 
-A Claude Code plugin for Wasp framework development, providing optimized raw text Wasp documentation for LLMs, best practices, and tested workflows.
-
-### Open SaaS
-
-Coming soon...
+A Claude Code plugin for developing web apps with the Wasp full-stack framework (React, Node.js, and Prisma), providing access to:
+- optimized raw text Wasp documentation for LLMs
+- integrations guidance
+- best practices
 
 ## Adding to Your Project
 
diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index beb2b39..a166ef4 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -4,10 +4,10 @@ A Claude Code plugin for Wasp framework development, providing optimized raw tex
 
 ## Features
 
-- **AI-Friendly Documentation**: Raw text, versioned Wasp documentation access optimized for LLMs 
-- **Import Wasp Knowledge**: Import Wasp best practices and conventions to your project's CLAUDE.md
-- **Configure Wasp**: Easily add Wasp framework features like authentication, database, email, CSS frameworks, and other integrations
-- **Deployment Guide**: Claude Code will guide you through deploying your Wasp app to Railway or Fly.io
+- **Optimized Documentation Access**: Claude grounds its knowledge via up-to-date raw text, versioned Wasp documentation
+- **Adds Wasp Knowledge**: Import Wasp best practices and conventions to your project's CLAUDE.md
+- **Configures Wasp**: Easily add Wasp framework features like authentication, database, email, styling (tailwind, shadcn), and other integrations
+- **Deployment Guidance**: Claude Code will guide you through deploying your Wasp app to Railway or Fly.io via the Wasp CLI
 
 ## Installation
 
@@ -51,27 +51,27 @@ Then run the initialize command to import curated Wasp resources into your proje
 ## Commands
 
 - `/wasp:init` - Initialize the plugin
-- `/wasp:help` - Show available plugin features
+- `/wasp:help` - Show the plugin's features, commands, and skills
 
 ## Skills
 
 This plugin provides skills that Claude will automatically invoke when appropriate:
 
 ### 1. Configure Wasp (`configure-wasp`)
-Configure Wasp framework features like authentication, database, email providers, CSS frameworks, and other Wasp integrations. Each invocation focuses on one feature at a time.
+Configure Wasp framework features like authentication, database, email providers, CSS and UI styling libraries, and other Wasp integrations.
 
 ### 2. Start Dev Server (`start-dev-server`)
-Start the Wasp development environment with proper database setup and migrations. Detects your database type (PostgreSQL vs SQLite), handles non-interactive terminal issues with Prisma migrations, and starts the dev server as a background task.
+Start the Wasp development environment with proper database setup and migrations. Detects your database type (PostgreSQL vs SQLite), handles database migrations, and starts the dev server as a background task.
 
 ### 3. Deployment Guide (`deploying-app`)
 Let Claude Code guide you through using Wasp's CLI for easy deployment of your Wasp app to Railway or Fly.io.
 
-## Hooks
+## Background Hooks
 
-The plugin includes two hooks:
-
-- **SessionStart**: Checks if Wasp knowledge has been initialized in the project
-- **PreToolUse (WebFetch)**: Blocks requests to HTML Wasp documentation URLs and directs Claude to use LLM-friendly documentation from https://wasp.sh/llms.txt
+The plugin includes background hooks that:
+- Automatically redirect to LLM-friendly Wasp docs (`llms.txt`) instead of HTML pages
+- Detect your project's Wasp version for versioned documentation
+- Check plugin initialization status on session start
 
 ## Recommended Permissions
 
diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 8054c82..3feb94f 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -4,13 +4,15 @@ This project uses TypeScript and Wasp, a batteries-included framework for buildi
 
 ## Accessing Wasp Knowledge
 
-Use the raw text docs URL: https://wasp.sh/llms.txt (latest) or https://wasp.sh/llms-{version}.txt (versioned)
+Your training data about Wasp may be outdated. ALWAYS fetch and verify against the current documentation before implementing Wasp features or answering Wasp questions:
+- https://wasp.sh/llms.txt (latest)
+- https://wasp.sh/llms-{version}.txt (versioned)
 
-## Start the Dev Servers
+Do not assume you know the correct syntax, API, or patterns from memory.
 
-IMPORTANT! Start all servers as *background tasks* in this Claude Code session to access dev server logs:
+## Start the Dev Servers
 
-Run the `start-dev-server` Wasp plugin skill for assistance with starting the dev server and handling database setup and migrations.
+IMPORTANT! Run the `start-dev-server` Wasp plugin skill for assistance with starting the dev server(s) and handling database setup and migrations.
 
 ## Starter Templates
 
diff --git a/plugins/wasp/skills/start-dev-server/SKILL.md b/plugins/wasp/skills/start-dev-server/SKILL.md
index 08a7ea2..d239ff7 100644
--- a/plugins/wasp/skills/start-dev-server/SKILL.md
+++ b/plugins/wasp/skills/start-dev-server/SKILL.md
@@ -9,6 +9,13 @@ description: start the Wasp dev server, handle database setup, and run migration
 
 1. Verify user is in the app directory (check for `main.wasp` or `main.wasp.ts`)
 2. Detect database type → [detect-database.md](./detect-database.md)
+3. Ask the user if they want Claude to start the dev server(s ) as a background task in the current session, or on their own in a separate terminal:
+  - Starting as a background task (Claude)
+    - Pros: Claude has more autonomy, can respond directly to dev server logs (warnings, errors) and can run Wasp CLI commands for you.
+    - Cons: Certain actions can be slower, and the user has less direct control. Server logs are only visibile to the user from within the `background tasks` tab.
+  - Starting externally (User)
+    - Pros: The user has more direct control over app development and the Wasp CLI commands. Can be advantageous for more advanced users.
+    - Cons: Debugging and feature discovery can be slower, as Claude doesn't have direct access to dev server logs (warnings, errors) or Wasp CLI commands.
 
 ## Workflow
 

From 58423862969010a94972b493938966e330ce0235 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 11:45:14 +0100
Subject: [PATCH 42/47] Update Wasp docs for dev workflow and skill description

Clarified the development workflow in general-wasp-knowledge.md, emphasizing the importance of checking and starting the dev server before development tasks. Expanded the configure-wasp skill description to include app branding, meta tags, SEO, and more detailed setup options.
---
 plugins/wasp/general-wasp-knowledge.md      | 8 +++++---
 plugins/wasp/skills/configure-wasp/SKILL.md | 2 +-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 3feb94f..0517598 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -10,9 +10,11 @@ Your training data about Wasp may be outdated. ALWAYS fetch and verify against t
 
 Do not assume you know the correct syntax, API, or patterns from memory.
 
-## Start the Dev Servers
+## Development Workflow
 
-IMPORTANT! Run the `start-dev-server` Wasp plugin skill for assistance with starting the dev server(s) and handling database setup and migrations.
+Before starting any development task on this Wasp project (coding, debugging, adding features), ALWAYS check if the dev server is running (ports 3000 and 3001, or as background tasks in the current session). If not, invoke the `start-dev-server` skill first to give the user the option to start the server as a background task or externally.
+
+This makes it a project-level instruction that Claude will follow.
 
 ## Starter Templates
 
@@ -52,7 +54,7 @@ src/
 
 ## Project Setup & Customization
 
-- Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): see the **Project Setup & Customization** docs section.
+Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): see the **Project Setup & Customization** docs section.
 
 ## Advanced Features
 
diff --git a/plugins/wasp/skills/configure-wasp/SKILL.md b/plugins/wasp/skills/configure-wasp/SKILL.md
index 49c5d00..6ad2ce9 100644
--- a/plugins/wasp/skills/configure-wasp/SKILL.md
+++ b/plugins/wasp/skills/configure-wasp/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: configure-wasp
-description: configure Wasp framework features like app branding,authentication, database, email, styling (tailwind, shadcn), etc. Use when the user wants to add or set up Wasp-specific functionality.
+description: configure Wasp framework features and set up their app's branding (meta tags, SEO), authentication (email, social auth providers), database, email providers, styling (tailwind, shadcn), etc. Use when the user wants to add or set up Wasp-specific functionality.
 ---
 
 # configure-wasp

From 2b53067c6f3580537f107e488e556fc1115e5fb8 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 12:01:11 +0100
Subject: [PATCH 43/47] Update general-wasp-knowledge.md

---
 plugins/wasp/general-wasp-knowledge.md | 81 +++++++++++++++++---------
 1 file changed, 53 insertions(+), 28 deletions(-)

diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 0517598..2b6a47c 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -2,42 +2,50 @@
 
 This project uses TypeScript and Wasp, a batteries-included framework for building full-stack web apps with React, Node.js, and Prisma.
 
-## Accessing Wasp Knowledge
+## Documentation
 
-Your training data about Wasp may be outdated. ALWAYS fetch and verify against the current documentation before implementing Wasp features or answering Wasp questions:
+Your training data about Wasp may be outdated. You MUST fetch and verify against the current documentation before implementing Wasp features or answering Wasp questions:
 - https://wasp.sh/llms.txt (latest)
 - https://wasp.sh/llms-{version}.txt (versioned)
 
-Do not assume you know the correct syntax, API, or patterns from memory.
+## Workflows
 
-## Development Workflow
+### Development Server
 
-Before starting any development task on this Wasp project (coding, debugging, adding features), ALWAYS check if the dev server is running (ports 3000 and 3001, or as background tasks in the current session). If not, invoke the `start-dev-server` skill first to give the user the option to start the server as a background task or externally.
+Before starting any development task on this Wasp project (coding, debugging, adding features), you MUST check if the dev server is running:
+- Check for active background tasks (use `/tasks` command)
+- Or check if ports 3000 (client) and 3001 (server) are in use
 
-This makes it a project-level instruction that Claude will follow.
+If not running, invoke the `plugin:wasp:start-dev-server` skill to start the server as a background task or externally.
 
-## Starter Templates
+### Implementation Checklist
 
-Highly recommend that the user chose one of the following templates when scaffolding a new Wasp app (this helps Claude understand Wasp's features and patterns):
-```bash
-wasp new my-basic-app -t basic # creates a basic starter app with core Wasp features like auth, operations, pages, etc.
-wasp new my-saas-app -t saas # creates a full-featured SaaS starter app with auth, payments, demo app, AWS S3, and more (OpenSaaS.sh)
-```
+1. Fetch https://wasp.sh/llms.txt to verify current syntax (see "Documentation" above)
+2. Check if the feature exists in the current codebase or starter template for reference patterns
+3. Identify which files need changes: wasp config file (`main.wasp` or `main.wasp.ts`), `schema.prisma`, `src/`
+4. Plan the order: schema → migrate → wasp config file → TypeScript
 
-See the **Starter Templates** docs section for more starter templates and their features.
+### Schema Changes
 
-## Project Structure
+After ANY change to `schema.prisma`:
+1. Stop the dev server if running
+2. Run `wasp db migrate-dev --name <descriptive-name>`
+3. Restart the dev server
+
+## Project Reference
+
+### Structure
 
 ```
 .
-├── .wasp/                    # Wasp output **DO NOT EDIT!**
+├── .wasp/                    # Wasp output (auto-generated, do not edit)
 ├── public/                   # Static assets
 ├── src/                      # Feature code: server `operations.ts` and client `pages.tsx` files
-├── main.wasp or main.wasp.ts # App definition: routes, pages, auth, operations, jobs, etc.
-├── schema.prisma             # Database schema
+├── main.wasp or main.wasp.ts # Wasp config file: routes, pages, auth, operations, jobs, etc.
+├── schema.prisma             # Database schema (Prisma)
 ```
 
-### Organization Principle
+### Code Organization
 
 Organize by **feature** (vertical), not by type (client/server):
 
@@ -52,11 +60,21 @@ src/
 │   └── google.ts
 ```
 
-## Project Setup & Customization
+### Starter Templates
+
+Highly recommend that the user chose one of the following templates when scaffolding a new Wasp app (this helps Claude understand Wasp's features and patterns):
+```bash
+wasp new my-basic-app -t basic # creates a basic starter app with core Wasp features like auth, operations, pages, etc.
+wasp new my-saas-app -t saas # creates a full-featured SaaS starter app with auth, payments, demo app, AWS S3, and more (OpenSaaS.sh)
+```
+
+See the **Starter Templates** section in https://wasp.sh/llms.txt for more templates.
 
-Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): see the **Project Setup & Customization** docs section.
+### Customization
 
-## Advanced Features
+Wasp provides layers of customization on top of the tools it uses (vite, expressjs, react-query, client and server setup, etc.): see the **Project Setup & Customization** section in https://wasp.sh/llms.txt.
+
+### Advanced Features
 
 Wasp provides **advanced features**:
 - custom HTTP API endpoints
@@ -66,9 +84,9 @@ Wasp provides **advanced features**:
 - middleware
 - email sending
 
-See the **Advanced Features** docs section for more details.
+See the **Advanced Features** section in https://wasp.sh/llms.txt for more details.
 
-## Import Conventions
+### Import Conventions
 
 **In TypeScript files:**
 - ✅ `import type { User } from 'wasp/entities'`
@@ -76,7 +94,6 @@ See the **Advanced Features** docs section for more details.
 - ✅ `import { getTasks, createTask, useQuery } from 'wasp/client/operations'`
 - ✅ `import { SubscriptionStatus } from '@prisma/client'` (for Prisma enums)
 - ✅ Local code: relative paths `import { X } from './X'`
-- ❌ Never `@wasp/...` or `@src/...`
 - ⚠️ Call actions directly using `async/await`. DO NOT use Wasp's `useAction` hook unless optimistic updates are needed.
 
 **In main.wasp:**
@@ -84,16 +101,24 @@ See the **Advanced Features** docs section for more details.
 - ❌ Never relative paths
 
 **In main.wasp.ts:**
-See the **TypeScript Config** docs section for more details.
+See the **TypeScript Config** section in https://wasp.sh/llms.txt for more details.
+
+## Troubleshooting
+
+### Debugging
+
+When errors occur:
+1. Check server terminal for backend errors (localhost:3001)
+2. Check client terminal for frontend build errors (localhost:3000)
+3. Use `plugin:wasp:chrome-devtools` for browser console errors
 
-## Common Mistakes
+### Common Mistakes
 
 | Symptom | Fix |
 |---------|-----|
 | `context.entities.X undefined` | Add entity to `entities: [...]` in main.wasp |
-| Schema changes not applying | Run `wasp db migrate-dev` |
+| Schema changes not applying | Run `wasp db migrate-dev --name <descriptive-name>` |
 | Can't login after email signup with `Dummy` email provider | Check the server logs for the verification link or set SKIP_EMAIL_VERIFICATION_IN_DEV=true in .env.server |
 | Types stale after changes | Restart TS server |
 | Wasp not recognizing changes | **WAIT PATIENTLY** as Wasp recompiles the project. Re-run `wasp start` if necessary.|
-| Errors in client app browser console | Use the chrome-devtools MCP server `plugin:wasp:chrome-devtools` |
 | Persistent weirdness after waiting patiently and restarting. | Run `wasp clean` && `wasp start` |

From 3eccc0f740551191d9a4bfd1b4f6200a45db3f16 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 12:53:48 +0100
Subject: [PATCH 44/47] Add expert advice command and update documentation

Introduced the /wasp:expert-advice command for app improvement suggestions by a Wasp expert. Updated README and help skill documentation to reference the new command and improved example prompts formatting.
---
 README.md                                     |  1 +
 plugins/wasp/commands/expert-advice.md        | 14 +++++++++
 plugins/wasp/skills/wasp-plugin-help/SKILL.md | 29 +++++++++----------
 3 files changed, 29 insertions(+), 15 deletions(-)
 create mode 100644 plugins/wasp/commands/expert-advice.md

diff --git a/README.md b/README.md
index 92b4f09..edba909 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ A Claude Code plugin for developing web apps with the Wasp full-stack framework
 - optimized raw text Wasp documentation for LLMs
 - integrations guidance
 - best practices
+- expert advice on app improvements
 
 ## Adding to Your Project
 
diff --git a/plugins/wasp/commands/expert-advice.md b/plugins/wasp/commands/expert-advice.md
new file mode 100644
index 0000000..eec927b
--- /dev/null
+++ b/plugins/wasp/commands/expert-advice.md
@@ -0,0 +1,14 @@
+---
+argument-hint: [advice request]
+description: Get advice on app improvements and functionality from a Wasp expert. Takes optional arguments for more specific requests e.g. `/wasp:expert-advice how can I improve account management?`.
+---
+
+1. Explore the current codebase
+2. Check the wasp docs https://wasp.sh/llms.txt
+3. Explore this plugin's skills and commands by running `/wasp:help`
+4. Decide on a few improvements (if the user supplies arguments in the command, use them as a starting point, if not, your ideas can be app features, code improvements, enhancements, etc.)
+5. Present the improvements to the user with their names, descriptions, and pros and cons
+
+**User's assist request:** $ARGUMENTS
+
+
diff --git a/plugins/wasp/skills/wasp-plugin-help/SKILL.md b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
index 7fbfb7f..c5a553a 100644
--- a/plugins/wasp/skills/wasp-plugin-help/SKILL.md
+++ b/plugins/wasp/skills/wasp-plugin-help/SKILL.md
@@ -21,20 +21,14 @@ This plugin turns Claude Code into a Wasp framework expert, giving you an AI ass
 
 ## 💬 Example Wasp Prompts to Ask Claude
 
-> "Add Google authentication to my app"
-
-> "Help me add ShadCN UI to my app"
-
-> "Start a new SaaS app using Wasp's SaaS starter template" 
-
-> "Set up email sending with SendGrid"
-
-> "Which Wasp features should I use for this task?"
-
-> "Why isn't my recurring job working?"
-
-> "Deploy my app to Railway"
-
+- *"Add `Google authentication` to my app"*  
+- *"Help me add `ShadCN UI` to my app"*  
+- *"Start a new SaaS app using `Wasp's SaaS starter template`"*  
+- *"Set up email sending with `SendGrid`"*  
+- *"Solve the errors in the `browser console`"*  
+- *"Which `Wasp features` should I use for this task?"*  
+- *"Why isn't my `recurring job` working?"*  
+- *"Deploy my app to `Railway`"*  
 
 ## 🤖 Skills
 
@@ -76,7 +70,7 @@ Guided deployment workflow that helps you:
 
 Commands are used to interact with the plugin. Commands are run by the user when they want to invoke a specific prompt/action:
 
-1. `/wasp:init`: 
+1. `/wasp:init`:
   - Initialize the plugin for your project. 
   - Copies Wasp knowledge to your project
   - Links it in your `CLAUDE.md` file
@@ -85,6 +79,11 @@ Commands are used to interact with the plugin. Commands are run by the user when
 2. `/wasp:help`:
   - Displays this help guide
 
+3. `/wasp:expert-advice [advice request]`:
+  - Get advice on app improvements and functionality from a Wasp expert
+  - Optionally provide arguments for more specific requests (e.g., `/wasp:expert-advice how can I improve account management?`)
+  - Explores your codebase, Wasp docs, and plugin features to suggest improvements with pros and cons
+
 
 ## 📖 Documentation Access
 

From f71950bf517109e458931226d2955cdf3b895243 Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 12:58:14 +0100
Subject: [PATCH 45/47] Update expert-advice.md

---
 plugins/wasp/commands/expert-advice.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/wasp/commands/expert-advice.md b/plugins/wasp/commands/expert-advice.md
index eec927b..570d0d5 100644
--- a/plugins/wasp/commands/expert-advice.md
+++ b/plugins/wasp/commands/expert-advice.md
@@ -5,7 +5,7 @@ description: Get advice on app improvements and functionality from a Wasp expert
 
 1. Explore the current codebase
 2. Check the wasp docs https://wasp.sh/llms.txt
-3. Explore this plugin's skills and commands by running `/wasp:help`
+3. Explore this plugin's skills and commands
 4. Decide on a few improvements (if the user supplies arguments in the command, use them as a starting point, if not, your ideas can be app features, code improvements, enhancements, etc.)
 5. Present the improvements to the user with their names, descriptions, and pros and cons
 

From 90384ad8d1ee9c03e65b96c25990ee06770e22aa Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Thu, 18 Dec 2025 17:27:58 +0100
Subject: [PATCH 46/47] Update Wasp plugin docs and init command instructions

Added missing skills to the permissions list in README.md. Updated the init command to use AskUserQuestion for user confirmation and clarified instructions to not amend the general-wasp-knowledge.md file, but to amend CLAUDE.md for custom rules. Minor cleanup in expert-advice.md.
---
 plugins/wasp/README.md                 | 2 ++
 plugins/wasp/commands/expert-advice.md | 2 --
 plugins/wasp/commands/init.md          | 4 ++--
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/plugins/wasp/README.md b/plugins/wasp/README.md
index a166ef4..331ef7f 100644
--- a/plugins/wasp/README.md
+++ b/plugins/wasp/README.md
@@ -86,6 +86,8 @@ For the best experience, add these permissions to your project or user settings:
       "Bash(wasp deploy:*)",
       "WebFetch(domain:wasp.sh)",
       "WebFetch(domain:raw.githubusercontent.com)"
+      "Skill(wasp:wasp-plugin-help)",
+      "Skill(wasp:start-dev-server)",
     ]
   }
 }
diff --git a/plugins/wasp/commands/expert-advice.md b/plugins/wasp/commands/expert-advice.md
index 570d0d5..e923bbc 100644
--- a/plugins/wasp/commands/expert-advice.md
+++ b/plugins/wasp/commands/expert-advice.md
@@ -10,5 +10,3 @@ description: Get advice on app improvements and functionality from a Wasp expert
 5. Present the improvements to the user with their names, descriptions, and pros and cons
 
 **User's assist request:** $ARGUMENTS
-
-
diff --git a/plugins/wasp/commands/init.md b/plugins/wasp/commands/init.md
index 93b7bcc..4b65170 100644
--- a/plugins/wasp/commands/init.md
+++ b/plugins/wasp/commands/init.md
@@ -2,7 +2,7 @@
 description: Add Wasp knowledge to your project's CLAUDE.md
 ---
 
-0. inform the user that this process will give Claude access to info on Wasp's features, commands, workflows, and best practices by copying the `general-wasp-knowledge.md` file into the project directory and importing it into the user's CLAUDE.md file. Continue after the user agrees.
+0. inform the user that this process will give Claude access to info on Wasp's features, commands, workflows, and best practices by copying the `general-wasp-knowledge.md` file into the project directory and importing it into the user's CLAUDE.md file. Use the AskUserQuestion tool to ask the user if they want to continue.
 1. copy the file `${CLAUDE_PLUGIN_ROOT}/general-wasp-knowledge.md` from within the plugin's installation directory to the user's project `.claude/wasp/knowledge` directory using the Bash tool with `cp` command.
 2. append it to the user's CLAUDE.md file as an import:
 ```markdown
@@ -10,5 +10,5 @@ description: Add Wasp knowledge to your project's CLAUDE.md
 
 Wasp knowledge can be found at @.claude/wasp/knowledge/general-wasp-knowledge.md
 ```
-3. inform the user that process is complete and they can amend the `general-wasp-knowledge.md` file if they want.
+3. inform the user that process is complete and they SHOULD NOT amend the `general-wasp-knowledge.md` file, but should ammend their CLAUDE.md file with their own custom Wasp rules, if desired.
 4. also inform the user they can run `/wasp:help` to see the plugin's available commands and skills.

From 50a5ee15e9c1341ad754b1ba3aa2461ebc5888ff Mon Sep 17 00:00:00 2001
From: vincanger <70215737+vincanger@users.noreply.github.com>
Date: Fri, 19 Dec 2025 12:16:43 +0100
Subject: [PATCH 47/47] Update instructions for checking browser console errors

Revised guidance in general-wasp-knowledge.md and start-dev-server/SKILL.md to prompt users to choose a tool for checking browser console errors, offering both mcp__plugin_wasp_chrome-devtools and Claude Code's built-in Chrome browser function. This clarifies the process and tool options for verifying client app issues.
---
 plugins/wasp/general-wasp-knowledge.md        | 6 ++++--
 plugins/wasp/skills/start-dev-server/SKILL.md | 5 +++--
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/plugins/wasp/general-wasp-knowledge.md b/plugins/wasp/general-wasp-knowledge.md
index 2b6a47c..ea1e8d7 100644
--- a/plugins/wasp/general-wasp-knowledge.md
+++ b/plugins/wasp/general-wasp-knowledge.md
@@ -16,7 +16,7 @@ Before starting any development task on this Wasp project (coding, debugging, ad
 - Check for active background tasks (use `/tasks` command)
 - Or check if ports 3000 (client) and 3001 (server) are in use
 
-If not running, invoke the `plugin:wasp:start-dev-server` skill to start the server as a background task or externally.
+If not running, invoke the `start-dev-server` skill to start the server as a background task or externally.
 
 ### Implementation Checklist
 
@@ -110,7 +110,9 @@ See the **TypeScript Config** section in https://wasp.sh/llms.txt for more detai
 When errors occur:
 1. Check server terminal for backend errors (localhost:3001)
 2. Check client terminal for frontend build errors (localhost:3000)
-3. Use `plugin:wasp:chrome-devtools` for browser console errors
+3. Confirm there are no client app issues in the browser console. Ask the user to choose which tool they'd prefer via the AskUserQuestion tool and run it for the user:
+  - the `mcp__plugin_wasp_chrome-devtools`
+  - Claude Code's built-in Chrome browser function
 
 ### Common Mistakes
 
diff --git a/plugins/wasp/skills/start-dev-server/SKILL.md b/plugins/wasp/skills/start-dev-server/SKILL.md
index d239ff7..271d7d2 100644
--- a/plugins/wasp/skills/start-dev-server/SKILL.md
+++ b/plugins/wasp/skills/start-dev-server/SKILL.md
@@ -67,5 +67,6 @@ wasp start
 ### Step 5: Verify
 
 1. Confirm client (`localhost:3000`) and server (`localhost:3001`) are running
-2. Note any warnings
-3. Use `plugin:wasp:chrome-devtools` to check browser console for errors
+2. Confirm there are no client app issues in the browser console. Ask the user to choose which tool they'd prefer via the AskUserQuestion tool and run it for the user:
+  - the `mcp__plugin_wasp_chrome-devtools`
+  - Claude Code's built-in Chrome browser function