@claude-code-mastery/starter-kit 1.0.0 → 1.2.0

package/.claude/.starter-kit/profiles/clean.md

@@ -74,7 +74,13 @@ project/
 2. **Run the batch scaffold script** — this replaces all individual file creation with a single command:
 
 ```bash
-bash "$(pwd)/scripts/scaffold-clean.sh" "$PROJECT_PATH" "$PROJECT_NAME" "$(pwd)"
+# Resolve the kit source: npm global install takes priority over CWD
+if [ -f ~/.claude/starter-kit-source-path ]; then
+  KIT=$(cat ~/.claude/starter-kit-source-path)
+else
+  KIT="$(pwd)"
+fi
+bash "$KIT/scripts/scaffold-clean.sh" "$PROJECT_PATH" "$PROJECT_NAME" "$KIT"
 ```
 
 The script handles ALL of the following in one execution (~100ms) with a progress indicator:

package/.claude/.starter-kit/profiles/go.md

@@ -394,7 +394,7 @@ When creating a Go project, the CLAUDE.md MUST include these Go-specific rules:
 8. Create `Dockerfile` (multi-stage with scratch, using template above)
 9. Create `.golangci.yml` (using template above)
 10. Create Go-specific `CLAUDE.md` (with Go rules above + universal security rules)
-11. Copy `.claude/` contents from starter kit — only commands with `scope: project` in frontmatter (skills, hooks, settings.json copied in full)
+11. **If NOT using npm global install** (`~/.claude/starter-kit-source-path` does not exist): Copy `.claude/` contents from starter kit - only commands with `scope: project` in frontmatter (skills, hooks, settings.json copied in full). **If npm global install is active**: skip this step - commands/skills/hooks already live in `~/.claude/` globally.
 12. Create `project-docs/` templates (ARCHITECTURE.md, INFRASTRUCTURE.md, DECISIONS.md)
 13. Create `.env`, `.env.example`, `.gitignore` (Go-specific), `.dockerignore`
 14. Create `CLAUDE.local.md` template

package/.claude/.starter-kit/profiles/node.md

@@ -81,13 +81,22 @@ Based on answers, scaffold the project.
 **If the resolved choices exactly match the default profile** (fullstack + next + mongo + tailwind + docker + pnpm), use the batch scaffold script for maximum speed:
 
 ```bash
-bash "$(pwd)/scripts/scaffold-default.sh" "$PROJECT_PATH" "$PROJECT_NAME" "$(pwd)"
+# Resolve the kit source: npm global install takes priority over CWD
+if [ -f ~/.claude/starter-kit-source-path ]; then
+  KIT=$(cat ~/.claude/starter-kit-source-path)
+else
+  KIT="$(pwd)"
+fi
+bash "$KIT/scripts/scaffold-default.sh" "$PROJECT_PATH" "$PROJECT_NAME" "$KIT"
 ```
 
 The script handles ALL of the following in one execution with progress indicators:
-- Creates all directories (src/, .claude/, project-docs/, tests/, scripts/, .github/)
-- Copies project-scoped commands, all skills, and all hooks
-- Writes settings.json (full 9-hook config)
+- Creates all directories (src/, project-docs/, tests/, scripts/, .github/)
+- For clone users: copies project-scoped commands, all skills, and all hooks into the project's .claude/
+- For npm users: skips local .claude/ copy (commands/skills/hooks already live globally in ~/.claude/)
+- Writes settings.json (10-hook config) for clone users only
+- Installs StrictDB (npm package) + query system
+- Creates Next.js app structure (layout, page, API health route, instrumentation)
 - Installs StrictDB (npm package) + query system
 - Creates Next.js app structure (layout, page, API health route, instrumentation)
 - Creates TypeScript, Next.js, Tailwind, PostCSS, Vitest, Playwright configs

package/.claude/.starter-kit/profiles/python.md

@@ -415,7 +415,7 @@ When creating a Python project, the CLAUDE.md MUST include these Python-specific
 10. Create `Makefile` with dev, test, lint, format, run targets
 11. Create `Dockerfile` (multi-stage with python:3.12-slim)
 12. Create Python-specific CLAUDE.md (with Python rules + universal security rules)
