claudenv 1.0.1 → 1.0.2

package/README.md

@@ -1,103 +1,77 @@
 # claudenv
 
-One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) documentation for any project.
+One command to set up [Claude Code](https://docs.anthropic.com/en/docs/claude-code) in any project. Claude AI analyzes your codebase and generates all the documentation it needs to work effectively.
 
-## Installation
-
-Run directly without installing — pick your package manager:
+## Quick Start
 
 ```bash
-npx claudenv          # npm
-pnpm dlx claudenv     # pnpm
-bunx claudenv         # bun
-yarn dlx claudenv     # yarn
+npm i -g claudenv && claudenv
 ```
 
-Or install globally:
+Done. Open Claude Code in any project and type `/claudenv`.
 
-```bash
-npm i -g claudenv
-```
+## How It Works
 
-## Quick start
+**One-time setup** — install and activate:
 
 ```bash
-cd your-project
-npx claudenv
+npm i -g claudenv && claudenv
 ```
 
-Scans your project, detects the tech stack, asks a few questions, and generates everything Claude Code needs to understand your codebase.
+This installs the `/claudenv` command globally into `~/.claude/`, making it available in every project.
 
-Skip the questions with `-y`:
+**In any project** — open Claude Code and type `/claudenv`.
 
-```bash
-npx claudenv -y
-```
-
-## Usage in Claude Code
+Claude AI will:
+1. Read your manifest files, configs, and source code
+2. Detect your tech stack, frameworks, and tooling
+3. Ask you about the project (description, deployment, conventions)
+4. Generate all documentation files
+5. Install slash commands for ongoing maintenance
 
-### Option A: Global install + shell command
+**Step 3.** You now have three commands available in Claude Code:
 
-```bash
-npm i -g claudenv
-# Then inside Claude Code, just run:
-claudenv
-```
-
-### Option B: Slash command (auto-installed)
-
-After running `claudenv` in your project, the `.claude/commands/init-docs.md` file is created. This gives you the `/init-docs` slash command inside Claude Code, which does the same thing — analyzes the project and generates documentation.
+| Command | What it does |
+|---------|-------------|
+| `/init-docs` | Regenerate documentation from scratch |
+| `/update-docs` | Scan for changes and propose updates |
+| `/validate-docs` | Check that documentation is complete and correct |
 
-## What gets generated
+## What Gets Generated
 
 ```
 your-project/
-├── CLAUDE.md                          # Project overview, commands, architecture
-├── _state.md                          # Track decisions and context across sessions
-├── .claude/
-│   ├── rules/
-│   │   ├── code-style.md              # Coding conventions (scoped by file paths)
-│   │   ├── testing.md                 # Testing patterns and commands
-│   │   └── workflow.md                # Claude Code best practices
-│   ├── settings.json                  # Validation hooks
-│   ├── commands/
-│   │   ├── init-docs.md               # /init-docs — regenerate docs interactively
-│   │   ├── update-docs.md             # /update-docs — refresh from current state
-│   │   └── validate-docs.md           # /validate-docs — check docs are correct
-│   ├── skills/
-│   │   └── doc-generator/             # Auto-invoked when docs need updating
-│   │       ├── SKILL.md
-│   │       ├── scripts/validate.sh
-│   │       └── templates/detection-patterns.md
-│   └── agents/
-│       └── doc-analyzer.md            # Read-only analysis subagent
+├── CLAUDE.md                              # Project overview, commands, architecture
+├── _state.md                              # Session memory (decisions, focus, issues)
+└── .claude/
+    ├── rules/
+    │   ├── code-style.md                  # Coding conventions (scoped by file paths)
+    │   ├── testing.md                     # Test patterns and commands
+    │   └── workflow.md                    # Claude Code best practices
+    ├── settings.json                      # Validation hooks
+    ├── commands/
+    │   ├── init-docs.md                   # /init-docs
+    │   ├── update-docs.md                 # /update-docs
+    │   └── validate-docs.md              # /validate-docs
+    ├── skills/
+    │   └── doc-generator/                 # Auto-triggers when docs need updating
+    └── agents/
+        └── doc-analyzer.md                # Read-only analysis subagent
 ```
 
-### Key files
+### Key Files
 
 | File | Purpose |
 |------|---------|
-| `CLAUDE.md` | Compact project overview (< 60 lines) with `@import` references to rule files |
-| `_state.md` | Tracks current focus, key decisions, known issues — persists context between sessions |
-| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, `/clear`, subagents, git discipline |
+| `CLAUDE.md` | Compact project overview with `@import` references to rule files |
+| `_state.md` | Persists context between sessions — current focus, decisions, known issues |
+| `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, subagents, git discipline |
 | `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
 | `.claude/rules/testing.md` | Test framework patterns and commands |
 
-## After setup
+## Tech Stack Detection
 
-Inside Claude Code, you get three slash commands:
-
-| Command | What it does |
-|---------|-------------|
-| `/init-docs` | Re-run interactive documentation setup |
-| `/update-docs` | Scan for changes and propose doc updates |
-| `/validate-docs` | Check that documentation is complete and correct |
-
-The `doc-generator` skill auto-triggers when Claude detects your docs are outdated.
-
-## What it detects
-
-**10+ languages** and **25+ frameworks** out of the box:
+Claude AI reads your actual code, but the following are auto-detected for context:
 
 - **Languages**: TypeScript, JavaScript, Python, Go, Rust, Ruby, PHP, Java, Kotlin, C#
 - **Frameworks**: Next.js, Vite, Nuxt, SvelteKit, Astro, Angular, Django, FastAPI, Flask, Rails, Laravel, Spring Boot, and more
@@ -106,51 +80,39 @@ The `doc-generator` skill auto-triggers when Claude detects your docs are outdat
 - **CI/CD**: GitHub Actions, GitLab CI, Jenkins, CircleCI
 - **Linters/formatters**: ESLint, Biome, Prettier, Ruff, RuboCop, golangci-lint, Clippy
 
-## CLI reference
+## CLI Reference
 
 ```
-Usage: claudenv [dir] [options]
-
-Options:
-  -y, --yes        Skip prompts, use auto-detected defaults
-  --overwrite      Overwrite existing files
-  -V, --version    Show version
-  -h, --help       Show help
-
-Commands:
-  init [dir]       Interactive setup (default when no command given)
-  generate         Non-interactive generation (templates only)
-  validate         Check documentation completeness
+claudenv                Install /claudenv into ~/.claude/ (default)
+claudenv install        Same as above (explicit)
+claudenv install -f     Reinstall, overwriting existing files
+claudenv uninstall      Remove /claudenv from ~/.claude/
+claudenv init [dir]     Legacy: static analysis + terminal prompts (no AI)
+claudenv init -y        Legacy: skip prompts, auto-detect everything
+claudenv generate       Templates only, no scaffold
+claudenv validate       Check documentation completeness
 ```
 
-## Install from source
+## Alternative: Run Without Installing
 
 ```bash
-git clone https://github.com/AGoldian/claudenv.git
-cd claudenv
-npm install
-npm link
-
-# Then in any project:
-claudenv
+npx claudenv            # npm
+pnpm dlx claudenv       # pnpm
+bunx claudenv           # bun
 ```
 
-## Programmatic API
-
-```javascript
-import { detectTechStack, generateDocs, writeDocs, installScaffold } from 'claudenv';
+## Uninstall
 
-const detected = await detectTechStack('/path/to/project');
-const { files } = await generateDocs('/path/to/project', {
-  ...detected,
-  projectDescription: 'My awesome project',
-  generateRules: true,
-  generateHooks: true,
-});
-await writeDocs('/path/to/project', files);
-await installScaffold('/path/to/project');
+```bash
+claudenv uninstall      # Remove from ~/.claude/
+npm uninstall -g claudenv
 ```
 
+## Requirements
+
+- Node.js >= 20
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+
 ## License
 
 MIT

package/bin/cli.js

@@ -9,6 +9,7 @@ import { detectTechStack } from '../src/detector.js';
 import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
 import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
 import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
+import { installGlobal, uninstallGlobal } from '../src/installer.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -20,17 +21,28 @@ program
   .description('One command to set up Claude Code documentation for any project')
   .version(pkgJson.version);
 
-// --- Default action: running without subcommand triggers init ---
+// --- Default action: install global Claude Code command ---
 program
-  .argument('[dir]', 'Project directory', '.')
-  .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
-  .option('--overwrite', 'Overwrite existing files')
-  .action(runInit);
+  .option('-f, --force', 'Overwrite existing files')
+  .action(runInstall);
 
-// --- init (explicit subcommand, same logic) ---
+// --- install (explicit subcommand, same logic) ---
+program
+  .command('install')
+  .description('Install /claudenv command globally into ~/.claude/')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(runInstall);
+
+// --- uninstall ---
+program
+  .command('uninstall')
+  .description('Remove /claudenv command from ~/.claude/')
+  .action(runUninstall);
+
+// --- init (legacy static flow for backward compatibility) ---
 program
   .command('init')
-  .description('Interactive setup — detect stack, ask questions, generate docs')
+  .description('Legacy: static analysis + interactive setup (no Claude AI)')
   .argument('[dir]', 'Project directory', '.')
   .option('-y, --yes', 'Skip prompts, use auto-detected defaults')
   .option('--overwrite', 'Overwrite existing files')
@@ -102,7 +114,56 @@ program
   });
 
 // =============================================
-// Main init logic
+// Install / Uninstall
+// =============================================
+async function runInstall(opts) {
+  console.log(`\n  claudenv v${pkgJson.version}\n`);
+  console.log('  Installing Claude Code integration...\n');
+
+  const force = opts.force || false;
+  const { written, skipped } = await installGlobal({ force });
+
+  if (written.length > 0) {
+    console.log(`  Installed ${written.length} file(s) to ~/.claude/:\n`);
+    for (const f of written) console.log(`    + ${f}`);
+  }
+
+  if (skipped.length > 0) {
+    console.log(`\n  Skipped ${skipped.length} existing file(s) (use --force to overwrite):\n`);
+    for (const f of skipped) console.log(`    ~ ${f}`);
+  }
+
+  if (written.length === 0 && skipped.length > 0) {
+    console.log('\n  Already installed. Use --force to reinstall.');
+  }
+
+  console.log(`
+  Done! Now open Claude Code in any project and type:
+
+    /claudenv
+
+  Claude will analyze your project and generate documentation.
+`);
+}
+
+async function runUninstall() {
+  console.log(`\n  claudenv v${pkgJson.version}\n`);
+  console.log('  Removing Claude Code integration...\n');
+
+  const { removed } = await uninstallGlobal();
+
+  if (removed.length > 0) {
+    console.log(`  Removed ${removed.length} item(s) from ~/.claude/:\n`);
+    for (const f of removed) console.log(`    - ${f}`);
+  } else {
+    console.log('  Nothing to remove — not installed.');
+  }
+
+  console.log();
+}
+
+// =============================================
+// Legacy init logic
 // =============================================
 async function runInit(dirArg, opts) {
   // Commander passes (dir, opts) for arguments, or (opts) for options-only

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claudenv",
-  "version": "1.0.1",
-  "description": "One command to set up Claude Code documentation for any project — detects tech stack, generates CLAUDE.md, rules, hooks, commands, and skills",
+  "version": "1.0.2",
+  "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {
     "claudenv": "./bin/cli.js"
@@ -23,17 +23,17 @@
     "prepublishOnly": "vitest run"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
-    "@inquirer/prompts": "^7.0.0",
-    "commander": "^13.0.0",
-    "ejs": "^3.1.10",
-    "glob": "^11.0.0",
+    "@inquirer/prompts": "^8.0.0",
+    "commander": "^14.0.0",
+    "ejs": "^4.0.0",
+    "glob": "^13.0.0",
     "smol-toml": "^1.3.0"
   },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "vitest": "^4.0.0"
   },
   "keywords": [
     "claude",

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

@@ -0,0 +1,150 @@
+---
+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:*)
+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/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: Validate
+
+Run the validation script:
+```bash
+bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true
+```
+
+Fix any errors found.
+
+## Phase 6: 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/skills/doc-generator/
+  + .claude/agents/doc-analyzer.md
+
+Available commands:
+  /init-docs      — Regenerate documentation from scratch
+  /update-docs    — Update docs when project changes
+  /validate-docs  — Check documentation completeness
+
+Next steps:
+  1. Review and edit CLAUDE.md
+  2. git add .claude/ CLAUDE.md _state.md && git commit -m "Add Claude Code docs"
+```

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

@@ -0,0 +1,49 @@
+---
+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
+- User mentions "documentation", "CLAUDE.md", "project setup", or "claudenv"
+- 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`.
+
+### 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
+
+## 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/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/update-docs.md

@@ -0,0 +1,49 @@
+---
+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)
+
+## 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.

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

@@ -0,0 +1,40 @@
+---
+description: Validate project documentation for completeness and correctness
+allowed-tools: Read, Glob, Grep, Bash(bash:*)
+disable-model-invocation: true
+---
+
+# Validate Project Documentation
+
+Run validation checks on the project's Claude Code documentation.
+
+## Step 1: Run Bash Validation
+
+Execute the validation script:
+!`bash .claude/skills/doc-generator/scripts/validate.sh 2>&1 || true`
+
+## Step 2: Deep Validation
+
+Perform additional checks that require reading file contents:
+
+1. **Read CLAUDE.md** and verify:
+   - All `@import` references resolve to existing files
+   - Commands in the ## Commands section match actual scripts in package.json / pyproject.toml / Makefile
+   - Directories in ## Architecture section actually exist
+
+2. **Read .claude/rules/*.md** files and verify:
+   - YAML frontmatter `paths` globs match files that exist in the project
+   - Referenced tools (linters, formatters, test frameworks) are actually installed
+
+3. **Read .claude/settings.json** and verify:
+   - Valid JSON structure
+   - Referenced hook scripts exist at the specified paths
+
+## Step 3: Report
+
+Present a clear summary:
+- List all **errors** (things that must be fixed)
+- List all **warnings** (things that should be reviewed)
+- Provide a **pass/fail** verdict
+
+If there are errors, suggest specific fixes for each one.

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: doc-generator
+description: Generates and updates project documentation including CLAUDE.md, rules, and hooks. Use when the user asks about documentation, project setup, CLAUDE.md, or when detecting that documentation is missing or outdated.
+allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
+---
+
+# Documentation Generator Skill
+
+## When to use
+- User mentions documentation, CLAUDE.md, or project setup
+- User asks to configure Claude Code for their project
+- New files detected that change the tech stack (new framework, test runner, etc.)
+- After major refactoring that changes directory structure
+- When CLAUDE.md references files or directories that no longer exist
+
+## Process
+
+### 1. Detect Tech Stack
+Scan the project root for manifest files, framework configs, and tooling:
+
+@.claude/skills/doc-generator/templates/detection-patterns.md
+
+### 2. Cross-Reference Existing Documentation
+If CLAUDE.md already exists, read it and identify:
+- Outdated commands or directory references
+- Missing entries for new tools/dependencies
+- Stale @imports pointing to removed files
+
+### 3. Generate or Update
+- For new documentation: generate CLAUDE.md, _state.md, .claude/rules/code-style.md, .claude/rules/testing.md, .claude/rules/workflow.md
+- For updates: propose specific changes and wait for user approval
+- Always present generated content for review before writing
+- NEVER create .md files beyond the ones listed above unless the user explicitly asks
+
+### 4. Validate
+After writing, run the validation script:
+```
+bash .claude/skills/doc-generator/scripts/validate.sh
+```
+
+Fix any errors before completing.
+
+## Output Format
+Generated CLAUDE.md should follow this structure:
+- `# CLAUDE.md` heading
+- `## Project overview` — one-sentence description with stack
+- `## Commands` — all dev/build/test/lint commands
+- `## Architecture` — key directories with descriptions
+- `## Conventions` — @imports to code-style.md and testing.md
+- `## Workflow` — @import to workflow.md (Claude Code best practices)
+- `## Memory` — reference to _state.md for session persistence
+- `## Rules` — project-specific rules as bullet points
+
+Additionally generate:
+- `_state.md` — project state tracking (decisions, focus, known issues)
+- `.claude/rules/workflow.md` — Claude Code workflow best practices

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/scripts/validate.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Documentation validation script for Claude Code hooks.
+# Exit 0 = success, Exit 2 = block action (sends stderr to Claude).
+# POSIX-compatible for macOS and Linux.
+set -euo pipefail
+
+ERRORS=0
+WARNINGS=0
+
+error() {
+  echo "ERROR: $1" >&2
+  ERRORS=$((ERRORS + 1))
+}
+
+warn() {
+  echo "WARN: $1" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ok() {
+  echo "OK: $1"
+}
+
+# --- Required files ---
+
+if [ -f "CLAUDE.md" ] && [ -s "CLAUDE.md" ]; then
+  ok "CLAUDE.md exists and is non-empty"
+else
+  error "CLAUDE.md is missing or empty"
+fi
+
+# --- Required sections in CLAUDE.md ---
+
+if [ -f "CLAUDE.md" ]; then
+  for section in "## Commands" "## Architecture"; do
+    if grep -q "^${section}" CLAUDE.md 2>/dev/null; then
+      ok "CLAUDE.md has ${section}"
+    else
+      error "CLAUDE.md is missing required section: ${section}"
+    fi
+  done
+
+  # Check that ## Commands has at least one backtick-quoted command
+  # Use awk instead of head -n -1 for macOS compatibility
+  COMMANDS_SECTION=$(sed -n '/^## Commands/,/^## /p' CLAUDE.md | awk 'NR>1{print prev} {prev=$0}')
+  if echo "$COMMANDS_SECTION" | grep -q '`'; then
+    ok "## Commands section contains command examples"
+  else
+    warn "## Commands section has no inline code examples"
+  fi
+
+  # Check @import references
+  while IFS= read -r line; do
+    # Skip lines inside code blocks
+    case "$line" in
+      '```'*) continue ;;
+    esac
+    # Match bare @path lines (not emails, not inline)
+    if echo "$line" | grep -qE '^@[^@[:space:]]+$'; then
+      IMPORT_PATH=$(echo "$line" | sed 's/^@//')
+      # Resolve ~ to HOME
+      case "$IMPORT_PATH" in
+        '~/'*) IMPORT_PATH="${HOME}/${IMPORT_PATH#\~/}" ;;
+      esac
+      if [ -f "$IMPORT_PATH" ]; then
+        ok "@import ${IMPORT_PATH} resolves"
+      else
+        error "@import reference '${IMPORT_PATH}' does not resolve to a file"
+      fi
+    fi
+  done < CLAUDE.md
+fi
+
+# --- Optional structure checks ---
+
+if [ -d ".claude" ]; then
+  ok ".claude/ directory exists"
+else
+  warn ".claude/ directory not found"
+fi
+
+if [ -f ".claude/settings.json" ]; then
+  # Validate JSON syntax (requires python or node)
+  if command -v node >/dev/null 2>&1; then
+    if node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json','utf-8'))" 2>/dev/null; then
+      ok ".claude/settings.json is valid JSON"
+    else
+      error ".claude/settings.json is not valid JSON"
+    fi
+  elif command -v python3 >/dev/null 2>&1; then
+    if python3 -c "import json; json.load(open('.claude/settings.json'))" 2>/dev/null; then
+      ok ".claude/settings.json is valid JSON"
+    else
+      error ".claude/settings.json is not valid JSON"
+    fi
+  fi
+fi
+
+# --- Summary ---
+
+echo ""
+echo "Validation complete: ${ERRORS} error(s), ${WARNINGS} warning(s)"
+
+if [ "$ERRORS" -gt 0 ]; then
+  exit 2
+fi
+
+exit 0

