purecontext-mcp 1.5.2 → 1.11.0

package/SAFE-CHANGES.md

@@ -1,156 +1,208 @@
-# Making Changes Safely
-
-The hardest part of changing code in a large codebase is not writing the new code — it's understanding what the old code touches. Every change that breaks something unexpected does so because the developer didn't know about a dependency they couldn't see.
-
-PureContext gives you two tools that together form a complete pre-change analysis workflow: **blast radius** (what does this touch?) and **context bundle** (what does this need?).
-
----
-
-## The blast radius: knowing your impact before you start
-
-Before you change anything, find out what depends on it.
-
-**Scenario:** You're refactoring a utility function `formatCurrency` that's been in the codebase for three years. It's used everywhere, but you don't know exactly where.
-
-> "Before I refactor formatCurrency, show me everything that uses it."
-
-Claude calls `get_blast_radius` and returns:
-
-```
-formatCurrency() is imported by 23 files:
-  Direct importers (depth 1):
-    src/billing/invoice.ts
-    src/reporting/pdf-generator.ts
-    src/api/responses/pricing.ts
-    src/ui/components/PriceDisplay.tsx
-    ... (8 more)
-
-  Transitive importers (depth 2–3):
-    src/api/routes/orders.ts  (via billing/invoice.ts)
-    src/workers/monthly-report.ts  (via reporting/pdf-generator.ts)
-    ... (9 more)
-
-  Total files affected: 23
-```
-
-You now know the scope before you've written a line. If the blast radius is 23 files, you know this change needs careful testing. If it's 2, you can move quickly.
-
-**What the blast radius tells you:**
-- Files you need to update if the function's signature changes
-- Test files that will break if behavior changes
-- Services that will fail if the function is removed
-- The difference between "safe to refactor locally" and "needs a deprecation cycle"
-
-**Using blast radius for deletion decisions:**
-
-> "I think this helper is unused — can you confirm?"
-
-```
-get_blast_radius(symbolId: "legacyFormatDate-id") →
-  importers: []
-  count: 0
-```
-
-Zero importers. Safe to delete. `find_dead_code` will surface all such symbols at once across the whole codebase.
-
----
-
-## The context bundle: understanding what you're changing
-
-Once you know the impact scope, understand the code itself before you touch it.
-
-**Scenario:** You need to modify the `processOrder` function but you've never worked in this part of the codebase. You need to understand what it calls, what data it expects, and what it produces.
-
-> "Give me everything I need to understand processOrder before I change it."
-
-Claude calls `get_context_bundle` starting from `processOrder` with a depth of 2:
-
-```
-Context bundle for processOrder():
-
-  processOrder()          src/orders/processor.ts    (the function itself, 67 lines)
-  validateCart()          src/cart/validator.ts      (called by processOrder, 34 lines)
-  calculateTax()          src/billing/tax.ts          (called by processOrder, 28 lines)
-  formatPrice()           src/utils/format.ts         (called by validateCart, 12 lines)
-  OrderRecord             src/db/models/order.ts      (the data shape, 22 lines)
-
-  Token estimate: 1,240 tokens
-  Files covered: 5
-```
-
-1,240 tokens for a complete picture of the order processing flow. Reading those 5 files directly would be ~8,000 tokens and would include unrelated functions, imports, and comments.
-
-**Setting depth:** `maxDepth: 1` gives you just the direct dependencies. `maxDepth: 3` follows the dependency chain further but returns more. Start at 2 and go deeper only if you need it.
-
-**Setting a token budget:** If you're working within a context window budget, set `maxTokens` and the bundle will stop collecting symbols once the estimate exceeds it — always returning the most directly connected ones first.
-
----
-
-## The complete pre-change workflow
-
-This is the pattern to use before any significant change:
-
-```
-1. Identify the symbol you're changing
-   search_symbols(query: "processOrder") → find the right one
-
-2. Check the blast radius
-   get_blast_radius(symbolId) → how many files are affected?
-
-3. Understand the symbol in context
-   get_context_bundle(symbolId, maxDepth: 2) → what does it depend on?
-
-4. Make the change
-
-5. Verify nothing became orphaned
-   find_dead_code(repoId) → any exports that are now unused?
-
-6. Re-index (if you changed signatures)
-   index_folder → incremental, fast, picks up your changes
-```
-
----
-
-## Detecting architectural violations before they ship
-
-PureContext can also check whether your change violates the project's intended layer structure. If your codebase has defined architectural layers — for example, "core services must not import from API controllers" — the `get_layer_violations` tool checks for violations across the whole codebase.
-
-> "Check if my changes introduced any architectural boundary violations."
-
-```
-get_layer_violations(repoId) →
-
-  VIOLATION: src/core/billing.ts imports from src/api/middleware/auth.ts
-  Layer: core → api  (not allowed per layer rules)
-  Import: AuthMiddleware
-```
-
-Catch these before code review, not during.
-
----
-
-## For teams: sharing impact analysis
-
-In a team environment, blast radius analysis is especially valuable during planning. Before a developer starts on a change, ask PureContext to assess the scope:
-
-> "We're planning to move the authentication service from JWT to session-based auth. What's the blast radius of changing the validateToken function?"
-
-The answer tells the team how many files need to be updated, which services are affected, and whether this is a one-person job or a coordinated migration. That's a planning conversation that used to require a senior engineer's memory of the codebase.
-
----
-
-## For legacy codebases
-
-Legacy codebases are where blast radius analysis pays off most. Nobody knows all the call sites for a function that's been there for five years. PureContext does.
-
-Before refactoring anything in a legacy system:
-
-1. Run `find_dead_code` first — it often reveals that 20% of what you thought you needed to understand is actually unused
-2. Use blast radius on the symbols you do need to change — the dependency graph doesn't lie
-3. Use context bundle to understand the chain before proposing a change to your team
-
-This transforms "I think this change is safe but I'm not sure" into "I know exactly which 7 files this change affects and here they are."
-
----
-
-→ Reference: [MCP Tools Reference](../docs/06-tools-reference.md) — `get_blast_radius`, `get_context_bundle`, `find_importers`, `find_dead_code`, `get_layer_violations`
+# Making Changes Safely
+
+The hardest part of changing code in a large codebase is not writing the new code — it's understanding what the old code touches. Every change that breaks something unexpected does so because the developer didn't know about a dependency they couldn't see.
+
+PureContext gives you two tools that together form a complete pre-change analysis workflow: **blast radius** (what does this touch?) and **context bundle** (what does this need?).
+
+---
+
+## The blast radius: knowing your impact before you start
+
+Before you change anything, find out what depends on it.
+
+**Scenario:** You're refactoring a utility function `formatCurrency` that's been in the codebase for three years. It's used everywhere, but you don't know exactly where.
+
+> "Before I refactor formatCurrency, show me everything that uses it."
+
+Claude calls `get_blast_radius` and returns:
+
+```
+formatCurrency() is imported by 23 files:
+  Direct importers (depth 1):
+    src/billing/invoice.ts
+    src/reporting/pdf-generator.ts
+    src/api/responses/pricing.ts
+    src/ui/components/PriceDisplay.tsx
+    ... (8 more)
+
+  Transitive importers (depth 2–3):
+    src/api/routes/orders.ts  (via billing/invoice.ts)
+    src/workers/monthly-report.ts  (via reporting/pdf-generator.ts)
+    ... (9 more)
+
+  Total files affected: 23
+```
+
+You now know the scope before you've written a line. If the blast radius is 23 files, you know this change needs careful testing. If it's 2, you can move quickly.
+
+**What the blast radius tells you:**
+- Files you need to update if the function's signature changes
+- Test files that will break if behavior changes
+- Services that will fail if the function is removed
+- The difference between "safe to refactor locally" and "needs a deprecation cycle"
+
+**Using blast radius for deletion decisions:**
+
+> "I think this helper is unused — can you confirm?"
+
+```
+get_blast_radius(symbolId: "legacyFormatDate-id") →
+  importers: []
+  count: 0
+```
+
+Zero importers. Safe to delete. `find_dead_code` will surface all such symbols at once across the whole codebase.
+
+---
+
+## The context bundle: understanding what you're changing
+
+Once you know the impact scope, understand the code itself before you touch it.
+
+**Scenario:** You need to modify the `processOrder` function but you've never worked in this part of the codebase. You need to understand what it calls, what data it expects, and what it produces.
+
+> "Give me everything I need to understand processOrder before I change it."
+
+Claude calls `get_context_bundle` starting from `processOrder` with a depth of 2:
+
+```
+Context bundle for processOrder():
+
+  processOrder()          src/orders/processor.ts    (the function itself, 67 lines)
+  validateCart()          src/cart/validator.ts      (called by processOrder, 34 lines)
+  calculateTax()          src/billing/tax.ts          (called by processOrder, 28 lines)
+  formatPrice()           src/utils/format.ts         (called by validateCart, 12 lines)
+  OrderRecord             src/db/models/order.ts      (the data shape, 22 lines)
+
+  Token estimate: 1,240 tokens
+  Files covered: 5
+```
+
+1,240 tokens for a complete picture of the order processing flow. Reading those 5 files directly would be ~8,000 tokens and would include unrelated functions, imports, and comments.
+
+**Setting depth:** `maxDepth: 1` gives you just the direct dependencies. `maxDepth: 3` follows the dependency chain further but returns more. Start at 2 and go deeper only if you need it.
+
+**Setting a token budget:** If you're working within a context window budget, set `maxTokens` and the bundle will stop collecting symbols once the estimate exceeds it — always returning the most directly connected ones first.
+
+---
+
+## The one-call pre-flight: `prepare_change`
+
+The workflow below is the explicit, step-by-step version. When you just want the verdict, `prepare_change` runs the whole pre-flight in a single call — it resolves the target, predicts the files you'll touch, and returns the risk, the co-change partners you're about to forget, the tests, and any architectural flags, each with a plain-English reason.
+
+> "I want to rename validateToken. What's the impact?"
+
+```
+prepare_change(repoId, intent: "rename", targetSymbolId: "validateToken-id") →
+
+  verdict: "ready"
+  predictedChange: { changedFilePaths: [ ...12 files... ] }
+  risk: { band: "review" }
+  missingCoChange: [ "src/api/session-store.ts" ]   ← moves with this historically, NOT in your plan
+  reasons: [
+    "Aggregate change risk: review.",
+    "1 file historically co-changes with the target but is NOT in the predicted change: src/api/session-store.ts."
+  ]
+```
+
+It is **judgment, not actuation** — it never edits. If the target is ambiguous it returns `verdict: "ambiguous_target"` with candidates and asks you to pick, rather than guessing. Keep `predictedChange.changedFilePaths` and `missingCoChange[].filePath` — `verify_change` uses them afterward.
+
+---
+
+## The complete pre-change workflow
+
+This is the pattern to use before any significant change:
+
+```
+1. Identify the symbol you're changing
+   search_symbols(query: "processOrder") → find the right one
+
+2. Get a composite risk read
+   get_symbol_risk(symbolId) → band (low/review/high) + reasons
+
+3. Check the blast radius
+   get_blast_radius(symbolId) → how many files are affected?
+
+4. Find what moves with it that the import graph can't show
+   get_co_change(symbolId) → files that historically change together
+                             (e.g. the test or config that must move too)
+
+5. Understand the symbol in context
+   get_context_bundle(symbolId, maxDepth: 2) → dependencies + historicalNeighbors
+
+6. Make the change (and its co-changers, if they need to move together)
+
+7. Verify nothing became orphaned
+   find_dead_code(repoId) → any exports that are now unused?
+
+8. Re-index (if you changed signatures)
+   index_folder → incremental, fast, picks up your changes
+```
+
+> For a `high`-risk symbol, treat steps 3–4 as mandatory: the co-changers are the second-order edits most likely to break. For a quick inline signal, pass `includeRisk: true` to `search_symbols` to see each candidate's `{ band, riskScore }` before you pick one.
+
+---
+
+## Closing the loop: confirming the change was complete
+
+The steps above are the *before*. After you've made the change, `verify_change` reconciles what you actually did against the prediction — it's how you catch the co-change partner you meant to touch but didn't.
+
+> "Here's my diff. Did I cover everything?"
+
+```
+verify_change(repoId, diff: "<git diff>",
+  predictedFilePaths: [ ...from prepare_change... ],
+  predictedCoChange: [ "src/api/session-store.ts" ]) →
+
+  verdict: "incomplete"
+  unaddressedCoChange: [ "src/api/session-store.ts" ]   ← you planned around it; still untouched
+  unplannedChanges: [ ]
+```
+
+`complete` = every planned file touched, no co-change or coverage gaps; `incomplete` = a planned partner or untested symbol remains; `scope_expanded` = you touched files that weren't predicted. And `compare_change_impact` (against a `get_architecture_snapshot` baseline) tells you whether the change introduced a *new* import cycle or layer violation — never blaming it for pre-existing ones.
+
+---
+
+## Detecting architectural violations before they ship
+
+PureContext can also check whether your change violates the project's intended layer structure. If your codebase has defined architectural layers — for example, "core services must not import from API controllers" — the `get_layer_violations` tool checks for violations across the whole codebase.
+
+> "Check if my changes introduced any architectural boundary violations."
+
+```
+get_layer_violations(repoId) →
+
+  VIOLATION: src/core/billing.ts imports from src/api/middleware/auth.ts
+  Layer: core → api  (not allowed per layer rules)
+  Import: AuthMiddleware
+```
+
+Catch these before code review, not during.
+
+---
+
+## For teams: sharing impact analysis
+
+In a team environment, blast radius analysis is especially valuable during planning. Before a developer starts on a change, ask PureContext to assess the scope:
+
+> "We're planning to move the authentication service from JWT to session-based auth. What's the blast radius of changing the validateToken function?"
+
+The answer tells the team how many files need to be updated, which services are affected, and whether this is a one-person job or a coordinated migration. That's a planning conversation that used to require a senior engineer's memory of the codebase.
+
+---
+
+## For legacy codebases
+
+Legacy codebases are where blast radius analysis pays off most. Nobody knows all the call sites for a function that's been there for five years. PureContext does.
+
+Before refactoring anything in a legacy system:
+
+1. Run `find_dead_code` first — it often reveals that 20% of what you thought you needed to understand is actually unused
+2. Use blast radius on the symbols you do need to change — the dependency graph doesn't lie
+3. Use context bundle to understand the chain before proposing a change to your team
+
+This transforms "I think this change is safe but I'm not sure" into "I know exactly which 7 files this change affects and here they are."
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `prepare_change`, `verify_change`, `compare_change_impact`, `get_symbol_risk`, `get_co_change`, `get_blast_radius`, `get_context_bundle`, `find_importers`, `find_dead_code`, `get_layer_violations`

