@claude-code-mastery/starter-kit 1.0.0

package/.claude/.starter-kit/shared/deployment-dokploy.md

@@ -0,0 +1,158 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## Dokploy on Hostinger VPS (if selected)
+
+When Dokploy is selected as the hosting target, scaffold a complete deployment pipeline:
+
+### Deployment Architecture
+```
+Code → Docker Build → Local Test → Docker Hub → Dokploy (webhook) → Live
+```
+
+### Required Environment Variables (.env.example additions)
+
+```bash
+# Dokploy Deployment
+DOKPLOY_URL=http://your-vps-ip:3000/api
+DOKPLOY_API_KEY=your_dokploy_api_key
+DOKPLOY_APP_ID=your_application_id
+DOKPLOY_REFRESH_TOKEN=your_webhook_refresh_token
+
+# Docker Hub
+DOCKER_HUB_USER=your_docker_username
+DOCKER_IMAGE_NAME=your_docker_username/your_app_name
+
+# Region (if multi-region)
+DEPLOY_REGION=us
+```
+
+### Deployment Script: scripts/deploy.sh
+
+Create this deployment script:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Load environment
+source .env
+
+IMAGE="$DOCKER_IMAGE_NAME:latest"
+TAG="${1:-latest}"
+
+echo "=== Building Docker image ==="
+docker build -t "$IMAGE" .
+
+echo "=== Testing locally ==="
+docker run -d -p 3000:3000 --name deploy-test "$IMAGE"
+sleep 5
+
+if ! curl -sf http://localhost:3000 > /dev/null; then
+  echo "ERROR: Local test FAILED. Aborting deployment."
+  docker logs deploy-test
+  docker stop deploy-test && docker rm deploy-test
+  exit 1
+fi
+
+echo "Local test PASSED."
+docker stop deploy-test && docker rm deploy-test
+
+echo "=== Pushing to Docker Hub ==="
+docker push "$IMAGE"
+
+echo "=== Deploying via Dokploy ==="
+RESPONSE=$(curl -s -X POST \
+  -H "x-api-key: $DOKPLOY_API_KEY" \
+  -H "Content-Type: application/json" \
+  "$DOKPLOY_URL/application.deploy" \
+  -d "{\"applicationId\":\"$DOKPLOY_APP_ID\"}")
+
+echo "Dokploy response: $RESPONSE"
+echo "=== Deployment complete ==="
+```
+
+### Dokploy API Reference (for CLAUDE.md)
+
+Add these to the project's CLAUDE.md when Dokploy is selected:
+
+```markdown
+## Deployment Commands
+
+### Deploy (build, test, push, deploy)
+bash scripts/deploy.sh
+
+### Dokploy API (direct)
+# List all projects
+curl -s -H "x-api-key: $DOKPLOY_API_KEY" "$DOKPLOY_URL/project.all"
+
+# Deploy application
+curl -s -X POST -H "x-api-key: $DOKPLOY_API_KEY" -H "Content-Type: application/json" \
+  "$DOKPLOY_URL/application.deploy" -d '{"applicationId":"APP_ID"}'
+
+# Redeploy (rebuild)
+curl -s -X POST -H "x-api-key: $DOKPLOY_API_KEY" -H "Content-Type: application/json" \
+  "$DOKPLOY_URL/application.redeploy" -d '{"applicationId":"APP_ID"}'
+
+# Start / Stop
+curl -s -X POST -H "x-api-key: $DOKPLOY_API_KEY" -H "Content-Type: application/json" \
+  "$DOKPLOY_URL/application.start" -d '{"applicationId":"APP_ID"}'
+
+# Webhook deploy (no auth needed — use refresh token)
+curl -X POST http://your-vps-ip:3000/api/deploy/REFRESH_TOKEN
+```
+
+### Multi-Region Support (if selected)
+
+When `multiregion` is selected, scaffold for US + EU:
+
+```bash
+# .env.example additions for multi-region
+DOKPLOY_URL_US=http://us-vps-ip:3000/api
+DOKPLOY_API_KEY_US=your_us_api_key
+DOKPLOY_APP_ID_US=your_us_app_id
+
+DOKPLOY_URL_EU=http://eu-vps-ip:3000/api
+DOKPLOY_API_KEY_EU=your_eu_api_key
+DOKPLOY_APP_ID_EU=your_eu_app_id
+```
+
+**CRITICAL multi-region rules (add to CLAUDE.md):**
+- US containers NEVER connect to EU databases, and vice versa
+- Each container gets region-specific `STRICTDB_URI` (e.g., `STRICTDB_URI_US`, `STRICTDB_URI_EU`)
+- `DEPLOY_REGION` env var must match the VPS region
+- When pushing images: push `:latest` for US, push `:eu` tag for EU
+- ALWAYS deploy to both regions — never leave them out of sync
+
+### scripts/deploy-all.sh (multi-region)
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+source .env
+
+IMAGE="$DOCKER_IMAGE_NAME"
+
+# Build and test locally first
+docker build -t "$IMAGE:latest" .
+docker run -d -p 3000:3000 --name deploy-test "$IMAGE:latest"
+sleep 5
+curl -sf http://localhost:3000 > /dev/null || { echo "FAILED"; docker logs deploy-test; docker stop deploy-test; docker rm deploy-test; exit 1; }
+docker stop deploy-test && docker rm deploy-test
+
+# Push both tags
+docker push "$IMAGE:latest"
+docker tag "$IMAGE:latest" "$IMAGE:eu"
+docker push "$IMAGE:eu"
+
+# Deploy to both regions
+echo "Deploying to US..."
+curl -s -X POST -H "x-api-key: $DOKPLOY_API_KEY_US" -H "Content-Type: application/json" \
+  "$DOKPLOY_URL_US/application.deploy" -d "{\"applicationId\":\"$DOKPLOY_APP_ID_US\"}"
+
+echo "Deploying to EU..."
+curl -s -X POST -H "x-api-key: $DOKPLOY_API_KEY_EU" -H "Content-Type: application/json" \
+  "$DOKPLOY_URL_EU/application.deploy" -d "{\"applicationId\":\"$DOKPLOY_APP_ID_EU\"}"
+
+echo "=== Both regions deployed ==="
+```
+

