invar-tools 1.10.0__tar.gz → 1.12.0__tar.gz

{invar_tools-1.10.0 → invar_tools-1.12.0}/.claude/skills/develop/SKILL.md

@@ -2,7 +2,7 @@
 name: develop
 description: Implementation phase following USBV workflow. Use when task is clear and actionable - "add", "implement", "create", "fix", "update", "build", "write". Requires Check-In at start and Final at end.
 _invar:
-  version: "5.0"
+  version: "5.1"
   managed: skill
 ---
 <!--invar:skill-->
@@ -189,6 +189,52 @@ Co-Authored-By: Claude <noreply@anthropic.com>"
 - All TodoWrite items complete
 - Integration works (if applicable)
 
+#### Isolation Requirement (DX-75)
+
+**For non-trivial implementations (>3 functions OR >200 lines), VALIDATE requires isolation:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  VALIDATE with Isolation                                    │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  Why: You (the builder) have context contamination.         │
+│  You "know" what the code is supposed to do.                │
+│  You cannot objectively verify your own work.               │
+│                                                             │
+│  Steps:                                                     │
+│  1. Main Agent: Run invar_guard() — mechanical checks       │
+│                                                             │
+│  2. Spawn Isolated VALIDATOR (Task tool, model=opus):       │
+│     ┌─────────────────────────────────────────────────┐    │
+│     │  RECEIVES:                                      │    │
+│     │  - Implementation files                         │    │
+│     │  - Contracts (@pre/@post)                       │    │
+│     │  - Original task description                    │    │
+│     │                                                 │    │
+│     │  DOES NOT RECEIVE:                              │    │
+│     │  - Development conversation                     │    │
+│     │  - Your reasoning or decisions                  │    │
+│     │  - Previous iterations                          │    │
+│     │                                                 │    │
+│     │  TASK: "Does this implementation satisfy the    │    │
+│     │  contracts? Are there gaps or edge cases?"      │    │
+│     └─────────────────────────────────────────────────┘    │
+│                                                             │
+│  3. If VALIDATOR finds issues:                              │
+│     - Main agent fixes                                      │
+│     - Spawn NEW validator (never reuse)                     │
+│     - Repeat until PASS                                     │
+│                                                             │
+│  Exit: Guard PASS + Isolated Validator PASS                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Skip isolation when:**
+- Simple changes (<3 functions AND <200 lines)
+- Pure refactoring (no behavior change)
+- Documentation-only changes
+
 ## Task Batching
 
 For multiple tasks:

