pi-jscpd 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -7,6 +7,27 @@ published releases use [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-09-18
+
+### Added
+
+- Added an explicit **pi-jscpd** benchmarks table and `docs/benchmarks.md` for
+  isolated `/jscpd scan` runs on pinned public Vite, React, Vue, Svelte,
+  Express, and Prettier trees.
+
+### Changed
+
+- Keep jscpd summary statistics when a structured report lists more clone pairs
+  than the session may retain, and present bounded findings instead of failing
+  the whole scan as an invalid report.
+- Certified Pi 0.85.1 across both supported Node fixtures and widened the Pi
+  peer range through the 0.85 line after API review, packed-artifact checks,
+  compact/expanded transcript probes, narrow real-TUI smoke tests, and active
+  scan cancellation/cleanup verification.
+- Concentrated the approved public version in one reviewed source so release
+  preparation no longer repeats the same version literal across publication
+  guards.
+
 ## [0.2.1] - 2026-09-06
 
 ### Added
@@ -123,7 +144,8 @@ published releases use [Semantic Versioning](https://semver.org/).
 - Project paths, child output, reports, temporary directories, cancellation,
   configuration trust, and lifecycle cleanup are bounded and fail open.
 
-[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/revazi/pi-jscpd/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/revazi/pi-jscpd/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/revazi/pi-jscpd/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/revazi/pi-jscpd/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/revazi/pi-jscpd/compare/v0.1.0...v0.1.1

package/CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to pi-jscpd
+# 👋 Contributing to pi-jscpd
 
 Thanks for helping improve `pi-jscpd`. Changes should preserve the extension's
 quiet, advisory, read-only, bounded, and fail-open behavior. jscpd remains the
@@ -23,6 +23,30 @@ agent flow is insufficient. Do not propose an independent clone detector,
 automatic source edits, surprise binary installation, or mandatory
 JavaScript-only parsing in the core workflow.
 
+## Validation and adoption feedback
+
+Use the [feedback form](https://github.com/revazi/pi-jscpd/issues/new?template=adoption-feedback.yml)
+for installation, scoped scans, finding review, navigation, configuration, and
+team-workflow observations. Prefer the [bug report](https://github.com/revazi/pi-jscpd/issues/new?template=bug-report.yml)
+for a reproducible defect and the [feature request](https://github.com/revazi/pi-jscpd/issues/new?template=feature-request.yml)
+for a concrete proposal. Suspected vulnerabilities belong in private reporting
+under [SECURITY.md](SECURITY.md).
+
+Feedback is optional and manually submitted to a public issue. Supply only
+versions, coarse size/latency/count buckets, generic formats, and at most six
+short observation bullets. Do not include credentials, private paths, source
+fragments, raw reports, raw child output, terminal captures, account/repository
+identifiers, or attachments. Choose Unknown / Not tested rather than conducting
+new scans or sharing identifying details. The form is guidance, not an automatic
+redaction mechanism: review every answer before submitting.
+
+Distinguish the pairs actually inspected from omitted/unreviewed findings, and
+keep inspection candidates, likely expected repetition, and uncertain judgments
+separate. These are provisional priorities—not approved refactors or a measured
+false-positive rate. Feedback informs the next milestone; it does not activate a
+feature candidate by itself. Existing [validation limitations](docs/m8-validation.md#remaining-acceptance-and-decision)
+remain explicit.
+
 ## Development setup
 
 Use a host from the [compatibility matrix](docs/compatibility.md). Install the
@@ -42,7 +66,11 @@ approved Effect runtime boundary, type checks strict ESM TypeScript, runs
 Biome's formatting/lint checks, and executes the network-free test suite. The
 documentation and hygiene checks validate public local links, release metadata,
 ignored/private path policy, package metadata, and the non-publishing readiness
-workflow. `pack:certify` installs and exercises the exact tarball.
+workflow. Tests also parse every issue-template YAML file, validate the form
+fields used by this repository, and check feedback privacy/bucket requirements
+and issue-template links without contacting GitHub. The exact-pinned development
+`yaml` dependency is only a validation parser; it adds no extension runtime
+service. `pack:certify` installs and exercises the exact tarball.
 CI repeats those checks on Node 22.19.0 and 24.12.0.
 
 Tests must not require network access, read or modify global Pi configuration,

package/README.md

@@ -6,14 +6,22 @@
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![GitHub issues](https://img.shields.io/github/issues/revazi/pi-jscpd.svg)](https://github.com/revazi/pi-jscpd/issues)
 
-A quiet, read-only duplication guardrail for the [Pi coding agent](https://github.com/earendil-works/pi), powered by [jscpd](https://github.com/kucherenko/jscpd).
+A quiet, read-only duplication guardrail for the
+[Pi coding agent](https://github.com/earendil-works/pi), powered by
+[jscpd](https://github.com/kucherenko/jscpd).
 
 `pi-jscpd` detects duplicate blocks introduced during a Pi session, shows both
 locations, and helps you inspect, refactor, test, and verify the result. jscpd
 remains the source of truth for tokenization, clone detection, supported
 languages, and statistics.
 
-## Install
+| 🤫 Quiet | 🧭 Advisory | 🌍 Polyglot | 🛟 Fail open |
+| --- | --- | --- | --- |
+| Clean checks stay out of the model | Never blocks a write or edits source | Uses jscpd’s languages, not a JS-only parser | A missing analyzer never breaks Pi |
+
+[Install](#install) · [Usage](#usage) · [pi-jscpd benchmarks](#pi-jscpd-benchmarks) · [Overview](#interactive-overview) · [Safety](#safety-and-privacy)
+
+## 📦 Install
 
 ```sh
 pi install npm:pi-jscpd
@@ -23,14 +31,18 @@ pi install npm:pi-jscpd
 separate analyzer setup or runtime download. It prefers a compatible project or
 `PATH` installation and otherwise uses its bundled analyzer.
 
-Start Pi in your project and verify the setup:
+Start (or restart) Pi in your project, check readiness, then scan a directory
+that exists in your project:
 
 ```text
 /jscpd status
+/jscpd scan src
 ```
 
-If no compatible binary is available, the extension stays dormant and Pi
-continues normally.
+No extension configuration is required. A scoped scan finds matches only within
+its targets; use `/jscpd scan` to include the whole project. If no compatible
+binary is available, the extension stays dormant and Pi continues normally;
+status explains how to recover.
 
 In TUI sessions, the extension performs one best-effort, metadata-only npm check
 and shows a warning only when a newer `pi-jscpd` release is available. The check
@@ -38,21 +50,21 @@ is bounded to 1.5 seconds, never sends project data, and never downloads or
 installs package content. Set `PI_JSCPD_DISABLE_UPDATE_NOTICE=1` (or run Pi
 offline) to disable it.
 
-## Usage
+## ⌨️ Usage
 
 Run `/jscpd` to open the interactive overview. Opening it shows status only; it
 never starts an implicit scan.
 
-| Command | Purpose |
-| --- | --- |
-| `/jscpd` | Open the responsive overview |
-| `/jscpd changed` | Show unacknowledged duplication introduced this session |
-| `/jscpd scan` | Scan the whole project |
-| `/jscpd scan src tests` | Scan specific in-project files or directories |
-| `/jscpd status` | Show binary, configuration, mode, and last-check status |
-| `/jscpd off` | Disable scans for the current session |
-| `/jscpd on` | Re-enable scans for the current session |
-| `/jscpd help` | Show command help |
+| | Command | Purpose |
+| --- | --- | --- |
+| 🖥️ | `/jscpd` | Open the responsive overview |
+| 🆕 | `/jscpd changed` | Show unacknowledged duplication introduced this session |
+| 🔍 | `/jscpd scan` | Scan the whole project |
+| 📂 | `/jscpd scan src tests` | Scan specific in-project files or directories |
+| 📋 | `/jscpd status` | Show binary, configuration, mode, and last-check status |
+| ⏸️ | `/jscpd off` | Disable scans for the current session |
+| ▶️ | `/jscpd on` | Re-enable scans for the current session |
+| ❓ | `/jscpd help` | Show command help |
 
 Pi can use the same operations through the `jscpd_run` tool:
 
@@ -78,7 +90,32 @@ description at startup and loads its full workflow guidance on demand when a
 duplication task matches or the user invokes the skill command. The extension
 and `jscpd_run` tool remain usable when skills are disabled.
 
-## How session checks work
+For short walkthroughs, see [clean scans, new session duplication, and intentional
+duplication](docs/adoption.md). A finding is a reason to inspect, not permission
+to refactor.
+
+## 📊 pi-jscpd benchmarks
+
+These are **pi-jscpd** benchmarks, not a raw `jscpd` CLI. Each cell is an isolated
+Pi 0.85.1 `/jscpd scan` through this extension (packaged jscpd `5.1.2` still
+detects). Full-tree snapshots, not session findings and not a quality ranking.
+Median of three fresh host processes on macOS arm64 / Node 24.12.0, 2026-09-17.
+
+| | Project | Version | Blocks | Dup. lines | `/jscpd scan` |
+| --- | --- | --- | ---: | ---: | ---: |
+| ⚡ | [Vite](https://github.com/vitejs/vite) | [v8.3.0](https://github.com/vitejs/vite/tree/434e8e9495436a60789f2b588a04a6a24a3d1661) | 524 | 5.91% | 498 ms |
+| ⏱️ | [React](https://github.com/facebook/react) | [v19.3.0](https://github.com/facebook/react/tree/1d34f91dfde6bba84d08b683aaba164c7194dacb) | 10,812 | 17.38% | 3.11 s |
+| ⚡ | [Vue](https://github.com/vuejs/core) | [v3.5.43](https://github.com/vuejs/core/tree/5be58b4c475c1d14b4abacbfeda610394a0ee4e5) | 805 | 6.71% | 451 ms |
+| ⏱️ | [Svelte](https://github.com/sveltejs/svelte) | [svelte@5.57.0](https://github.com/sveltejs/svelte/tree/7bc0a70fe64dbb3fa3848b741963f31d1e10a8dc) | 1,102 | 8.27% | 1.25 s |
+| ⚡ | [Express](https://github.com/expressjs/express) | [v5.2.1](https://github.com/expressjs/express/tree/dbac741a49a5a64336b70c06e85c2e2706e36336) | 274 | 11.19% | 142 ms |
+| ⏱️ | [Prettier](https://github.com/prettier/prettier) | [3.9.8](https://github.com/prettier/prettier/tree/4f2ab6765d7cb29408a2abdac75d023d64d44107) | 976 | 4.88% | 1.16 s |
+
+⚡ under 1 s · ⏱️ 1 s or more. Totals are jscpd’s; the session lists a bounded subset.
+Version links open the exact scanned commit. Method and sample times:
+[pi-jscpd benchmark method](docs/benchmarks.md). Scheduled refresh:
+[#111](https://github.com/revazi/pi-jscpd/issues/111).
+
+## 🔄 How session checks work
 
 At session start, the extension captures one bounded, in-memory project baseline.
 It then tracks successful writes and edits made through Pi's built-in `write`
@@ -87,11 +124,11 @@ and `edit` tools.
 After Pi settles, one coalesced background check compares the current project
 with the baseline:
 
-- clean checks stay out of model context;
-- failures remain advisory and available through `/jscpd status`;
-- new duplicate blocks are reported with both locations;
-- existing repository duplication is omitted from changed-only results; and
-- actionable automatic findings never trigger a surprise model turn.
+- 🤫 clean checks stay out of model context;
+- ⚠️ failures remain advisory and available through `/jscpd status`;
+- 📍 new duplicate blocks are reported with both locations;
+- 🗂️ existing repository duplication is omitted from changed-only results; and
+- 🚫 actionable automatic findings never trigger a surprise model turn.
 
 Displayed findings are acknowledged for the active conversation branch so the
 same unchanged block is not repeatedly reported. Baselines, source bytes,
@@ -101,20 +138,27 @@ Manual edits, shell commands, custom mutation tools, deletes, and renames are no
 attributed because Pi does not provide a stable structured file list for them.
 Use `/jscpd scan` when changes happened outside built-in `write` or `edit`.
 
-## Interactive overview
+## 🖥️ Interactive overview
+
+![Real /jscpd findings view: one Python duplicate block, both current locations, and advisory review guidance](docs/images/jscpd-findings.png)
+
+*Real Pi TUI, disposable synthetic project, explicit project scan and Enter to
+expand. Monochrome terminal-cell capture cropped to the overlay; no mock results.
+This is current duplication, not a session-delta example.
+[Capture details and text alternative](docs/adoption.md#visual-provenance).*
 
 Bare `/jscpd` opens a status-first, Fallow-style bounded TUI with:
 
-- a framed overview of mode, binary, configuration, last check, and explicit
+- 📋 a framed overview of mode, binary, configuration, last check, and explicit
   changed/project scan actions;
-- a searchable, scrollable findings navigator that retains up to 100 findings,
+- 🔎 a searchable, scrollable findings navigator that retains up to 100 findings,
   initially shows 10, and reveals the next 10 with `L` or by navigating past the
   last shown row—without rescanning or changing configuration;
-- both duplicate locations, size, format, session relationship, inline detail,
+- 📍 both duplicate locations, size, format, session relationship, inline detail,
   verification, and omission/ambiguity context;
-- `j`/`k`, arrows, Home/End, paging, expand/collapse, search, and multi-selection
+- ⌨️ `j`/`k`, arrows, Home/End, paging, expand/collapse, search, and multi-selection
   controls consistent with Pi Fallow's navigator; and
-- a bounded `e`/`a` handoff that closes the overlay and loads selected findings
+- ✉️ a bounded `e`/`a` handoff that closes the overlay and loads selected findings
   into Pi's editor for user review.
 
 The extra overlay cache is in-memory and TUI-only. `maxFindings` still caps
@@ -125,7 +169,7 @@ runs project tests, or refactors automatically. In RPC, JSON, and print modes,
 explicit subcommands remain available and the bare command uses a bounded
 non-interactive fallback.
 
-## Configuration
+## ⚙️ Configuration
 
 Project configuration is optional:
 
@@ -156,9 +200,16 @@ Clone thresholds, formats, ignore rules, and other detection policy belong in
 jscpd's normal configuration, such as `.jscpd.json` or package-level jscpd
 settings. The extension does not maintain a parallel clone policy.
 
-## Fallow coexistence
+## 🤝 Fallow coexistence
+
+| | Choose | When it fits |
+| --- | --- | --- |
+| 🧬 | `pi-jscpd` | Focused polyglot duplicate-block review, session deltas, or reuse of existing jscpd detection/CI policy |
+| 🌿 | Pi Fallow | Broader JavaScript/TypeScript codebase analysis, including duplication, dead code, complexity, and related checks |
+| 🤝 | Both | Fallow's broader checks plus scoped jscpd analysis where its formats or existing policy add value; avoid checking the same duplication scope twice without a reason |
 
-Pi Fallow can also detect duplication. With the default `auto` policy,
+Neither replaces the other's full workflow or your repository's tests and CI
+policy. Pi Fallow can also detect duplication. With the default `auto` policy,
 `pi-jscpd` conservatively detects supported signs of active Fallow duplication
 analysis and moves automatic jscpd checks to on-demand mode to avoid duplicate
 warnings.
@@ -170,25 +221,25 @@ Explicit `/jscpd changed`, project scans, and scoped scans remain available. Set
 See [Fallow coexistence](docs/fallow-coexistence.md) for the supported signals
 and limitations.
 
-## Safety and privacy
+## 🔒 Safety and privacy
 
-- Advisory and read-only by default.
-- Never downloads packages at runtime or mutates source.
-- Invokes binaries with argument arrays, never a shell command string.
-- Keeps reports in restrictive temporary directories and removes them after
+- 🧭 Advisory and read-only by default.
+- 📦 Never downloads packages at runtime or mutates source.
+- 🧱 Invokes binaries with argument arrays, never a shell command string.
+- 🧹 Keeps reports in restrictive temporary directories and removes them after
   success, failure, timeout, cancellation, or shutdown.
-- Bounds process time, output, report size, findings, paths, and persisted state.
-- Omits source fragments, raw child output, temporary paths, and internal
+- ⏱️ Bounds process time, output, report size, findings, paths, and persisted state.
+- 🙈 Omits source fragments, raw child output, temporary paths, and internal
   fingerprints from results.
-- Reads extension configuration only for trusted projects.
-- Fails open so analyzer problems do not break the Pi session.
+- 🔐 Reads extension configuration only for trusted projects.
+- 🛟 Fails open so analyzer problems do not break the Pi session.
 
-## Requirements
+## ✅ Requirements
 
 | Component | Supported |
 | --- | --- |
 | Node.js | `>=22.19.0 <23` or `>=24 <25` |
-| Pi packages | `>=0.84.4 <0.85.0` |
+| Pi packages | `>=0.84.4 <0.85.0` or `>=0.85.1 <0.86.0` (tested with `0.85.1`) |
 | TypeBox | `>=1.3.7 <2` |
 | Effect | Exact reviewed `3.22.1` runtime foundation |
 | jscpd | Bundled `5.1.2`; compatible project-local or `PATH` v5 installations are preferred |
@@ -196,7 +247,20 @@ and limitations.
 See the [compatibility policy](docs/compatibility.md) for the exact tested
 fixtures and certification matrix.
 
-## More Pi packages by Revaz
+## 💬 Share feedback
+
+Tried a scan or the onboarding examples? Use the optional [validation and adoption
+feedback form](https://github.com/revazi/pi-jscpd/issues/new?template=adoption-feedback.yml).
+It asks for version information and coarse size, latency, and finding-review
+buckets; “Unknown” and “Not tested” are welcome. No new scan is required.
+
+Submissions are public and manual—no telemetry or automatic submission is added.
+Do not include credentials, private paths, source fragments, raw reports, raw
+child output, terminal captures, or account/repository identifiers. For a
+reproducible defect, prefer the [bug report](https://github.com/revazi/pi-jscpd/issues/new?template=bug-report.yml);
+report vulnerabilities [privately](SECURITY.md).
+
+## 🧩 More Pi packages by Revaz
 
 | Package | Purpose |
 | --- | --- |
@@ -206,7 +270,7 @@ fixtures and certification matrix.
 | [`pi-tmux-orchestrator`](https://www.npmjs.com/package/pi-tmux-orchestrator) | Multi-agent coordination in tmux |
 | [`@tasklight/pi-tasklight`](https://www.npmjs.com/package/@tasklight/pi-tasklight) | Tasklight notifications for Pi |
 
-## Development
+## 🛠️ Development
 
 ```sh
 npm ci --ignore-scripts
@@ -228,16 +292,19 @@ workflow files.
 
 Useful documentation:
 
-- [Effect architecture and conformance](docs/effect-architecture.md)
-- [Automatic checkpoint lifecycle](docs/automatic-checkpoint.md)
-- [`/jscpd` overlay contract](docs/overlay-interaction.md)
-- [Fallow coexistence](docs/fallow-coexistence.md)
-- [Compatibility and packed-artifact certification](docs/compatibility.md)
-- [Release preparation and publication policy](docs/release.md)
-- [Contributing](CONTRIBUTING.md)
-- [Security policy](SECURITY.md)
-- [Changelog](CHANGELOG.md)
-
-## License
+- 📊 [pi-jscpd benchmarks](docs/benchmarks.md)
+- ✨ [First scans and safe finding review](docs/adoption.md)
+- 🧬 [Effect architecture and conformance](docs/effect-architecture.md)
+- ⏱️ [Automatic checkpoint lifecycle](docs/automatic-checkpoint.md)
+- 🖥️ [`/jscpd` overlay contract](docs/overlay-interaction.md)
+- 🤝 [Fallow coexistence](docs/fallow-coexistence.md)
+- ✅ [Compatibility and packed-artifact certification](docs/compatibility.md)
+- 📋 [Real-project validation evidence](docs/m8-validation.md)
+- 🏷️ [Release preparation and publication policy](docs/release.md)
+- 👋 [Contributing](CONTRIBUTING.md)
+- 🔐 [Security policy](SECURITY.md)
+- 📝 [Changelog](CHANGELOG.md)
+
+## 📄 License
 
 [MIT](./LICENSE) © 2026 Revaz Zakalashvili

package/SECURITY.md

@@ -1,4 +1,4 @@
-# Security policy
+# 🔐 Security policy
 
 ## Supported versions
 

package/docs/adoption.md

@@ -0,0 +1,131 @@
+# ✨ First scans and safe finding review
+
+[Install and run your first scan](../README.md#install), then choose the smallest
+useful scope below. These examples describe expected workflows, not transcripts
+or claims about your repository. All scans are read-only and advisory.
+
+## ✦ Clean scan: start with one scope
+
+```text
+/jscpd scan src
+```
+
+If jscpd finds no duplicate blocks under `src` with the current detection policy,
+the explicit result is clean. This does **not** prove the entire repository is
+free of duplication: matches outside that target, ignored files, unsupported
+formats, and blocks below the configured thresholds are outside the result.
+A failure or timeout is not a clean scan; `/jscpd status` gives bounded diagnostics
+and Pi can continue normally.
+
+To compare two areas, include both:
+
+```text
+/jscpd scan src lib
+```
+
+Replace the targets with existing in-project paths. Quote a path containing spaces,
+for example `/jscpd scan "sample app"`. Scoped scans compare only their targets;
+`/jscpd changed` instead compares the full project and filters by tracked Pi edits.
+
+## 🔄 New in this session: distinguish new work from existing debt
+
+Suppose `src/orders.py` already contains a block when a fresh Pi session begins.
+Later, Pi's built-in `write` or `edit` adds matching code in `src/summary.py`.
+With a usable baseline and an identifiable new pair, the changed check can show:
+
+- `src/summary.py`: **new in this session**;
+- `src/orders.py`: **existing match**;
+- the duplicate block's line spans, size, and format for inspection.
+
+```text
+/jscpd changed
+```
+
+Automatic checks normally surface actionable new findings after Pi settles,
+without starting another model turn. If the finding was already surfaced, an
+explicit changed check may omit it because it is acknowledged—not because it was
+fixed. Existing repository duplication is also omitted from changed-only findings.
+Use `/jscpd scan src` (or a project scan for matches outside `src`) to inspect
+current duplication regardless of acknowledgement.
+
+A full or scoped `scan` labels **current locations**; it does not determine which
+side is new. A missing/partial baseline or ambiguous identity is not proof of a
+new duplicate. Shell commands, manual edits, and custom mutation tools are not
+tracked as Pi-owned changes; use an explicit `scan` for those changes.
+See [session checks](../README.md#how-session-checks-work) for the lifecycle and
+[Fallow coexistence](fallow-coexistence.md) when automatic checks are on demand.
+
+## 📌 Intentional duplication: use normal jscpd policy
+
+A duplicate test fixture may deliberately preserve an independent example or a
+protocol boundary. Inspect both locations and ask whether they should evolve
+together. Keeping the duplicate can be the correct outcome; no exclusion is
+required merely to dismiss an advisory finding.
+
+If the maintainer decides a fixture directory should be outside detection,
+merge a narrow exclusion into the repository's existing `.jscpd.json` policy:
+
+```json
+{
+  "ignore": ["**/test/fixtures/**"]
+}
+```
+
+This is an example for a deliberately excluded fixture directory, not a
+recommendation to ignore all tests. Preserve other ignore entries and settings;
+do not replace an existing configuration with this snippet. Repositories using
+package-level jscpd settings should keep their policy there instead. Detection
+policy does not belong in `.pi/jscpd-guardrail.json`.
+
+Review the policy change through the normal agent/code-review flow, then rerun
+the same scan scope. Fewer findings after an exclusion mean less code was analyzed,
+not that source duplication was removed. Start a fresh Pi session (rather than
+resuming previously tracked edits) before a session-delta comparison under changed
+detection policy so its baseline uses the same policy.
+
+## 🔍 Review without automatic refactoring
+
+1. Open `/jscpd`, choose a scan action, then press Enter on a finding to expand
+   both locations. Opening the overview itself does not scan.
+2. Read both blocks and surrounding behavior before deciding whether to share
+   code, retain independent implementations, or propose a narrow exclusion.
+3. Optionally press `e` to load the current/selected finding into Pi's editor.
+   Review the prompt before submitting; the handoff does not submit or edit code.
+4. Only make a justified change through your normal agent flow. Run relevant
+   project tests, then repeat the same scan scope. Verification can report removed,
+   remaining, or newly created duplicate blocks; it does not prove behavior is
+   correct. Respect omitted and safely unclassified counts.
+
+[Full overlay controls](overlay-interaction.md#keyboard-and-accessibility-contract)
+and the on-demand `/skill:jscpd` provide the detailed workflow without adding
+routine guidance to every model turn. `/jscpd off` disables both explicit and
+automatic scans for this session; `/jscpd on` restores scanning. Neither edits
+configuration, enforces a threshold on Pi writes, or refactors code.
+
+## 📷 Visual provenance
+
+The [README image](images/jscpd-findings.png) comes from the unmodified source
+extension at `fa7872d`, loaded by real Pi 0.85.1 with Node 24.12.0 and bundled
+jscpd 5.1.2 on macOS arm64. An isolated, disposable project contained two generated
+Python files; no private repository was used. The real analyzer found one pair
+(14 lines, 89 tokens). Both files existed before Pi started, so this image shows
+**current locations**, not newly introduced duplication.
+
+Capture sequence: regular TUI at 80 columns by 32 rows, `/jscpd`, `s` for project
+scan, Enter to expand the finding. The terminal cells were rasterized in monochrome
+and cropped to the overlay. No text, counts, labels, or results were substituted;
+compact-row truncation and wrapping are the actual TUI output. The image is
+1192×652 pixels and is intended to remain readable when scaled to README width.
+
+Text alternative: one Python duplicate block links `src/orders.py:1-14` and
+`src/summary.py:1-14`. Detail records a verification checkpoint, explains that a
+project scan cannot decide which location is new, and asks the user to inspect
+both locations and surrounding behavior before changing code.
+
+The capture run used offline mode, isolated home/agent/temp directories, no
+session persistence, no project trust approval, no resource discovery, and no
+provider or built-in tool calls. Pi quit normally; no analyzer reports remained.
+Only the cropped sanitized PNG and this aggregate provenance are retained—not
+raw terminal output, source fixtures, reports, host/account data, or private paths.
+This adoption visual is separate from the [#99 validation
+evidence](m8-validation.md); it makes no additional performance or usability claim.

package/docs/automatic-checkpoint.md

@@ -1,4 +1,4 @@
-# Automatic advisory checkpoint decision
+# ⏱️ Automatic advisory checkpoint decision
 
 Status: **implemented with Effect-owned scheduling and automatic delivery**
 
@@ -33,8 +33,9 @@ candidate check, not one process per write or model turn.
 
 ## Evidence
 
-The decision was evaluated against Pi 0.84.4's installed extension
-documentation, public type definitions, and `AgentSession` runtime.
+The decision was originally evaluated against Pi 0.84.4 and rechecked against
+Pi 0.85.1's published extension documentation, public type definitions, and
+`AgentSession` runtime. The 0.85 lifecycle contract remains compatible.
 
 Pi documents and types distinguish the candidate events as follows:
 

package/docs/benchmarks.md

@@ -0,0 +1,78 @@
+# 📊 pi-jscpd benchmarks
+
+These rows are **pi-jscpd benchmarks**, not a raw `jscpd` CLI. Each sample loads the
+source extension into an isolated Pi 0.85.1 RPC host and runs `/jscpd scan` on a
+pinned public tree. jscpd `5.1.2` remains the detector; the times and outcomes
+include capability resolution, report decoding, normalization, and the public
+notify. They are **full-tree duplication snapshots**, not session-delta findings
+and not a code-quality ranking.
+
+Host: macOS arm64, Node 24.12.0, Pi 0.85.1, packaged jscpd `5.1.2`. Date:
+2026-09-17. No project `.jscpd.json`. Shallow clones of the listed tags. Reports
+stayed in owned temporary directories and were removed. Pi ran offline, without
+discovery, project trust, session persistence, a provider, or built-in tools.
+
+Three fresh Pi processes per project. **Scan** is milliseconds from `/jscpd scan`
+until the extension notify. Host ready (start + command discovery) was about
+1.2–1.5 s and is **not** included in scan time.
+
+## pi-jscpd snapshot
+
+| Project | Pin | Sources | Duplicate blocks | Dup. lines | Median `/jscpd scan` |
+| --- | --- | ---: | ---: | ---: | ---: |
+| [Vite](https://github.com/vitejs/vite) | [v8.3.0](https://github.com/vitejs/vite/tree/434e8e9495436a60789f2b588a04a6a24a3d1661) | 1,107 | 524 | 5.91% | 498 ms |
+| [React](https://github.com/facebook/react) | [v19.3.0](https://github.com/facebook/react/tree/1d34f91dfde6bba84d08b683aaba164c7194dacb) | 7,962 | 10,812 | 17.38% | 3.11 s |
+| [Vue](https://github.com/vuejs/core) | [v3.5.43](https://github.com/vuejs/core/tree/5be58b4c475c1d14b4abacbfeda610394a0ee4e5) | 598 | 805 | 6.71% | 451 ms |
+| [Svelte](https://github.com/sveltejs/svelte) | [svelte@5.57.0](https://github.com/sveltejs/svelte/tree/7bc0a70fe64dbb3fa3848b741963f31d1e10a8dc) | 4,499 | 1,102 | 8.27% | 1.25 s |
+| [Express](https://github.com/expressjs/express) | [v5.2.1](https://github.com/expressjs/express/tree/dbac741a49a5a64336b70c06e85c2e2706e36336) | 183 | 274 | 11.19% | 142 ms |
+| [Prettier](https://github.com/prettier/prettier) | [3.9.8](https://github.com/prettier/prettier/tree/4f2ab6765d7cb29408a2abdac75d023d64d44107) | 3,320 | 976 | 4.88% | 1.16 s |
+
+Every row returned findings. Notifies stayed at 47 lines (presentation cap).
+React and Svelte keep jscpd’s full totals; the session retains at most 1,000
+path-resolved pairs and does not keep source fragments or the raw JSON.
+
+Prettier clone counts were 976 / 982 / 976. The table keeps the repeating
+976 / 4.88% snapshot.
+
+Sample `/jscpd scan` times (ms):
+
+| Project | First | Later | Median |
+| --- | ---: | ---: | ---: |
+| Vite | 560 | 470, 498 | 498 |
+| React | 3,107 | 3,210, 2,974 | 3,107 |
+| Vue | 399 | 459, 451 | 451 |
+| Svelte | 1,292 | 1,251, 1,241 | 1,251 |
+| Express | 142 | 141, 145 | 142 |
+| Prettier | 1,163 | 1,112, 1,177 | 1,163 |
+
+## How to read this
+
+- This is the extension’s explicit project scan, not `jscpd` invoked by hand
+  and not a TUI overlay run.
+- **Sources** and **duplicate blocks** come from the public notify summary after
+  decoding. They are jscpd totals, even when extra pairs are omitted from the
+  listed findings.
+- **Median scan** is not a SLA. It includes analyzer work plus `pi-jscpd`
+  decoding and presentation.
+- A higher percentage is not “worse code.” Scaffolding and tests duplicate on
+  purpose.
+
+Scheduled refresh is tracked in
+[issue #111](https://github.com/revazi/pi-jscpd/issues/111).
+
+## Reproduction
+
+On a supported Node fixture with this repository’s locked dependencies:
+
+1. Shallow-clone each tag into an owned temporary directory.
+2. Start isolated Pi 0.85.1 in RPC mode: offline, no session, no discovery, no
+   project trust, no built-in tools, `--tools jscpd_run`, and `-e` pointing at
+   this source extension. Put the packaged `node_modules/.bin` on `PATH`.
+3. After the host is ready, send `/jscpd scan`. Time until the extension notify.
+   Keep only the summary line (counts and timings). Do not retain notify bodies,
+   paths, or reports.
+4. Repeat in three fresh Pi processes. Confirm stderr is empty and report
+   directories are gone after shutdown.
+5. Delete the clone.
+
+Do not commit clones, reports, or source fragments.