package/.claude/.starter-kit/shared/feature-manifest.md

@@ -0,0 +1,43 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## Feature Manifest — MANDATORY Final Step (ALL modes except Clean)
+
+**After scaffolding completes and BEFORE the final verification checklist**, write `.claude/features.json` to the new project based on what was scaffolded.
+
+### Map scaffolding choices to features
+
+| Scaffolding Choice | Feature Name | Files to List |
+|-------------------|-------------|---------------|
+| `database = mongo` | `mongo` | `scripts/db-query.ts`, `scripts/queries/example-find-user.ts`, `scripts/queries/example-count-docs.ts` |
+| `database = postgres\|mysql\|mssql\|sqlite` | `postgres` | `scripts/db-query.ts` |
+| Vitest installed | `vitest` | `vitest.config.ts` |
+| Playwright installed | `playwright` | `playwright.config.ts` |
+| Docker selected | `docker` | `Dockerfile` |
+| Content pipeline | `content` | `scripts/build-content.ts`, `scripts/content.config.json` |
+
+### Write the manifest
+
+```json
+{
+  "schemaVersion": 1,
+  "installedBy": "claude-code-mastery-starter-kit",
+  "language": "<node|go|python>",
+  "features": {
+    "<feature-name>": {
+      "version": "1.0.0",
+      "installedAt": "<current-ISO-timestamp>",
+      "updatedAt": null,
+      "files": ["<list-of-files>"]
+    }
+  }
+}
+```
+
+Write to `$PROJECT_PATH/.claude/features.json`.
+
+**For Clean mode:** The scaffold-clean.sh script already creates an empty manifest (`"features": {}`). No additional action needed.
+
+**For Go/Python modes:** Map the same features (e.g., Go with MongoDB via StrictDB → `mongo` feature with `internal/database/mongo.go` in files).
+
+---
+

package/.claude/.starter-kit/shared/mcp-and-pooler.md

@@ -0,0 +1,38 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## AI-Pooler Setup (if @rulecatch/ai-pooler in npm list)
+
+When the default profile or user selects ai-pooler:
+
+```bash
+# Free monitor mode — works immediately, no API key needed
+# Run in a separate terminal to see live AI activity
+npx @rulecatch/ai-pooler monitor --no-api-key
+
+# Full setup with API key (for violation tracking, dashboards, and alerts)
+npx @rulecatch/ai-pooler init --api-key=dc_your_key --region=us
+```
+
+Add to `.env.example`:
+```bash
+RULECATCH_API_KEY=dc_your_api_key_here
+RULECATCH_REGION=us
+```
+
+## MCP Server Setup (if selected)
+
+When MCP servers are selected, add them to the project setup:
+
+```bash
+# Context7 — Live documentation (eliminates outdated API answers)
+claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
+
+# Playwright — E2E testing
+claude mcp add playwright -- npx -y @anthropic-ai/playwright-mcp
+
+# RuleCatch — AI development analytics & rule monitoring
+npx @rulecatch/mcp-server init
+```
+
+Add selected MCP servers to the project's CLAUDE.md under a "## MCP Servers" section.
+