package/scaffold/global/.claude/skills/claudenv/scaffold/.claude/skills/doc-generator/templates/detection-patterns.md

@@ -0,0 +1,76 @@
+# Tech Stack Detection Patterns
+
+Use these patterns to identify the project's tech stack by scanning for files.
+
+## Language / Runtime Detection (check manifest files first)
+
+| File | Language | Runtime |
+|------|----------|---------|
+| `package.json` | JavaScript/TypeScript | Node.js |
+| `pyproject.toml`, `setup.py`, `requirements.txt` | Python | Python |
+| `go.mod` | Go | Go |
+| `Cargo.toml` | Rust | Rust |
+| `Gemfile` | Ruby | Ruby |
+| `composer.json` | PHP | PHP |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java/Kotlin | JVM |
+| `*.csproj`, `*.sln` | C# | .NET |
+
+**TypeScript override**: If `tsconfig.json` exists alongside `package.json`, the language is TypeScript.
+
+## Framework Detection (check config files)
+
+| File | Framework |
+|------|-----------|
+| `next.config.js/mjs/ts` | Next.js |
+| `nuxt.config.ts/js` | Nuxt |
+| `vite.config.js/ts/mts` | Vite |
+| `svelte.config.js` | SvelteKit |
+| `astro.config.mjs/ts` | Astro |
+| `angular.json` | Angular |
+| `manage.py` | Django |
+| `config/routes.rb` | Rails |
+| `artisan` | Laravel |
+| `application.properties/yml` | Spring Boot |
+
+## Package Manager Detection (check lockfiles)
+
+| File | Package Manager |
+|------|----------------|
+| `package-lock.json` | npm |
+| `yarn.lock` | Yarn |
+| `pnpm-lock.yaml` | pnpm |
+| `bun.lockb`, `bun.lock` | Bun |
+| `poetry.lock` | Poetry |
+| `Pipfile.lock` | Pipenv |
+| `uv.lock` | uv |
+
+## Test Framework Detection
+
+| File | Framework |
+|------|-----------|
+| `vitest.config.*` | Vitest |
+| `jest.config.*` | Jest |
+| `playwright.config.*` | Playwright |
+| `cypress.config.*` | Cypress |
+| `pytest.ini`, `conftest.py` | pytest |
+| `.rspec` | RSpec |
+
+Also check dependencies in `package.json` or `pyproject.toml`.
+
+## CI/CD Detection
+
+| Path | System |
+|------|--------|
+| `.github/workflows/*.yml` | GitHub Actions |
+| `.gitlab-ci.yml` | GitLab CI |
+| `Jenkinsfile` | Jenkins |
+| `.circleci/config.yml` | CircleCI |
+
+## Monorepo Detection
+
+| File | Tool |
+|------|------|
+| `turbo.json` | Turborepo |
+| `nx.json` | Nx |
+| `lerna.json` | Lerna |
+| `pnpm-workspace.yaml` | pnpm workspaces |

