purecontext-mcp 1.1.0 → 1.1.2

package/guide/why-purecontext.md

@@ -0,0 +1,73 @@
+# Why PureContext
+
+## The problem is not tokens. It's accuracy.
+
+When an AI agent works with your code, the quality of its answers depends entirely on what you put in front of it. Give it an entire 800-line file to find one function and two things happen: you burn thousands of tokens getting there, and the AI spends most of that context on code that has nothing to do with your question.
+
+Token savings are the measurable side effect of a more fundamental improvement: **AI gets better answers from precise context than from bulk context.**
+
+A 45-line function retrieved by name gives Claude exactly what it needs. An 800-line file gives Claude the function plus seven unrelated utilities, three deprecated helpers, a wall of imports, and a pile of comments about things that were fixed in 2019. All of that crowds out the signal.
+
+PureContext fixes this by giving AI agents a way to navigate code the way experienced engineers do — by name, by meaning, by dependency — rather than by reading everything and hoping.
+
+---
+
+## What changes in practice
+
+### Your AI assistant gets fewer hallucinations
+
+Hallucinations in coding tasks most often happen when the AI is working from incomplete or outdated context. If Claude has to read a file from two weeks ago that you haven't reindexed, or guess at function signatures from imports rather than seeing the actual definition, it will make things up convincingly.
+
+PureContext indexes your codebase on demand and re-indexes incrementally as you work. When Claude asks for `validatePaymentMethod`, it gets the current definition — not a guess, not a stale version, the actual code as it exists right now.
+
+### You stop copy-pasting code into the chat
+
+Without PureContext, a typical conversation goes:
+
+> "I need help understanding how the order processing pipeline works."
+> *[You open five files, copy the relevant parts, paste them into the chat]*
+> "Here's the OrderProcessor class, here's the CartValidator, here's..."
+
+With PureContext, Claude navigates the codebase itself. You describe what you want to understand and Claude fetches the relevant symbols, follows the dependency chain, and builds its own picture. You stay in the conversation; you're not the file fetcher.
+
+### Large codebases become navigable
+
+A solo developer working on a 500-file TypeScript monorepo, and an enterprise team working on a 40,000-file Java platform, face the same structural problem: the codebase is too large to hold in any context window. PureContext makes both tractable by turning "read these files" into "retrieve these symbols."
+
+The difference matters most in enterprise environments where no single person knows the whole codebase, onboarding takes months, and getting AI to help requires giving it enough context to be useful without hitting token limits.
+
+### AI agents can plan changes safely
+
+Before PureContext, asking an AI to help you change a core function was risky. The AI didn't know what depended on it. It couldn't see what would break.
+
+With the dependency graph tools, Claude can check the blast radius of any change before touching it — see what imports the function, follow the transitive dependency chain, and tell you "this change will affect 14 files across 3 services." That's the difference between AI assistance and AI guesswork.
+
+---
+
+## Who this is for
+
+**Solo developers** get a faster inner loop. Index your project once, then navigate it with natural language instead of file browsing. The AI remembers the structure so you don't have to keep re-explaining it in every conversation.
+
+**Teams** get a shared understanding of the codebase. When one developer indexes the repository on a shared server, everyone on the team can search it. New developers get a pre-built picture of the codebase on day one. Senior engineers don't spend their week explaining architecture.
+
+**Enterprise environments** get the audit trails, access controls, rate limiting, and Docker-based deployment that make AI-assisted development compatible with security requirements. PureContext doesn't read your code and send it to a third party — it indexes locally and serves over your own network.
+
+---
+
+## What PureContext is not
+
+It is not a replacement for reading code. There will always be times when you need to read a file carefully, understand edge cases, or review logic line by line. PureContext makes those moments targeted — you know which file, which function, which 45 lines matter — instead of exploratory.
+
+It is not a code editor or language server. It does not type-check, lint, or autocomplete. Those tools solve different problems.
+
+It is not magic. The quality of its output depends on the quality of your codebase structure, documentation, and naming. Well-named functions with docstrings are searchable from the first index. Undocumented spaghetti becomes searchable with AI summarization enabled — but meaningful naming still wins.
+
+---
+
+## The compounding effect
+
+The value of PureContext grows with use. The index improves as your codebase improves. The dependency graph becomes more useful as you add more framework adapters. Git history integration becomes richer as the project ages. AI summaries mean that even undocumented code becomes discoverable.
+
+On a fresh solo project: **useful from day one** for navigation and symbol retrieval.
+
+On a two-year-old enterprise codebase: **transformative** — because that's where the navigation problem is most acute and where accurate AI assistance has the most value.