package/.claude/.starter-kit/shared/mongo-setup.md

@@ -0,0 +1,20 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## MongoDB Test Query System (projects with `mongo` database)
+
+When the project uses MongoDB (via StrictDB), ALWAYS scaffold the db-query system:
+
+1. Create `scripts/db-query.ts` — the master index/CLI runner
+2. Create `scripts/queries/` directory for individual query files
+3. Add the db-query rules to the project's `CLAUDE.md`
+
+**The rule that MUST be in every StrictDB/MongoDB project's CLAUDE.md:**
+
+> ALL ad-hoc / test / dev database queries go through `scripts/db-query.ts`.
+> When asked to look something up in the database:
+> 1. Create a query file in `scripts/queries/<name>.ts`
+> 2. Register it in `scripts/db-query.ts`
+> 3. NEVER create standalone scripts or inline queries in `src/`
+
+This prevents Claude from scattering random query scripts all over the project.
+

package/.claude/.starter-kit/shared/profile-config.md

@@ -0,0 +1,65 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## Profile System: claude-mastery-project.conf
+
+If the user passes `default` (or any profile name), read `claude-mastery-project.conf` from the project root. This file defines reusable presets so users don't re-type preferences.
+
+### claude-mastery-project.conf Format
+
+```ini
+# Claude Mastery Project Configuration
+# Define profiles with preset options for /new-project
+
+[default]
+type = fullstack
+framework = next
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+options = seo, tailwind, docker, ci
+mcp = playwright, context7, rulecatch
+
+[api]
+type = api
+framework = fastify
+hosting = dokploy
+package_manager = pnpm
+database = mongo
+options = docker, ci
+mcp = context7, rulecatch
+
+[static-site]
+type = webapp
+framework = astro
+hosting = static
+package_manager = pnpm
+options = seo, tailwind
+mcp = context7
+
+[quick]
+type = webapp
+framework = vite
+hosting = vercel
+package_manager = pnpm
+options = tailwind
+mcp = context7
+```
+
+### How Profiles Work
+
+1. Read `claude-mastery-project.conf` from project root (or `~/.claude/claude-mastery-project.conf` for global defaults)
+2. Parse the named profile section
+3. Apply all settings from the profile
+4. Any additional arguments OVERRIDE profile settings
+5. Missing settings from profile = ask the user
+
+Examples:
+- `/new-project my-app default` — uses [default] profile for everything
+- `/new-project my-app api` — uses [api] profile
+- `/new-project my-app default vercel` — uses [default] but overrides hosting to Vercel
+- `/new-project my-app` — no profile, asks all questions
+
+### Create Default Config
+
+When scaffolding the starter kit itself, create `claude-mastery-project.conf` with the profiles above as starting templates. Users customize to their preferences.
+

package/.claude/.starter-kit/shared/seo.md