-13. Copy `.claude/` contents from starter kit — only commands with `scope: project` in frontmatter (skills, hooks, settings.json copied in full)
+13. **If NOT using npm global install** (`~/.claude/starter-kit-source-path` does not exist): Copy `.claude/` contents from starter kit - only commands with `scope: project` in frontmatter (skills, hooks, settings.json copied in full). **If npm global install is active**: skip this step - commands/skills/hooks already live in `~/.claude/` globally.
 14. Create `project-docs/` templates (ARCHITECTURE.md, INFRASTRUCTURE.md, DECISIONS.md)
 15. Create `.env`, `.env.example`, `.gitignore` (Python-specific), `.dockerignore`
 16. Create `CLAUDE.local.md` template

package/.claude/commands/show-user-guide.md

@@ -8,43 +8,46 @@ Open the User Guide for the Claude Code Mastery Project Starter Kit.
 
 ## Steps
 
-1. **Check for the HTML file** at `docs/user-guide.html` in the project root.
-
-2. **Open in browser** — try the GitHub Pages URL first, fall back to local file:
+1. **Open the User Guide** — try the GitHub Pages URL first, then fall back to a local copy if one exists:
 
    **Primary (online):**
    ```
    https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html
    ```
 
-   **Fallback (local):**
+   **Local fallback** (only if the repo was cloned):
    ```
    docs/user-guide.html
    ```
 
-3. **Detect the environment** and use the correct open command:
+2. **Detect the environment** and use the correct open command:
    - **WSL:** `wslview <url>`
    - **macOS:** `open <url>`
    - **Linux:** `xdg-open <url>`
 
-4. **Also mention** the markdown version is available at `USER_GUIDE.md` in the project root for reading directly in GitHub or a text editor.
-
 ## Detection Logic
 
 ```bash
-# Detect platform and open URL
 URL="https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html"
-LOCAL="docs/user-guide.html"
-
-if grep -qi microsoft /proc/version 2>/dev/null; then
-  # WSL
-  wslview "$URL" 2>/dev/null || wslview "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
-elif [[ "$OSTYPE" == "darwin"* ]]; then
-  # macOS
-  open "$URL" 2>/dev/null || open "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
+LOCAL="$(pwd)/docs/user-guide.html"
+
+open_url() {
+  if grep -qi microsoft /proc/version 2>/dev/null; then
+    wslview "$1" 2>/dev/null
+  elif [[ "$OSTYPE" == "darwin"* ]]; then
+    open "$1" 2>/dev/null
+  else
+    xdg-open "$1" 2>/dev/null
+  fi
+}
+
+# Always try online first
+if open_url "$URL"; then
+  echo "Opened online User Guide."
+elif [ -f "$LOCAL" ] && open_url "$LOCAL"; then
+  echo "Opened local User Guide."
 else
-  # Linux
-  xdg-open "$URL" 2>/dev/null || xdg-open "$LOCAL" 2>/dev/null || echo "Could not open browser. Visit: $URL"
+  echo "Could not open browser. Visit: $URL"
 fi
 ```
 
@@ -52,7 +55,6 @@ fi
 
 After opening, tell the user:
 
-> User Guide opened in your browser.
+> User Guide opened.
 > - **Online:** https://thedecipherist.github.io/claude-code-mastery-project-starter-kit/user-guide.html
-> - **Markdown:** `USER_GUIDE.md` (project root)
 > - **Tip:** Use `/help` to see all available commands at any time.

package/.dockerignore

@@ -0,0 +1,39 @@
+# Environment & Secrets
+.env
+.env.*
+.env.local
+secrets.json
+credentials.json
+
+# Git
+.git/
+.gitignore
+
+# Dependencies
+node_modules/
+
+# Build & IDE
+dist/
+.next/
+.vscode/
+.idea/
+
+# Claude Code
+.claude/
+CLAUDE.md
+CLAUDE.local.md
+
+# Testing
+coverage/
+test-results/
+playwright-report/
+
+# Documentation (not needed in container)
+project-docs/
+docs/
+*.md
+!README.md
+
+# OS
+.DS_Store
+Thumbs.db

package/.env.example

