memorydetective 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -6,6 +6,40 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-05-01
+
+Response-size + cycle-scoped queries + license switch + first-run engagement.
+
+### Added
+
+- **`reachableFromCycle` tool** — cycle-scoped reachability + per-class counting. Pick a cycle by `cycleIndex` or `rootClassName` substring, get instance counts of every class reachable from that cycle root. Distinguishes the actual culprit (the cycle root) from its retained dependencies. API shape inspired by Meta's `memlab` predicate-based queries. Tool count: 19 → 20.
+- **`verbosity` parameter** on `analyzeMemgraph`, `findCycles`, and `reachableFromCycle`. Three levels: `compact` (default — drops module prefixes, collapses nested SwiftUI `ModifiedContent` into `+N modifiers`, truncates deep generics with a hash placeholder), `normal` (lighter shortening, depth preserved), `full` (Swift demangled names verbatim).
+- **`maxClassesInChain` parameter** on `analyzeMemgraph` (default 10). Caps the per-cycle `classesInChain` array to the top N unique classes ranked by occurrence count, with app-level types prioritized over SwiftUI internals. The full unique-class total is reported in a new `classesInChainTotal` field for context.
+- **Class-name shortener** (`src/parsers/shortenClassName.ts`) — three layers (drop modules, collapse `ModifiedContent` chains, truncate deep generics) with deterministic hash placeholders so the same nested type produces the same short code across runs (useful for diffing two memgraphs).
+- **First-run CLI banner** — first time `memorydetective` runs in non-JSON mode on a machine, prints a one-time message pointing at the GitHub repo, `USAGE.md`, and the sponsor link. Marker stored at `~/.config/memorydetective/seen` so it never re-prints.
+- **Help / output footers** — `--help` and `analyze`/`classify` non-JSON output append a discreet `# ⭐ github.com/carloshpdoc/memorydetective` line. JSON output is untouched (won't break pipes / CI).
+
+### Changed
+
+- **License: MIT → Apache 2.0.** Permissions are unchanged for users (commercial use, modification, distribution all allowed). Apache 2.0 adds an explicit patent grant + a `NOTICE` file mechanism; the `NOTICE` file ships in the npm tarball and surfaces project attribution in downstream "About" / acknowledgements screens.
+- `analyzeMemgraph` default response is now ~80% smaller for SwiftUI-heavy memgraphs (the per-cycle `classesInChain` no longer floods with hundreds of demangled SwiftUI generics; class names per node compress from 1000+ chars to ~200). Full-fidelity output is still available via `verbosity: "full"`.
+- README: license badge updated to Apache 2.0; tool count updated 19 → 20.
+
+### Notes
+
+- No breaking changes — all new parameters have sensible defaults. Old callers continue to work; they just receive smaller, more readable responses.
+
+## [1.0.1] — 2026-05-01
+
+### Added
+
+- `USAGE.md` walkthrough covering the three usage modes (CLI, `--json`, MCP), the 8 cycle patterns and their fix hints, the end-to-end flow of how fixes go from diagnosis to a code edit (memorydetective diagnoses; the LLM agent applies the edit using its own code-editing tools), common follow-up prompts, and troubleshooting. README links to it from the Quickstart pointer line.
+- `USAGE.md` is included in the npm tarball (added to `package.json` `files` whitelist).
+
+### Changed
+
+- No code changes from `1.0.0` — this is a documentation bump.
+
 ## [1.0.0] — 2026-05-01
 
 First public release. **19 MCP tools** for iOS leak hunting and performance investigation, plus a thin CLI mode for scripting and CI.
@@ -63,5 +97,7 @@ When called with no arguments it starts the MCP server over stdio.
 - **`captureMemgraph`** does not work on physical iOS devices — `leaks(1)` only attaches to processes on the local Mac (which includes iOS simulators). Memory Graph capture from a physical device still requires Xcode.
 - **`detectLeaksInXCUITest`** is flagged experimental: orchestration logic is implemented but not yet validated against a wide set of production XCUITest runs.
 
-[Unreleased]: https://github.com/carloshpdoc/memorydetective/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/carloshpdoc/memorydetective/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/carloshpdoc/memorydetective/compare/v1.0.1...v1.1.0
+[1.0.1]: https://github.com/carloshpdoc/memorydetective/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/carloshpdoc/memorydetective/releases/tag/v1.0.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Carlos Henrique
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Carlos Henrique
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,19 @@
+memorydetective
+Copyright 2026 Carlos Henrique
+
+Licensed under the Apache License, Version 2.0 (the "License").
+A copy of the License is included in this distribution as `LICENSE`,
+and is also available at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Project home:
+    https://github.com/carloshpdoc/memorydetective
+
+This product includes software developed by Carlos Henrique
+(https://github.com/carloshpdoc).
+
+If `memorydetective` saves you time, please consider:
+  • Starring the repository: https://github.com/carloshpdoc/memorydetective
+  • Sponsoring development: https://github.com/sponsors/carloshpdoc
+  • Buying me a coffee: https://buymeacoffee.com/carloshperc

package/README.md

@@ -4,7 +4,8 @@
 
 [![npm](https://img.shields.io/npm/v/memorydetective.svg)](https://www.npmjs.com/package/memorydetective)
 [![CI](https://github.com/carloshpdoc/memorydetective/actions/workflows/ci.yml/badge.svg)](https://github.com/carloshpdoc/memorydetective/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/carloshpdoc/memorydetective?style=flat&logo=github)](https://github.com/carloshpdoc/memorydetective/stargazers)
 [![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](#requirements)
 [![node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen.svg)](#requirements)
 
@@ -40,7 +41,7 @@ memorydetective analyze   ~/Desktop/myapp.memgraph
 memorydetective classify  ~/Desktop/myapp.memgraph
 ```
 
-→ See [Examples](#examples) for chat-driven flows · [API](#api) for the full tool reference · [Configure](#configure) for Claude Desktop / Cursor / Cline.
+→ See [Examples](#examples) for chat-driven flows · [API](#api) for the full tool reference · [Configure](#configure) for Claude Desktop / Cursor / Cline · [USAGE.md](./USAGE.md) for the full walkthrough including how fixes flow from diagnosis to your codebase.
 
 ---
 
@@ -176,9 +177,9 @@ Copilot's MCP integration moves fast — if this snippet is stale, see the [VS C
 
 ## API
 
-19 MCP tools, grouped by purpose.
+20 MCP tools, grouped by purpose.
 
-### Read & analyze (12)
+### Read & analyze (13)
 
 | Tool | What |
 |---|---|
@@ -186,6 +187,7 @@ Copilot's MCP integration moves fast — if this snippet is stale, see the [VS C
 | `findCycles` | Extract just the ROOT CYCLE blocks as flattened chains, with optional `className` substring filter. |
 | `findRetainers` | "Who is keeping `<class>` alive?" — returns retain chain paths from a top-level node down to the match. |
 | `countAlive` | Count instances by class. Provide `className` for one number, or omit for top-N most-leaked classes. |
+| `reachableFromCycle` | Cycle-scoped reachability. "How many `<X>` instances are reachable from the cycle rooted at `<Y>`?" — distinguishes the actual culprit from its retained dependencies. |
 | `diffMemgraphs` | Compare two `.memgraph` snapshots: total deltas + class-count changes + cycles new/gone/persisted. |
 | `classifyCycle` | Match each ROOT CYCLE against a built-in catalog of 8 known patterns (TagIndexProjection, ForEachState, Combine sink, Task captures, NotificationCenter observer, etc.) with confidence + fix hint. |
 | `analyzeHangs` | Parse `xctrace` `potential-hangs` schema; return Hang vs Microhang counts + top N longest. |
@@ -293,17 +295,19 @@ If `memorydetective` saves you time, you can support continued development:
 
 Every contribution helps keep this maintained and documented.
 
-## Roadmap
+## License
 
-- **v0.1.x** (current) — 12 MCP tools, 8 cycle patterns, CLI mode.
-- **v0.2** — community-contributable cycle catalog, Claude Code plugin (`/plugin install memorydetective`), close the `analyzeTimeProfile` SIGSEGV gap. Design docs in [docs/](./docs/).
-- **Phase 3** (gated) — GitHub Action + SaaS dashboard for PR-time leak detection.
+Apache 2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
 
-See [docs/v0.2-roadmap.md](./docs/v0.2-roadmap.md) for the full plan.
+Permits commercial use, modification, distribution, patent use. Includes attribution clause via the `NOTICE` file.
 
-## License
+## Companion MCPs
+
+`memorydetective` focuses on memory-graph and trace artifacts. To bridge "found this leak in the cycle" with "find it in your codebase", pair it with a Swift source-aware MCP. Recommended:
+
+- [SwiftLens](https://github.com/swiftlens/swiftlens) — wraps SourceKit-LSP for Swift symbol lookup, reference search, hover info. Different license model (non-commercial); read its terms before using in a paid product.
 
-MIT — see [LICENSE](./LICENSE).
+A future version of `memorydetective` may include a similar source-bridging surface natively under Apache 2.0; see the v1.2 roadmap notes in the design docs.
 
 ## Why "memorydetective"?
 

package/USAGE.md

@@ -0,0 +1,259 @@
+# Usage guide
+
+Walkthrough of how `memorydetective` actually works in practice — what each tool returns, how fixes flow from diagnosis to your codebase, and the architecture decision behind splitting "diagnose" from "edit".
+
+For a quick API reference, see the [`README.md`](./README.md). For the full changelog, see [`CHANGELOG.md`](./CHANGELOG.md).
+
+---
+
+## 1. Three ways to use it
+
+### 1a. CLI mode — quickest way to see it work
+
+```bash
+npm install -g memorydetective
+memorydetective --version    # 1.0.0
+
+# Run analyze on any .memgraph file
+memorydetective analyze ~/Desktop/myapp.memgraph
+```
+
+What you see (terminal output, ANSI-coloured):
+
+```
+┌─ memorydetective analyze ──────────────────────────────────────┐
+│ Path: /Users/.../myapp.memgraph
+│ Process: MyApp (pid 12345)
+│ Bundle: com.example.myapp
+└────────────────────────────────────────────────────────────────┘
+
+  60,436 leaks (7.89 MB)
+  4 ROOT CYCLE blocks
+
+  Top cycle: Swift._DictionaryStorage<SwiftUI.AnyHashable2, SwiftUI…
+    chain length: 545 nodes
+    app-level classes in chain: Closure context, DetailViewModel,
+        ItemRepositoryImpl, ItemGraphQLDataSource, GraphQLClient
+
+  Diagnosis:
+    60436 leaks; 4 ROOT CYCLE blocks. Largest top-level cycle:
+    Swift._DictionaryStorage… (chain of 545 nodes). App-level
+    classes in chains: Closure context, DetailViewModel, …
+```
+
+Then ask the classifier for fix advice:
+
+```bash
+memorydetective classify ~/Desktop/myapp.memgraph
+```
+
+You see one block per ROOT CYCLE, like:
+
+```
+  Root: Swift._DictionaryStorage<SwiftUI.AnyHashable2, SwiftUI…
+    Match: swiftui.tag-index-projection (high confidence)
+    Fix hint:
+      Replace `[weak self]` capture in tap closures with a static
+      helper, OR weak-capture the coordinator/view-model directly
+      with `[weak coord = self.coordinator]`. The `.tag()` modifier
+      on photo carousels is the usual culprit.
+    Also matched: swiftui.dictstorage-weakbox-cycle,
+                  closure.viewmodel-wrapped-strong,
+                  swiftui.foreach-state-tap
+```
+
+### 1b. JSON mode — for scripts and CI
+
+```bash
+memorydetective analyze ~/Desktop/myapp.memgraph --json | jq .totals
+memorydetective classify ~/Desktop/myapp.memgraph --json | jq '.classified[0].primaryMatch'
+```
+
+The JSON shape mirrors the MCP tool's response — same fields, no ANSI colours, ready to pipe into anything.
+
+### 1c. MCP mode — the actual product UX
+
+This is what we built it for: an LLM agent (Claude Code, Claude Desktop, Cursor, Cline, Kiro, …) drives the investigation by chat.
+
+Add to your MCP client config (Claude Code shown):
+
+```jsonc
+// ~/.claude/settings.json
+{
+  "mcpServers": {
+    "memorydetective": { "command": "memorydetective" }
+  }
+}
+```
+
+Open Claude Code in your iOS project and just ask:
+
+> Diagnose `~/Desktop/myapp.memgraph` and find where to fix in this codebase.
+
+Claude orchestrates the full flow (see [section 3](#3-how-fixes-actually-flow-from-diagnosis-to-edit)).
+
+---
+
+## 2. The 8 cycle patterns and their fix hints
+
+`classifyCycle` ships with a built-in catalog of common iOS retain-cycle patterns. Each pattern returns a `fixHint` — a plain-English string describing the fix direction.
+
+| Pattern ID | When it matches | Fix hint (summary) |
+|---|---|---|
+| `swiftui.tag-index-projection` | `TagIndexProjection<Int>` appears in chain (`.tag()` modifier capturing self) | Replace `[weak self]` capture with a static helper, or weak-capture the coordinator/view-model directly. |
+| `swiftui.dictstorage-weakbox-cycle` | Root is `_DictionaryStorage<…WeakBox<AnyLocationBase>>` | SwiftUI internal observation graph cycle. Find your app-level types in the chain and break the strong capture there. |
+| `swiftui.foreach-state-tap` | `SwiftUI.ForEachState` in chain | ForEachState held by a tap-gesture closure capturing `self`. Make the tap handler a static function or capture properties weakly. |
+| `closure.viewmodel-wrapped-strong` | `__strong` edge with `_viewModel.wrappedValue` in label | Closure captures `_viewModel.wrappedValue` strongly. Capture the underlying ObservableObject weakly: `[weak vm = _viewModel.wrappedValue]`. |
+| `viewcontroller.uinavigationcontroller-host` | `UINavigationController` + `UIHostingController` both in chain | Clear `viewControllers = []` in `dismantleUIViewController` to break the host->VC->host cycle. |
+| `combine.sink-store-self-capture` | `AnyCancellable` + `Closure context` | `.sink { self.x = … }` keeps self alive through the AnyCancellable that's stored on self. Capture explicitly: `.sink { [weak self] in self?.x = … }`. |
+| `concurrency.task-without-weak-self` | `_Concurrency.Task<…>` + `Closure context` | `Task { }` body strongly captures self for the lifetime of the task. `Task { [weak self] in guard let self else { return }; … }`. |
+| `notificationcenter.observer-strong` | `NotificationCenter` / `NSNotificationCenter` + `Closure context` | Block-form `addObserver(forName:...)` keeps the block alive in the center. Use `[weak self]` in the block, or store the returned `NSObjectProtocol` and call `removeObserver(_:)` in `deinit`. |
+
+**Confidence tiers**: each pattern is checked at `high` first, then `medium`. If multiple patterns fire on the same cycle, all matches are returned — the highest-confidence one is `primaryMatch`, the rest are in `allMatches`.
+
+**The hints are deliberately textual, not code patches.** That's by design — see the next section.
+
+---
+
+## 3. How fixes actually flow from diagnosis to edit
+
+`memorydetective` is the **diagnose** side. It tells you **what** is wrong, **where in the cycle**, and **what type of fix** is needed. It does **not** edit your code.
+
+The **edit** side comes from your LLM agent (Claude Code, Cursor, Cline, …) using its native code-editing tools (Read, Grep, Edit, …).
+
+This split is intentional:
+
+- The fix depends on your real code (file paths, surrounding context, naming). `memorydetective` knows nothing about your codebase.
+- LLM agents already excel at code editing. Letting them keep that role keeps `memorydetective` focused.
+- The catalog of known patterns becomes the knowledge moat; the LLM brings the codebase awareness.
+
+### Concrete end-to-end example
+
+Configuration (one-time): `memorydetective` registered as an MCP server in Claude Code, as shown in [section 1c](#1c-mcp-mode--the-actual-product-ux).
+
+You open Claude Code in your iOS project and ask:
+
+> **You:** I exported `~/Desktop/myapp.memgraph` after closing some detail screens — something is leaking. Diagnose and find where to fix in this codebase.
+
+What Claude does, step by step:
+
+1. **Calls `analyzeMemgraph(path: "~/Desktop/myapp.memgraph")`**
+   - Receives: 60,436 leaks, 4 ROOT CYCLE blocks, top cycle is a `_DictionaryStorage` chain.
+
+2. **Calls `classifyCycle(path: "~/Desktop/myapp.memgraph")`**
+   - Receives: pattern `swiftui.tag-index-projection` (high confidence) + fix hint about `.tag()` and weak capture.
+
+3. **Uses its own code-editing tools to find the offending file:**
+   - `Grep` for `.tag(` in your `*.swift` files.
+   - `Grep` for `onImageSliderTap` (or whatever closure name surfaced in the chain).
+   - `Read` the candidate files to see how the closure is captured.
+
+4. **Presents the proposed fix in chat:**
+
+   > **Claude:** Found the cycle. `WishlistPlaceDetailsView.swift:142` passes `onImageSliderTap` as a closure that captures `self`. The `.tag(index)` modifier on the carousel `ForEach` is what triggers the SwiftUI internal `TagIndexProjection` observation that pins the cycle.
+   >
+   > Suggested fix: hoist the handler to a `static` function and capture only what's needed weakly:
+   > ```swift
+   > // before
+   > onImageSliderTap: { index in
+   >     self.viewModel.handlePhotoTap(at: index)
+   > }
+   >
+   > // after
+   > onImageSliderTap: { [weak vm = _viewModel.wrappedValue,
+   >                      weak coord = self.coordinator] index in
+   >     Self.handlePhotoTap(index: index, viewModel: vm, coordinator: coord)
+   > }
+   >
+   > // plus a static helper:
+   > private static func handlePhotoTap(
+   >     index: Int,
+   >     viewModel: DetailViewModel?,
+   >     coordinator: DetailsCoordinator?
+   > ) { /* ... */ }
+   > ```
+   >
+   > Want me to apply this?
+
+5. **You accept** → Claude calls its own `Edit` tool → diff appears in your IDE → you review and commit.
+
+6. **(Optional) Verify the fix:** export a fresh `.memgraph` after running the same flow, then ask Claude:
+
+   > **You:** Did the fix work? Compare `~/Desktop/myapp-before.memgraph` to `~/Desktop/myapp-after.memgraph`.
+
+   Claude calls `diffMemgraphs` — instance counts dropped, the `swiftui.tag-index-projection` cycle is gone from `cycles.persisted`, present in `cycles.goneFromBefore`.
+
+### Why this is better than "memorydetective generates the diff"
+
+If `memorydetective` tried to generate a code patch, it would have to:
+- Parse Swift source
+- Understand the file's import graph
+- Track the actual variable names and types in scope
+- Match surrounding code style
+
+That's exactly what an LLM agent already does — and does well. Splitting the responsibility keeps each side simple. `memorydetective` knows **iOS perf**; the agent knows **your codebase**. They compose.
+
+---
+
+## 4. Common follow-up requests
+
+Once you have the diagnosis, here are useful follow-up prompts you can paste into Claude:
+
+| Prompt | What Claude calls |
+|---|---|
+| "How many `DetailViewModel` instances are leaking?" | `countAlive(path, className: "DetailViewModel")` |
+| "Show the retain chain that keeps `DetailViewModel` alive." | `findRetainers(path, className: "DetailViewModel")` |
+| "Compare `~/Desktop/before.memgraph` to `~/Desktop/after.memgraph` — did the leak go away?" | `diffMemgraphs(before, after)` |
+| "Render the cycle as a Mermaid graph for the PR description." | `renderCycleGraph(path, format: "mermaid")` |
+| "Profile this app on my iPhone for 90 seconds and tell me about hangs." | `listTraceDevices` → `recordTimeProfile` → `analyzeHangs` |
+| "Pull the last 5 minutes of `error`-level logs from `MyApp`." | `logShow(last: "5m", process: "MyApp", level: "default")` |
+| "Run my XCUITest with leak detection." | `detectLeaksInXCUITest(workspace, scheme, testIdentifier, …)` |
+
+The agent decides which tool to call based on your prompt — you don't need to remember the tool names.
+
+---
+
+## 5. Troubleshooting
+
+### `memorydetective: command not found`
+
+The npm global install isn't on your `$PATH`. Check:
+
+```bash
+which memorydetective
+npm prefix -g
+```
+
+If `npm prefix -g` returns something not in your `$PATH`, add it. Or use the binary directly:
+
+```bash
+$(npm prefix -g)/bin/memorydetective --version
+```
+
+### `analyzeTimeProfile` returns a SIGSEGV notice
+
+Known limit. `xcrun xctrace export` of the `time-profile` schema crashes on heavy unsymbolicated traces. Workarounds (in order of effort):
+
+1. Open the trace once in Instruments.app (forces symbolication), then close it. Re-run `analyzeTimeProfile`.
+2. Re-record with a shorter `--time-limit` (try 30 s instead of 90 s).
+3. For hang analysis specifically, use `analyzeHangs` instead — it parses a different (lighter) schema that doesn't crash.
+
+### `captureMemgraph` fails on a physical iOS device
+
+By design. `leaks(1)` only attaches to processes on the local Mac (which includes iOS simulators). Memory Graph capture from a physical device goes through Xcode's debugger over USB — different mechanism, no public CLI equivalent. Use Xcode's Memory Graph button + File → Export Memory Graph for physical devices.
+
+### Tests pass locally but fail in CI
+
+The stress test has a wallclock budget that's tighter on slower runners. If you see `expected NNNms to be less than 2000`, bump `PARSE_BUDGET_MS` in `src/stress.test.ts`.
+
+### `detectLeaksInXCUITest` says "after-capture failed"
+
+The app process exited before `leaks --outputGraph` could attach. Configure your XCUITest to keep the app alive at end-of-test (e.g. `XCTAssertTrue(true); _ = XCTWaiter.wait(for: [...], timeout: 1.0)`), or use a longer simulator boot. This tool is **experimental** in v1.0 — feedback welcome.
+
+---
+
+## 6. Where to go from here
+
+- **Add a new cycle pattern**: see the *Adding a cycle pattern to `classifyCycle`* section in [`README.md`](./README.md#contributing).
+- **Run a custom analysis from scratch**: every tool's input schema is documented via the MCP `tools/list` request. Hit the server with `{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}` over stdio.
+- **Open an issue**: https://github.com/carloshpdoc/memorydetective/issues — bug reports, feature requests, and pattern contributions are all welcome.