@@ -0,0 +1,113 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## Mandatory SEO (ALL Web Projects)
+
+Every web project MUST include these SEO fundamentals. This is non-negotiable for any page that serves HTML.
+
+### 1. HTML Meta Tags (in layout/head)
+
+```html
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Page Title — Site Name</title>
+  <meta name="description" content="Concise page description (150-160 chars)">
+  <meta name="robots" content="index, follow">
+  <link rel="canonical" href="https://example.com/current-page">
+
+  <!-- Open Graph (Facebook, LinkedIn, Discord) -->
+  <meta property="og:type" content="website">
+  <meta property="og:title" content="Page Title">
+  <meta property="og:description" content="Page description">
+  <meta property="og:image" content="https://example.com/og-image.png">
+  <meta property="og:url" content="https://example.com/current-page">
+  <meta property="og:site_name" content="Site Name">
+
+  <!-- Twitter Card -->
+  <meta name="twitter:card" content="summary_large_image">
+  <meta name="twitter:title" content="Page Title">
+  <meta name="twitter:description" content="Page description">
+  <meta name="twitter:image" content="https://example.com/og-image.png">
+</head>
+```
+
+### 2. JSON-LD Structured Data (schema.org)
+
+EVERY web project must include at minimum an Organization or WebSite schema:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "WebSite",
+  "name": "Your Site Name",
+  "url": "https://example.com",
+  "description": "Site description",
+  "publisher": {
+    "@type": "Organization",
+    "name": "Your Organization",
+    "logo": {
+      "@type": "ImageObject",
+      "url": "https://example.com/logo.png"
+    }
+  }
+}
+</script>
+```
+
+For specific page types, add the appropriate schema:
+- **Article pages:** `@type: "Article"` with author, datePublished, dateModified
+- **Product pages:** `@type: "Product"` with price, availability, reviews
+- **FAQ pages:** `@type: "FAQPage"` with question/answer pairs
+- **How-to pages:** `@type: "HowTo"` with steps
+- **Breadcrumbs:** `@type: "BreadcrumbList"` on all pages with navigation depth
+
+### 3. Technical SEO Files
+
+Create these in the project root (or public directory):
+
+**robots.txt:**
+```
+User-agent: *
+Allow: /
+Sitemap: https://example.com/sitemap.xml
+```
+
+**sitemap.xml** (or generate dynamically):
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  <url>
+    <loc>https://example.com/</loc>
+    <lastmod>2025-01-01</lastmod>
+    <priority>1.0</priority>
+  </url>
+</urlset>
+```
+
+### 4. Performance SEO
+
+- Images MUST use WebP format with `alt` attributes
+- Include `<link rel="preconnect">` for external domains (fonts, analytics, CDNs)
+- Set proper cache headers for static assets
+- Ensure Largest Contentful Paint (LCP) < 2.5 seconds
+
+### 5. Framework-Specific SEO
+
+**Next.js:**
+- Use `metadata` export in layout.tsx / page.tsx (App Router)
+- Use `generateMetadata()` for dynamic pages
+- JSON-LD via `<script>` in layout or use `next-seo` package
+- next/image for automatic WebP conversion and lazy loading
+- Automatic sitemap generation with `next-sitemap`
+
+**Vite + React (SPA):**
+- Use `react-helmet-async` for dynamic `<head>` management
+- For SEO-critical SPAs, consider prerendering with `vite-plugin-ssr` or `prerender-spa-plugin`
+- NOTE: SPAs have inherent SEO limitations — if SEO is critical, recommend SSR
+
+**Astro:**
+- Built-in `<head>` management in `.astro` layouts
+- Automatic sitemap with `@astrojs/sitemap`
+- Built-in image optimization
+

package/.claude/.starter-kit/shared/sql-setup.md

@@ -0,0 +1,37 @@
+<!-- Part of /new-project scaffolding. Read via .claude/commands/new-project.md when the selection requires it; not a standalone command. -->
+
+## SQL Database Setup (projects with `postgres`, `mysql`, `mssql`, or `sqlite` database)
+
+When the project uses a SQL database (PostgreSQL, MySQL, MSSQL, or SQLite), StrictDB handles the connection via `STRICTDB_URI`:
+
+1. Install StrictDB and the appropriate driver based on database choice:
+   - All databases: `npm install strictdb@^0.1.0`
+   - PostgreSQL: `npm install pg @types/pg`
+   - MySQL: `npm install mysql2`
+   - MSSQL: `npm install mssql`
+   - SQLite: `npm install better-sqlite3 @types/better-sqlite3`
+2. Set `STRICTDB_URI` in `.env.example` with placeholder
+3. Add StrictDB rules to the project's CLAUDE.md
+
+**The rule that MUST be in every SQL project's CLAUDE.md:**
+
+> ALL SQL database access goes through StrictDB. No exceptions.
+> NEVER create connection pools manually — StrictDB manages connections.
+> NEVER import database drivers directly — use StrictDB's API.
+> ALWAYS use parameterized queries — NEVER string-interpolate values into SQL.
+
+**STRICTDB_URI examples for .env.example:**
+```bash
+# PostgreSQL
+STRICTDB_URI=postgresql://user:password@localhost:5432/mydb
+
+# MySQL
+STRICTDB_URI=mysql://user:password@localhost:3306/mydb
+
+# MSSQL
+STRICTDB_URI=mssql://user:password@localhost:1433/mydb
+
+# SQLite
+STRICTDB_URI=file:./data/app.db
+```
+