package/USER-GUIDE.md

@@ -2,13 +2,15 @@
 
 This guide explains what PureContext does, why it changes the way you work with code, and how to use its features effectively. Each section focuses on a capability area with real examples and concrete workflows.
 
+PureContext gives an AI agent two things: **precise retrieval** (pull the exact symbol you need instead of reading whole files — the token-efficient foundation) and **change intelligence** (know what a change affects, what moves with it, and how risky it is — *before* the edit). The first makes every interaction cheap; the second is what lets an agent change unfamiliar code safely.
+
 For parameter-level documentation — every tool input, output, and flag — see the [Reference Manual](docs/README.md).
 
 ---
 
 ## Start here
 
-- [Why PureContext](WHY-PURECONTEXT.md) — The full case: what actually improves when AI has precise context instead of bulk context, who benefits, and what PureContext does not do
+- [Why PureContext](WHY-PURECONTEXT.md) — The full case: why precise context beats bulk context, why *safe change* (not just retrieval) is the differentiator, who benefits, and what PureContext does not do
 
 ---
 

package/WHY-PURECONTEXT.md

@@ -1,73 +1,103 @@
-# 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.
+# 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.
+
+That precise retrieval is the **foundation**. It's also where the bigger shift begins.
+
+---
+
+## The bigger problem: agents can read code, but not change it safely
+
+Finding code is the easy half — and increasingly, every agent harness can do it. The hard half is *changing* code you didn't write: knowing what depends on a function, what quietly moves alongside it, and whether it's safe to touch at all.
+
+That's the context a careful senior engineer carries in their head and a fresh agent simply doesn't have. PureContext gives the agent that context as tools it can call **before** it edits:
+
+- **Blast radius** (`get_blast_radius`) — every file that transitively depends on a symbol, so a change is never blind.
+- **Temporal co-change** (`get_co_change`) — the files that historically move *together* in commits but don't import each other: the test, the migration, the feature flag. The coupling the dependency graph can't see.
+- **Composite change risk** (`get_symbol_risk`) — one banded `low` / `review` / `high` verdict fusing churn, centrality, complexity, test gaps, and co-change, with plain-English reasons. Deliberately code-centered: no author or productivity metrics.
+- **Refactor-safety checks** (`check_rename_safe` / `check_delete_safe` / `check_move_safe`, `plan_refactoring`) — a pre-flight verdict before a rename, delete, move, or multi-step refactor.
+
+This is what sets PureContext apart from a fast symbol index: it doesn't just help an agent *find* code, it helps it *change* code without breaking what it can't see. The token-efficient retrieval underneath is what makes every one of those checks cheap enough to run on every edit.
+
+---
+
+## A closed loop, not just a warning
+
+The checks above are the *before*. PureContext closes the loop around the whole edit:
+
+1. **`prepare_change`** — before editing, state your intent (rename, delete, modify, extract) and a target. PureContext resolves the exact change set and returns one pre-flight verdict: the files you'll touch, the composite risk, the historically co-changing files you're *about to forget*, the tests to run, and any architectural flags — in plain English, with reasons, not a bare confidence number. If the target is ambiguous it tells you and asks; it never guesses.
+2. **You make the edit.** PureContext does not. Your agent already has a file-write tool; PureContext's job is judgment, not a second pair of hands.
+3. **`verify_change`** — after editing, hand back the real diff. PureContext reconciles what you *did* against what it *predicted*: which co-change partners you addressed, which you still haven't, what you changed that wasn't planned, and whether any changed code is still untested. "Complete," "incomplete," or "scope expanded" — with the reasons.
+4. **`compare_change_impact`** — snapshot the architecture before, and afterwards PureContext reports only what your change *introduced*: a new import cycle, a new layer violation. It never blames you for problems that were already there.
+
+That before → edit → verify → compare loop is the difference between a tool that *flags* risk and one that confirms the change was actually safe and complete.
+
+---
+
+## 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 change code safely, not just read it
+
+Before PureContext, asking an AI to change a core function was a gamble — it didn't know what depended on the code, what moved with it, or whether it was risky to touch.
+
+Now Claude checks the blast radius, the historical co-changers, and a composite risk score *before* editing, and can tell you: *"this is high-risk and untested — it affects 14 files across 3 services and usually moves with `ledger.ts` and `refund.test.ts`, so I'll update those in the same change."* 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 a second editor — it never applies your changes for you.** It tells the agent what's safe and what's still missing; the agent does the writing. Judgment, not actuation.
+
+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.