package/scaffold/global/.claude/skills/claudenv/templates/detection-patterns.md

@@ -0,0 +1,76 @@
+# Tech Stack Detection Patterns
+
+Use these patterns to identify the project's tech stack by scanning for files.
+
+## Language / Runtime Detection (check manifest files first)
+
+| File | Language | Runtime |
+|------|----------|---------|
+| `package.json` | JavaScript/TypeScript | Node.js |
+| `pyproject.toml`, `setup.py`, `requirements.txt` | Python | Python |
+| `go.mod` | Go | Go |
+| `Cargo.toml` | Rust | Rust |
+| `Gemfile` | Ruby | Ruby |
+| `composer.json` | PHP | PHP |
+| `pom.xml`, `build.gradle`, `build.gradle.kts` | Java/Kotlin | JVM |
+| `*.csproj`, `*.sln` | C# | .NET |
+
+**TypeScript override**: If `tsconfig.json` exists alongside `package.json`, the language is TypeScript.
+
+## Framework Detection (check config files)
+
+| File | Framework |
+|------|-----------|
+| `next.config.js/mjs/ts` | Next.js |
+| `nuxt.config.ts/js` | Nuxt |
+| `vite.config.js/ts/mts` | Vite |
+| `svelte.config.js` | SvelteKit |
+| `astro.config.mjs/ts` | Astro |
+| `angular.json` | Angular |
+| `manage.py` | Django |
+| `config/routes.rb` | Rails |
+| `artisan` | Laravel |
+| `application.properties/yml` | Spring Boot |
+
+## Package Manager Detection (check lockfiles)
+
+| File | Package Manager |
+|------|----------------|
+| `package-lock.json` | npm |
+| `yarn.lock` | Yarn |
+| `pnpm-lock.yaml` | pnpm |
+| `bun.lockb`, `bun.lock` | Bun |
+| `poetry.lock` | Poetry |
+| `Pipfile.lock` | Pipenv |
+| `uv.lock` | uv |
+
+## Test Framework Detection
+
+| File | Framework |
+|------|-----------|
+| `vitest.config.*` | Vitest |
+| `jest.config.*` | Jest |
+| `playwright.config.*` | Playwright |
+| `cypress.config.*` | Cypress |
+| `pytest.ini`, `conftest.py` | pytest |
+| `.rspec` | RSpec |
+
+Also check dependencies in `package.json` or `pyproject.toml`.
+
+## CI/CD Detection
+
+| Path | System |
+|------|--------|
+| `.github/workflows/*.yml` | GitHub Actions |
+| `.gitlab-ci.yml` | GitLab CI |
+| `Jenkinsfile` | Jenkins |
+| `.circleci/config.yml` | CircleCI |
+
+## Monorepo Detection
+
+| File | Tool |
+|------|------|
+| `turbo.json` | Turborepo |
+| `nx.json` | Nx |
+| `lerna.json` | Lerna |
+| `pnpm-workspace.yaml` | pnpm workspaces |