package/guide/workflow-onboarding.md

@@ -0,0 +1,114 @@
+# Workflow: Onboarding to a New Codebase
+
+**Scenario:** You've just joined a fintech startup. The codebase is a Node.js/TypeScript monorepo with eight microservices — payments, accounts, notifications, reporting, identity, audit, gateway, and shared-lib. Total: ~6,000 files, ~80,000 symbols. Your first task is to fix a bug in the payment processing flow. You don't know the codebase at all.
+
+Your tech lead has indexed the shared PureContext server and given you an API key. This is your first day.
+
+---
+
+## The session
+
+**You:** "I'm new to this codebase. I need to understand how the payment processing flow works — from when a user submits a payment to when it's confirmed. Can you walk me through it?"
+
+**Claude** calls `get_file_tree` and `search_symbols(query: "payment", kind: "route")`:
+
+```
+Payment-related routes:
+  POST /v1/payments              services/gateway/src/routes/payments.ts
+  POST /v1/payments/:id/capture  services/gateway/src/routes/payments.ts
+  GET  /v1/payments/:id          services/gateway/src/routes/payments.ts
+```
+
+Entry point found: the gateway service handles incoming payment requests. Claude calls `get_file_outline("services/gateway/src/routes/payments.ts")`:
+
+```
+PaymentRoutes
+  handleCreatePayment()   POST handler, validates request, forwards to payment service
+  handleCapturePayment()  Captures a previously authorized payment
+  handleGetPayment()      Returns payment status
+```
+
+**Claude:** "Payment requests enter through the gateway service at `handleCreatePayment`. Let me trace what happens from there."
+
+Claude calls `get_context_bundle(symbolId: "handleCreatePayment", maxDepth: 2)`:
+
+```
+Context bundle (depth 2, ~2,400 tokens):
+
+  handleCreatePayment()      gateway/routes/payments.ts     — the entry handler
+  PaymentServiceClient       gateway/clients/payment.ts     — gRPC client to payment service
+  createPayment()            services/payment/src/core.ts   — the actual business logic
+  validatePaymentRequest()   services/payment/src/validators.ts
+  PaymentRepository          services/payment/src/db/repo.ts
+  ChargeProvider             services/payment/src/providers/stripe.ts
+```
+
+**Claude:** "The flow is: gateway receives the HTTP request → validates it → calls the payment service via gRPC → the payment service validates the request, saves a record, and calls the Stripe provider. Let me get the source for `createPayment` so you can see the core logic."
+
+You now understand the service topology and the call chain — from an HTTP POST to a Stripe API call — in under 2 minutes, without reading a single file manually.
+
+---
+
+## Finding the bug
+
+**You:** "The bug I'm looking at is that payments are being marked as 'confirmed' even when Stripe returns a 'requires_action' status. Where would that status handling be?"
+
+**Claude** calls `search_symbols(query: "requires_action")`:
+
+```
+No exact match. Trying semantic search...
+
+search_semantic(query: "handle stripe payment status requires action") →
+
+  handlePaymentStatus()    services/payment/src/status-handler.ts    similarity: 0.92
+  processStripeWebhook()   services/payment/src/webhooks/stripe.ts   similarity: 0.87
+  updatePaymentState()     services/payment/src/state-machine.ts     similarity: 0.84
+```
+
+**Claude:** "`handlePaymentStatus` looks like the most likely location. Let me retrieve it."
+
+`get_symbol_source(symbolId: "handlePaymentStatus")` returns 67 lines. Claude reads it and finds:
+
+```typescript
+case 'requires_action':
+case 'requires_payment_method':
+  // TODO: implement 3DS handling
+  return updatePaymentState(paymentId, 'confirmed'); // ← the bug
+```
+
+Found in 4 minutes. Without PureContext, you'd have been reading files in the payment service hoping to find the status handling code.
+
+---
+
+## Understanding the impact before fixing
+
+**You:** "Before I fix this, I need to understand what else depends on `updatePaymentState`. If I change how it works, what breaks?"
+
+**Claude** calls `get_blast_radius(symbolId: "updatePaymentState")`:
+
+```
+updatePaymentState() is imported by 8 files:
+
+  services/payment/src/status-handler.ts    (the file we're fixing)
+  services/payment/src/webhooks/stripe.ts   (webhook handler)
+  services/payment/src/retry.ts             (retry logic)
+  services/payment/test/status.test.ts      (tests)
+  services/payment/test/integration.test.ts
+  services/reporting/src/sync.ts            (cross-service! reporting reads payment state)
+  services/audit/src/listeners.ts           (cross-service! audit logs state changes)
+  services/notifications/src/triggers.ts    (cross-service! triggers on state changes)
+```
+
+**Claude:** "Changing `updatePaymentState` affects three other services: reporting, audit, and notifications. The fix to handle `requires_action` correctly shouldn't break these — they're just listening for state changes — but you should verify the test coverage in each service."
+
+You now know the blast radius of your fix before writing a line. You know which tests to run and which service owners to notify. This conversation — from "I'm new" to "I understand the fix and its impact" — took about 15 minutes.
+
+---
+
+## What made this possible
+
+- **No file browsing.** You never opened a file explorer or searched GitHub. Claude navigated the codebase and retrieved exactly the relevant code.
+- **No onboarding sessions needed.** A senior engineer's time was not required. The shared index gave Claude enough context to explain the architecture accurately.
+- **Bug found by meaning, not name.** `search_semantic` found `handlePaymentStatus` even though it didn't contain the exact search terms.
+- **Impact known before the fix.** `get_blast_radius` revealed the cross-service dependencies that aren't obvious from reading the payment service alone.
+- **Token efficient.** The entire session — architecture overview, bug location, blast radius analysis — used roughly 8,000 tokens. Reading the relevant files directly would have cost 50,000+ tokens and still required knowing which files to read.