invar_tools-1.12.0/.claude/skills/review/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: review
+description: Adversarial code review. Code is GUILTY until proven INNOCENT. Every round spawns isolated subagent reviewing FULL scope.
+_invar:
+  version: "7.0"
+  managed: skill
+---
+<!--invar:skill-->
+
+# Review Skill (Adversarial)
+
+## Mandatory Rules (MUST follow, NO exceptions)
+
+1. **EVERY round MUST spawn isolated subagent** (Task tool with model=opus)
+2. **EVERY round reviews FULL scope** (all files, not just changes)
+3. **Code is GUILTY until proven INNOCENT**
+4. **NO user confirmation between rounds** — just do it
+5. **MAX_ROUNDS = 5**
+
+**Violation = Review Invalid.** If you skip subagent or review only changes, the review is worthless.
+
+---
+
+## Scope Classification (DX-75)
+
+**Before starting, classify the scope:**
+
+| Classification | Criteria | Strategy |
+|----------------|----------|----------|
+| **SMALL** | <5 files AND <1500 lines | THOROUGH (no enumeration) |
+| **MEDIUM** | 5-10 files OR 1500-5000 lines | HYBRID (enum + open) |
+| **LARGE** | >10 files OR >5000 lines | CHUNKED (parallel subagents) |
+
+**Why different strategies?**
+- SMALL: Pre-enumeration causes "checklist mentality" — you only verify listed items, miss variants
+- LARGE: Without enumeration, attention drifts — later files get less scrutiny
+
+---
+
+## Strategy: THOROUGH (SMALL scope)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  THOROUGH STRATEGY (for SMALL scope)                        │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  ⚠️ DO NOT pre-enumerate issues or patterns                 │
+│  ⚠️ DO NOT use grep/sig to "find issues first"              │
+│                                                             │
+│  Instead:                                                   │
+│  1. Read each file COMPLETELY, line by line                 │
+│  2. Apply checklist A-G as you read                         │
+│  3. Trust your judgment to find issues                      │
+│  4. Look for VARIANTS and EDGE CASES                        │
+│                                                             │
+│  Why: Pre-enumeration narrows focus to known patterns.      │
+│  Small scope = you CAN read everything thoroughly.          │
+│  This finds issues that pattern matching misses.            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Strategy: HYBRID (MEDIUM scope)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  HYBRID STRATEGY (for MEDIUM scope)                         │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  Phase 0: ENUMERATE (Main Agent)                            │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Use grep/invar_sig to find:                        │   │
+│  │  - All @pre/@post contracts                         │   │
+│  │  - All @invar:allow escape hatches                  │   │
+│  │  - Hardcoded strings (secrets?)                     │   │
+│  │  - subprocess/exec/eval calls                       │   │
+│  │  - bare except clauses                              │   │
+│  │  Create issue_map with file:line for each           │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  Phase 1: GUIDED REVIEW (Isolated Subagent)                 │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  Pass issue_map to subagent                         │   │
+│  │  Subagent verifies each item                        │   │
+│  │  Reports: "Checked N/M items from issue_map"        │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                             │
+│  Phase 2: OPEN DISCOVERY (Same Subagent)                    │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  "Now forget the issue_map.                         │   │
+│  │   Look for issues NOT in the map:                   │   │
+│  │   - Variants of listed patterns                     │   │
+│  │   - Logic errors                                    │   │
+│  │   - Edge cases"                                     │   │
+│  │  Reports: "Found N additional issues"               │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Strategy: CHUNKED (LARGE scope)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CHUNKED STRATEGY (for LARGE scope)                         │
+│  ───────────────────────────────────────────────────────────│
+│                                                             │
+│  1. Split files into chunks of ~3-5 files each              │
+│                                                             │
+│  2. For each chunk (can be parallel):                       │
+│     - Spawn isolated subagent                               │
+│     - Use HYBRID strategy within chunk                      │
+│                                                             │
+│  3. Cross-chunk analysis:                                   │
+│     - Check cross-file dependencies                         │
+│     - Check API consistency                                 │
+│                                                             │
+│  4. Merge all findings, deduplicate                         │
+│                                                             │
+│  Why: Prevents "attention fatigue" on file 8+ of 15.        │
+│  Each chunk gets fresh attention.                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2-Step Loop (MANDATORY workflow)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Round N:                                                   │
+│                                                             │
+│  1. REVIEWER [Subagent] ─────────────────────────────────── │
+│     • Spawn NEW isolated agent (Task tool)                  │
+│     • Use strategy based on scope classification            │
+│     • Review ALL files in scope (full checklist A-G)        │
+│     • Return: issues[] or APPROVED                          │
+│                                                             │
+│  2. FIXER [Main Agent] ──────────────────────────────────── │
+│     • Fix CRITICAL/MAJOR issues with CODE                   │
+│     • Run invar_guard()                                     │
+│     • Cannot declare quality_met                            │
+│                                                             │
+│  → Loop until: APPROVED OR max_rounds OR no_progress        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Why new subagent each round?**
+- Main agent has context contamination from fixing
+- "Fresh eyes" impossible in same context
+- Round 2+ drifts to "verify my fixes" not "find problems"
+
+---
+
+## Review Checklist (apply to ALL files)
+
+> **Principle:** Only items requiring semantic judgment. Mechanical checks handled by Guard.
+
+### A. Contract Semantic Value
+
+- [ ] Does @pre constrain inputs beyond type checking?
+  - Bad: `@pre(lambda x: isinstance(x, int))`
+  - Good: `@pre(lambda x: x > 0 and x < MAX_VALUE)`
+- [ ] Does @post verify meaningful output properties?
+  - Bad: `@post(lambda result: result is not None)`
+  - Good: `@post(lambda result: len(result) == len(input))`
+- [ ] Could someone implement correctly from contracts alone?
+- [ ] Are boundary conditions explicit in contracts?
+
+### B. Doctest Coverage
+
+- [ ] Do doctests cover normal, boundary, and error cases?
+- [ ] Are doctests testing behavior, not just syntax?
+
+### C. Code Quality
+
+- [ ] Is duplicated code worth extracting?
+- [ ] Is naming consistent and clear?
+- [ ] Is complexity justified?
+
+### D. Escape Hatch Audit
+
+- [ ] Is each @invar:allow justification valid?
+- [ ] Could refactoring eliminate the need?
+
+### E. Logic Verification
+
+- [ ] Do contracts correctly capture intended behavior?
+- [ ] Are there paths that bypass contract checks?
+- [ ] Are there implicit assumptions not in contracts?
+
+### F. Security
+
+- [ ] Are inputs validated against security threats (injection, XSS)?
+- [ ] No hardcoded secrets (API keys, passwords, tokens)?
+- [ ] Are authentication/authorization checks correct?
+
+### G. Error Handling
+
+- [ ] Are exceptions caught at appropriate level?
+- [ ] Are error messages clear without leaking sensitive info?
+- [ ] Is there graceful degradation on failure?
+
+---
+
+## Subagent Prompt Templates
+
+### THOROUGH (SMALL scope)
+
+```
+You are an independent Adversarial Code Reviewer.
+
+RULES:
+1. Code is GUILTY until proven INNOCENT
+2. You did NOT write this code — no emotional attachment
+3. Find reasons to REJECT, not accept
+4. Be specific: file:line + concrete fix
+
+STRATEGY: THOROUGH READING
+- Read each file COMPLETELY, line by line
+- DO NOT pre-scan for patterns — just READ
+- Look for VARIANTS and EDGE CASES
+- Trust your judgment
+
+SCOPE: [list all files]
+
+Apply checklist A-G to each file.
+
+OUTPUT FORMAT:
+## Verdict: APPROVED | NEEDS WORK | REJECTED
+## Critical Issues (must fix)
+| ID | File:Line | Issue | Fix |
+## Major Issues (should fix)
+| ID | File:Line | Issue | Fix |
+## Minor Issues (backlog)
+| ID | File:Line | Issue | Fix |
+```
+
+### HYBRID (MEDIUM scope)
+
+```
+You are an independent Adversarial Code Reviewer.
+
+RULES:
+1. Code is GUILTY until proven INNOCENT
+2. You did NOT write this code — no emotional attachment
+3. Find reasons to REJECT, not accept
+4. Be specific: file:line + concrete fix
+
+STRATEGY: HYBRID (two passes)
+
+PASS 1 - GUIDED:
+Using this issue_map, verify each potential issue:
+[issue_map from Phase 0]
+
+Report: "Verified X/Y items from issue_map"
+
+PASS 2 - OPEN DISCOVERY:
+Now FORGET the issue_map. Read the code fresh.
+Look for issues NOT in the map:
+- Variants of listed patterns
+- Logic errors
+- Edge cases
+
+Report: "Found N additional issues not in issue_map"
+
+SCOPE: [list all files]
+
+OUTPUT FORMAT:
+## Verdict: APPROVED | NEEDS WORK | REJECTED
+## From Issue Map (Pass 1)
+| ID | File:Line | Issue | Fix |
+## Additional Findings (Pass 2)
+| ID | File:Line | Issue | Fix |
+```
+
+---
+
+## Exit Conditions
+
+| Condition | Exit Reason | Result |
+|-----------|-------------|--------|
+| Subagent returns APPROVED | `quality_met` | Ready for merge |
+| round >= 5 | `max_rounds` | Manual review needed |
+| Same issues 2 rounds | `no_improvement` | Architectural issue |
+
+---
+
+## Exit Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 REVIEW COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Scope:** SMALL | MEDIUM | LARGE
+**Strategy:** THOROUGH | HYBRID | CHUNKED
+**Exit:** quality_met | max_rounds | no_improvement
+**Rounds:** N / 5
+**Guard:** PASS | FAIL
+
+## Issues Table
+| Issue | Severity | Round | Status | Evidence |
+
+## Round Summary
+| Round | Found | Fixed |
+
+✓ Final: guard PASS | X errors, Y warnings
+```
+
+---
+
+## Scope Boundaries
+
+**IS for:** Finding bugs, verifying contracts, security review
+**NOT for:** New features → /develop | Understanding → /investigate
+
+## Excluded (Covered by Guard)
+
+Don't duplicate mechanical checks:
+- Core/Shell separation → Guard
+- Missing contracts → Guard
+- File/function size → Guard
+
+<!--/invar:skill--><!--invar:extensions-->
+<!-- User extensions preserved on update -->
+<!--/invar:extensions-->

{invar_tools-1.10.0 → invar_tools-1.12.0}/.github/workflows/ci.yml

@@ -48,9 +48,15 @@ jobs:
 
       - name: Check types with mypy
         run: |
-          mypy src/invar/ --ignore-missing-imports
-          mypy runtime/src/invar_runtime/ --ignore-missing-imports
-        continue-on-error: true
+          # Type check critical modules (MCP handlers, doc tools)
+          # Using --follow-imports=silent to check only specified files, not transitive deps
+          # Gradually expanding coverage. Templates excluded as example code.
+          mypy src/invar/mcp/handlers.py \
+               src/invar/core/doc_parser.py \
+               src/invar/core/doc_edit.py \
+               src/invar/shell/doc_tools.py \
+               --ignore-missing-imports \
+               --follow-imports=silent
 
   lint:
     runs-on: ubuntu-latest

{invar_tools-1.10.0 → invar_tools-1.12.0}/.invar/context.md

@@ -51,10 +51,10 @@
 
 ## Current State
 
-- **PyPI:** `invar-tools` v1.10.0 + `invar-runtime` v1.3.0
+- **PyPI:** `invar-tools` v1.12.0 + `invar-runtime` v1.3.0
 - **Protocol:** v5.0 (USBV workflow, DX-58 critical section)
-- **Status:** Feature complete, TypeScript support added
-- **Recent:** LX-05 (language-agnostic), LX-06 (TypeScript tooling), LX-07 (Extension Skills)
+- **Status:** Feature complete, TypeScript support added (DX-78)
+- **Recent:** DX-78 (TypeScript Compiler API integration), LX-05 (language-agnostic), LX-06 (TypeScript tooling), LX-07 (Extension Skills)
 - **Blockers:** None
 
 ## Active Work
@@ -117,6 +117,55 @@ Smart Guard (`invar guard`) runs multiple verification layers:
 
 ---
 
+## TypeScript Integration (DX-78)
+
+**Status:** Complete and reviewed (2026-01-03)
+
+### Architecture
+
+- **Python wrapper:** `src/invar/shell/ts_compiler.py` (uses subprocess to call Node.js)
+- **TypeScript tool:** `src/invar/node_tools/ts-query.js` (TypeScript Compiler API)
+- **Python refs:** `src/invar/shell/py_refs.py` (jedi library)
+- **CLI integration:** `perception.py`, `guard.py` (multi-language routing)
+- **MCP integration:** `handlers.py`, `server.py` (invar_refs tool)
+
+### Supported Commands
+
+| Command | Python | TypeScript |
+|---------|--------|------------|
+| `invar sig <file>` | ✅ | ✅ |
+| `invar map <path>` | ✅ | ✅ |
+| `invar refs <file>::<symbol>` | ✅ (jedi) | ✅ (TS Compiler API) |
+
+### Security Model
+
+- **Single-shot subprocess:** Process starts, runs query, outputs JSON, exits
+- **No orphan risk:** No persistent Node.js processes
+- **Path validation:** All file paths validated before subprocess execution
+- **JSON parsing:** Input validation with error handling
+
+### Dependencies
+
+- **Runtime:** Node.js + TypeScript package (peer dependency)
+- **Python:** jedi library (required for Python refs)
+- **Detection:** Automatic via tsconfig.json presence
+
+### Known Limitations
+
+- Requires tsconfig.json in project root
+- TypeScript project must be compilable
+- No support for decorator metadata yet
+
+### Review History
+
+- **2026-01-03:** Adversarial review completed
+  - Fixed 4 critical TypeScript bugs (JSON parsing, null checks, I/O error handling, TOCTOU)
+  - Fixed 5 major Python bugs (column hardcoding, missing markers, weak tests, dynamic types)
+  - 32 integration tests passing
+  - Guard: 0 errors, 0 warnings
+
+---
+
 ## Release Process
 
 **Do NOT use `twine upload` manually.** GitHub Actions handles PyPI publishing.
@@ -136,6 +185,7 @@ gh release create vX.Y.Z --title "vX.Y.Z - Title" --notes "..."
 
 | Version | Date | Highlights |
 |---------|------|------------|
+| 1.12.0 | 2026-01 | TypeScript Compiler API integration (DX-78), multi-language refs |
 | 1.9.0 | 2026-01 | Extension Skills (LX-07), TypeScript support (LX-05/06) |
 | 1.8.0 | 2025-12 | Claude hooks improvements, interactive init (DX-70) |
 | 1.5.0 | 2025-12 | Language-agnostic protocol templates |

{invar_tools-1.10.0 → invar_tools-1.12.0}/.pre-commit-config.yaml

@@ -26,6 +26,15 @@ repos:
         stages: [pre-commit]
         types: [python]
 
+      # Mypy - Static type checker (checks critical modules only)
+      - id: mypy
+        name: Type Check (mypy)
+        entry: bash -c 'source .venv/bin/activate && mypy src/invar/mcp/handlers.py src/invar/core/doc_parser.py src/invar/core/doc_edit.py src/invar/shell/doc_tools.py --ignore-missing-imports --follow-imports=silent'
+        language: system
+        pass_filenames: false
+        stages: [pre-commit]
+        types: [python]
+
       # Smart Invar Guard - Full verification (static + doctests)
       # Runs full guard when rule files are modified, --changed otherwise
       # Note: invar guard already includes doctests, no separate pytest needed

{invar_tools-1.10.0 → invar_tools-1.12.0}/CLAUDE.md

@@ -288,6 +288,37 @@ When continuing from a previous session summary:
 3. **Display phase header** before resuming work
 4. **Re-read context.md** for project state
 
+## TypeScript Code Review
+
+**CRITICAL:** TypeScript files in `src/invar/node_tools/` are PART of this project and MUST be reviewed.
+
+When reviewing TypeScript code (*.js, *.ts files):
+
+### TypeScript-Specific Checklist
+
+- [ ] **Error Handling:** All `JSON.parse()` calls wrapped in try/catch
+- [ ] **Null Safety:** Optional property access uses `?.` or explicit null checks
+- [ ] **I/O Safety:** All `fs.readFileSync()` wrapped in try/catch
+- [ ] **Race Conditions:** No TOCTOU (check-then-use) patterns with file operations
+- [ ] **Type Guards:** Runtime type checks for external inputs
+- [ ] **Resource Cleanup:** No resource leaks in language services
+
+### Common TypeScript Vulnerabilities
+
+| Pattern | Risk | Fix |
+|---------|------|-----|
+| `JSON.parse(input)` | Crashes on invalid JSON | `try { JSON.parse() } catch { error }` |
+| `obj.prop.method()` | TypeError if prop is null | `obj.prop?.method()` or null check |
+| `if (exists(f)) read(f)` | TOCTOU race condition | `try { read(f) } catch { handle }` |
+| `fs.readFileSync()` in loop | One error kills all | Wrap each call in try/catch |
+
+### Integration Points
+
+TypeScript files interact with Python via:
+- **Subprocess:** Node.js process spawned by Python wrapper
+- **JSON protocol:** Structured input/output via stdin/stdout
+- **Path safety:** All file paths validated in Python layer before subprocess
+
 <!--/invar:user-->
 
 ---

{invar_tools-1.10.0 → invar_tools-1.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invar-tools
-Version: 1.10.0
+Version: 1.12.0
 Summary: AI-native software engineering tools with design-by-contract verification
 Project-URL: Homepage, https://github.com/tefx/invar
 Project-URL: Documentation, https://github.com/tefx/invar#readme
@@ -24,7 +24,9 @@ Requires-Python: >=3.11
 Requires-Dist: crosshair-tool>=0.0.60
 Requires-Dist: hypothesis>=6.0
 Requires-Dist: invar-runtime>=1.0
+Requires-Dist: jedi>=0.19
 Requires-Dist: jinja2>=3.0
+Requires-Dist: markdown-it-py>=3.0
 Requires-Dist: mcp>=1.0
 Requires-Dist: pre-commit>=3.0
 Requires-Dist: pydantic>=2.0
@@ -145,7 +147,19 @@ Guard passed.
 
 ## 🚀 Quick Start
 
-> **Language Support:** Python (full), TypeScript (verification via Zod contracts).
+### Tool × Language Support
+
+| Tool | Python | TypeScript | Notes |
+|------|--------|------------|-------|
+| `invar guard` | ✅ Full | ⚠️ Partial | TS: tsc + eslint + vitest |
+| `invar sig` | ✅ Full | ✅ Full | TS: TS Compiler API |
+| `invar map` | ✅ Full | ✅ Full | TS: With reference counts |
+| `invar refs` | ✅ Full | ✅ Full | Cross-file reference finding |
+| `invar doc *` | ✅ Full | ✅ Full | Language-agnostic |
+
+**TypeScript Notes:**
+- Requires Node.js + TypeScript (most TS projects have these)
+- Falls back to regex parser if Node.js unavailable
 
 ### 📦 Two Packages, Different Purposes
 
@@ -178,6 +192,7 @@ uvx invar-tools init
 # Or quick setup (skip prompts)
 uvx invar-tools init --claude    # Claude Code
 uvx invar-tools init --pi        # Pi Coding Agent
+uvx invar-tools init --mcp-only  # MCP tools only (legacy projects)
 
 # Add runtime contracts to your project
 pip install invar-runtime
@@ -301,14 +316,17 @@ function average(items: number[]): number {
 
 ### ✅ Solution 2: Multi-Layer Verification
 
-Guard provides fast feedback. Agent sees errors, fixes immediately:
+Guard provides fast feedback **on top of standard type checking**. Agent sees errors, fixes immediately:
 
 | Layer | Tool | Speed | What It Catches |
 |-------|------|-------|-----------------|
+| **Type Check*** | mypy (Python) / tsc (TypeScript) | ~1s | Type errors, missing annotations |
 | **Static** | Guard rules | ~0.5s | Architecture violations, missing contracts |
-| **Doctest** | pytest | ~2s | Example correctness |
-| **Property** | Hypothesis | ~10s | Edge cases via random inputs |
-| **Symbolic** | CrossHair | ~30s | Mathematical proof of contracts |
+| **Doctest** | pytest / vitest | ~2s | Example correctness |
+| **Property** | Hypothesis / fast-check | ~10s | Edge cases via random inputs |
+| **Symbolic** | CrossHair / (TS: N/A) | ~30s | Mathematical proof of contracts |
+
+<sup>* Requires separate installation: `pip install mypy` or configure TypeScript in your project</sup>
 
 ```
 ┌──────────┐   ┌───────────┐   ┌───────────┐   ┌────────────┐