package/src/installer.js

@@ -0,0 +1,109 @@
+import { mkdir, cp, rm, readdir, stat } from 'node:fs/promises';
+import { join, dirname, relative } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLD_GLOBAL = join(__dirname, '..', 'scaffold', 'global');
+
+/**
+ * Get the path to ~/.claude/
+ */
+function getClaudeHome() {
+  return join(homedir(), '.claude');
+}
+
+/**
+ * Recursively list all files in a directory (relative paths).
+ */
+async function listFiles(dir, base = dir) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listFiles(full, base));
+    } else {
+      files.push(relative(base, full));
+    }
+  }
+  return files;
+}
+
+/**
+ * Install global Claude Code artifacts to ~/.claude/.
+ * Copies scaffold/global/.claude/ contents into ~/.claude/.
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.force] - Overwrite existing files
+ * @param {string} [options.claudeHome] - Override ~/.claude/ path (for testing)
+ * @returns {Promise<{written: string[], skipped: string[]}>}
+ */
+export async function installGlobal(options = {}) {
+  const { force = false, claudeHome } = options;
+  const targetBase = claudeHome || getClaudeHome();
+  const sourceBase = join(SCAFFOLD_GLOBAL, '.claude');
+
+  const files = await listFiles(sourceBase);
+  const written = [];
+  const skipped = [];
+
+  for (const relPath of files) {
+    const src = join(sourceBase, relPath);
+    const dest = join(targetBase, relPath);
+
+    // Check if file exists and skip unless force
+    if (!force) {
+      try {
+        await stat(dest);
+        skipped.push(relPath);
+        continue;
+      } catch {
+        // File doesn't exist — proceed
+      }
+    }
+
+    await mkdir(dirname(dest), { recursive: true });
+    await cp(src, dest);
+
+    // Make .sh files executable
+    if (relPath.endsWith('.sh')) {
+      const { chmod } = await import('node:fs/promises');
+      await chmod(dest, 0o755);
+    }
+
+    written.push(relPath);
+  }
+
+  return { written, skipped };
+}
+
+/**
+ * Remove global Claude Code artifacts from ~/.claude/.
+ *
+ * @param {object} [options]
+ * @param {string} [options.claudeHome] - Override ~/.claude/ path (for testing)
+ * @returns {Promise<{removed: string[]}>}
+ */
+export async function uninstallGlobal(options = {}) {
+  const { claudeHome } = options;
+  const targetBase = claudeHome || getClaudeHome();
+  const removed = [];
+
+  const targets = [
+    join(targetBase, 'commands', 'claudenv.md'),
+    join(targetBase, 'skills', 'claudenv'),
+  ];
+
+  for (const target of targets) {
+    try {
+      await stat(target);
+      await rm(target, { recursive: true });
+      removed.push(relative(targetBase, target));
+    } catch {
+      // Doesn't exist — skip
+    }
+  }
+
+  return { removed };
+}