package/guide/workflow-pr-review.md

@@ -0,0 +1,199 @@
+# Workflow: Reviewing a Pull Request
+
+**Scenario:** It's Tuesday morning. You open GitHub and find a pull request sitting in your queue: "Migrate user authentication to OAuth2 — 40 files changed." You're the designated reviewer. The author is a colleague you trust, but this is a large, cross-cutting change affecting the core authentication flow. You have about 45 minutes before your next meeting.
+
+Without context, you'd start reading diffs top to bottom, hoping to understand the intent as you go. With PureContext, you start by understanding the impact, then read strategically.
+
+---
+
+## Step 1: Understand the scope before reading anything
+
+**You:** "I have a PR to review — 40 files changed in the authentication migration. Before I read any diffs, give me a symbol-level analysis of what actually changed."
+
+**Claude** calls `analyze_diff(base: "main", head: "feature/oauth2-migration")`:
+
+```
+Symbols modified (signature changed — potential breaking changes):
+  authenticateUser()         apps/auth/validator.py    signature changed
+  require_auth               apps/auth/decorators.py   implementation changed
+  UserPermissions            apps/core/types.py         fields added
+
+Symbols modified (implementation only — no signature change):
+  JWTMiddleware              apps/auth/middleware.py    replaced internally
+  createSession()            apps/auth/session.py       updated token format
+  ... (12 more)
+
+Symbols added (new in this PR):
+  OAuthClient                apps/auth/oauth2.py        new class
+  exchangeOAuthCode()        apps/auth/oauth2.py        new
+  refreshOAuthToken()        apps/auth/oauth2.py        new
+  OAuthCallbackView          apps/auth/views.py          new
+  ... (8 more)
+
+Symbols deleted:
+  generateLegacyToken()      apps/auth/legacy.py        removed
+  OldSessionManager          apps/auth/sessions.py      removed
+  validateBasicAuth()        apps/auth/basic.py         removed
+
+Blast radius of modified symbols: 47 files
+Review priority: HIGH (signature changes to authenticateUser and require_auth)
+```
+
+In 30 seconds you know:
+- The signature of `authenticateUser` changed — everything that calls it may need to be checked
+- `require_auth` was modified — it wraps 134 view functions, so behavior changes here affect the entire application
+- Three symbols were deleted — are they truly dead, or are there call sites the PR missed?
+- The real blast radius is 47 files, not 40 (some impact is indirect)
+
+This frames your entire review before you've read a diff.
+
+---
+
+## Step 2: Verify the deleted symbols were actually unused
+
+The deleted symbols are the first concern. Deleting code that's still called causes a runtime error.
+
+**You:** "Three symbols were deleted. Verify that they had no importers in main — confirm they were actually dead code before this PR."
+
+**Claude** calls `get_blast_radius` on each deleted symbol against the main branch index:
+
+```
+generateLegacyToken()  — 0 importers in main (confirmed dead)
+OldSessionManager      — 0 importers in main (confirmed dead)
+validateBasicAuth()    — 0 importers in main (confirmed dead)
+```
+
+All three confirmed dead. The author cleaned up dead code correctly. This concern is closed.
+
+---
+
+## Step 3: Check the signature change for `authenticateUser`
+
+A signature change to a function is the highest-risk change in any PR. It means every call site needs to handle the new interface.
+
+**You:** "authenticateUser changed its signature. Show me the old signature, the new one, and all the places that call it."
+
+**Claude** retrieves the symbol history for `authenticateUser` and the current source:
+
+```
+Old signature (main):
+  def authenticate_user(username: str, password: str) -> Optional[User]
+
+New signature (this PR):
+  def authenticate_user(credentials: OAuthCredentials | PasswordCredentials) -> AuthResult
+```
+
+The parameter type changed from two positional strings to a union type, and the return type changed from `Optional[User]` to `AuthResult`. This is a significant interface change.
+
+**Claude** calls `find_references(symbolId: "authenticateUser")` on the current branch:
+
+```
+authenticate_user() is called in 6 places:
+
+  apps/auth/views.py:45      LoginView.post()         ← using new signature ✓
+  apps/users/tests/test_auth.py:23   test_login()    ← updated ✓
+  apps/users/tests/test_auth.py:67   test_lockout()  ← updated ✓
+  apps/api/auth.py:89        api_login()              ← using new signature ✓
+  apps/admin/views.py:134    admin_login()            ← still using old signature ✗
+  apps/integrations/sso.py:67  sso_authenticate()    ← still using old signature ✗
+```
+
+Two call sites weren't updated. `admin_login` and `sso_authenticate` are still passing two positional string arguments. This is a bug in the PR — it would pass type checking if the types weren't enforced strictly, but would fail at runtime.
+
+You've found the blocking issue in the PR. Two minutes into the review.
+
+---
+
+## Step 4: Verify the critical path
+
+`require_auth` is the decorator used by 134 views. It was modified. You need to know the modification is backward compatible.
+
+**You:** "require_auth was modified. Show me what changed and verify that all 134 views that use it still work with the new implementation."
+
+**Claude** retrieves the new source for `require_auth`:
+
+```python
+def require_auth(view_func):
+    @wraps(view_func)
+    def wrapper(request, *args, **kwargs):
+        # NEW: Accept both JWT (legacy) and OAuth2 Bearer tokens
+        auth_header = request.META.get('HTTP_AUTHORIZATION', '')
+        if auth_header.startswith('Bearer '):
+            user = authenticate_oauth_token(auth_header[7:])
+        else:
+            user = authenticate_jwt_token(request)  # legacy path preserved
+        if user is None:
+            return HttpResponse(status=401)
+        request.user = user
+        return view_func(request, *args, **kwargs)
+    return wrapper
+```
+
+The implementation accepts both token formats — OAuth2 Bearer tokens and the legacy JWT. The 134 decorated views don't need to be updated because the decorator handles the transition transparently. This is a good implementation decision, and it's verifiable from the code.
+
+**You:** "This looks correct — it's a compatible shim. But check: is there any test that specifically covers the JWT fallback path in the new implementation?"
+
+**Claude** calls `search_symbols(query: "authenticate_jwt_token", filePath: "tests/**")`:
+
+```
+authenticate_jwt_token referenced in tests:
+  tests/auth/test_middleware.py    test_jwt_fallback()   ← exists ✓
+  tests/auth/test_decorators.py    test_require_auth()   ← exists ✓
+```
+
+The fallback path is tested. The implementation is sound.
+
+---
+
+## Step 5: Check for any missed text-level dependencies
+
+Symbol analysis catches structured dependencies. But JWT-specific string patterns — cache keys, token format strings, configuration keys — might be missed.
+
+**You:** "Search for any remaining references to the old JWT configuration key or the old session format that might have been missed."
+
+**Claude** calls `search_text(query: "JWT_SECRET", filePath: "**/*.py")`:
+
+```
+Remaining JWT_SECRET references:
+  apps/auth/oauth2.py:156    settings.JWT_SECRET   ← why does the new OAuth module reference this?
+```
+
+Unexpected. The new OAuth2 module references `JWT_SECRET`. You open the source:
+
+```python
+# Temporary: use JWT_SECRET as the OAuth state parameter signing key
+# TODO: Replace with dedicated OAUTH_STATE_SECRET before merge
+state_sig = hmac.new(settings.JWT_SECRET.encode(), ...)
+```
+
+The author left a TODO comment but didn't create a separate configuration key. This is a code smell — the OAuth implementation is reusing the JWT secret for a different purpose, which violates key isolation. Flag it in the review.
+
+---
+
+## The review summary
+
+45 minutes, structured review. Findings:
+
+| Finding | Severity | Location |
+|---------|----------|----------|
+| `authenticate_user` called with old signature | **Blocking** | `admin/views.py:134`, `integrations/sso.py:67` |
+| JWT secret reused as OAuth state signing key | **Major** — flag before merge | `auth/oauth2.py:156` |
+| Deleted symbols confirmed dead | **Pass** | legacy.py, sessions.py, basic.py |
+| `require_auth` shim correctly backward compatible | **Pass** | auth/decorators.py |
+| Legacy fallback path covered by tests | **Pass** | tests/auth/ |
+
+You found two real issues — one blocking, one major — before reading most of the diff. The blocking issue (two call sites using the wrong signature) would have been a runtime error in production. The major issue (key reuse) is a security design problem.
+
+---
+
+## What made this review effective
+
+**Start with impact, not diffs.** `analyze_diff` gave you the symbol-level map before you read anything. You knew where to focus.
+
+**Verify deletions first.** Deleted code that's still called is the most dangerous class of PR error. Checking blast radius for deleted symbols takes 30 seconds and catches the worst case.
+
+**Find all call sites for signature changes.** `find_references` across the branch revealed the two missed call sites that static analysis alone might have missed in a dynamically typed codebase.
+
+**Use text search for string-level dependencies.** Symbol analysis doesn't catch JWT_SECRET usage in string context. Text search does.
+
+**Know when to stop.** With the two blocking issues identified and the critical path verified, you have what you need to write a meaningful review. You don't need to read all 40 diffs to give a quality review — you need to read the right ones.