@@ -523,7 +541,7 @@ Cursor users get full verification via MCP:
 |----------------|---------|----------|
 | `INVAR.md` | Protocol for AI agents | Required |
 | `.invar/` | Config, context, examples | Required |
-| `.pre-commit-config.yaml` | Verification before commit | Optional |
+| `.pre-commit-config.yaml` | Verification before commit (Ruff, mypy*, Guard) | Optional |
 | `src/core/`, `src/shell/` | Recommended structure | Optional |
 | `CLAUDE.md` | Agent instructions | Claude Code |
 | `.claude/skills/` | Workflow + extension skills | Claude Code |
@@ -532,6 +550,8 @@ Cursor users get full verification via MCP:
 | `.mcp.json` | MCP server config | Claude Code |
 | `AGENT.md` | Universal agent instructions | Other agents |
 
+<sup>* mypy hook included in `.pre-commit-config.yaml` but requires: `pip install mypy`</sup>
+
 **Note:** If `pyproject.toml` exists, Guard configuration goes there as `[tool.invar.guard]` instead of `.invar/config.toml`.
 
 **Recommended structure:**
@@ -584,7 +604,22 @@ These customizations are preserved when updating skills via `invar skill add`.
 
 ## 🔄 Legacy Project Migration
 
-For existing projects that want to adopt Invar's patterns, use the `/invar-onboard` skill:
+### Quick Start: MCP Tools Only
+
+For projects that want Invar's MCP tools **without adopting the framework**:
+
+```bash
+uvx invar-tools init --mcp-only
+```
+
+This creates only `.mcp.json` — no INVAR.md, CLAUDE.md, or Core/Shell structure. Your AI agent gets access to:
+- **Document tools** (`invar_doc_toc`, `invar_doc_read`, etc.)
+- **Code navigation** (`invar_sig`, `invar_map`)
+- **Basic verification** (`invar_guard` with minimal rules)
+
+### Full Adoption: `/invar-onboard`
+
+For projects that want to fully adopt Invar's patterns, use the `/invar-onboard` skill:
 
 ```bash
 # Install the onboarding skill
@@ -785,9 +820,17 @@ rules = ["missing_contract", "shell_result"]
 | `invar guard --coverage` | Collect branch coverage from tests |
 | `invar init` | Initialize or update project (interactive) |
 | `invar init --claude` | Quick setup for Claude Code |
+| `invar init --pi` | Quick setup for Pi agent |
+| `invar init --mcp-only` | MCP tools only (no framework files) |
 | `invar uninstall` | Remove Invar from project (preserves user content) |
 | `invar sig <file>` | Show signatures and contracts |
 | `invar map` | Symbol map with reference counts |
+| `invar doc toc <file>` | View document structure (headings) |
+| `invar doc read <file> <section>` | Read specific section by slug/fuzzy/index |
+| `invar doc find <pattern> <files>` | Search sections by title pattern |
+| `invar doc replace <file> <section>` | Replace section content |
+| `invar doc insert <file> <anchor>` | Insert content relative to section |
+| `invar doc delete <file> <section>` | Delete section |
 | `invar rules` | List all rules with severity |
 | `invar test` | Property-based tests (Hypothesis) |
 | `invar verify` | Symbolic verification (CrossHair) |
@@ -805,6 +848,13 @@ rules = ["missing_contract", "shell_result"]
 | `invar_guard` | Smart multi-layer verification |
 | `invar_sig` | Extract signatures and contracts |
 | `invar_map` | Symbol map with reference counts |
+| `invar_doc_toc` | Extract document structure (TOC) |
+| `invar_doc_read` | Read specific section |
+| `invar_doc_read_many` | Read multiple sections (batch) |
+| `invar_doc_find` | Search sections by title pattern |
+| `invar_doc_replace` | Replace section content |
+| `invar_doc_insert` | Insert content relative to section |
+| `invar_doc_delete` | Delete section |
 
 ---