@@ -0,0 +1,74 @@
+# ==========================================
+# Environment Variables
+# ==========================================
+# Copy this to .env and fill in real values
+# NEVER commit .env to git
+#
+# Run /setup for interactive configuration
+# ==========================================
+
+# ------------------------------------------
+# Application
+# ------------------------------------------
+NODE_ENV=development
+# Port assignment: Website=3000, API=3001, Dashboard=3002 (see CLAUDE.md port table)
+PORT=3000
+
+# ------------------------------------------
+# Database (StrictDB — auto-detects backend from URI scheme)
+# ------------------------------------------
+STRICTDB_URI=YOUR_DATABASE_CONNECTION_STRING_HERE
+
+# Multi-region database (uncomment if using /setup with multi-region)
+# STRICTDB_URI_US=YOUR_US_DATABASE_URI_HERE
+# STRICTDB_URI_EU=YOUR_EU_DATABASE_URI_HERE
+
+# ------------------------------------------
+# Authentication
+# ------------------------------------------
+JWT_SECRET=YOUR_JWT_SECRET_HERE
+
+# ------------------------------------------
+# GitHub
+# ------------------------------------------
+GITHUB_USERNAME=YOUR_GITHUB_USERNAME_HERE
+
+# ------------------------------------------
+# Analytics (Rybbit)
+# ------------------------------------------
+NEXT_PUBLIC_RYBBIT_SITE_ID=YOUR_RYBBIT_SITE_ID_HERE
+NEXT_PUBLIC_RYBBIT_URL=https://app.rybbit.io
+
+# ------------------------------------------
+# Docker
+# ------------------------------------------
+DOCKER_HUB_USER=YOUR_DOCKER_HUB_USERNAME_HERE
+DOCKER_IMAGE_NAME=YOUR_DOCKER_HUB_USER/YOUR_PROJECT_NAME
+
+# ------------------------------------------
+# Deployment (single-server)
+# ------------------------------------------
+VPS_IP=YOUR_VPS_IP_HERE
+DOKPLOY_URL=YOUR_DOKPLOY_URL_HERE
+DOKPLOY_API_KEY=YOUR_DOKPLOY_API_KEY_HERE
+DOKPLOY_APP_ID=YOUR_DOKPLOY_APP_ID_HERE
+DOKPLOY_REFRESH_TOKEN=YOUR_DOKPLOY_REFRESH_TOKEN_HERE
+
+# Multi-region deployment (uncomment if using /setup with multi-region)
+# VPS_IP_US=YOUR_US_VPS_IP_HERE
+# VPS_IP_EU=YOUR_EU_VPS_IP_HERE
+# DOKPLOY_URL_US=YOUR_US_DOKPLOY_URL_HERE
+# DOKPLOY_URL_EU=YOUR_EU_DOKPLOY_URL_HERE
+# DOKPLOY_API_KEY_US=YOUR_US_DOKPLOY_API_KEY_HERE
+# DOKPLOY_API_KEY_EU=YOUR_EU_DOKPLOY_API_KEY_HERE
+# DOKPLOY_APP_ID_US=YOUR_US_DOKPLOY_APP_ID_HERE
+# DOKPLOY_APP_ID_EU=YOUR_EU_DOKPLOY_APP_ID_HERE
+# DOKPLOY_REFRESH_TOKEN_US=YOUR_US_DOKPLOY_REFRESH_TOKEN_HERE
+# DOKPLOY_REFRESH_TOKEN_EU=YOUR_EU_DOKPLOY_REFRESH_TOKEN_HERE
+# DEPLOY_REGION=us
+
+# ------------------------------------------
+# Monitoring (RuleCatch)
+# ------------------------------------------
+RULECATCH_API_KEY=YOUR_RULECATCH_API_KEY_HERE
+RULECATCH_REGION=us

package/.gitignore

@@ -0,0 +1,70 @@
+# Environment & Secrets
+.env
+.env.local
+.env.production
+.env.staging
+secrets.json
+credentials.json
+service-account.json
+
+# Claude Code personal overrides
+CLAUDE.local.md
+.claude/settings.local.json
+
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+.next/
+out/
+
+# TypeScript
+*.tsbuildinfo
+
+# Testing
+coverage/
+.nyc_output/
+test-results/
+playwright-report/
+
+# IDE
+.vscode/settings.json
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Temporary AI research files
+_ai_temp/
+
+# MDD working directory (docs, audit notes, reports)
+.mdd/
+
+# Misc
+*.bak
+*.tmp
+
+
+.code-workspace
+
+mdd_dashboard_prompt.md
+# MDD audit reports (ephemeral — regenerated by /mdd audit)
+.mdd/audits/
+# MDD active jobs (ephemeral — deleted on completion)
+.mdd/jobs/
+
+*.Zone.Identifier
+_.claude/
+_gh_readme.md