@arthai/agents 1.0.0

package/dist/plugins/spark/skills/calibrate/SKILL.md

@@ -0,0 +1,1807 @@
+---
+name: calibrate
+description: "Deep-learn a project and configure the full toolkit — scans code patterns, recommends MCP servers/agents/skills/workflows, installs everything. The single entry point for project adaptation. Usage: /calibrate <full|rescan|recommend|status>"
+user-invocable: true
+arguments: "<full|rescan|recommend|status>"
+---
+
+# /calibrate — Project Learning & Toolkit Adaptation
+
+The single entry point that makes the toolkit deeply understand a new project and configures
+everything to fit. Goes far beyond `/scan` — reads actual source code to learn architecture
+patterns, coding conventions, domain language, and testing style. Then recommends and installs
+the exact MCP servers, agents, skills, and workflows the project needs.
+
+**This is what makes the toolkit feel alive for a new project.**
+
+## When to Use
+
+- **First time**: New user installs the toolkit on their project → run `/calibrate`
+- **Rescan**: Project has evolved significantly → run `/calibrate rescan`
+- **After major changes**: New framework, new service, new team member → `/calibrate rescan`
+
+## Argument Parsing
+
+| Input | Action |
+|-------|--------|
+| `/calibrate` | Full calibration if never run; **auto-rescan** if already calibrated |
+| `/calibrate full` | Force full calibration even if already calibrated |
+| `/calibrate rescan` | Explicit rescan — update project-profile.md, show what changed |
+| `/calibrate recommend` | Show recommendations without installing (read-only) |
+| `/calibrate status` | Show current calibration state — what's installed, what's stale |
+
+## Execution Steps
+
+### Phase 0: Prior Calibration Detection (MANDATORY — runs before anything else)
+
+Before starting ANY work, check if this project has already been calibrated:
+
+```bash
+# Check for existing calibration
+test -f "$CLAUDE_PROJECT_DIR/.claude/project-profile.md"
+```
+
+**If `project-profile.md` EXISTS and user ran `/calibrate` (no argument):**
+
+1. Read the first 5 lines of `project-profile.md` to get the calibration date
+2. Tell the user:
+   ```
+   This project was already calibrated on {date}.
+
+   Running /calibrate rescan to update — not a full re-calibration.
+   To force a full re-calibration, run: /calibrate full
+   ```
+3. **Automatically switch to rescan mode** — jump to the "## `/calibrate rescan`" section below. Do NOT run the full Phase 1-6 pipeline.
+
+**If `project-profile.md` DOES NOT exist:**
+- Proceed with full calibration (Phase 1 below)
+
+**If user explicitly ran `/calibrate full`:**
+- Proceed with full calibration even if profile exists (user wants a clean re-do)
+
+| Input | project-profile.md exists? | Action |
+|-------|---------------------------|--------|
+| `/calibrate` | No | Full calibration (Phase 1-6) |
+| `/calibrate` | Yes | **Auto-switch to rescan** |
+| `/calibrate full` | Either | Force full calibration |
+| `/calibrate rescan` | Either | Rescan (diff + update) |
+| `/calibrate recommend` | Either | Read-only recommendations |
+| `/calibrate status` | Either | Show calibration health |
+
+### Phase 1: Deep Project Scan
+
+This goes far deeper than `/scan`. Read **actual source code** to understand HOW the team builds, not just WHAT tools they use.
+
+#### Step 1.1: Foundation Scan
+
+Run `/scan` first if CLAUDE.md has `<!-- TODO -->` placeholders or doesn't exist. This populates
+the basics (tech stack, services, test commands, infrastructure). Then proceed to deep scan.
+
+#### Step 1.2: Architecture Pattern Analysis
+
+Read 8-12 key source files to understand the project's architecture:
+
+#### Step 1.2a: Platform Detection (FIRST — determines everything else)
+
+Before reading source code, detect what KIND of project this is. The toolkit must handle
+ANY platform, not just web apps.
+
+**Platform detection signals:**
+
+| Signal Files | Platform | Category |
+|-------------|----------|----------|
+| `*.xcodeproj/`, `*.xcworkspace/`, `Package.swift` | **iOS / macOS (Swift)** | Mobile/Desktop native |
+| `*.swift` files + `Info.plist` | **iOS / macOS (Swift)** | Mobile/Desktop native |
+| `Podfile`, `Cartfile` | **iOS (CocoaPods/Carthage)** | Mobile native |
+| `android/`, `build.gradle`, `build.gradle.kts` | **Android (Kotlin/Java)** | Mobile native |
+| `AndroidManifest.xml` | **Android** | Mobile native |
+| `pubspec.yaml` + `lib/` + `*.dart` | **Flutter** | Mobile cross-platform |
+| `react-native.config.js`, `metro.config.js` | **React Native** | Mobile cross-platform |
+| `ios/` + `android/` + `package.json` | **React Native / Expo** | Mobile cross-platform |
+| `app.json` + `expo` in package.json | **Expo (React Native)** | Mobile cross-platform |
+| `*.sln`, `*.csproj` | **.NET / C#** | Desktop/Web/Game |
+| `*.unitypackage`, `Assets/`, `ProjectSettings/` | **Unity (C#)** | Game |
+| `project.godot` | **Godot** | Game |
+| `CMakeLists.txt`, `Makefile` + `*.c`/`*.cpp` | **C/C++** | Systems/Embedded |
+| `platformio.ini` | **Embedded (PlatformIO)** | Embedded |
+| `setup.py`/`pyproject.toml` + no web framework | **Python library/CLI** | Library |
+| `Cargo.toml` + no web framework | **Rust library/CLI** | Library |
+| `package.json` + no web framework | **Node library/CLI** | Library |
+| `*.tf`, `*.tfvars` | **Terraform** | Infrastructure |
+| `helm/`, `Chart.yaml` | **Kubernetes Helm** | Infrastructure |
+| `serverless.yml` | **Serverless** | Cloud functions |
+| `package.json` + `electron` | **Electron** | Desktop cross-platform |
+| `package.json` + `tauri` | **Tauri** | Desktop cross-platform |
+| `*.ipynb` files dominant | **Data Science / ML** | Data/ML |
+| `dvc.yaml`, `mlflow` in requirements | **ML Pipeline** | Data/ML |
+
+**Store the detected platform as `PLATFORM_TYPE`** — this drives which discovery patterns to use below.
+
+#### Step 1.2b: Platform-Specific Discovery
+
+Based on `PLATFORM_TYPE`, use the appropriate discovery sequence:
+
+##### Web Backend/Frontend (existing — FastAPI, Django, Next.js, Go, Rust, etc.)
+
+1. Find entry points:
+   - Python: `main.py`, `app/main.py`, `manage.py`, `wsgi.py`, `asgi.py`
+   - Node: `src/index.ts`, `src/app.ts`, `server.ts`, `pages/_app.tsx`, `app/layout.tsx`
+   - Go: `cmd/*/main.go`, `main.go`
+   - Rust: `src/main.rs`, `src/lib.rs`
+
+2. Find route/API definitions:
+   - FastAPI: files with `@router.` or `@app.` decorators
+   - Django: `urls.py` files, `views.py` files
+   - Express/Hono/Fastify: files with `router.get/post/put/delete`
+   - Next.js: `app/api/*/route.ts` files
+   - Go: files with `http.HandleFunc` or router setup
+   - GraphQL: `schema.graphql`, `*.graphql`, resolvers
+
+3. Find model/entity definitions:
+   - SQLAlchemy: `models/*.py` or `models.py` — classes inheriting `Base`
+   - Django: `*/models.py` — classes inheriting `models.Model`
+   - Prisma: `prisma/schema.prisma`
+   - Drizzle: `drizzle/schema.ts` or `db/schema.ts`
+   - TypeORM: `entities/*.ts`
+   - Go: `models/*.go` or struct definitions
+   - Rust: files with `#[derive(` macros
+
+4. Find service/business logic layer:
+   - `services/*.py`, `services/*.ts`, `internal/service/*.go`
+   - `lib/*.ts`, `utils/*.py`, `helpers/`
+   - Look for the pattern: do files import from models AND get imported by routes?
+
+5. Find middleware/auth:
+   - `middleware/`, `auth/`, `guards/`, `decorators/`
+   - Files containing `authenticate`, `authorize`, `protect`, `require_auth`
+
+##### iOS / macOS (Swift/Objective-C)
+
+1. Find entry points:
+   - `*App.swift` (SwiftUI app lifecycle) or `AppDelegate.swift` (UIKit lifecycle)
+   - `SceneDelegate.swift` (UIKit scene-based)
+   - `ContentView.swift` (SwiftUI root view)
+   - `main.swift` or `@main` attribute
+
+2. Find UI layer:
+   - **SwiftUI**: files with `import SwiftUI`, `struct *View: View`, `@State`, `@Binding`, `@Observable`
+   - **UIKit**: files with `import UIKit`, `class *ViewController: UIViewController`, storyboards (`.storyboard`)
+   - **Navigation**: `NavigationStack`, `NavigationView`, `UINavigationController`, coordinators
+   - **Design system**: shared styles, color assets (`Assets.xcassets`), custom components
+
+3. Find data layer:
+   - **Core Data**: `*.xcdatamodeld`, `NSManagedObject` subclasses, `@FetchRequest`
+   - **SwiftData**: `@Model` macro, `ModelContainer`, `ModelContext`
+   - **Realm**: `import RealmSwift`, `Object` subclasses
+   - **Network layer**: `URLSession` wrappers, Alamofire/Moya usage, API client classes
+   - **Combine/async**: `Publishers`, `async/await` patterns, `@Published`
+
+4. Find architecture pattern:
+   - **MVVM**: `*ViewModel` classes/structs, `@ObservableObject`, `@Published`
+   - **MVC**: ViewControllers with direct model access
+   - **TCA (Composable Architecture)**: `Reducer`, `Store`, `Effect`, `import ComposableArchitecture`
+   - **VIPER**: `*Router`, `*Interactor`, `*Presenter`, `*Entity`
+   - **Clean Architecture**: `UseCases/`, `Repositories/`, `Entities/`, `Interfaces/`
+
+5. Find dependency management:
+   - `Package.swift` → Swift Package Manager (read dependencies)
+   - `Podfile` → CocoaPods (read pods)
+   - `Cartfile` → Carthage
+   - `.xcodeproj/project.pbxproj` → frameworks, build settings
+
+6. Find testing:
+   - `*Tests/` directory → XCTest
+   - `*UITests/` directory → XCUITest (UI testing)
+   - `@testable import` → which modules are tested
+   - Snapshot tests: `swift-snapshot-testing` in Package.swift
+
+7. Find CI/CD:
+   - `fastlane/` directory → Fastlane for builds/deployment
+   - `.github/workflows/` with `xcodebuild` → GitHub Actions CI
+   - `Gymfile`, `Matchfile`, `Appfile` → Fastlane config
+   - Xcode Cloud configuration
+
+##### Android (Kotlin/Java)
+
+1. Find entry points:
+   - `*Application.kt` or `*Application.java` (Application class)
+   - `MainActivity.kt` (main Activity)
+   - `AndroidManifest.xml` (manifest — registered activities, permissions, services)
+
+2. Find UI layer:
+   - **Jetpack Compose**: `@Composable` functions, `import androidx.compose.*`
+   - **XML layouts**: `res/layout/*.xml`, `res/values/*.xml`
+   - **Navigation**: `NavController`, `NavHost`, `Navigation.xml`
+   - **Fragments**: `*Fragment.kt` files
+
+3. Find architecture pattern:
+   - **MVVM**: `*ViewModel` classes extending `ViewModel()`
+   - **MVI**: `sealed interface *Intent`, `*State` data classes
+   - **Clean Architecture**: `domain/`, `data/`, `presentation/` layers
+   - **Repository pattern**: `*Repository` interfaces + `*RepositoryImpl`
+
+4. Find data layer:
+   - **Room**: `@Entity`, `@Dao`, `@Database` annotations
+   - **Retrofit**: `@GET`, `@POST`, `interface *Api`
+   - **Hilt/Dagger**: `@Inject`, `@Module`, `@Provides`
+   - **DataStore**: `DataStore<Preferences>`, protobuf schemas
+
+5. Find dependency management:
+   - `build.gradle.kts` or `build.gradle` → dependencies block
+   - `libs.versions.toml` → version catalog
+   - `settings.gradle.kts` → module structure
+
+##### Flutter (Dart)
+
+1. Find entry points: `lib/main.dart`, `lib/app.dart`
+2. Find UI layer: `Widget` subclasses, `StatefulWidget`, `StatelessWidget`
+3. Find state management: Riverpod (`@riverpod`), BLoC (`*Bloc`, `*Cubit`), Provider, GetX
+4. Find data layer: `*Repository`, `*DataSource`, `*Model`, Hive/Isar/Drift
+5. Find packages: `pubspec.yaml` dependencies
+
+##### React Native / Expo
+
+1. Find entry points: `App.tsx`, `app/_layout.tsx` (Expo Router), `index.js`
+2. Find navigation: React Navigation (`@react-navigation/*`), Expo Router
+3. Find state: Redux, Zustand, Jotai, React Query
+4. Find native modules: `ios/`, `android/` dirs, `*.podspec`, native bridge files
+5. Find packages: `package.json` dependencies
+
+##### Data Science / ML
+
+1. Find entry points: `*.ipynb` notebooks, `train.py`, `predict.py`, `pipeline.py`
+2. Find models: `models/`, `*.pkl`, `*.pt`, `*.h5`, model configs
+3. Find data pipeline: `data/`, `scripts/`, DVC files, feature engineering
+4. Find experiment tracking: MLflow, Weights & Biases, TensorBoard configs
+5. Find packages: `requirements.txt`, `environment.yml`, `pyproject.toml`
+
+##### Unknown Platform — Adaptive Learning (see Step 1.2c)
+
+If the project doesn't match any known platform, trigger the adaptive learning protocol.
+
+#### Step 1.2c: Adaptive Learning for Unknown Platforms
+
+When `/calibrate` encounters a project it doesn't have built-in patterns for, it MUST
+learn what it needs rather than giving up or forcing web patterns onto a non-web project.
+
+**Adaptive learning protocol:**
+
+1. **Read the codebase structure** — Glob for all file extensions, directory patterns,
+   config files. Build a map of what's there without assuming what it means.
+   ```bash
+   # What languages are in this project?
+   find . -name "*.swift" -o -name "*.kt" -o -name "*.dart" -o -name "*.cs" \
+          -o -name "*.cpp" -o -name "*.rs" -o -name "*.go" -o -name "*.py" \
+          -o -name "*.ts" -o -name "*.js" -o -name "*.java" -o -name "*.rb" \
+     | sed 's/.*\.//' | sort | uniq -c | sort -rn
+
+   # What config files hint at the platform?
+   ls -la *.json *.yaml *.yml *.toml *.xml *.plist *.gradle* *.sln *.csproj 2>/dev/null
+
+   # What does the README say?
+   head -50 README.md
+   ```
+
+2. **Read the project's own documentation** — The project's README, CONTRIBUTING.md,
+   docs/ folder, and comments often explain the architecture and conventions better
+   than any external source.
+
+3. **Search the web for platform patterns** (using WebSearch tool):
+   - Query: "{detected framework} project structure best practices"
+   - Query: "{detected language} {detected framework} architecture patterns"
+   - Query: "{detected framework} testing conventions"
+   - Query: "{detected framework} CI/CD setup"
+
+   **Why web search**: When the toolkit encounters an iPhone app using SwiftUI with TCA
+   (The Composable Architecture), it doesn't know TCA patterns. But it can search for
+   "SwiftUI TCA project structure" and learn the conventions (Reducers, Features, Store).
+
+4. **Query MCP servers for platform knowledge** — If the project has MCP servers configured
+   that might have relevant knowledge (e.g., a Notion wiki about the project's architecture),
+   query them for platform-specific docs.
+
+5. **Read package/dependency manifests deeply** — The dependency list tells you what patterns
+   are in use. Each dependency implies conventions:
+   ```
+   Package.swift contains:
+     - "ComposableArchitecture" → TCA pattern (Reducers, Features, Store)
+     - "swift-snapshot-testing" → snapshot-based UI testing
+     - "Kingfisher" → async image loading
+     - "SwiftLint" → code style enforcement (read .swiftlint.yml for rules)
+
+   build.gradle contains:
+     - "hilt" → dependency injection via Hilt (look for @Inject, @Module)
+     - "room" → local database (look for @Entity, @Dao)
+     - "compose" → Jetpack Compose UI (look for @Composable)
+     - "mockk" → mocking library for tests
+   ```
+
+6. **Synthesize into the standard profile format** — Even for an unknown platform, the
+   output is the same: architecture patterns, coding conventions, testing style, domain model.
+   The categories are universal; only the specifics change.
+
+7. **Generate platform-specific custom agents** — For platforms without built-in agents:
+   ```
+   Detected: iOS app using SwiftUI + TCA + Core Data
+
+   Existing agents that partially apply:
+   - code-reviewer (universal) → ESSENTIAL
+   - architect (universal) → ESSENTIAL
+   - qa (universal) → ESSENTIAL, but needs iOS test knowledge
+   - frontend (React-focused) → NOT relevant for iOS
+
+   Custom agents to generate:
+   - ios-developer.md → SwiftUI/TCA patterns, Core Data, Swift conventions
+   - ios-qa.md → XCTest, XCUITest, snapshot testing, TestFlight
+   - ios-ops.md → Fastlane, Xcode Cloud, App Store Connect, provisioning profiles
+   ```
+
+   When generating custom agents for unknown platforms, the agent definition should include
+   the web-searched best practices so the agent can follow them without searching again.
+
+**What to extract (universal across ALL platforms):**
+
+```
+Architecture:
+- Layering pattern: flat | 2-layer | 3-layer | clean architecture | MVVM | MVC | TCA | VIPER
+- Dependency direction: which modules import which?
+- Shared abstractions: base classes, protocols, generics, shared interfaces
+- Error handling pattern: exceptions | Result types | error codes | throwing functions
+- Auth pattern: where and how is authentication handled?
+- Data access pattern: local DB | network API | both | offline-first
+- Navigation pattern: stack | tab | coordinator | router
+- State management: observable objects | Redux-like | reactive streams
+```
+
+#### Step 1.3: Coding Convention Extraction
+
+Read 5+ source files across different parts of the codebase. For each, note:
+
+```
+File naming:
+- kebab-case.ts | PascalCase.ts | snake_case.py | camelCase.ts
+- Feature-based dirs (user/user.service.ts) | type-based dirs (services/user.ts) | flat
+
+Naming conventions:
+- Variables: camelCase | snake_case | PascalCase
+- Functions/methods: camelCase | snake_case
+- Classes/types: PascalCase | SCREAMING_CASE for constants
+- Private members: _prefix | #private | no convention
+
+Import style:
+- Absolute from root (import { x } from '@/lib/x') | relative (import { x } from '../lib/x')
+- Barrel files (index.ts re-exports) | direct imports
+- Import grouping order: stdlib → external → internal → relative
+- Type imports separate (import type { X }) | mixed
+
+Error handling:
+- Custom error classes (AppError, NotFoundError) | framework errors (HTTPException) | raw Error
+- Try/catch with specific types | catch-all | Result/Either pattern
+- Error response format: { error: string } | { message, code } | { errors: [] }
+
+Logging:
+- Structured (logger.info({ key: val })) | console.log | framework logger | none
+- Log levels used: debug/info/warn/error
+
+Comments/docs:
+- JSDoc/docstrings on public functions | inline comments | none
+- Type annotations: strict (all functions) | partial | none
+```
+
+#### Step 1.4: Testing Pattern Analysis
+
+Find and read 3-5 existing test files:
+
+```bash
+# Look for test files
+# Python: test_*.py, *_test.py, tests/*.py
+# JS/TS: *.test.ts, *.spec.ts, __tests__/*.ts
+# Go: *_test.go
+# Rust: tests/*.rs, #[cfg(test)] modules
+```
+
+Extract:
+```
+Testing style:
+- Test framework: pytest | unittest | Jest | Vitest | Mocha | testing-library | Go testing | cargo test
+- Mock strategy: real DB | in-memory DB | mocks (unittest.mock/jest.mock) | MSW | test containers
+- Fixture strategy: factory functions | factory_boy | fixtures/ dir | beforeEach setup | conftest.py
+- Assertion style: assert x == y | expect(x).toBe(y) | assert.Equal | custom matchers
+- Test naming: test_what_when_then | describe/it blocks | test('should...') | TestFunctionName
+- Test organization: mirror source structure | flat tests/ dir | colocated with source
+- Coverage enforcement: yes (threshold) | no | CI-only
+- E2E tests: Playwright | Cypress | Selenium | none
+- API tests: httpx/TestClient | supertest | go httptest | none
+```
+
+#### Step 1.5: Domain Model Deep Scan
+
+Go beyond entity names — understand the business:
+
+```
+Domain entities:
+- List all model/entity classes with their fields
+- Identify relationships (foreign keys, many-to-many, embedded)
+- Find enum types and their values (these encode business states)
+- Find validators/constraints (min/max, regex, required fields)
+
+State machines:
+- Find fields like `status`, `state`, `phase` with enum values
+- Map allowed transitions (look for validation logic, if/match statements)
+- Identify terminal states (completed, cancelled, archived)
+
+Business rules:
+- Find validation functions, guard clauses, business logic checks
+- Look for comments explaining WHY (not just what)
+- Identify invariants (things that must always be true)
+
+Domain vocabulary:
+- What does the team call things? (e.g., "workspace" in UI vs "organization" in DB)
+- Abbreviations used in code (e.g., "txn" for transaction)
+- Domain-specific terms that agents need to know
+```
+
+#### Step 1.6: Integration & External Service Scan
+
+Detect what external services the project integrates with:
+
+```bash
+# Check env files for service hints
+cat .env.example .env.local .env 2>/dev/null | grep -E '^[A-Z_]+=' | sed 's/=.*//'
+
+# Check package files for SDK imports
+grep -r "import.*from" --include="*.ts" --include="*.py" --include="*.go" -l | head -20
+
+# Check docker-compose for services
+cat docker-compose.yml docker-compose.yaml 2>/dev/null
+```
+
+**Map env vars and imports to services:**
+
+| Signal | Service | MCP Server Available |
+|--------|---------|---------------------|
+| `DATABASE_URL` contains `postgres` | PostgreSQL | `@modelcontextprotocol/server-postgres` |
+| `DATABASE_URL` contains `mysql` | MySQL | `@benborla29/mcp-server-mysql` |
+| `DATABASE_URL` contains `sqlite` | SQLite | `@modelcontextprotocol/server-sqlite` |
+| `MONGODB_URI` or `MONGO_URL` | MongoDB | `@modelcontextprotocol/server-mongodb` |
+| `REDIS_URL` or `REDIS_HOST` | Redis | `redis-mcp-server` |
+| `SUPABASE_URL` or `@supabase/` import | Supabase | `@supabase/mcp-server-supabase` |
+| `NEON_DATABASE_URL` or `@neondatabase/` | Neon | `@neondatabase/mcp-server-neon` |
+| `GITHUB_TOKEN` or `@octokit/` import | GitHub | `@modelcontextprotocol/server-github` |
+| `GITLAB_TOKEN` or `gitlab` import | GitLab | `gitlab-mcp-server` |
+| `LINEAR_API_KEY` or `@linear/` import | Linear | `mcp-linear` |
+| `JIRA_*` or `jira` import | Jira | `@anthropic/mcp-server-jira` (if available) |
+| `NOTION_*` or `@notionhq/` import | Notion | `notion-mcp-server` |
+| `SLACK_*` or `@slack/` import | Slack | Claude Code Slack plugin (enabledPlugins) |
+| `DISCORD_*` or `discord.js` import | Discord | `discord-mcp` (local build) |
+| `SENTRY_DSN` or `@sentry/` import | Sentry | `@anthropic/mcp-server-sentry` (if available) |
+| `STRIPE_*` or `stripe` import | Stripe | `@anthropic/mcp-server-stripe` (if available) |
+| `AWS_*` or `boto3`/`@aws-sdk/` import | AWS | `@anthropic/mcp-server-aws` |
+| `CLOUDFLARE_*` or `wrangler` | Cloudflare | `@anthropic/mcp-server-cloudflare` |
+| `VERCEL_*` or `vercel.json` | Vercel | `@anthropic/mcp-server-vercel` |
+| `FIREBASE_*` or `firebase` import | Firebase | `firebase-mcp-server` |
+| `DOCKER_*` or `Dockerfile` exists | Docker | `@modelcontextprotocol/server-docker` |
+| Playwright config exists | Playwright | Browser automation (claude-in-chrome already available) |
+| `FIGMA_*` or Figma references | Figma | `@anthropic/mcp-server-figma` |
+| `TWILIO_*` or `twilio` import | Twilio | `twilio-mcp-server` |
+| `SENDGRID_*` or `@sendgrid/` import | SendGrid | `sendgrid-mcp-server` |
+| `OPENAI_API_KEY` or `openai` import | OpenAI | N/A (SDK direct) |
+| `ANTHROPIC_API_KEY` or `anthropic` import | Anthropic | N/A (SDK direct) |
+| `PINECONE_*` or `pinecone` import | Pinecone | `pinecone-mcp-server` |
+| `WEAVIATE_*` or `weaviate` import | Weaviate | `weaviate-mcp-server` |
+| `ELASTICSEARCH_*` or `elasticsearch` import | Elasticsearch | `elasticsearch-mcp-server` |
+| `RAILWAY_*` or `railway.json` | Railway | Railway MCP (toolkit has Railway skills) |
+
+**Mobile/Native platform tools:**
+
+| Signal | Service/Tool | Recommendation |
+|--------|-------------|---------------|
+| `*.xcodeproj` or `Package.swift` | **Xcode / Swift** | Recommend: SwiftLint (if not present), Fastlane, xcbeautify |
+| `Podfile` | **CocoaPods** | Note: pods detected, document pod install in profile |
+| `fastlane/` directory | **Fastlane** | Document lanes, recommend CI integration |
+| `build.gradle` + `kotlin` | **Android / Kotlin** | Recommend: ktlint, detekt, Gradle build scans |
+| `pubspec.yaml` | **Flutter / Dart** | Recommend: dart_code_metrics, flutter_lints |
+| `expo` in package.json | **Expo** | Recommend: EAS Build, expo-dev-client |
+| `.swiftlint.yml` | **SwiftLint** | Read rules — these ARE the project's coding conventions |
+| `*.xctestplan` | **Xcode Test Plans** | Document test targets and schemes |
+| `Matchfile` or `Appfile` | **Fastlane Match** | Code signing managed via Match |
+| `GoogleService-Info.plist` | **Firebase (iOS)** | Firebase MCP or Firebase console |
+| `google-services.json` | **Firebase (Android)** | Firebase MCP or Firebase console |
+| `*.entitlements` | **iOS Capabilities** | Document entitlements (push, sign-in, etc.) |
+| App Store Connect API key in env | **App Store Connect** | Recommend: Fastlane for automated distribution |
+| `TestFlight` references | **TestFlight** | Document beta distribution workflow |
+
+**Data Science / ML tools:**
+
+| Signal | Service/Tool | Recommendation |
+|--------|-------------|---------------|
+| `dvc.yaml` or `.dvc/` | **DVC** | Data version control — document pipeline |
+| `mlflow` in requirements | **MLflow** | Experiment tracking — document server URL |
+| `wandb` in requirements | **Weights & Biases** | Experiment tracking |
+| `*.ipynb` files | **Jupyter** | Recommend: notebook MCP for Claude interaction |
+| `environment.yml` | **Conda** | Document conda env setup |
+| `Dockerfile` + ML packages | **ML Container** | Docker-based training/serving |
+
+**Also check for CLI tools and build systems the project uses:**
+- `Makefile` → project has make targets (document them)
+- `Taskfile.yml` → project uses Task runner
+- `justfile` → project uses Just runner
+- `turbo.json` → project uses Turborepo
+- `nx.json` → project uses Nx monorepo
+- `pnpm-workspace.yaml` → pnpm monorepo
+- `lerna.json` → Lerna monorepo
+- `fastlane/Fastfile` → Fastlane lanes (document each lane)
+- `Earthfile` → Earthly build system
+- `Bazel` / `BUILD` files → Bazel build system
+- `xcodebuild` in CI → Xcode command-line builds
+
+#### Step 1.6b: Environment Discovery
+
+After detecting what services the project uses (Step 1.6), discover what **environments** those services run in. This builds on the service scan — environments are WHERE services run, not WHAT they are.
+
+**Tiered auto-detection signals (ordered by confidence):**
+
+**Tier 1 — Explicit environment config files (high confidence):**
+
+| Signal | Environment Name | Type |
+|--------|-----------------|------|
+| `.env.staging` | staging | staging |
+| `.env.production` or `.env.prod` | production | production |
+| `.env.preview` | preview | preview |
+| `docker-compose.staging.yml` or `docker-compose.prod.yml` | staging / production | staging / production |
+| GitHub Actions workflow with `environment:` key | value of `environment:` | infer from name |
+| `terraform/environments/staging/`, `terraform/environments/prod/` | staging / production | staging / production |
+| `k8s/overlays/staging/`, `k8s/overlays/production/` | staging / production | staging / production |
+| `helm/values-staging.yaml`, `helm/values-production.yaml` | staging / production | staging / production |
+| `vercel.json` exists | preview + production | preview + production (Vercel always has both) |
+| `fly.staging.toml` or multiple `fly.*.toml` | per-file | infer from filename |
+
+**Tier 2 — CI/CD pipeline analysis (medium confidence):**
+
+| Signal | What it tells us |
+|--------|-----------------|
+| GitHub Actions jobs named `deploy-staging`, `deploy-production` | Two deploy targets |
+| CI workflow with different secrets blocks per environment | Named deploy environments |
+| Branch protection rules on `main` + `staging` branches | Branch-per-environment model |
+| Netlify/Vercel preview deploy configuration | Preview environment exists |
+
+**Tier 3 — Env var naming patterns (low confidence — needs confirmation):**
+
+| Signal | What it tells us |
+|--------|-----------------|
+| `STAGING_DATABASE_URL`, `PROD_DATABASE_URL` in `.env.example` | Env-prefixed vars suggest multiple environments |
+| `DATABASE_URL` with no prefix | Single environment or env set at deploy time |
+
+**Tier 4 — Platform-specific detection (query if available):**
+
+| Platform | How to detect environments |
+|----------|--------------------------|
+| Railway | Query Railway MCP for project environments (Railway has first-class environment support) |
+| Vercel | Always has production + preview; check for custom domains per environment |
+| Fly.io | Check for `fly.staging.toml` or `FLY_APP_NAME` variants |
+| AWS / Terraform | Scan for workspace names, account IDs, or `var.environment` in .tf files |
+| Kubernetes | Check namespace names via kustomize overlays or `kubectl get namespaces` |
+| Heroku | Check for pipeline stages via `heroku pipelines:info` |
+
+**Discovery algorithm:**
+
+1. Scan for `.env.*` files → extract environment names from suffixes
+2. Scan CI/CD configs (`.github/workflows/*.yml`) → extract deploy target names and `environment:` values
+3. Scan IaC configs (Terraform, Kubernetes, Helm) → extract environment names from directory/file names
+4. Scan deploy platform configs (`railway.json`, `vercel.json`, `fly.toml`) → extract environments
+5. Query platform MCP servers if available (Railway MCP, Vercel CLI) → get live environment list
+6. Cross-reference all sources and deduplicate environment names
+7. For each discovered environment, gather:
+   - Type (development / staging / production / preview / canary — infer from name)
+   - URL (from deploy config, env vars, or domain settings)
+   - Health endpoint (from CLAUDE.md Infrastructure or `/health` convention)
+   - Deploy trigger (from CI/CD config — branch name, manual, auto)
+   - Branch (from CI/CD config — which branch triggers deploy, or `—` if not branch-based)
+   - Env var source (which `.env` file or secret store)
+   - Platform (from deploy config)
+8. ALWAYS include `local` as a `development` environment (populated from Local Dev Services scan in CLAUDE.md)
+9. Present findings to user for confirmation (see prompt below)
+
+**Files-first, MCP-second**: Always run Tier 1-3 (offline, file-based) detection before Tier 4 (MCP/CLI queries). This ensures discovery works even without platform MCP servers connected.
+
+**User confirmation prompt:**
+
+Use AskUserQuestion with one of these prompts based on detection results:
+
+**If 0 remote environments detected (only local):**
+```
+I found your local development environment but no remote environments.
+What environments does this project deploy to? (e.g., staging, production, preview)
+List them, or say 'none' if this is local-only:
+```
+
+**If 1+ remote environments detected:**
+```
+I detected these environments:
+
+  1. local (development) — {platform}, {url}
+  2. {name} ({type}) — {platform}, {url}
+  3. {name} ({type}) — {platform}, {url}
+
+Are there other environments I missed? (e.g., preview, canary, QA)
+Type environment names to add, or 'confirm' to proceed: [confirm]
+```
+
+**If greenfield project (< 5 source files, < 3 git commits):**
+Skip environment discovery entirely. Add note to project-profile.md:
+```
+## Environments
+No remote environments detected (greenfield project). Run `/calibrate rescan` after deploying.
+```
+
+**Rescan merge behavior (`/calibrate rescan`):**
+When rescanning, do NOT auto-remove previously detected environments. Instead:
+1. Re-run detection and compare with existing Environments section
+2. For new environments found: add them
+3. For existing environments not re-detected: ask user "I previously detected {env} but can't find it now. Remove it? [y/n]"
+4. For changed details (URL, branch): update silently
+
+After user confirmation, write the Environments table to CLAUDE.md and the detailed blocks to project-profile.md (Phase 2).
+
+The CLAUDE.md table format to write:
+```
+| Name | Type | URL | Health | Deploy | Branch |
+|------|------|-----|--------|--------|--------|
+| local | development | http://localhost:8000 | /health | manual | — |
+| staging | staging | https://staging.myapp.com | /health | push to staging | staging |
+```
+
+### Phase 1.7: Full Agent & Skill Evaluation (CRITICAL)
+
+This is what makes `/calibrate` different from a generic recommendation engine. It doesn't pick
+from a static list — it **reads every single agent and skill definition** in the toolkit and
+evaluates each one against the project's actual needs.
+
+#### How It Works
+
+1. **Read ALL agent definitions** from `~/.claude-agents/agents/*.md`:
+   - For each agent file, read the frontmatter (`name`, `description`, `tools`, `model`)
+   - Read the full body to understand what the agent does, what it expects, what patterns it follows
+   - Extract: what tech stacks it handles, what project signals it looks for, what CLAUDE.md sections it reads
+
+2. **Read ALL skill definitions** from `~/.claude-agents/skills/*/SKILL.md`:
+   - For each skill, read the frontmatter and full body
+   - Extract: what it does, what other skills/agents it chains to, what project state it needs
+   - Map dependencies: `/implement` needs `/planning` output, `/qa` reads Test Commands from CLAUDE.md, etc.
+
+3. **Read ALL hook definitions** from `~/.claude-agents/hooks/*.sh`:
+   - Read the header comments to understand what each hook does
+   - Identify which hooks are relevant for this project's workflow
+
+4. **Score each agent/skill against the project scan results:**
+
+   For each agent, evaluate:
+   ```
+   RELEVANCE SCORE (0-10):
+
+   Tech match (0-3):
+   - Does this agent handle the project's detected tech stack?
+   - python-backend + Python project = 3
+   - python-backend + Go project = 0
+   - architect + any project = 2 (always somewhat relevant)
+
+   Pattern match (0-3):
+   - Does the project have patterns this agent specializes in?
+   - qa-e2e + Playwright detected = 3
+   - qa-e2e + no E2E framework = 0 (but recommend setting up)
+   - sre + Railway detected = 3
+   - sre + no deploy platform = 1 (still useful for local ops)
+
+   Workflow fit (0-2):
+   - Does this agent fit into the project's natural workflow?
+   - frontend agent + project has React code = 2
+   - frontend agent + backend-only API = 0
+
+   Gap fill (0-2):
+   - Does this agent fill a capability gap the project currently has?
+   - qa-domain + project has complex business rules but no domain tests = 2
+   - content-strategist + developer tool with no marketing = 0
+   ```
+
+   **Scoring thresholds:**
+   - 7-10: **Essential** — install by default, include in recommended workflows
+   - 4-6: **Useful** — recommend, explain when to use
+   - 1-3: **Available** — mention but don't push
+   - 0: **Not relevant** — don't show unless user asks
+
+5. **Map skill chains into workflows:**
+
+   Based on what scored high, compose workflow sequences:
+   ```
+   If planning (8) + implement (8) + qa (9) + pr (7) all scored high:
+     → Core workflow: /planning → /implement → /qa → /pr
+
+   If sre (7) + ci-fix (6) scored high:
+     → Ops workflow: /sre status → /ci-fix (when CI breaks)
+
+   If design-studio-think (5) + design-studio-create (6) + design-studio-critique (5):
+     → Design workflow: design-studio-think → design-studio-create → design-studio-critique
+   ```
+
+6. **Identify gaps — things the project needs but no existing agent/skill covers:**
+
+   Compare project scan results against ALL agent/skill capabilities:
+   ```
+   Project has:          Toolkit covers:           Gap:
+   - Celery workers      - No celery agent         → Recommend custom celery-worker agent
+   - Django mgmt cmds    - No Django cmd agent      → Recommend custom django-commands agent
+   - Custom CLI tool      - No CLI agent            → Recommend custom cli agent
+   - GraphQL API         - REST-focused agents      → Recommend custom graphql agent
+   - Mobile app (React Native) - Web-focused frontend → Recommend custom mobile agent
+   - ML pipeline          - No ML agent             → Recommend custom ml-pipeline agent
+   - Terraform infra      - SRE covers some         → Recommend custom terraform agent or extend SRE
+   ```
+
+   **For non-web platforms (mobile, desktop, game, ML, embedded):**
+
+   The gap analysis is especially critical here because the toolkit has ZERO built-in agents
+   for these platforms. The evaluation should:
+
+   a) Score all universal agents (architect, code-reviewer, qa, product-manager) — these
+      apply to ANY project regardless of platform
+
+   b) Score all web-specific agents at 0 (frontend, python-backend) — they don't apply
+
+   c) Generate custom agents for the platform by:
+      - Using knowledge from the deep scan (Step 1.2b/1.2c)
+      - Using web-searched best practices for the platform
+      - Using patterns extracted from the project's own codebase
+      - Reading the project's own docs/README for architecture guidance
+
+   **Example — iOS App (SwiftUI + TCA):**
+   ```
+   Universal agents (still relevant):
+   - architect (8) → Essential — designs system architecture for any platform
+   - code-reviewer (7) → Essential — reviews Swift code quality
+   - qa (6) → Useful — orchestrates test runs, but needs XCTest knowledge
+   - product-manager (5) → Useful — feature planning is platform-agnostic
+   - design-studio-* (4) → Useful — UI/UX design is relevant for mobile
+
+   Web agents (not relevant):
+   - frontend (0) → React/Next.js focused, not Swift
+   - python-backend (0) → Python, not Swift
+   - ops (1) → can still run some commands
+
+   Custom agents to generate:
+   - ios-developer.md → SwiftUI/TCA patterns, Swift conventions, SPM
+     (seeded with conventions from Step 1.3 + TCA patterns from web search)
+   - ios-qa.md → XCTest, XCUITest, snapshot testing
+     (seeded with test patterns from Step 1.4)
+   - ios-ops.md → Fastlane, xcodebuild, TestFlight, provisioning
+     (seeded with CI/CD patterns from the project's fastlane/ dir)
+
+   Custom skills to generate:
+   - /build-ios → xcodebuild clean + build + test (replaces /probe)
+   - /deploy-ios → Fastlane beta distribution (replaces /sre deploy)
+   - /qa-ios → Run XCTest + XCUITest + snapshot tests (extends /qa)
+   ```
+
+   **How custom agents learn the platform (the key mechanism):**
+
+   When generating a custom agent for an unfamiliar platform, the agent definition
+   should embed the knowledge it needs inline — not just say "follow Swift conventions"
+   but actually include the specific conventions extracted from the codebase AND
+   web-searched best practices. This way the agent has the knowledge at invocation
+   time without needing to re-search.
+
+   ```markdown
+   # ios-developer.md (generated by /calibrate)
+
+   ## Swift Conventions (from this project's codebase)
+   - Naming: PascalCase types, camelCase properties/methods, SCREAMING_CASE constants
+   - File per type: each struct/class gets its own file
+   - Import order: Foundation → SwiftUI → External packages → Project modules
+   - Error handling: typed errors via enum conforming to Error protocol
+   - Async: async/await preferred over Combine, structured concurrency
+
+   ## TCA Patterns (from web search + this project's code)
+   - Feature modules: each feature has Reducer + View + State + Action
+   - File structure: Features/{FeatureName}/{FeatureName}.swift (reducer + view together)
+   - Dependencies: registered in DependencyValues extension
+   - Testing: use TestStore to assert state changes
+   ```
+
+   For each gap, draft what a custom agent/skill would look like and include it in recommendations.
+
+#### Agent/Skill Registry (What to Read)
+
+Read EVERY file in these directories:
+
+```
+~/.claude-agents/agents/          ← 26 agent definitions
+~/.claude-agents/skills/*/SKILL.md ← 31 skill definitions
+~/.claude-agents/hooks/           ← 13 hook definitions
+~/.claude-agents/examples/        ← Example customizations
+```
+
+**Parse each file to extract:**
+- Name and description (from frontmatter)
+- Tech stack requirements (from body — grep for framework names, tool names)
+- CLAUDE.md sections it reads (from "Read CLAUDE.md" instructions)
+- Other agents/skills it spawns or chains to
+- Model tier (opus/sonnet/haiku — affects cost)
+- What project signals trigger its use (from triage router patterns)
+
+**Build an internal evaluation matrix:**
+
+```
+| Agent/Skill | Tech Match | Pattern Match | Workflow Fit | Gap Fill | TOTAL | Verdict |
+|------------|-----------|--------------|-------------|---------|-------|---------|
+| python-backend | 3 (Python) | 3 (FastAPI) | 2 (has backend) | 0 | 8 | Essential |
+| frontend | 3 (React) | 2 (Next.js) | 2 (has frontend) | 0 | 7 | Essential |
+| qa | 2 (pytest+vitest) | 3 (tests exist) | 2 (core workflow) | 2 (no orchestration) | 9 | Essential |
+| sre | 2 (Railway) | 2 (has deploy) | 1 (not daily) | 1 | 6 | Useful |
+| design-studio-* | 0 (no design) | 0 | 0 | 0 | 0 | Not relevant |
+| ...
+```
+
+This matrix drives ALL recommendations — MCP servers, categories, workflows, custom agents.
+
+### Phase 2: Write Project Profile
+
+Write all findings to `.claude/project-profile.md`. This is the file agents read at runtime
+to understand HOW the project works, not just WHAT it uses.
+
+**Format:**
+
+```markdown
+# Project Profile — {project_name}
+<!-- Generated by /calibrate on {date} -->
+<!-- Agents read this for deep project context. Re-run /calibrate rescan to update. -->
+<!-- Last calibrated: {date} | Toolkit version: {version from install.sh} -->
+
+## Architecture
+
+**Pattern**: {detected pattern — e.g., "3-layer service architecture (routes → services → repositories)"}
+**Data flow**: {e.g., "HTTP request → Pydantic validation → service logic → SQLAlchemy ORM → PostgreSQL"}
+**Frontend pattern**: {e.g., "Feature-based folders, each with page + components + hooks + tests"}
+**API style**: {e.g., "REST, resource-based, versioned (/api/v1/)"}
+**Auth approach**: {e.g., "JWT Bearer via FastAPI dependency injection on protected routes"}
+
+### Key Directories
+| Directory | Purpose | Key patterns |
+|-----------|---------|-------------|
+| {dir} | {purpose} | {patterns used here} |
+
+### Dependency Flow
+```
+{ascii diagram showing how modules depend on each other}
+```
+
+## Coding Conventions
+
+### {Language 1 — e.g., Python}
+- **Naming**: {snake_case everywhere, PascalCase for classes}
+- **Imports**: {absolute from project root, grouped: stdlib → external → internal}
+- **Error handling**: {custom error hierarchy in app/errors.py — AppError → NotFoundError, ValidationError, etc.}
+- **Type annotations**: {strict — all public functions and return types annotated}
+- **Docstrings**: {Google style on all public functions}
+
+### {Language 2 — e.g., TypeScript}
+- **Naming**: {camelCase vars, PascalCase components, kebab-case files}
+- **Imports**: {absolute via @/ alias, type imports separate}
+- **Error handling**: {try/catch with typed errors, error boundaries for React}
+- **Components**: {function components only, props interface above component}
+
+### Shared Conventions
+- **Commit style**: {conventional commits | freeform | etc.}
+- **Branch naming**: {feature/xxx | feat/xxx | xxx}
+- **PR process**: {squash merge | merge commit | rebase}
+
+## Testing Conventions
+
+### {Backend}
+- **Framework**: {pytest}
+- **Mock strategy**: {real database via test fixtures, external APIs mocked with responses library}
+- **Fixtures**: {conftest.py with factory functions, shared test database}
+- **Naming**: {test_{what}_when_{condition}_then_{expected}}
+- **Coverage**: {enforced at 85% via pytest-cov}
+
+### {Frontend}
+- **Framework**: {Vitest + Testing Library}
+- **Mock strategy**: {MSW for API calls, local state for component tests}
+- **Naming**: {describe/it blocks — "it should render the form"}
+
+### E2E
+- **Framework**: {Playwright | Cypress | none detected}
+- **Patterns**: {page object model | direct selectors}
+
+## Domain Model
+
+**What this app does**: {1-2 sentence description derived from code}
+
+### Core Entities
+| Entity | Key Fields | States/Lifecycle | Relationships |
+|--------|-----------|-----------------|---------------|
+| {entity} | {important fields} | {status values if any} | {belongs to X, has many Y} |
+
+### Business Rules
+- {Rule 1 — derived from validators/guards}
+- {Rule 2}
+
+### State Transitions
+```
+{Entity}: {state1} → {state2} → {state3} (no backwards transitions)
+```
+
+### Domain Vocabulary
+| Code Term | UI Term | Meaning |
+|-----------|---------|---------|
+| {e.g., organization} | {e.g., workspace} | {what it represents} |
+
+## External Integrations
+| Service | How Used | Env Vars | MCP Available |
+|---------|----------|----------|--------------|
+| {service} | {purpose in this project} | {var names} | {yes/no + package name} |
+
+## Environments
+
+### {env_name} ({type})
+- **Platform**: {e.g., Docker Compose, Railway, Vercel, AWS, Kubernetes}
+- **URL**: {e.g., http://localhost:8000, https://staging.myapp.com}
+- **Health**: {endpoint path, e.g., /health}
+- **Database**: {e.g., postgres://localhost:5432/myapp_dev, Railway-managed postgres}
+- **Env file**: {e.g., .env.local, .env.staging, Railway env vars}
+- **Services**: {e.g., backend (port 8000), frontend (port 3000), postgres (port 5432)}
+- **Start**: {e.g., docker compose up -d, N/A (managed)}
+- **Deploy trigger**: {e.g., manual, push to staging branch, push to main}
+- **Access**: {e.g., direct (local), Railway CLI / MCP, kubectl}
+- **Access validated**: {true/false — checked during calibration}
+
+### Environment Access Methods
+| Environment | Database | Logs | Deploy | Health |
+|-------------|----------|------|--------|--------|
+| {env_name} | {e.g., postgres MCP (direct)} | {e.g., docker compose logs} | {e.g., manual} | {e.g., curl localhost:8000/health} |
+
+## Detected Workflows
+| Activity | Current Approach | Toolkit Equivalent |
+|----------|-----------------|-------------------|
+| {e.g., "Running tests"} | {e.g., "pytest from backend/"} | {e.g., "/qa or ops agent"} |
+| {e.g., "Deploying"} | {e.g., "git push to main → Railway auto-deploy"} | {e.g., "/sre deploy"} |
+
+## Recommended Toolkit Configuration
+
+### MCP Servers to Install
+| Server | Package | Why |
+|--------|---------|-----|
+| {name} | {npm package or install command} | {what it enables for this project} |
+
+### Agents (Priority Order)
+| Agent | Relevance | Why |
+|-------|-----------|-----|
+| {agent} | {essential/high/medium/low} | {what it does for this project specifically} |
+
+### Skills (Priority Order)
+| Skill | Relevance | Why |
+|-------|-----------|-----|
+| {skill} | {essential/high/medium} | {how this project uses it} |
+
+### Recommended Workflows
+| Workflow | Steps | When to Use |
+|----------|-------|-------------|
+| {name} | {skill1 → skill2 → skill3} | {situation} |
+
+### Custom Agents/Skills to Create
+| Name | Type | Purpose | Effort |
+|------|------|---------|--------|
+| {name} | {agent/skill} | {what gap it fills} | {small/medium} |
+```
+
+### Phase 3: Recommend
+
+Present findings to the user as a clear, actionable report. Group into sections.
+
+#### 3.1: Recommendations Summary
+
+```
+/calibrate Results for {project_name}
+======================================
+
+Project Profile: .claude/project-profile.md (written)
+
+## What I Learned
+
+Architecture: {1-line summary}
+Stack: {detected stack}
+Domain: {1-line what the app does}
+Stage: {greenfield/early/growth/scale}
+Team patterns: {1-2 key conventions}
+
+## Recommendations
+
+### MCP Servers ({N} recommended)
+
+These MCP servers connect Claude Code directly to your project's services:
+
+  ✦ {server_name} — {why}
+    Install: {command}
+
+  ✦ {server_name} — {why}
+    Install: {command}
+
+  ...
+
+### Toolkit Categories ({N} recommended)
+
+Based on your project, these toolkit categories are most valuable:
+
+  [x] core — Required (already installed if toolkit is set up)
+  [x] development — {why — e.g., "Your project has backend + frontend layers"}
+  [x] quality — {why — e.g., "You have pytest + Vitest, QA agents orchestrate both"}
+  [x] hooks — {why — e.g., "Triage router saves cost by routing to cheaper models"}
+  [x] guardrails — {why — e.g., "Session bootstrap, onboard, safety guards"}
+  [ ] operations — {why or why not}
+  [ ] strategy — {why or why not}
+  [ ] railway — {only if Railway detected}
+  [ ] consulting — {only if relevant}
+
+### Workflows for Your Project
+
+Your daily workflow should be:
+  1. /onboard — Start of session, see what's happening
+  2. {workflow step} — {why}
+  3. {workflow step} — {why}
+  4. /qa — Validate before shipping
+  5. /pr — Create PR with QA checks
+
+Other valuable workflows:
+  - {workflow} — {when to use}
+  - {workflow} — {when to use}
+
+### Custom Agents/Skills to Create ({N} recommended)
+
+Your project has patterns the generic toolkit doesn't cover:
+
+  ✦ {name} ({agent|skill}) — {what gap it fills}
+    {1-2 sentence description of what it would do}
+
+  ...
+
+### Tools & Plugins
+
+  ✦ {tool/plugin} — {why}
+
+## Install Plan
+
+I'll make these changes:
+  1. {action — e.g., "Add postgres MCP server to .claude/settings.json"}
+  2. {action — e.g., "Install categories: core, development, quality, hooks, guardrails"}
+  3. {action — e.g., "Create custom agent: django-management.md"}
+  4. {action — e.g., "Enable Slack plugin in settings"}
+  ...
+
+Proceed with all? Or pick which ones: [all / pick / skip]
+```
+
+Use AskUserQuestion to get the user's choice.
+
+#### 3.2: Handle User Choice
+
+| Choice | Action |
+|--------|--------|
+| `all` or `yes` | Execute full install plan |
+| `pick` | Present numbered list, let user select which to install |
+| `skip` | Skip installation, keep project-profile.md only |
+| Specific items (e.g., "1, 3, 5") | Install only those items |
+
+### Phase 4: Install Everything
+
+Execute the install plan based on user choices. Run each step, verify, report.
+
+#### 4.1: Install MCP Servers
+
+For each recommended MCP server the user approved, add it to the project's `.claude/settings.json`.
+
+**MCP Server Installation Database:**
+
+```python
+MCP_SERVERS = {
+    "postgres": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-postgres", "{DATABASE_URL}"],
+        "env_var": "DATABASE_URL",
+        "note": "Replace {DATABASE_URL} with your connection string, or set DATABASE_URL env var"
+    },
+    "sqlite": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "{DB_PATH}"],
+        "note": "Replace {DB_PATH} with path to your .db file"
+    },
+    "mysql": {
+        "command": "npx",
+        "args": ["-y", "@benborla29/mcp-server-mysql"],
+        "env": {"MYSQL_HOST": "localhost", "MYSQL_USER": "root", "MYSQL_DATABASE": "{DB_NAME}"},
+        "note": "Set MYSQL_* env vars"
+    },
+    "mongodb": {
+        "command": "npx",
+        "args": ["-y", "mongodb-mcp-server"],
+        "env": {"MONGODB_URI": "{MONGO_URI}"},
+        "note": "Set MONGODB_URI env var"
+    },
+    "redis": {
+        "command": "npx",
+        "args": ["-y", "redis-mcp-server"],
+        "env": {"REDIS_URL": "{REDIS_URL}"},
+        "note": "Set REDIS_URL env var"
+    },
+    "supabase": {
+        "command": "npx",
+        "args": ["-y", "@supabase/mcp-server-supabase"],
+        "env": {"SUPABASE_URL": "{URL}", "SUPABASE_SERVICE_ROLE_KEY": "{KEY}"},
+        "note": "Get from Supabase dashboard → Settings → API"
+    },
+    "neon": {
+        "command": "npx",
+        "args": ["-y", "@neondatabase/mcp-server-neon"],
+        "env": {"NEON_API_KEY": "{KEY}"},
+        "note": "Get from Neon console → Account → API Keys"
+    },
+    "github": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-github"],
+        "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "{TOKEN}"},
+        "note": "Create a fine-grained PAT at github.com/settings/tokens"
+    },
+    "gitlab": {
+        "command": "npx",
+        "args": ["-y", "gitlab-mcp-server"],
+        "env": {"GITLAB_TOKEN": "{TOKEN}", "GITLAB_URL": "https://gitlab.com"},
+        "note": "Create a PAT at gitlab.com/-/user_settings/personal_access_tokens"
+    },
+    "linear": {
+        "command": "npx",
+        "args": ["-y", "mcp-linear"],
+        "env": {"LINEAR_API_KEY": "{KEY}"},
+        "note": "Get from Linear → Settings → API"
+    },
+    "notion": {
+        "command": "npx",
+        "args": ["-y", "notion-mcp-server"],
+        "env": {"NOTION_API_KEY": "{KEY}"},
+        "note": "Create an internal integration at notion.so/my-integrations"
+    },
+    "sentry": {
+        "command": "npx",
+        "args": ["-y", "@sentry/mcp-server-sentry"],
+        "env": {"SENTRY_AUTH_TOKEN": "{TOKEN}"},
+        "note": "Get from sentry.io → Settings → Auth Tokens"
+    },
+    "cloudflare": {
+        "command": "npx",
+        "args": ["-y", "@anthropic/mcp-server-cloudflare"],
+        "env": {"CLOUDFLARE_API_TOKEN": "{TOKEN}"},
+        "note": "Get from dash.cloudflare.com → Profile → API Tokens"
+    },
+    "docker": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-docker"],
+        "note": "Requires Docker daemon running"
+    },
+    "puppeteer": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
+        "note": "Browser automation — headless Chrome"
+    },
+    "filesystem": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "{PROJECT_DIR}"],
+        "note": "Scoped file access — usually not needed since Claude Code has Read/Write"
+    },
+    "brave-search": {
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+        "env": {"BRAVE_API_KEY": "{KEY}"},
+        "note": "Web search capability — get key from api.search.brave.com"
+    }
+}
+```
+
+**How to add an MCP server to settings.json:**
+
+1. Read the existing `.claude/settings.json` (project-level) — create it if it doesn't exist
+2. Parse as JSON
+3. Add to the `mcpServers` key (create if missing)
+4. For servers that need env vars:
+   - Check if the env var is already set in `.env.local`, `.env`, or the shell environment
+   - If found, use the value
+   - If not found, add the server config with a placeholder and note to the user
+5. Write back the JSON (preserve existing settings, only add new MCP servers)
+
+**CRITICAL**: Never overwrite existing MCP server configs. Only ADD new ones. If a server
+with the same key already exists, skip it and note "already configured."
+
+**Also check for Claude Code plugins** (different from MCP servers):
+- If Slack integration detected → suggest enabling `slack@claude-plugins-official` in `enabledPlugins`
+
+#### 4.2: Install Toolkit Categories
+
+Run `install.sh` with the right categories:
+
+```bash
+~/.claude-agents/install.sh --categories {comma-separated-categories} {project_dir}
+```
+
+If toolkit is already installed, run a sync instead:
+```bash
+~/.claude-agents/install.sh {project_dir}
+```
+
+If specific categories need to be added to an existing install:
+1. Read `.claude/.claude-agents.conf` to get current categories
+2. Merge new categories with existing ones
+3. Run `install.sh --categories {merged-categories} {project_dir}`
+
+#### 4.3: Create Custom Agents
+
+For each recommended custom agent, generate a project-specific agent file.
+
+**Template for custom agents:**
+
+```markdown
+---
+name: {agent-name}
+description: {what it does for this specific project}
+tools: Read, Edit, Write, Bash, Grep, Glob
+model: sonnet
+---
+
+# {Agent Title}
+
+{Description of what this agent specializes in for this project.}
+
+## Project Context Discovery
+
+Before starting work:
+1. Read `CLAUDE.md` for project overview and tech stack
+2. Read `.claude/project-profile.md` for architecture patterns and conventions
+3. Read `.claude/knowledge/shared/conventions.md` for coding rules
+4. Read `.claude/knowledge/shared/domain.md` for business rules
+5. Read `.claude/knowledge/agents/{my-name}.md` if it exists for past learning
+
+## {Domain-Specific Section}
+
+{Project-specific instructions derived from the deep scan.
+Include actual patterns found in the codebase, naming conventions,
+file locations, and how this agent should write code that fits.}
+
+## Conventions (MUST FOLLOW)
+
+{Extracted from project-profile.md — naming, imports, error handling, etc.
+Be specific: "Use snake_case for all Python functions" not "follow conventions."}
+
+## Examples from This Project
+
+{Include 1-2 actual code snippets from the project that show the pattern
+this agent should follow. Extracted during the deep scan.}
+```
+
+Write custom agents as **regular files** (not symlinks) in `.claude/agents/`. The triage
+router auto-discovers them.
+
+#### 4.4: Create Custom Skills
+
+For each recommended custom skill, generate a project-specific skill.
+
+Create as a directory in `.claude/skills/{skill-name}/SKILL.md` — regular directory (not symlink).
+The triage router auto-discovers them.
+
+**Each custom skill should:**
+- Reference the project's actual commands (from CLAUDE.md)
+- Use the project's conventions (from project-profile.md)
+- Chain to existing toolkit skills where possible
+
+#### 4.5: Update CLAUDE.md
+
+If the deep scan found information that should be in CLAUDE.md but isn't:
+- Add missing Domain section content
+- Add missing Key Architecture descriptions
+- Add any custom commands or workflows discovered
+- **NEVER overwrite sections the user has already filled in**
+
+#### 4.6: Configure Recommended Workflows
+
+If the project would benefit from specific workflow chains, document them in the
+project profile under "Recommended Workflows" so the triage router and `/onboard`
+can reference them.
+
+### Phase 5: Verify & Report
+
+After installation, verify everything:
+
+1. Check MCP servers were added to settings.json correctly
+2. Check toolkit categories are installed (symlinks exist)
+3. Check custom agents/skills are in place
+4. Check project-profile.md was written
+5. Verify CLAUDE.md has no remaining `<!-- TODO -->` in critical sections
+
+**Final report:**
+
+```
+Calibration Complete
+====================
+
+Project Profile: .claude/project-profile.md ✓
+Knowledge Base: .claude/knowledge/ ✓ (seeded with {N} entries across {M} partitions)
+
+Installed:
+  ✓ MCP Servers: postgres, redis, linear (3 added to .claude/settings.json)
+  ✓ Toolkit: core, development, quality, hooks, guardrails (5 categories)
+  ✓ Custom Agents: django-management.md, celery-worker.md (2 created)
+  ✓ Custom Skills: migrate/SKILL.md (1 created)
+  ✓ Plugins: Slack enabled
+  ✓ External sources: Notion wiki, Linear issues, Slack #eng (3 connected)
+
+Knowledge Base Seeded:
+  shared/conventions  — {N} coding rules extracted from codebase
+  shared/domain       — {N} business rules from models + validators
+  shared/vocabulary   — {N} term mappings from code vs UI
+  shared/patterns     — {N} architecture patterns from source analysis
+  external/sources    — {N} team knowledge sources connected
+
+Needs attention:
+  ⚠ postgres MCP needs DATABASE_URL — set in .env.local
+  ⚠ linear MCP needs LINEAR_API_KEY — set in .env.local
+  ⚠ CLAUDE.md Domain section still has placeholders
+
+Your daily workflow:
+  /onboard → /planning <feature> → /implement <feature> → /qa → /pr
+
+The knowledge base will grow as you use the toolkit. Agents learn from your
+corrections and contribute back what they discover. Run /calibrate rescan
+after major changes, or /calibrate status to check health.
+```
+
+### Phase 6: Initialize Project Knowledge Base
+
+The knowledge base is the toolkit's long-term memory for this project. Every agent and skill
+reads from it AND writes to it. It replaces the simpler "learning log" concept with a proper
+partitioned knowledge system.
+
+#### 6.1: Knowledge Base Structure
+
+Create the full directory structure:
+
+```
+.claude/knowledge/
+├── README.md              ← How the knowledge base works (for humans)
+├── shared/                ← ALL agents and skills read this partition
+│   ├── conventions.md     ← Coding conventions learned from corrections
+│   ├── domain.md          ← Domain knowledge accumulated over time
+│   ├── patterns.md        ← Architecture patterns and when to use them
+│   ├── vocabulary.md      ← Project-specific terms, abbreviations, mappings
+│   └── decisions.md       ← Key decisions made and why (lightweight ADRs)
+├── agents/                ← Per-agent knowledge (agent reads its own + shared/)
+│   ├── frontend.md        ← Frontend agent's accumulated learning
+│   ├── python-backend.md  ← Backend agent's learning
+│   ├── qa.md              ← QA agent's test patterns, failure patterns
+│   ├── sre.md             ← SRE agent's deploy patterns, incident history
+│   └── {agent-name}.md    ← Created on first use by each agent
+├── skills/                ← Per-skill knowledge (skill reads its own + shared/)
+│   ├── planning.md        ← What planning has learned about this project
+│   ├── implement.md       ← Implementation patterns that worked
+│   ├── qa.md              ← Test strategies, coverage gaps found
+│   └── {skill-name}.md    ← Created on first use by each skill
+├── workflows/             ← Learned workflow patterns
+│   └── effective.md       ← Which workflow sequences work best for this project
+├── external/              ← Pointers to external knowledge sources
+│   └── sources.md         ← Links to wikis, Notion, Confluence, Linear, etc.
+└── meta/                  ← Knowledge base metadata
+    ├── change-detection.md ← File hashes for drift detection
+    └── stats.md           ← Usage stats, entry counts, staleness tracking
+```
+
+#### 6.2: Shared Knowledge Files
+
+**`.claude/knowledge/shared/conventions.md`:**
+```markdown
+# Coding Conventions
+<!-- Learned from user corrections and code analysis. All agents read this. -->
+<!-- Updated by: any agent that observes a user correction -->
+<!-- Last updated: {date} -->
+
+## Source: /calibrate deep scan ({date})
+{Conventions extracted during calibration — seeded from project-profile.md}
+
+## Learned from Use
+<!-- Entries below are added automatically when agents observe corrections -->
+
+### {date} — {convention name}
+**What happened**: {agent wrote X, user changed it to Y}
+**Rule**: {the convention to follow going forward}
+**Applies to**: {which files/patterns this affects}
+```
+
+**`.claude/knowledge/shared/domain.md`:**
+```markdown
+# Domain Knowledge
+<!-- Business rules, entity relationships, invariants. All agents read this. -->
+<!-- Updated by: qa-domain, planning, implement, or any agent that learns domain rules -->
+
+## Source: /calibrate deep scan ({date})
+{Domain model extracted during calibration — seeded from project-profile.md}
+
+## Learned from Use
+<!-- Entries below are added when agents discover domain rules not in code -->
+```
+
+**`.claude/knowledge/shared/vocabulary.md`:**
+```markdown
+# Project Vocabulary
+<!-- What the team calls things. Agents use these terms in communication. -->
+
+## Source: /calibrate deep scan ({date})
+| Code Term | UI Term | Team Shorthand | Meaning |
+|-----------|---------|----------------|---------|
+{Initial mappings from domain scan}
+
+## Learned from Use
+<!-- Added when users refer to things by names not in code -->
+```
+
+**`.claude/knowledge/shared/patterns.md`:**
+```markdown
+# Architecture Patterns
+<!-- How to write code that fits this project. All code-writing agents read this. -->
+
+## Source: /calibrate deep scan ({date})
+{Patterns extracted from codebase — how routes are structured, how services work, etc.}
+
+## Learned from Use
+<!-- Added when agents discover new patterns or user teaches better approaches -->
+```
+
+**`.claude/knowledge/shared/decisions.md`:**
+```markdown
+# Key Decisions
+<!-- Lightweight ADRs — decisions made during sessions with rationale. -->
+<!-- Prevents future agents from re-asking or contradicting past decisions. -->
+
+## Decisions
+<!-- Format: ### {date} — {title}
+     **Decision**: {what was decided}
+     **Why**: {rationale}
+     **Context**: {what prompted it}
+     **Alternatives considered**: {what else was discussed} -->
+```
+
+#### 6.3: Agent Knowledge Protocol
+
+Every agent should follow this read/write protocol:
+
+**On session start (READ):**
+```
+1. Read .claude/knowledge/shared/conventions.md  → know the coding rules
+2. Read .claude/knowledge/shared/domain.md       → know the business rules
+3. Read .claude/knowledge/shared/vocabulary.md   → know the terminology
+4. Read .claude/knowledge/shared/patterns.md     → know the architecture patterns
+5. Read .claude/knowledge/agents/{my-name}.md    → know my own past learning
+   (if it exists — skip on first use)
+```
+
+**During session (WRITE — when learning happens):**
+```
+When you observe any of these, write to the appropriate knowledge file:
+
+1. User corrects your code style/pattern → append to shared/conventions.md
+2. User teaches a domain rule not in code → append to shared/domain.md
+3. User uses a term/abbreviation you didn't know → append to shared/vocabulary.md
+4. You discover an architecture pattern from reading code → append to shared/patterns.md
+5. A decision is made about approach/architecture → append to shared/decisions.md
+6. You learn something specific to your domain → append to agents/{my-name}.md
+```
+
+**Write format for new entries:**
+```markdown
+### {date} — {title}
+**Source**: {agent/skill name}, session context
+**What was learned**: {the knowledge}
+**How to apply**: {when this matters for future work}
+```
+
+#### 6.4: Skill Knowledge Protocol
+
+Skills that orchestrate work should also read/write:
+
+**`/planning` writes to:** `skills/planning.md` — what worked, what the team preferred
+**`/implement` writes to:** `skills/implement.md` — implementation patterns, agent coordination
+**`/qa` writes to:** `skills/qa.md` — test strategies, common failure patterns, coverage gaps
+**`/pr` writes to:** `skills/qa.md` — review feedback patterns
+**`/sre` writes to:** `agents/sre.md` — deploy patterns, incident responses
+
+#### 6.5: External Knowledge Sources
+
+**`.claude/knowledge/external/sources.md`:**
+```markdown
+# External Knowledge Sources
+<!-- Pointers to where knowledge lives outside this repo -->
+
+## Connected Sources
+| Source | Type | URL/Location | What's There | How to Access |
+|--------|------|-------------|-------------|--------------|
+| {e.g., Notion} | Wiki | {URL} | Architecture docs, PRDs | Notion MCP server |
+| {e.g., Linear} | Issue tracker | {project URL} | Bug reports, feature requests | Linear MCP or `gh` |
+| {e.g., Confluence} | Docs | {URL} | Engineering standards | Web fetch |
+| {e.g., Figma} | Design | {URL} | UI designs, component specs | Figma MCP server |
+| {e.g., Slack #eng} | Discussion | {channel} | Real-time decisions | Slack plugin |
+
+## How Agents Should Use External Sources
+- **Before planning a feature**: Check Linear/Jira for existing issues and context
+- **Before designing UI**: Check Figma for existing design system and components
+- **Before making architecture decisions**: Check wiki/Confluence for existing ADRs
+- **When domain questions arise**: Check wiki for business rule documentation
+```
+
+During calibration, ask the user:
+```
+Where does your team keep knowledge outside the code?
+  - Issue tracker: [Linear / Jira / GitHub Issues / none]
+  - Documentation: [Notion / Confluence / GitBook / docs/ folder / none]
+  - Design: [Figma / Sketch / none]
+  - Communication: [Slack / Discord / Teams / none]
+  - Other: [any other tools?]
+```
+
+For each answer, add to `external/sources.md` AND recommend the corresponding MCP server
+if available. This is how MCP server recommendations connect to the knowledge system.
+
+#### 6.6: Change Detection
+
+**`.claude/knowledge/meta/change-detection.md`:**
+```markdown
+# Change Detection
+<!-- File hashes for drift detection. Session bootstrap hook checks these. -->
+<!-- When a hash changes → suggest /calibrate rescan -->
+
+| File | Hash (sha256 first 8) | Last Checked | Status |
+|------|----------------------|-------------|--------|
+| package.json | {hash} | {date} | current |
+| requirements.txt | {hash} | {date} | current |
+| pyproject.toml | {hash} | {date} | current |
+| docker-compose.yml | {hash} | {date} | current |
+| .env.example | {hash} | {date} | current |
+| prisma/schema.prisma | {hash} | {date} | current |
+| alembic/versions/ (count) | {count} | {date} | current |
+| CLAUDE.md | {hash} | {date} | current |
+```
+
+Generate hashes during calibration:
+```bash
+sha256sum {file} 2>/dev/null | cut -c1-8
+```
+
+The session bootstrap hook (`session-bootstrap.sh`) should check these hashes on session
+start and inject a warning if any have changed:
+```
+⚠ requirements.txt changed since last calibration — run /calibrate rescan
+```
+
+#### 6.7: Knowledge Base Stats
+
+**`.claude/knowledge/meta/stats.md`:**
+```markdown
+# Knowledge Base Stats
+<!-- Auto-updated. Shows health of the knowledge system. -->
+
+| Partition | Entries | Last Updated | Staleness |
+|-----------|---------|-------------|-----------|
+| shared/conventions | {N} | {date} | {fresh/stale} |
+| shared/domain | {N} | {date} | {fresh/stale} |
+| shared/vocabulary | {N} | {date} | {fresh/stale} |
+| shared/patterns | {N} | {date} | {fresh/stale} |
+| shared/decisions | {N} | {date} | {fresh/stale} |
+| agents/* | {N total} | {date} | {fresh/stale} |
+| skills/* | {N total} | {date} | {fresh/stale} |
+| workflows/effective | {N} | {date} | {fresh/stale} |
+
+Total entries: {N}
+Last calibration: {date}
+Sessions since calibration: {N}
+```
+
+#### 6.8: Knowledge Base README
+
+**`.claude/knowledge/README.md`:**
+```markdown
+# Project Knowledge Base
+
+This directory is the toolkit's long-term memory for this project. It was
+initialized by `/calibrate` and grows as agents and skills learn from use.
+
+## How it works
+
+- **shared/** — Knowledge ALL agents read. Coding conventions, domain rules,
+  architecture patterns, vocabulary. Updated when users correct agent output.
+- **agents/** — Per-agent learning. Each agent reads its own file for past
+  context. Written when an agent discovers something specific to its domain.
+- **skills/** — Per-skill learning. Written when a skill discovers what
+  approaches work best for this project.
+- **workflows/** — Which skill/agent sequences work best. Updated over time.
+- **external/** — Pointers to where knowledge lives outside the code
+  (Notion, Linear, Figma, Slack, etc.)
+- **meta/** — Change detection hashes and usage stats.
+
+## For humans
+
+You can read and edit any file here. If you notice an agent consistently
+getting something wrong, add a correction to `shared/conventions.md` and
+it will be picked up in the next session.
+
+To reset: delete this directory and run `/calibrate` again.
+To prune: run `/calibrate status` to see what's stale, then delete old entries.
+```
+
+---
+
+## `/calibrate rescan` — Update Existing Profile
+
+When running as rescan:
+
+1. Read existing `.claude/project-profile.md`
+2. Re-run the deep scan (Phase 1)
+3. Diff the old profile with new findings
+4. Present ONLY what changed:
+   ```
+   Rescan Results
+   ==============
+
+   Changed:
+     ✦ New dependency: celery added to requirements.txt
+     ✦ Architecture: new background worker pattern detected (backend/workers/)
+     ✦ Testing: E2E tests added (playwright.config.ts found)
+
+   New recommendations:
+     ✦ MCP Server: Redis (celery broker) — not currently configured
+     ✦ Agent: celery-worker agent for task scaffolding
+     ✦ Skill: /qa full now includes E2E (Playwright detected)
+
+   No changes:
+     ✦ Coding conventions unchanged
+     ✦ Domain model unchanged
+     ✦ Existing MCP servers still valid
+
+   Update project-profile.md and install changes? [yes/no/pick]
+   ```
+5. Install changes based on user choice
+6. Update file hashes in `.claude/knowledge/meta/change-detection.md`
+7. Refresh the "Source: /calibrate" sections in knowledge base files (preserve "Learned from Use" sections)
+8. Update `.claude/knowledge/meta/stats.md` with new counts
+
+---
+
+## `/calibrate status` — Current State
+
+Show what's calibrated:
+
+```
+Calibration Status
+==================
+
+Last calibrated: 2026-03-20 (5 days ago)
+Profile: .claude/project-profile.md ✓
+
+MCP Servers (3 configured):
+  ✓ postgres — connected
+  ✓ redis — connected
+  ✓ discord-mcp — connected
+
+Toolkit (5 categories installed):
+  ✓ core, development, quality, hooks, guardrails
+
+Custom (3 project-specific):
+  ✓ agents/django-management.md
+  ✓ agents/celery-worker.md
+  ✓ skills/migrate/SKILL.md
+
+Knowledge Base (.claude/knowledge/):
+  shared/conventions   — 12 entries (last updated 2 days ago) ✓
+  shared/domain        — 8 entries (last updated 3 days ago) ✓
+  shared/vocabulary    — 5 entries (last updated 1 day ago) ✓
+  shared/patterns      — 6 entries (seeded, no updates yet) ⚠
+  shared/decisions     — 3 entries (last updated 4 days ago) ✓
+  agents/*             — 4 agents have learning (frontend, python-backend, qa, sre)
+  skills/*             — 2 skills have learning (planning, implement)
+  workflows/effective  — 2 workflow patterns recorded
+  external/sources     — 3 sources connected (Notion, Linear, Slack)
+
+Change Detection:
+  ✓ package.json — unchanged
+  ⚠ requirements.txt — CHANGED since last calibration
+  ✓ docker-compose.yml — unchanged
+
+Recommendation: Run /calibrate rescan — requirements.txt has changed.
+```
+
+---
+
+## Agent & Skill Context Loading Protocol
+
+**IMPORTANT**: After calibrating, all agents and skills automatically load project knowledge.
+
+The CLAUDE.md managed block (injected by install.sh) should include these lines so every
+agent discovers the knowledge system through their standard "Read CLAUDE.md" step:
+
+```
+## Project Knowledge (auto-populated by /calibrate)
+
+If `.claude/project-profile.md` exists, read it for deep project context
+(architecture patterns, coding conventions, domain model, testing style).
+
+If `.claude/knowledge/` exists, this project has a knowledge base:
+- Read `.claude/knowledge/shared/conventions.md` before writing any code
+- Read `.claude/knowledge/shared/domain.md` before making domain decisions
+- Read `.claude/knowledge/shared/vocabulary.md` to use correct terminology
+- Read `.claude/knowledge/agents/{your-agent-name}.md` for your past learning
+- Write to knowledge files when you learn something new (see knowledge/README.md)
+```
+
+This means agents automatically pick up the profile AND knowledge base without needing
+individual agent file edits. The managed block acts as the discovery mechanism.
+
+### What Agents Write Back
+
+When an agent observes a correction or learns something new during a session, it should
+append to the appropriate knowledge file. This is how the knowledge base grows organically:
+
+| Observation | Write To |
+|-------------|----------|
+| User renames a variable you created | `shared/conventions.md` — naming rule |
+| User changes your error handling approach | `shared/conventions.md` — error handling rule |
+| User explains a business rule not in code | `shared/domain.md` — new domain rule |
+| User refers to something by a shorthand | `shared/vocabulary.md` — new term |
+| You discover a code pattern by reading code | `shared/patterns.md` — new pattern |
+| Team decides on an approach during planning | `shared/decisions.md` — new ADR |
+| You learn something domain-specific to your role | `agents/{your-name}.md` — agent learning |
+| A workflow sequence worked particularly well | `workflows/effective.md` — workflow pattern |
+
+### Knowledge Base Hygiene
+
+- Entries older than 90 days without being referenced should be reviewed for staleness
+- `/calibrate rescan` refreshes the "Source: /calibrate" sections but preserves "Learned from Use" entries
+- Contradictions between calibrate-seeded knowledge and learned-from-use entries should be resolved in favor of the learned entry (it's more recent and was validated by the user)
+- `/calibrate status` shows knowledge base health including entry counts and staleness
+
+---
+
+## MCP Server Verification
+
+After adding MCP servers to settings.json, the user needs to restart Claude Code for them
+to take effect. Always remind:
+
+```
+MCP servers added to .claude/settings.json. Restart Claude Code to activate them.
+After restart, run /mcp to verify they're connected.
+```
+
+---
+
+## Rules
+
+- **Never overwrite user-customized files** — check for symlinks vs regular files before touching
+- **Never remove existing MCP servers** — only add new ones
+- **Never remove existing toolkit categories** — only add new ones
+- **Always present recommendations before installing** — user must approve
+- **Always verify after installing** — don't report success until confirmed
+- **Custom agents/skills are regular files** — never symlink them (they're project-specific)
+- **Profile must be re-readable** — agents parse it every session, so keep format consistent
+- **Hash key files** — so `/calibrate status` can detect drift without re-scanning
+- **Rescan is incremental** — show what changed, don't re-present everything
+- **MCP server credentials** — never store real credentials in settings.json recommendations;
+  use env var references and instruct the user to set values in `.env.local`
+- **Read ALL agent/skill definitions** — never use a static list; always read the actual files
+  in `~/.claude-agents/agents/` and `~/.claude-agents/skills/*/SKILL.md` to build recommendations
+- **Knowledge base is append-only during sessions** — agents add entries, never delete them.
+  Only `/calibrate rescan` and manual user edits may remove entries
+- **Knowledge partitions are strict** — shared/ is for everyone, agents/{name}.md is for that
+  agent only. Never cross-write (e.g., frontend agent writing to agents/backend.md)
+- **Seed knowledge from scan, grow from use** — calibration seeds the initial knowledge base
+  entries from the deep scan. All subsequent entries come from agent/skill observations during
+  real sessions. The seed is the floor, not the ceiling
+- **External sources need MCP** — when the user points to an external knowledge source
+  (Notion, Linear, Figma), always check if a corresponding MCP server can bridge it. If yes,
+  recommend installing it so agents can query the source directly