claudenv 1.0.1 → 1.1.0

package/scaffold/global/.claude/commands/claudenv.md

@@ -0,0 +1,193 @@
+---
+description: Set up Claude Code documentation for this project — analyze tech stack, generate CLAUDE.md, rules, hooks, commands, and skills
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(mkdir:*), Bash(cp:*), Bash(chmod:*), Bash(curl:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# claudenv — Project Documentation Setup
+
+You are setting up Claude Code documentation for this project. Use your full capabilities to analyze the codebase — read files, understand architecture, and generate high-quality documentation.
+
+## Phase 1: Deep Project Analysis
+
+Scan the project thoroughly. Start with these discovery commands:
+
+**Manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "pom.xml" -o -name "build.gradle*" -o -name "*.csproj" -o -name "requirements.txt" -o -name "setup.py" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "nuxt.config.*" -o -name "svelte.config.*" -o -name "astro.config.*" -o -name "angular.json" -o -name "manage.py" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".eslintrc*" -o -name "biome.json" -o -name ".prettierrc*" -o -name "vitest.config.*" -o -name "jest.config.*" -o -name "pytest.ini" -o -name "conftest.py" -o -name "turbo.json" -o -name "nx.json" \) -not -path "*/node_modules/*" 2>/dev/null | head -30`
+
+**CI/CD:**
+!`find . -maxdepth 3 \( -path "*/.github/workflows/*" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile" -o -name ".circleci/config.yml" \) 2>/dev/null | head -10`
+
+**Existing docs:**
+!`find . -maxdepth 2 \( -name "README.md" -o -name "CLAUDE.md" -o -name "CONTRIBUTING.md" -o -name "_state.md" \) -not -path "*/node_modules/*" 2>/dev/null | head -10`
+
+**Directory structure:**
+!`ls -la`
+
+Now **read the manifest files** you found (package.json, pyproject.toml, etc.) to understand:
+- Project name and description
+- Dependencies and their purposes
+- Available scripts/commands
+- Dev vs production dependencies
+
+Also **read the README.md** if it exists — it often contains the best project description.
+
+**Read 3-5 key source files** to understand the actual code architecture, patterns, and conventions used.
+
+## Phase 2: Ask the User
+
+Based on your analysis, ask the user these questions **one at a time**, providing your best guess as context:
+
+1. **Project description**: "Based on my analysis, this appears to be [your analysis]. Is this correct, or would you describe it differently?"
+2. **Deployment**: "Where is this deployed?" (Vercel, AWS, Docker, bare metal, etc.)
+3. **Conventions**: "I noticed [patterns you found]. Are there other team conventions I should know about?"
+4. **Focus areas**: "Are there areas of the codebase that need special attention?" (complex logic, frequent bugs, etc.)
+
+If `$ARGUMENTS` includes `--force`, skip questions and use your best judgment from the analysis.
+
+## Phase 3: Generate Documentation
+
+Create the following files based on your REAL analysis of the code (not generic templates):
+
+### 3.1 CLAUDE.md (project root)
+Compact (under 60 lines) with these sections:
+- `## Project overview` — one sentence with detected stack, based on what you actually found
+- `## Commands` — all dev/build/test/lint/format commands from manifest files
+- `## Architecture` — key directories with descriptions based on ACTUAL content you read
+- `## Conventions` — @import references to rules files
+- `## Workflow` — @import to workflow.md
+- `## Memory` — reference to _state.md
+- `## Rules` — project-specific rules including: "NEVER create documentation files (.md) unless the user explicitly requests it"
+
+### 3.2 _state.md (project root)
+Session memory file:
+- `## Current Focus` — empty (user fills in)
+- `## Key Decisions` — pre-fill with architectural decisions you detected
+- `## Known Issues` — empty
+- `## Session Notes` — empty
+
+### 3.3 .claude/rules/code-style.md
+YAML frontmatter with path globs. Include language-specific and framework-specific conventions based on what you actually found in the code.
+
+### 3.4 .claude/rules/testing.md
+YAML frontmatter with test path globs. Include detected test framework, commands, patterns.
+
+### 3.5 .claude/rules/workflow.md
+Claude Code workflow best practices:
+- Plan mode usage
+- /compact and /clear for context management
+- Subagents for parallel tasks
+- Memory via _state.md (read at start, update at end)
+- Commit discipline
+- NEVER create .md files unless explicitly asked
+
+### 3.6 .claude/settings.json
+Validation hooks configuration (PostToolUse hooks for Write operations on doc files).
+
+**Present each file to the user for review before writing.** If `$ARGUMENTS` includes `--force`, write without confirmation.
+
+## Phase 4: Install Project Commands & Skills
+
+Copy the following scaffold files from the global skill directory into this project:
+
+```bash
+# Create directories
+mkdir -p .claude/commands .claude/skills/doc-generator/scripts .claude/skills/doc-generator/templates .claude/agents
+
+# Copy project-level scaffold from global skill
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/init-docs.md .claude/commands/init-docs.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/update-docs.md .claude/commands/update-docs.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/validate-docs.md .claude/commands/validate-docs.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/SKILL.md .claude/skills/doc-generator/SKILL.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/scripts/validate.sh .claude/skills/doc-generator/scripts/validate.sh
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/detection-patterns.md .claude/skills/doc-generator/templates/detection-patterns.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/mcp-servers.md .claude/skills/doc-generator/templates/mcp-servers.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md .claude/commands/setup-mcp.md
+cp ~/.claude/skills/claudenv/scaffold/.claude/agents/doc-analyzer.md .claude/agents/doc-analyzer.md
+chmod +x .claude/skills/doc-generator/scripts/validate.sh
+```
+
+If any file already exists, **skip it** unless `$ARGUMENTS` includes `--force`.
+
+## Phase 5: MCP Server Configuration
+
+Configure MCP servers for this project by searching the official MCP Registry.
+
+Read the MCP server reference:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
+**5.1 Identify technologies to search for:**
+Based on your Phase 1 analysis, list the key technologies that might have MCP servers (databases, cloud services, APIs, dev tools).
+
+**5.2 Search the registry:**
+For each technology, query the MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+**5.3 Verify trust:**
+For each candidate with an npm package, check monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+Filter out servers with <100 monthly downloads.
+
+**5.4 Present recommendations:**
+Group as Essential / Recommended / Optional. For each, explain why it's relevant and show download counts.
+
+Ask the user which to configure. If `$ARGUMENTS` includes `--force`, auto-select Essential + Recommended.
+
+**5.5 Generate `.mcp.json`:**
+Write `.mcp.json` with selected servers using `${ENV_VAR}` placeholders for secrets. Follow the format in the MCP server reference.
+
+**5.6 List environment variables:**
+Tell the user how to configure required secrets:
+```
+claude config set env.VAR_NAME "your-value"
+```
+
+## Phase 6: Validate
+
+Run the validation script:
+```bash
+bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true
+```
+
+Fix any errors found.
+
+## Phase 7: Summary
+
+Print a summary of everything created:
+```
+claudenv setup complete!
+
+Created:
+  + CLAUDE.md
+  + _state.md
+  + .claude/rules/code-style.md
+  + .claude/rules/testing.md
+  + .claude/rules/workflow.md
+  + .claude/settings.json
+  + .claude/commands/init-docs.md
+  + .claude/commands/update-docs.md
+  + .claude/commands/validate-docs.md
+  + .claude/commands/setup-mcp.md
+  + .claude/skills/doc-generator/
+  + .claude/agents/doc-analyzer.md
+  + .mcp.json (if MCP servers were configured)
+
+Available commands:
+  /init-docs      — Regenerate documentation from scratch
+  /update-docs    — Update docs when project changes
+  /validate-docs  — Check documentation completeness
+  /setup-mcp      — Add or update MCP server configuration
+
+Next steps:
+  1. Review and edit CLAUDE.md
+  2. Configure any required MCP secrets: claude config set env.VAR_NAME "value"
+  3. git add .claude/ CLAUDE.md _state.md .mcp.json && git commit -m "Add Claude Code docs"
+```

package/scaffold/global/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+description: Recommend and configure MCP servers based on project analysis
+allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# MCP Server Setup
+
+You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
+
+## Step 1: Analyze the Project
+
+Understand what this project uses:
+
+**Read existing documentation:**
+- Read CLAUDE.md if it exists — it contains the tech stack summary
+- Read _state.md if it exists
+
+**Check for existing MCP config:**
+- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
+
+**Scan manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Scan framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files you found. Identify:
+- Programming languages and frameworks
+- Databases (PostgreSQL, MongoDB, Redis, etc.)
+- Cloud services (AWS, GCP, Azure)
+- External APIs (Stripe, Sentry, etc.)
+- Dev tools (Docker, GitHub Actions, etc.)
+
+## Step 2: Search the MCP Registry
+
+Read the MCP server reference for search and evaluation guidance:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
+For each major technology in the project, search the official MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+For each candidate server with an npm package, verify trust by checking monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+
+Optionally check GitHub stars for additional trust signal:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+```
+
+**Filtering rules:**
+- Remove servers with <100 monthly npm downloads
+- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
+- When multiple servers exist for the same technology, pick the one with the highest downloads
+
+## Step 3: Present Recommendations
+
+Group your recommendations into three tiers:
+
+**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
+
+**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
+
+**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
+
+For each recommendation, explain:
+- **What it does** and why it's relevant to THIS project
+- **Monthly npm downloads** (trust signal)
+- **Environment variables required** and whether they need secrets
+
+Ask the user which servers to configure.
+
+If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
+
+## Step 4: Generate .mcp.json
+
+Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
+
+**If `.mcp.json` already exists:**
+- Read it and parse the existing `mcpServers` entries
+- Merge new servers into the existing config — do NOT remove or overwrite existing entries
+- If a server key already exists, skip it (preserve the user's existing config)
+
+**Key rules:**
+- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
+- Non-secret env vars can use literal values when appropriate
+- Use `npx -y <package>@latest` for stdio/npm servers
+- Use the `type` and `url` from remotes for HTTP/SSE servers
+
+Write the `.mcp.json` file.
+
+## Step 5: Update CLAUDE.md
+
+If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
+
+If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
+
+## Step 6: Environment Variables
+
+List all required environment variables and how to configure them:
+
+```
+To configure secrets, run:
+  claude config set env.VAR_NAME "your-value"
+
+Required environment variables:
+  VAR_NAME — Description of what this is and where to get it
+```
+
+Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.

package/scaffold/global/.claude/skills/claudenv/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: claudenv
+description: Detects missing or outdated project documentation and offers to generate or update it. Triggers when CLAUDE.md is missing, when the user mentions documentation setup, or when significant project changes are detected.
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(mkdir:*), Bash(cp:*), Bash(chmod:*)
+---
+
+# claudenv — Documentation Management Skill
+
+## When to auto-trigger
+- CLAUDE.md does not exist in the project root
+- `.mcp.json` does not exist in a project that has CLAUDE.md
+- User mentions "documentation", "CLAUDE.md", "project setup", or "claudenv"
+- User mentions "MCP", "MCP servers", or "mcp.json"
+- User asks to configure Claude Code for their project
+- After major refactoring that changes directory structure
+
+## Capabilities
+
+### Initial Setup
+If no CLAUDE.md exists, suggest running `/claudenv` to set up full documentation.
+
+### Update Detection
+When working in a project with existing documentation, watch for:
+- New dependencies added to manifest files
+- New directories created that aren't in CLAUDE.md Architecture section
+- Changed scripts in package.json / pyproject.toml
+- New config files (linter, formatter, test framework)
+
+When changes are detected, suggest running `/update-docs`.
+
+### MCP Configuration
+When `.mcp.json` is missing in a project that already has CLAUDE.md, suggest running `/setup-mcp` to configure MCP servers. When the user mentions MCP servers, offer to run `/setup-mcp`.
+
+### Validation
+After documentation changes, run the validation script:
+```bash
+bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true
+```
+
+## Reference
+
+For tech stack detection patterns, see:
+@~/.claude/skills/claudenv/templates/detection-patterns.md
+
+For MCP server search, evaluation, and configuration, see:
+@~/.claude/skills/claudenv/templates/mcp-servers.md
+
+## Project-level scaffold
+
+The following files are available for installation into projects at `~/.claude/skills/claudenv/scaffold/`:
+- `.claude/commands/init-docs.md` — Interactive documentation regeneration
+- `.claude/commands/update-docs.md` — Refresh docs from current state
+- `.claude/commands/validate-docs.md` — Run validation checks
+- `.claude/skills/doc-generator/SKILL.md` — Per-project doc generation skill
+- `.claude/skills/doc-generator/scripts/validate.sh` — Bash validation script
+- `.claude/skills/doc-generator/templates/detection-patterns.md` — Detection reference
+- `.claude/commands/setup-mcp.md` — MCP server recommendation and setup
+- `.claude/skills/doc-generator/templates/mcp-servers.md` — MCP registry reference
+- `.claude/agents/doc-analyzer.md` — Read-only analysis subagent

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/agents/doc-analyzer.md

@@ -0,0 +1,70 @@
+---
+name: doc-analyzer
+description: Analyzes project structure for documentation. Use proactively when scanning codebases or evaluating documentation completeness.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+memory: project
+---
+
+You are a documentation analysis specialist. Your job is to scan project files and determine the tech stack, build commands, testing patterns, and coding conventions.
+
+## Analysis Process
+
+When analyzing a project:
+
+1. **Manifest files first** — Read package.json, pyproject.toml, go.mod, Cargo.toml, Gemfile, or composer.json to identify the language, dependencies, and scripts.
+
+2. **Framework detection** — Look for framework config files (next.config.js, vite.config.ts, manage.py, etc.) to identify the application framework.
+
+3. **Tooling inventory** — Scan for:
+   - Linter configs (.eslintrc*, biome.json, ruff.toml, .golangci.yml)
+   - Formatter configs (.prettierrc*, .editorconfig)
+   - Test configs (vitest.config.*, jest.config.*, pytest.ini, conftest.py)
+   - CI/CD files (.github/workflows/, .gitlab-ci.yml)
+   - Infrastructure (Dockerfile, docker-compose.yml, terraform/, *.tf)
+
+4. **Read existing documentation** — Check for README.md, CONTRIBUTING.md, CLAUDE.md, and any docs/ directory.
+
+5. **Directory structure** — Use Glob to map the top-level directory layout and identify key source directories.
+
+## Output Format
+
+Output your findings as structured JSON:
+
+```json
+{
+  "language": "typescript",
+  "runtime": "node",
+  "framework": "next.js",
+  "packageManager": "pnpm",
+  "testFramework": "vitest",
+  "linter": "eslint",
+  "formatter": "prettier",
+  "ci": "github-actions",
+  "containerized": true,
+  "monorepo": null,
+  "scripts": {
+    "dev": "pnpm next dev",
+    "build": "pnpm next build",
+    "test": "pnpm vitest run",
+    "lint": "pnpm next lint"
+  },
+  "directories": [
+    { "path": "src/app/", "description": "App Router pages and layouts" },
+    { "path": "src/components/", "description": "React components" },
+    { "path": "src/lib/", "description": "Shared utilities" }
+  ],
+  "existingDocs": ["README.md"],
+  "recommendations": [
+    "CLAUDE.md is missing — generate one",
+    "No .claude/rules/ directory — consider adding code style rules"
+  ]
+}
+```
+
+## Rules
+
+- **NEVER modify files.** You are read-only.
+- Only read and report findings.
+- If you cannot determine something with confidence, say so rather than guessing.
+- Prioritize accuracy over completeness.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/init-docs.md

@@ -0,0 +1,69 @@
+---
+description: Analyze project and generate Claude Code documentation interactively
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
+argument-hint: [--force]
+disable-model-invocation: true
+---
+
+# Project Documentation Generator
+
+You are generating Claude Code documentation for this project. Follow the phases below carefully.
+
+## Phase 1: Project Analysis
+
+Scan the project to detect the tech stack. Read the following detected files:
+
+**Package managers and manifests:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "pom.xml" -o -name "build.gradle*" -o -name "*.csproj" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**Framework configs:**
+!`find . -maxdepth 2 \( -name "tsconfig.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "nuxt.config.*" -o -name "svelte.config.*" -o -name "astro.config.*" -o -name "angular.json" -o -name "manage.py" -o -name "docker-compose.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**CI/CD:**
+!`find . -maxdepth 3 \( -path "*/.github/workflows/*" -o -name ".gitlab-ci.yml" -o -name "Jenkinsfile" -o -name ".circleci/config.yml" \) 2>/dev/null | head -10`
+
+**Existing documentation:**
+!`find . -maxdepth 2 \( -name "README.md" -o -name "CLAUDE.md" -o -name "CONTRIBUTING.md" \) -not -path "*/node_modules/*" 2>/dev/null | head -10`
+
+Read the manifest files you found above to understand dependencies, scripts, and project structure.
+
+## Phase 2: Clarifying Questions
+
+Based on your analysis, ask the user these questions **ONE AT A TIME**, waiting for each answer before proceeding to the next:
+
+1. **Project description**: "What is the primary purpose of this project?" (e.g., SaaS web app, REST API, CLI tool, shared library)
+2. **Deployment**: "What deployment target does this project use?" (e.g., Vercel, AWS, Docker, bare metal, not yet decided)
+3. **Conventions**: "Are there any team conventions not captured in config files?" (naming patterns, branching strategy, PR process, coding standards)
+4. **Focus areas**: "What areas of the codebase should Claude pay special attention to?" (critical business logic, complex algorithms, areas prone to bugs)
+
+## Phase 3: Generate Documentation
+
+After gathering all answers, generate these files:
+
+### CLAUDE.md
+Create a compact `CLAUDE.md` (under 60 lines) in the project root containing:
+- **Project overview**: One-sentence description including detected stack
+- **Commands**: All detected dev/build/test/lint commands with descriptions
+- **Architecture**: Key directories and their purposes (read the actual directory structure)
+- **Conventions**: @import references to `.claude/rules/code-style.md` and `.claude/rules/testing.md`
+- **Workflow**: @import reference to `.claude/rules/workflow.md`
+- **Memory**: Reference to `_state.md` for session persistence
+- **Rules**: Project-specific rules, including: "NEVER create documentation files (.md) unless the user explicitly requests it"
+
+### _state.md
+Create `_state.md` in the project root for tracking project state across sessions:
+- **Current Focus**: What is being worked on
+- **Key Decisions**: Architecture and design decisions (pre-fill from detected stack)
+- **Known Issues**: Bugs, tech debt, gotchas
+- **Session Notes**: Context to preserve between sessions
+
+### .claude/rules/code-style.md
+Create coding convention rules based on detected linter, formatter, framework, and user-specified conventions. Include YAML frontmatter with path globs to scope the rules.
+
+### .claude/rules/testing.md
+Create testing rules based on detected test framework. Include test commands, file patterns, and best practices. Include YAML frontmatter with path globs.
+
+### .claude/rules/workflow.md
+Create Claude Code workflow best practices including: plan mode usage, /compact and /clear, subagents, memory via _state.md, commit discipline, and the rule to NEVER create .md files unless explicitly asked.
+
+**Present each file to the user for confirmation before writing it.** If the argument `$ARGUMENTS` includes `--force`, write all files without confirmation.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+description: Recommend and configure MCP servers based on project analysis
+allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
+disable-model-invocation: true
+argument-hint: [--force]
+---
+
+# MCP Server Setup
+
+You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
+
+## Step 1: Analyze the Project
+
+Understand what this project uses:
+
+**Read existing documentation:**
+- Read CLAUDE.md if it exists — it contains the tech stack summary
+- Read _state.md if it exists
+
+**Check for existing MCP config:**
+- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
+
+**Scan manifest files:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
+
+**Scan framework and tooling configs:**
+!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files you found. Identify:
+- Programming languages and frameworks
+- Databases (PostgreSQL, MongoDB, Redis, etc.)
+- Cloud services (AWS, GCP, Azure)
+- External APIs (Stripe, Sentry, etc.)
+- Dev tools (Docker, GitHub Actions, etc.)
+
+## Step 2: Search the MCP Registry
+
+Read the MCP server reference for search and evaluation guidance:
+@.claude/skills/doc-generator/templates/mcp-servers.md
+
+For each major technology in the project, search the official MCP Registry API:
+```bash
+curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
+```
+
+For each candidate server with an npm package, verify trust by checking monthly downloads:
+```bash
+curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
+```
+
+Optionally check GitHub stars for additional trust signal:
+```bash
+curl -s 'https://api.github.com/repos/<owner>/<repo>'
+```
+
+**Filtering rules:**
+- Remove servers with <100 monthly npm downloads
+- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
+- When multiple servers exist for the same technology, pick the one with the highest downloads
+
+## Step 3: Present Recommendations
+
+Group your recommendations into three tiers:
+
+**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
+
+**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
+
+**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
+
+For each recommendation, explain:
+- **What it does** and why it's relevant to THIS project
+- **Monthly npm downloads** (trust signal)
+- **Environment variables required** and whether they need secrets
+
+Ask the user which servers to configure.
+
+If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
+
+## Step 4: Generate .mcp.json
+
+Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
+
+**If `.mcp.json` already exists:**
+- Read it and parse the existing `mcpServers` entries
+- Merge new servers into the existing config — do NOT remove or overwrite existing entries
+- If a server key already exists, skip it (preserve the user's existing config)
+
+**Key rules:**
+- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
+- Non-secret env vars can use literal values when appropriate
+- Use `npx -y <package>@latest` for stdio/npm servers
+- Use the `type` and `url` from remotes for HTTP/SSE servers
+
+Write the `.mcp.json` file.
+
+## Step 5: Update CLAUDE.md
+
+If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
+
+If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
+
+## Step 6: Environment Variables
+
+List all required environment variables and how to configure them:
+
+```
+To configure secrets, run:
+  claude config set env.VAR_NAME "your-value"
+
+Required environment variables:
+  VAR_NAME — Description of what this is and where to get it
+```
+
+Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/commands/update-docs.md

@@ -0,0 +1,50 @@
+---
+description: Refresh project documentation from current state
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(diff:*)
+disable-model-invocation: true
+---
+
+# Update Project Documentation
+
+You are updating the existing Claude Code documentation for this project.
+
+## Step 1: Read Current Documentation
+
+Read the existing documentation files:
+- @CLAUDE.md
+- Read any files referenced by @imports in CLAUDE.md
+
+## Step 2: Scan Current State
+
+Detect the current tech stack:
+
+**Package managers:**
+!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+**Framework configs:**
+!`find . -maxdepth 2 \( -name "tsconfig.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "manage.py" -o -name "docker-compose.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
+
+Read the manifest files to check for new dependencies, scripts, or configuration changes since the documentation was last generated.
+
+## Step 3: Identify Changes
+
+Compare the current state against the existing documentation:
+- **New dependencies or tools** not mentioned in CLAUDE.md
+- **Changed scripts** (renamed, added, or removed)
+- **New directories** not covered in Architecture section
+- **Stale references** to files or directories that no longer exist
+- **Missing conventions** based on new config files (e.g., new linter added)
+- **Missing or outdated `.mcp.json`** — if `.mcp.json` doesn't exist, or if new technologies have been added that could benefit from MCP servers, suggest running `/setup-mcp`
+
+## Step 4: Propose Updates
+
+Present a **diff-style summary** of proposed changes to each documentation file. For each change:
+- Show what currently exists
+- Show what should be updated
+- Explain why the change is needed
+
+Wait for user approval before writing any changes.
+
+## Step 5: Apply Updates
+
+After user approval, update the documentation files. Preserve any user-written content that was manually added — only update sections that correspond to detected/generated content.