@kujolang/paperclip 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.7 - 2026-09-04
+
+- Rewrite the README in plain English with a 30-second install path, first-use steps,
+  copyable agent requests, and clear compatibility notes.
+- Add monochrome npm and CI badges alongside the standard Kujo version, license, and
+  build badges.
+- Correct the documented Context Pack file limits and reject unknown `npm run`
+  commands in repository documentation.
+- Upgrade the bundled Kujo runtime to 1.2.3 and refresh the Node and React DOM type
+  definitions after full verification.
+
 ## 0.1.6 - 2026-09-03
 
 - Add deterministic Chromium coverage for both Paperclip UI surfaces, all primary

package/README.md

@@ -1,12 +1,16 @@
 # Kujo for Paperclip
 
-[![Version](https://img.shields.io/badge/version-0.1.6-black)](https://github.com/kujolang/paperclip/releases/tag/v0.1.6)
+[![Version](https://img.shields.io/badge/version-0.1.7-black)](https://github.com/kujolang/paperclip/releases/tag/v0.1.7)
+[![npm](https://img.shields.io/npm/v/%40kujolang%2Fpaperclip?label=npm&color=black)](https://www.npmjs.com/package/@kujolang/paperclip)
+[![CI](https://img.shields.io/github/actions/workflow/status/kujolang/paperclip/ci.yml?branch=main&label=CI&color=black)](https://github.com/kujolang/paperclip/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey)](LICENSE)
 [![built with Kujo](https://img.shields.io/badge/built%20with-Kujo-white.svg)](https://github.com/kujolang/kujo)
 
-Add scoped context, change review, and reproducible failure evidence to Paperclip.
+Kujo helps Paperclip agents choose useful context, review changes, and save clear
+failure evidence. It runs locally inside Paperclip and works in the current task view.
+You do not need the Classic Task Interface.
 
-## Install
+## Install in 30 seconds
 
 You need Paperclip `2026.824.1` or later and Node.js `24.11.0` or later.
 
@@ -14,48 +18,69 @@ You need Paperclip `2026.824.1` or later and Node.js `24.11.0` or later.
 npx paperclipai plugin install @kujolang/paperclip
 ```
 
-Restart Paperclip if it is already running. Kujo appears automatically inside Paperclip's current task view. On project and run pages, open the **Kujo** tab. You do not need to switch to the Classic Task Interface.
+Restart Paperclip if it is already running, then open an issue. The Kujo workspace
+appears in the task view. You can also open the **Kujo** tab on project, issue detail,
+and run pages.
 
-The npm package includes the correct Kujo runtime for macOS arm64/x64, Linux arm64/x64, and Windows x64. Installation does not run `preinstall`, `install`, or `postinstall` scripts.
+The npm package includes the right Kujo runtime for macOS arm64/x64, Linux arm64/x64,
+and Windows x64. You do not need a separate Kujo install or Kujo API key. Installation
+does not run `preinstall`, `install`, or `postinstall` scripts.
 
-See [Installation](docs/INSTALLATION.md) for upgrades, local development installs, and uninstall behavior.
+Use the package name exactly as shown for now. Current Paperclip releases mishandle a
+scoped package with an exact version suffix. The upstream fix is open in
+[paperclipai/paperclip#12745](https://github.com/paperclipai/paperclip/pull/12745).
 
-## Use
+See [Installation](docs/INSTALLATION.md) for upgrades, local development installs,
+uninstall behavior, and release checks.
 
-Open an issue to use the inline Kujo workspace, or open the **Kujo** tab on a project, issue detail page, or run to:
+## First use
 
-- generate a **Review Pack** for the working tree;
-- create a task-specific **Context Pack**;
-- capture bounded, redacted **Failure Evidence**.
+1. Open the Paperclip issue you want to work on.
+2. Generate a focused **Context Pack** before the agent reads the repository broadly.
+3. Make and test the change with the project's normal tools.
+4. Generate a **Review Pack** to inspect scope, risk, and suggested checks.
+5. If a command fails, save its bounded output as **Failure Evidence**.
 
-Agents can call four tools:
+Kujo stores the latest result in Paperclip plugin state. It does not write reports into
+the project repository.
+
+## What Kujo adds
+
+| Workflow | What it does | Kujo component |
+| --- | --- | --- |
+| **Context Pack** | Selects a small, task-specific set of files before an agent reads broadly. | Scent |
+| **Review Pack** | Measures change size, explains risk signals, and prepares a review handoff. | ChangeBucket and PatchBrief |
+| **Failure Evidence** | Turns supplied command details and logs into a bounded, redacted record. | CaseFile |
+
+The four component snapshots are pinned, checksummed, and shipped with the plugin. The
+plugin does not download component code while installing or running.
+
+## Agent tools
+
+Paperclip agents can call four tools:
 
 | Tool | Use |
 | --- | --- |
-| `kujolang.paperclip:review-changes` | Measure change size and create a review handoff. |
-| `kujolang.paperclip:capture-failure` | Save supplied command output as redacted evidence. It never reruns the command. |
-| `kujolang.paperclip:get-context` | Select a bounded set of files for a task. |
-| `kujolang.paperclip:get-context-content` | Read safe content from files selected by an existing Context Pack. |
+| `kujolang.paperclip:get-context` | Select files for a task at minimal, focused, or broad depth. |
+| `kujolang.paperclip:get-context-content` | Read safe content from files already selected by a Context Pack. |
+| `kujolang.paperclip:review-changes` | Measure a working tree or Git range and create a review handoff. |
+| `kujolang.paperclip:capture-failure` | Save supplied command output as redacted evidence. It never runs the command. |
 
-Example agent requests:
+Example requests:
 
 ```text
 Use kujolang.paperclip:get-context with task "trace the OAuth callback" and depth "focused".
-Use kujolang.paperclip:review-changes after the edit and report the suggested tests as suggestions, not completed checks.
+Read only the selected files needed for the change.
+Use kujolang.paperclip:review-changes after the edit.
+Report suggested tests as suggestions, not completed checks.
 If a check fails, use kujolang.paperclip:capture-failure with the command, exit code, and bounded log.
 ```
 
-The content tool only reads files selected by the matching Context Pack. It rejects other paths, binary files, oversized files, traversal, and symlink escapes.
+The content tool reads only files selected by the matching Context Pack. It rejects
+other paths, binary files, oversized files, traversal, and symlink escapes.
 
-See [Usage](docs/USAGE.md) for tool inputs, UI actions, artifact fields, and common workflows.
-
-## What it adds
-
-- **Review Pack** uses ChangeBucket to measure the change and PatchBrief to explain it.
-- **Failure Evidence** uses CaseFile to turn supplied logs into a reviewable record.
-- **Context Pack** uses Scent to select relevant files before an agent reads broadly.
-
-All four component snapshots are pinned, checksummed, and shipped in the package. The plugin does not fetch component code at runtime.
+See [Usage](docs/USAGE.md) for all tool inputs, UI actions, artifact fields, and the
+recommended agent sequence.
 
 ## Compatibility
 
@@ -63,38 +88,58 @@ All four component snapshots are pinned, checksummed, and shipped in the package
 | --- | --- |
 | Paperclip host | `>=2026.824.1` |
 | `@paperclipai/plugin-sdk` | `2026.824.1` |
-| `@kujolang/kujo-runtime` | `1.2.2` |
+| `@kujolang/kujo-runtime` | `1.2.3` |
 | Node.js | `>=24.11.0` |
 
-The npm package is `@kujolang/paperclip`. Its Paperclip manifest ID is `kujolang.paperclip` because manifest IDs do not accept npm scope syntax.
+The npm package is `@kujolang/paperclip`. Its Paperclip manifest ID is
+`kujolang.paperclip` because manifest IDs do not accept npm scope syntax.
+
+The plugin tests the minimum supported Paperclip SDK and the latest compatible SDK in
+CI. Its manifest temporarily accepts the host's `0.0.0` fallback until Paperclip ships
+the host-version fix in PR #12745; the documented and tested support floor remains
+`2026.824.1`.
 
 ## Configure
 
-Paperclip builds the settings form from the plugin manifest. You can enable or disable each feature, set an absolute Kujo binary override, allow or deny `PATH` fallback, and change bounded process limits.
+Paperclip builds the settings form from the plugin manifest. You can turn each feature
+on or off, set an absolute Kujo binary override, allow or deny `PATH` fallback, and
+change bounded process limits.
 
-Defaults are safe for normal repositories: a 27-second timeout, 2 MB stdout limit, and 256 KB stderr limit. The timeout stays below Paperclip's bridge deadline so the worker can return a structured result. See [Configuration](docs/CONFIGURATION.md) for every setting and limit.
+The defaults suit normal repositories: a 27-second timeout, 2 MB stdout limit, and
+256 KB stderr limit. The timeout stays below Paperclip's bridge deadline so the worker
+can return a structured result. See [Configuration](docs/CONFIGURATION.md) for every
+setting and limit.
 
 ## How it runs
 
-The worker resolves Kujo in this order:
+The worker looks for Kujo in this order:
 
-1. configured absolute binary;
-2. bundled `@kujolang/kujo-runtime` binary;
+1. a configured absolute binary;
+2. the bundled `@kujolang/kujo-runtime` binary;
 3. an absolute `kujo` found on `PATH`, when allowed;
 4. a structured error with a repair hint.
 
-Each child process uses an argument array with `shell: false`, a small environment, a canonical Paperclip workspace, a timeout, and output caps. Review and context commands are read-only. Failure Evidence records supplied text and never exposes a command runner.
+Each child process receives an argument array with `shell: false`, a small environment,
+a canonical Paperclip workspace, a timeout, and output caps. Review and Context Pack
+commands are read-only. Failure Evidence records supplied text and never exposes a
+command runner.
 
 ## Develop
 
 ```bash
 npm ci --ignore-scripts
 npm run verify
+npx playwright install chromium
+npm run test:ui
 ```
 
-`npm run verify` type-checks the source, runs contract, hardening, and real-component tests, verifies component checksums, audits dependency integrity and licenses, produces an SBOM, builds the worker/manifest/UI bundles, and inspects the npm tarball.
+`npm run verify` checks repository conventions, types, contracts, hardening,
+real-component behavior, component checksums, dependency integrity, licenses, the
+SBOM, bundles, and the npm tarball. The Playwright suite covers both Paperclip UI
+surfaces, their actions, responsive layouts, accessibility, and approved screenshots.
 
-Read [AGENTS.md](AGENTS.md) before agent-assisted changes and [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+Read [AGENTS.md](AGENTS.md) before agent-assisted changes and
+[CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
 
 ## Documentation
 
@@ -114,4 +159,5 @@ Read [AGENTS.md](AGENTS.md) before agent-assisted changes and [CONTRIBUTING.md](
 
 ## License
 
-MIT. Bundled Kujo components keep their canonical MIT licenses and recorded provenance.
+MIT. Bundled Kujo components keep their canonical MIT licenses and recorded
+provenance.

package/VERSION

@@ -1 +1 @@
-0.1.6
+0.1.7

package/dist/manifest.js

@@ -18879,7 +18879,7 @@ var DEFAULT_LIMITS = {
   maxInputLogBytes: 2e5,
   maxContextFileBytes: 2e3
 };
-var PLUGIN_VERSION = "0.1.6";
+var PLUGIN_VERSION = "0.1.7";
 var MINIMUM_HOST_VERSION = "0.0.0";
 
 // src/config/schema.ts

package/dist/worker.js

@@ -33062,7 +33062,7 @@ var CONTEXT_BUDGETS = {
   focused: 16e3,
   broad: 4e4
 };
-var PLUGIN_VERSION = "0.1.6";
+var PLUGIN_VERSION = "0.1.7";
 var PAPERCLIP_API_VERSION = 1;
 
 // src/config/schema.ts

package/docs/COMPATIBILITY.md

@@ -6,7 +6,7 @@
 | --- | --- | --- |
 | Paperclip | `2026.824.1` and later in the current compatibility train | SDK minimum and latest |
 | Node.js | `24.11.0` through the latest Node 24 release | minimum and latest Node 24 |
-| Kujo runtime | bundled `1.2.2` | five native targets |
+| Kujo runtime | bundled `1.2.3` | five native targets |
 
 The plugin supports macOS arm64/x64, Linux arm64/x64, and Windows x64. CI runs the full plugin suite on each target at the minimum Node version. A separate compatibility job tests the minimum and latest Paperclip SDK against the minimum and latest Node 24 release.
 

package/docs/INSTALLATION.md

@@ -12,6 +12,12 @@
 npx paperclipai plugin install @kujolang/paperclip
 ```
 
+Use the package name without an exact version suffix until Paperclip ships
+[paperclipai/paperclip#12745](https://github.com/paperclipai/paperclip/pull/12745).
+Current hosts misparse exact scoped references such as
+`@kujolang/paperclip@0.1.7`; the unversioned command above installs the current npm
+release correctly.
+
 Restart Paperclip if it is running. Open an issue and confirm that the Kujo workspace appears in the current task view. On project and run pages, open the **Kujo** tab. No Classic Task Interface setting is required.
 
 The package installs `@kujolang/kujo-runtime` and one matching optional native package. Supported targets are macOS arm64/x64, Linux arm64/x64, and Windows x64. No Kujo package uses `preinstall`, `install`, or `postinstall`.

package/docs/MAINTENANCE_HANDOFF.md

@@ -5,7 +5,7 @@ Updated September 3, 2026.
 ## Current state
 
 `@kujolang/paperclip` is ready for public use within its documented scope. Version
-`0.1.6` is published on npm and GitHub. The released plugin:
+`0.1.7` is published on npm and GitHub. The released plugin:
 
 - works in Paperclip's current task view without requiring the Classic Task Interface;
 - provides Review, Context, and Failure Evidence workflows in the inline workspace and
@@ -20,6 +20,28 @@ No known plugin defect blocks normal public use. The remaining work is upstream
 distribution work: the host-version change is waiting on Paperclip maintainers, and
 catalog distribution is not available yet.
 
+## Next-agent brief
+
+There is no plugin-owned release work waiting. Start with
+[paperclipai/paperclip#12745](https://github.com/paperclipai/paperclip/pull/12745):
+it is open, ready for review, mergeable, and green as of September 3, 2026. Respond to
+maintainer feedback, but do not raise this plugin's manifest minimum while that change
+is absent from a public Paperclip release.
+
+After Paperclip publishes the fix:
+
+1. verify that `npx paperclipai plugin install @kujolang/paperclip@0.1.7` succeeds;
+2. replace the temporary `MINIMUM_HOST_VERSION = "0.0.0"` value in
+   `src/config/defaults.ts` with the real supported floor;
+3. update the compatibility tests and documentation;
+4. run `npm ci --ignore-scripts`, `npm run verify`, `npm run test:ui`, and the
+   minimum/latest clean-install matrix; and
+5. release a patch through the signed-tag workflow if the package changes.
+
+Separately, check Paperclip's documentation for an official catalog or marketplace
+submission path. None exists today, so catalog submission is parked rather than
+failed. Do not create or use an unofficial listing process.
+
 ## At a glance
 
 | Work | State | Next action |
@@ -29,7 +51,7 @@ catalog distribution is not available yet.
 | Browser/UI regression coverage | Complete | Maintain the approved baselines with UI changes |
 | Dependency updates | Complete | Continue normal Dependabot review |
 | Paperclip catalog listing | Not currently available | Recheck when Paperclip publishes a marketplace process |
-| Kujo plugin release | Complete | Verify and retain the v0.1.6 release evidence |
+| Kujo plugin release | Complete | Verify and retain the v0.1.7 release evidence |
 
 ## Work queue
 
@@ -43,10 +65,10 @@ catalog distribution is not available yet.
 The Paperclip CLI currently misparses an exact scoped npm package reference:
 
 ```bash
-npx paperclipai plugin install @kujolang/paperclip@0.1.6
+npx paperclipai plugin install @kujolang/paperclip@0.1.7
 ```
 
-It looks for a directory named `@kujolang/paperclip@0.1.6` after npm installs the
+It looks for a directory named `@kujolang/paperclip@0.1.7` after npm installs the
 package. Installing the current version without a version suffix works:
 
 ```bash
@@ -177,11 +199,13 @@ This is a distribution task, not a prerequisite for installing the public npm pa
 
 **Owner:** Plugin release maintainer
 
-**State:** v0.1.6 released
+**State:** v0.1.7 released
 
-Version 0.1.6 consolidates the browser coverage and dependency maintenance. Its tagged
-workflow runs the full repository, browser, compatibility, supply-chain, packaging,
-and clean-install gates before publication through npm trusted publishing.
+Version 0.1.7 adds the plain-English install and first-use guide, monochrome npm and CI
+badges, corrected Context Pack limits, documentation command validation, and current
+runtime and type dependencies. Its tagged workflow runs the full repository, browser,
+compatibility, supply-chain, packaging, and clean-install gates before publication
+through npm trusted publishing.
 
 ## Recommended next-agent sequence
 
@@ -233,5 +257,7 @@ provenance, and clean public install are all verified.
 
 ## Release evidence
 
-- GitHub release: <https://github.com/kujolang/paperclip/releases/tag/v0.1.6>
-- npm package: <https://www.npmjs.com/package/@kujolang/paperclip/v/0.1.6>
+- GitHub release: <https://github.com/kujolang/paperclip/releases/tag/v0.1.7>
+- release workflows: <https://github.com/kujolang/paperclip/actions/workflows/release.yml>
+- npm package: <https://www.npmjs.com/package/@kujolang/paperclip/v/0.1.7>
+- npm SLSA provenance: <https://registry.npmjs.org/-/npm/v1/attestations/@kujolang%2fpaperclip@0.1.7>

package/docs/USAGE.md

@@ -63,9 +63,9 @@ Depth controls the token and file budget:
 
 | Depth | Token budget | File limit |
 | --- | ---: | ---: |
-| `minimal` | 4,000 | 12 |
-| `focused` | 16,000 | 40 |
-| `broad` | 40,000 | 100 |
+| `minimal` | 4,000 | 2 |
+| `focused` | 16,000 | 3 |
+| `broad` | 40,000 | 4 |
 
 Start without content. Review the selected paths and reasons, then request content only when needed.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kujolang/paperclip",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Make Paperclip agent work easier to scope, review, reproduce, and verify.",
   "license": "MIT",
   "homepage": "https://github.com/kujolang/paperclip#readme",
@@ -49,7 +49,7 @@
     "prepublishOnly": "npm run verify"
   },
   "dependencies": {
-    "@kujolang/kujo-runtime": "1.2.2",
+    "@kujolang/kujo-runtime": "1.2.3",
     "@paperclipai/plugin-sdk": "2026.824.1",
     "zod": "4.5.4"
   },
@@ -63,9 +63,9 @@
   },
   "devDependencies": {
     "@playwright/test": "1.62.1",
-    "@types/node": "26.4.0",
+    "@types/node": "26.4.1",
     "@types/react": "19.2.18",
-    "@types/react-dom": "19.2.5",
+    "@types/react-dom": "19.2.7",
     "esbuild": "0.28.2",
     "react": "19.2.8",
     "react-dom": "19.2.8",