package/guide/workflow-refactoring.md

@@ -0,0 +1,172 @@
+# Workflow: Refactoring Legacy Code
+
+**Scenario:** Your team inherited a legacy Python web application — a Django monolith that's been running for six years. The authentication system uses a custom JWT implementation that predates the team's tenure. You've been asked to replace it with a standard OAuth2 flow. The problem: nobody on the current team fully understands how the old authentication system is wired together. It grew organically, it's partially documented, and there are integration tests that haven't run in eight months.
+
+This is not a rare scenario. It is the normal state of software that has lived long enough.
+
+---
+
+## Phase 1: Understand what exists
+
+**You:** "I need to replace the legacy JWT authentication with OAuth2. Before touching anything, help me understand how the current authentication system works — what it's made of, where it's used, and what depends on it."
+
+**Claude** calls `search_symbols(query: "authenticate", filePath: "apps/auth/**")`:
+
+```
+apps/auth/jwt.py             authenticate_token()    function
+apps/auth/jwt.py             generate_token()        function
+apps/auth/jwt.py             validate_claims()       function
+apps/auth/middleware.py      JWTMiddleware            class
+apps/auth/decorators.py      require_auth             function (decorator)
+apps/auth/views.py           LoginView                class (view)
+apps/auth/views.py           LogoutView               class (view)
+apps/auth/views.py           RefreshTokenView         class (view)
+```
+
+Eight symbols in the auth module. Claude retrieves the outline for each file and builds a mental model. Then you ask the critical question:
+
+**You:** "How widely is `require_auth` used across the application? This is the decorator — everything using it will need to work differently after the migration."
+
+**Claude** calls `get_blast_radius(symbolId: "require_auth")`:
+
+```
+require_auth is used in 47 files across 12 Django apps:
+
+  apps/users/views.py           18 decorated views
+  apps/billing/views.py         12 decorated views
+  apps/orders/views.py          9 decorated views
+  apps/admin_panel/views.py     6 decorated views
+  apps/api/views.py             31 decorated views
+  ... (7 more apps)
+
+  Total decorated views: 134
+  Also used in: 3 custom middleware files
+```
+
+134 views. The scope is clear before you've planned a single line of migration. You're not doing a small change — you're touching the entire application's access control layer.
+
+---
+
+## Phase 2: Understand the current implementation
+
+**You:** "Let me see the full context bundle for authenticate_token — I need to understand exactly how it works before designing the replacement."
+
+`get_context_bundle(symbolId: "authenticate_token", maxDepth: 3)` returns:
+
+```
+authenticate_token()       apps/auth/jwt.py          — main function, 45 lines
+validate_claims()          apps/auth/jwt.py          — claim validation, 28 lines
+AuthUser                   apps/users/models.py      — the user model it returns
+UserPermissions            apps/auth/permissions.py  — permission model
+get_user_from_cache()      apps/core/cache.py        — Redis user caching, 22 lines
+settings.JWT_SECRET        apps/core/settings.py     — the signing key location
+
+Token estimate: 1,840 tokens
+```
+
+With the context bundle loaded, Claude explains how the current implementation works: JWT is decoded, the `sub` claim is extracted, the user is looked up from Redis cache first, then the database, and a combined `AuthUser` object is returned with permissions. The cache key format is `auth:user:{user_id}`.
+
+This is knowledge that should be in documentation but isn't. Now it is — extracted directly from the code.
+
+---
+
+## Phase 3: Find the hidden dependencies
+
+**You:** "Are there any places outside the auth module that interact directly with the JWT format, tokens, or the user cache? I don't want to miss something that breaks silently."
+
+**Claude** calls `search_text(query: "JWT_SECRET")` and `search_text(query: "auth:user:", is_regex: false)`:
+
+```
+JWT_SECRET references:
+  apps/auth/jwt.py:34          settings.JWT_SECRET  (expected)
+  apps/integrations/webhooks.py:89  settings.JWT_SECRET  (unexpected!)
+  scripts/generate_test_tokens.py:12  settings.JWT_SECRET
+
+auth:user: cache key references:
+  apps/auth/jwt.py:67          (expected)
+  apps/core/cache.py:45        (expected)
+  apps/analytics/sessions.py:128   (unexpected!)
+```
+
+Two surprises: `webhooks.py` is generating JWTs independently (a parallel implementation you didn't know existed), and `analytics/sessions.py` is reading directly from the user cache using the key format. Both would silently break after the migration if you hadn't found them.
+
+This is the difference between a migration that works and a migration that works until three months later when a webhook or analytics edge case surfaces.
+
+---
+
+## Phase 4: Check for dead code before migrating
+
+**You:** "Are there any auth-related functions that are already dead — unused exports we shouldn't bother migrating?"
+
+**Claude** calls `find_dead_code(repoId)` filtered to auth-related files:
+
+```
+Dead code in auth module:
+
+  generate_legacy_token()    apps/auth/legacy.py    — not imported anywhere
+  OldSessionManager          apps/auth/sessions.py  — class with no instantiations
+  validate_basic_auth()      apps/auth/basic.py     — imported nowhere
+```
+
+Three functions that can be deleted immediately without migration. The legacy session manager dates from before the JWT implementation. Migrating it would be wasted effort.
+
+---
+
+## Phase 5: Plan the migration path
+
+With a complete picture of the system, you can now plan the migration confidently:
+
+```
+Migration plan (informed by PureContext analysis):
+
+1. Create OAuth2 implementation alongside existing JWT:
+   - New: apps/auth/oauth2.py
+   - Preserve: existing JWT system during transition
+
+2. Create a compatibility shim in require_auth:
+   - Accept both JWT (existing) and OAuth2 Bearer tokens
+   - No changes to 134 view files — they use the decorator, not the auth logic
+
+3. Fix the hidden dependencies first:
+   - apps/integrations/webhooks.py — replace with OAuth2 client credentials
+   - apps/analytics/sessions.py — update cache key reading logic
+
+4. Migrate clients gradually:
+   - Internal services first, external API clients last
+
+5. Delete dead code before merging:
+   - apps/auth/legacy.py, sessions.py, basic.py
+
+6. Remove JWT system when all clients confirmed migrated
+```
+
+The plan addresses all the blast radius, the hidden dependencies, and the dead code — in the right order. A migration plan shaped by actual analysis rather than assumptions.
+
+---
+
+## Phase 6: After the migration
+
+Once the migration is complete, re-index and verify:
+
+**You:** "The migration is done. Check for any dead code that the old JWT implementation left behind, and verify there are no remaining JWT references."
+
+```
+search_text(query: "JWT_SECRET") → 0 results
+search_text(query: "jwt.decode") → 0 results
+find_dead_code() →
+  apps/auth/jwt.py (authenticate_token, generate_token, validate_claims) — now dead
+```
+
+The old JWT module is now entirely dead code. Safe to delete.
+
+---
+
+## What this workflow demonstrates
+
+**Discovery before commitment.** Understanding the full scope — 134 decorated views, 2 hidden dependencies, 3 dead functions — happened before a single line of migration code was written. The plan emerged from evidence, not guesswork.
+
+**Hidden dependencies surfaced.** `search_text` for string literals and cache key patterns found things that symbol search alone wouldn't catch. Text search and symbol search complement each other.
+
+**Migration sequencing informed by data.** The decision to use a compatibility shim in `require_auth` (avoiding changes to 134 files) came directly from the blast radius analysis. Without that number, you might have tried to update each view individually.
+
+**Verification at the end.** Re-indexing after the migration and checking for remaining references gives you a definitive answer: the migration is complete, not "probably complete."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "purecontext-mcp",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Token-efficient source code navigation MCP server for AI agents",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,14 @@
     "grammars/",
     "prebuilds/",
     "src/ui/dist/",
-    "scripts/check-sqlite.js"
+    "scripts/check-sqlite.js",
+    "README.md",
+    "AGENT_INSTRUCTIONS.md",
+    "AGENT_INSTRUCTIONS_SHORT.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "docs/",
+    "guide/"
   ],
   "main": "./dist/index.js",
   "exports": {