@kujolang/paperclip 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,28 @@
+# Architecture
+
+```text
+Paperclip issue/project/run context
+  -> @kujolang/paperclip worker (typed validation and workspace resolution)
+  -> @kujolang/kujo-runtime (configured, bundled, then optional PATH fallback)
+  -> allowlisted pinned component (ChangeBucket, PatchBrief, CaseFile, Scent)
+  -> bounded machine output
+  -> normalized schema v1
+  -> Paperclip plugin state and native detail tab
+```
+
+Paperclip remains the system of record for companies, projects, workspaces, issues, runs, approvals, budgets, and authentication. The plugin requests only project/workspace reads, agent-tool registration, plugin state, its detail tab, and its managed guidance skill.
+
+All execution enters through `executeKujo()`. It uses `spawn`, never a shell, validates a real absolute working directory, passes a minimal allowlisted environment, caps stdout/stderr, and applies a timeout. Feature code can call only IDs in the compiled component registry. Registry resolution validates the complete bundle against the lock before returning an entrypoint. Context selection runs against a task-ranked temporary mirror of at most four Git-visible regular files, so ignored dependency trees and other ambient files never enter Scent's walk.
+
+Artifacts use Paperclip state scopes: Review and Context Packs are stored against their project or issue; Failure Evidence is stored against its run. Generated CaseFile/Scent scratch output is created in a private temporary directory and removed after normalization. Project repositories remain read-only.
+
+## Public contracts
+
+- npm packages and runtime resolver API documented in the Kujo runtime repository
+- Paperclip manifest API version 1 and minimum host version `2026.824.1`
+- four namespaced agent tools declared in the manifest and worker
+- component lock schema version 1
+- Review Pack, Failure Evidence, and Context Pack schema version 1
+- additive JSON compatibility within a plugin major version
+
+Review generation captures a git snapshot before parallel read-only ChangeBucket/PatchBrief calls and checks it afterward. Partial PatchBrief failure preserves an accurate ChangeBucket footprint and records component status. Context cache identity combines workspace, HEAD/dirty fingerprint, normalized task, depth, and component version. The v0.1 worker records the key but intentionally regenerates instead of adding a second cache index.

package/docs/CATALOG_SUBMISSION.md

@@ -0,0 +1,25 @@
+# Paperclip catalog submission
+
+**Name:** Kujo — Reviewable Agent Work  
+**Package:** `@kujolang/paperclip`  
+**Repository/support:** `https://github.com/kujolang/paperclip`  
+**License:** MIT  
+**Minimum host:** Paperclip `2026.824.1`  
+
+**Description:** Add scoped context, change review, and reproducible evidence to Paperclip agent workflows.
+
+## Requested capabilities
+
+- `agent.tools.register`: four explicitly declared bounded tools
+- `projects.read`, `project.workspaces.read`: canonical workspace resolution only
+- `plugin.state.read`, `plugin.state.write`: normalized artifact persistence
+- `ui.detailTab.register`: one shared Kujo tab on project/issue/run details
+- `skills.managed`: optional Scoped Repository Context guidance
+
+The plugin requests no HTTP, secret, issue-write, approval, budget, database, job, webhook, or arbitrary local-folder capability.
+
+## UI walkthrough
+
+The shared Kujo tab starts with runtime/artifact status. Issue/project views provide **Generate Review Pack**, **Generate Context Pack**, and **Capture Failure Evidence** actions. Review shows blast radius, explainable signals, and clearly labeled suggested verification. Failure Evidence shows bounded excerpts and redaction counts. Context shows selected paths, reasons, estimated tokens, depth, and stale/budget status. Run views show associated persisted evidence without exposing a terminal.
+
+Catalog review should require the tagged cross-platform workflow, npm provenance for all six runtime packages and this plugin, install/upgrade/uninstall evidence on the declared minimum host, and the security assertions in `THREAT_MODEL.md`.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,21 @@
+# Compatibility policy
+
+## Supported versions
+
+| Dependency | Supported range | CI coverage |
+| --- | --- | --- |
+| 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 |
+
+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.
+
+## Change rules
+
+- Patch releases keep the same artifact schemas and minimum host train.
+- Before 1.0, a minor release may add fields or raise a minimum version. The changelog must call out either change.
+- Readers accept additive fields but reject unknown schema versions.
+- Context content requires the same company, project, workspace, and Git snapshot that produced the pack.
+- Component and runtime updates require the full native matrix and clean-install smoke test.
+
+Paperclip releases outside the tested train are not supported until the scheduled compatibility job passes and the table is updated.

package/docs/CONFIGURATION.md

@@ -0,0 +1,33 @@
+# Configuration
+
+Paperclip renders these settings from the plugin manifest.
+
+## Runtime
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `runtime.binary` | `null` | Absolute Kujo binary override. Relative paths are rejected. |
+| `runtime.allowSystemPathFallback` | `true` | Allow a compatible absolute `kujo` found on `PATH` after bundled resolution fails. |
+
+Bundled runtime resolution is the normal choice. Use an override only for controlled development or recovery.
+
+## Features
+
+| Setting | Default | Meaning |
+| --- | --- | --- |
+| `features.review` | `true` | Enable Review Pack tools and actions. |
+| `features.failureEvidence` | `true` | Enable Failure Evidence tools and actions. |
+| `features.context` | `true` | Enable Context Pack tools and actions. |
+| `features.verification` | `false` | Reserve the experimental verification surface. Enabling it produces a warning in `0.1.x`. |
+
+## Process limits
+
+| Setting | Default | Allowed range |
+| --- | ---: | ---: |
+| `limits.timeoutMs` | 27,000 | 1,000–27,000 |
+| `limits.maxStdoutBytes` | 2,000,000 | 1,024–10,000,000 |
+| `limits.maxStderrBytes` | 256,000 | 1,024–2,000,000 |
+
+Raising a limit increases the resources available to a local component and the amount of data the host may retain. Change limits only for a known repository need.
+
+Other fixed bounds include a 200 KB Failure Evidence log input, 100 KB Context Pack selection limit per file, and 1 MB hard refusal for content reads.

package/docs/INSTALLATION.md

@@ -0,0 +1,53 @@
+# Installation
+
+## Requirements
+
+- Paperclip `2026.824.1` or later
+- Node.js `24.11.0` or later
+- a Paperclip project with a local Git workspace for Review and Context Packs
+
+## Install from npm
+
+```bash
+npx paperclipai plugin install @kujolang/paperclip
+```
+
+Restart Paperclip if it is running. Open a project, issue, or run, select the **Kujo** tab, and check the status panel.
+
+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`.
+
+## Upgrade
+
+Use Paperclip's plugin upgrade command for `@kujolang/paperclip`, then restart the host. Keep the plugin, Paperclip host, and Kujo runtime within the versions listed in the main README.
+
+Artifact schema version 1 stays readable across compatible `0.1.x` releases.
+
+## Uninstall
+
+Use Paperclip's normal plugin uninstall flow. A standard uninstall follows the host's retention policy for plugin state. An explicit purge removes plugin state. Neither operation changes project source.
+
+## Develop from source
+
+Clone `kujolang/kujo` and `kujolang/paperclip` as siblings. Build Kujo, then install and verify the plugin:
+
+```bash
+cd kujo
+cargo build --release --bin kujo
+
+cd ../paperclip
+npm ci --ignore-scripts
+npm run verify
+```
+
+Set `KUJO_INTEGRATION_BINARY` if the Kujo binary is not at `../kujo/target/release/kujo`.
+
+## Verify a release
+
+After publication:
+
+```bash
+npm view @kujolang/paperclip version dist.integrity dist.attestations
+npm pack @kujolang/paperclip --dry-run
+```
+
+Install it in a clean Paperclip host, confirm the Kujo status panel, and exercise one Review, Failure Evidence, and Context Pack before promoting the release.

package/docs/OPERATIONS.md

@@ -0,0 +1,60 @@
+# Operations
+
+## Health and audit trail
+
+Paperclip reports worker health and component integrity in the plugin status view. A healthy worker has four verified components. Runtime compatibility is checked when a feature first runs.
+
+Successful generation, Context content reads, and data clearing write company-scoped Paperclip activity events. Events contain the operation, entity, and artifact ID. They do not contain source, logs, commands, or file contents. Paperclip owns activity-log retention and export.
+
+The plugin stores only the latest artifact of each type for an entity. State namespaces include the company ID. Use **Clear Kujo data** on a project or issue to remove its Review, Failure, and Context artifacts. Paperclip owns backup retention and deletion for run-scoped state.
+
+## Upgrade
+
+1. Read the changelog and compatibility table.
+2. Back up Paperclip by using the host's normal backup process.
+3. Install the exact target version: `npx paperclipai plugin install @kujolang/paperclip@<version>`.
+4. Restart the worker.
+5. Check plugin health, generate a Context Pack in a test project, and run a Review Pack against a small known change.
+
+The reader validates stored artifact schemas. It ignores corrupt or unsupported artifacts instead of rendering them. Generate a new artifact after an upgrade if an older one no longer loads.
+
+## Rollback
+
+Install the previous exact version and restart the worker. Do not reuse a Context Pack across a rollback unless its schema, workspace ID, and Git snapshot still match. Generate a new pack when in doubt.
+
+If a bad release affected stored data, clear the entity's Kujo data before regenerating it. A rollback does not restore artifacts that a newer version replaced.
+
+## Rotate bundled components
+
+Component updates must start from clean, reviewed source repositories at exact commits.
+
+1. Update `components.sources.json` with the source commit and version.
+2. Run `npm run components:sync`.
+3. Review the full component diff and generated lock file.
+4. Run `npm run verify` on every supported platform.
+5. Release the plugin only after the referenced Kujo runtime is available on npm.
+
+Never hand-edit a bundled file without updating its canonical source. Runtime checks reject any file that differs from the component lock.
+
+## Recover from corrupt state
+
+If a detail view shows no artifact after an upgrade, inspect worker logs for schema or state errors. Clear the entity's Kujo data, then regenerate the artifact. Do not edit Paperclip's plugin-state tables directly.
+
+If component integrity fails, reinstall the exact npm package. If runtime resolution fails, remove an invalid binary override or reinstall optional dependencies. Keep system `PATH` fallback disabled on tightly controlled hosts.
+
+## Incident response
+
+1. Disable the affected feature in company settings. Server-side checks block its tools, actions, reads, and Context content access.
+2. Stop or restart the plugin worker. Shutdown cancels active Kujo process groups.
+3. Preserve Paperclip activity records, worker logs, package version, component lock, and npm integrity metadata.
+4. Clear affected artifacts if they may contain sensitive data.
+5. Rotate any credential found in supplied logs. Redaction is a safeguard, not proof that a log contains no secret.
+6. Report product vulnerabilities through the private channel in `SECURITY.md`.
+
+Do not post private logs, workspace paths, or exploit details in public issues.
+
+## Service expectations
+
+Kujo for Paperclip is a local plugin. Availability follows the Paperclip host and local Kujo process. The project does not promise a response-time or uptime SLA. GitHub issues are the public support channel for reproducible non-security defects. Security reports use GitHub Security Advisories.
+
+Each operation has a hard time and output budget. Review and Context reject Git-visible files larger than 25 MB or workspaces with more than 100,000 Git-visible files before starting a bundled analyzer. Split or exclude oversized inputs instead of raising this guard.

package/docs/README.md

@@ -0,0 +1,18 @@
+# Documentation
+
+Start with [Installation](INSTALLATION.md), then [Usage](USAGE.md).
+
+| Document | Purpose |
+| --- | --- |
+| [Installation](INSTALLATION.md) | Requirements, install, upgrade, uninstall, and local development. |
+| [Usage](USAGE.md) | UI actions, agent tools, inputs, outputs, and workflows. |
+| [Configuration](CONFIGURATION.md) | Feature switches, runtime selection, and limits. |
+| [Compatibility](COMPATIBILITY.md) | Supported host, SDK, Node, runtime, and schema rules. |
+| [Architecture](ARCHITECTURE.md) | Host integration, components, state, and data flow. |
+| [Threat model](THREAT_MODEL.md) | Assets, trust boundaries, abuse cases, and mitigations. |
+| [Troubleshooting](TROUBLESHOOTING.md) | Runtime, component, workspace, and output errors. |
+| [Release readiness](RELEASE_READINESS.md) | Release order, test matrix, and operator checks. |
+| [Operations](OPERATIONS.md) | Health, audit, retention, upgrades, rollback, recovery, and incident response. |
+| [Catalog submission](CATALOG_SUBMISSION.md) | Paperclip catalog metadata and review evidence. |
+
+Repository policy lives in [SECURITY.md](../SECURITY.md), [CONTRIBUTING.md](../CONTRIBUTING.md), and [AGENTS.md](../AGENTS.md).

package/docs/RELEASE_READINESS.md

@@ -0,0 +1,46 @@
+# v0.1 release readiness
+
+## Gates
+
+| Gate | Local result |
+| --- | --- |
+| TypeScript strict typecheck | automated by `npm run verify` |
+| Unit/contract tests | automated by Vitest |
+| Official Paperclip SDK worker harness | automated by Vitest |
+| Real ChangeBucket/PatchBrief fixture | automated by Vitest |
+| Real CaseFile redaction fixture | automated by Vitest |
+| Real Scent relevance/budget fixture | automated by Vitest |
+| Component SHA-256/provenance | `components:verify` |
+| Dependency audit, integrity, licenses, and SBOM | `supply-chain:verify` |
+| Tenant isolation and stored-state validation | automated by Vitest |
+| Feature-policy enforcement on tools and UI bridges | automated by Vitest |
+| Hostile Git configuration suppression | automated by Vitest |
+| Timeout, cancellation, and descendant-process cleanup | automated by Vitest |
+| Oversized workspace rejection | automated by Vitest |
+| Worker/manifest/UI bundles | esbuild with official SDK preset |
+| npm tarball contents | `pack:verify` |
+| Runtime resolver/package tests | owned by the Kujo runtime repository |
+
+The release order is platform runtime packages, neutral `@kujolang/kujo-runtime`, component sync/verification, plugin tarball clean-install verification, then `@kujolang/paperclip`. Platform binaries and the resolver must use the same Kujo version. The resolver is published last among runtime packages so it never points to missing versions.
+
+## Matrix
+
+The runtime release workflows build and smoke macOS arm64/x64, Linux arm64/x64, and Windows x64. Paperclip CI tests those five targets. A separate compatibility matrix tests Node.js 24.11 and current Node.js 24 against the minimum, locked, and latest compatible Paperclip SDK versions. Local plugin feature execution is verified on the developer host; every supported target is exercised during a tagged release.
+
+The tag workflow accepts only an annotated PGP-signed tag whose name matches `package.json`. It verifies the repository, packs once, attests that tarball, publishes that exact file with npm provenance, and attaches its checksum, CycloneDX SBOM, component lock, and JSON schemas to the GitHub release.
+
+## Performance bounds
+
+- component timeout: 27 seconds, below the Paperclip bridge deadline
+- stdout: 2 MB; stderr: 256 KB
+- Failure Evidence input: 200 KB with explicit middle truncation
+- Git-visible workspace: 100,000 files and 25 MB per file before component execution
+- Context presets: approximately 4K/16K/40K tokens and 2/3/4 files
+- context file: 2 KB during selection and 1 MB hard read refusal
+- Review file rows retained by canonical output; UI eagerly renders at most 20 context entries and 12 suggested tests
+
+The v0.1 deterministic suite remains in Vitest because these contracts combine the Paperclip SDK harness, native-process bounds, filesystem escape checks, and JSON assertions directly. Kujo Spec/Eval would add a second runner without improving determinism for this release; the versioned schemas and fixture cases are ready to export into Eval when the plugin adds executable verification.
+
+## Release decision
+
+SHIP only after the protected-branch checks pass, the compatibility workflow passes, the signed-tag workflow succeeds, the seven runtime/plugin npm names are available, a clean-room npm install passes, and a real Paperclip host loads the published package and exercises its tools.

package/docs/THREAT_MODEL.md

@@ -0,0 +1,26 @@
+# Threat model
+
+## Assets and trust boundaries
+
+The protected assets are project source, credentials, Paperclip tenant identity, plugin state, and the integrity of generated evidence. Paperclip plugin code is trusted installed code; manifest capabilities gate worker host APIs but same-origin plugin UI is not an isolation boundary. Native runtime and bundled Kujo source are release inputs verified by package/component checksums.
+
+## Attack surfaces and controls
+
+| Surface | Control |
+| --- | --- |
+| Malicious filenames, refs, or tool parameters | Zod validation, bounded lengths, strict git-ref grammar, no shell interpolation |
+| Workspace traversal or symlink escape | Host workspace lookup, `realpath`, containment checks, selected-path allowlist |
+| Arbitrary Kujo scripts | Compile-time component ID union and locked registry; no user path parameter |
+| Huge files, diffs, logs, or process output | Component budgets, file/byte limits, stdout/stderr caps, timeouts, bounded UI rows |
+| Secrets in logs/files | Safe environment allowlist, CaseFile/Scent redaction, second defensive redaction, sensitive-path denylist |
+| Package/component substitution | exact dependency versions, platform package selection, lock commit/version/license/SHA-256, runtime integrity verification |
+| Cross-company spoofing | action company scope comes from immutable host context; tool scope comes from `ToolRunContext` |
+| Stale or corrupt artifacts | schema version, provenance, git snapshot fingerprint, stale marker, component integrity check |
+| Worker failure | structured errors returned from tools; component nonzero exit does not crash the host |
+
+The plugin does not execute suggested tests, rerun failures, expose terminal access, mutate `PATH`, inherit arbitrary environment values, download code at runtime, or write artifacts into project source by default.
+
+## Residual risks
+
+Pattern redaction is defense in depth, not a mathematical guarantee. Operators should still review artifacts before external sharing. Paperclip UI code is trusted same-origin JavaScript in the current plugin architecture. Native package publication and cross-platform CI require supply-chain controls outside the running worker; release uses npm provenance and publishes the neutral resolver last.
+

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,12 @@
+# Troubleshooting
+
+- `KUJO_RUNTIME_NOT_FOUND`: reinstall with optional dependencies enabled, confirm the target is supported, or configure an absolute Kujo 1.2+ binary.
+- `KUJO_RUNTIME_INCOMPATIBLE`: upgrade the configured/PATH runtime to 1.2 or remove the override to use the bundled version.
+- `KUJO_COMPONENT_INTEGRITY_FAILED`: reinstall the plugin from npm; do not edit installed bundle files.
+- `KUJO_WORKSPACE_NOT_FOUND`: attach a primary local workspace to the Paperclip project.
+- `KUJO_EXEC_TIMEOUT` or `KUJO_OUTPUT_LIMIT`: narrow the change/context or raise the administrator limit within the schema maximum.
+- Not a git repository: Review Pack requires a git-backed workspace with a valid `HEAD`; Context and Failure Evidence remain independently usable.
+- Stale Review/Context Pack: regenerate after HEAD or the dirty working tree changes.
+- Unsupported target: v0.1 supports macOS arm64/x64, Linux arm64/x64, and Windows x64.
+- Worker crash: open plugin health, verify the exact Paperclip compatibility train, then reinstall. Component failures should normally appear as structured feature errors rather than crash the worker.
+

package/docs/USAGE.md

@@ -0,0 +1,95 @@
+# Usage
+
+## Paperclip UI
+
+Open the **Kujo** detail tab on a project or issue.
+
+- **Generate Review Pack** measures the current working tree and builds a handoff.
+- **Generate Context Pack** selects files for a task at minimal, focused, or broad depth.
+- **Capture Failure Evidence** stores supplied command details and logs after bounding and redaction.
+
+Run views display saved evidence. They do not expose a terminal.
+
+## Agent tools
+
+### Review changes
+
+```json
+{
+  "mode": "working_tree"
+}
+```
+
+Use range mode only with valid Git refs:
+
+```json
+{
+  "mode": "range",
+  "base": "main",
+  "head": "HEAD"
+}
+```
+
+The result includes changed-file and churn counts, risk level, explainable signals, component status, stale state, and suggested tests. Suggested tests are not proof that a command ran.
+
+### Capture failure evidence
+
+```json
+{
+  "title": "Unit test failed",
+  "command": "npm test",
+  "exitCode": 1,
+  "durationMs": 4200,
+  "log": "bounded test output",
+  "notes": "failure occurred after the parser change"
+}
+```
+
+The tool does not execute `command`. It stores bounded, redacted evidence from the supplied fields.
+
+### Get context
+
+```json
+{
+  "task": "trace the OAuth callback and its tests",
+  "depth": "focused",
+  "includeContent": false
+}
+```
+
+Depth controls the token and file budget:
+
+| Depth | Token budget | File limit |
+| --- | ---: | ---: |
+| `minimal` | 4,000 | 12 |
+| `focused` | 16,000 | 40 |
+| `broad` | 40,000 | 100 |
+
+Start without content. Review the selected paths and reasons, then request content only when needed.
+
+### Get selected content
+
+```json
+{
+  "contextPackId": "context-pack-id",
+  "paths": ["src/oauth.ts", "tests/oauth.spec.ts"],
+  "maxTokens": 8000
+}
+```
+
+Each path must belong to the referenced Context Pack and remain inside the workspace. Omit `paths` to read all selected files within the token budget.
+
+## Recommended agent sequence
+
+1. Request a focused Context Pack for the task.
+2. Read only the selected content needed for the change.
+3. Make and test the change with the normal project tools.
+4. Generate a Review Pack.
+5. Capture Failure Evidence only for commands that actually failed.
+6. Report completed checks separately from suggested checks.
+
+## Stored artifacts
+
+The plugin stores the latest normalized artifact in Paperclip plugin state for its project, issue, or run scope. It does not write reports into the project workspace.
+
+Schemas are published in `schemas/`. Consumers should ignore unknown fields added by compatible future releases.

package/examples/agent-workflow.md

@@ -0,0 +1,20 @@
+# Agent workflow
+
+Ask the agent to select context before broad reading:
+
+```text
+Use kujolang.paperclip:get-context with task "trace the OAuth callback" and depth "focused".
+Read only the selected files needed for the task.
+```
+
+After the change, request a Review Pack:
+
+```text
+Use kujolang.paperclip:review-changes. Report suggested checks as suggestions unless you ran them.
+```
+
+If a command fails, save bounded evidence without rerunning it:
+
+```text
+Use kujolang.paperclip:capture-failure with the command, exit code, and relevant log excerpt.
+```

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@kujolang/paperclip",
+  "version": "0.1.0",
+  "description": "Make Paperclip agent work easier to scope, review, reproduce, and verify.",
+  "license": "MIT",
+  "homepage": "https://github.com/kujolang/paperclip#readme",
+  "bugs": { "url": "https://github.com/kujolang/paperclip/issues" },
+  "repository": { "type": "git", "url": "git+https://github.com/kujolang/paperclip.git" },
+  "type": "module",
+  "engines": {
+    "node": ">=24.11.0"
+  },
+  "files": [
+    "dist",
+    "bundled",
+    "docs",
+    "examples",
+    "schemas",
+    "skills",
+    "CHANGELOG.md",
+    "README.md",
+    "SECURITY.md",
+    "VERSION",
+    "LICENSE"
+  ],
+  "paperclipPlugin": {
+    "manifest": "./dist/manifest.js",
+    "worker": "./dist/worker.js",
+    "ui": "./dist/ui"
+  },
+  "scripts": {
+    "build": "node esbuild.config.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "components:sync": "node scripts/sync-components.mjs --local-root ..",
+    "components:verify": "node scripts/verify-components.mjs",
+    "repository:verify": "node scripts/verify-repository.mjs",
+    "supply-chain:verify": "node scripts/verify-supply-chain.mjs",
+    "verify": "npm run repository:verify && npm run typecheck && npm test && npm run components:verify && npm run supply-chain:verify && npm run build && npm run pack:verify",
+    "pack:verify": "node scripts/verify-package.mjs",
+    "release:dry-run": "npm run verify",
+    "prepublishOnly": "npm run verify"
+  },
+  "dependencies": {
+    "@kujolang/kujo-runtime": "1.2.2",
+    "@paperclipai/plugin-sdk": "2026.824.1",
+    "zod": "4.4.3"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "24.0.0",
+    "@types/react": "19.2.0",
+    "esbuild": "0.28.2",
+    "react": "19.1.1",
+    "rollup": "4.62.4",
+    "typescript": "5.9.2",
+    "vitest": "4.1.10"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/schemas/changebucket-analysis.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kujolang.ai/schemas/paperclip/changebucket-analysis-v1.json",
+  "type": "object",
+  "required": ["base", "head", "summary", "categories", "files"],
+  "properties": {
+    "base": { "type": "string" },
+    "head": { "type": "string" },
+    "summary": {
+      "type": "object",
+      "required": ["files_changed", "lines_added", "lines_deleted", "total_churn", "risk_level"],
+      "properties": {
+        "files_changed": { "type": "integer", "minimum": 0 },
+        "lines_added": { "type": "integer", "minimum": 0 },
+        "lines_deleted": { "type": "integer", "minimum": 0 },
+        "total_churn": { "type": "integer", "minimum": 0 },
+        "risk_level": { "enum": ["low", "medium", "high"] }
+      },
+      "additionalProperties": true
+    },
+    "categories": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
+    "files": { "type": "array" }
+  },
+  "additionalProperties": true
+}

package/schemas/context-pack.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kujolang.ai/schemas/paperclip/context-pack-v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "id", "generatedAt", "task", "depth", "budget", "estimatedTokens", "files", "workspaceId", "projectId", "snapshot", "stale", "cacheKey", "provenance"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^context_" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "task": { "type": "string", "minLength": 1 },
+    "depth": { "enum": ["minimal", "focused", "broad"] },
+    "budget": { "type": "integer", "minimum": 1 },
+    "estimatedTokens": { "type": "integer", "minimum": 0 },
+    "files": { "type": "array" },
+    "workspaceId": { "type": "string" },
+    "projectId": { "type": "string" },
+    "snapshot": { "type": "object" },
+    "stale": { "type": "boolean" },
+    "cacheKey": { "type": "string" },
+    "provenance": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/schemas/failure-evidence.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kujolang.ai/schemas/paperclip/failure-evidence-v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "id", "capturedAt", "context", "failure", "environment", "evidence", "redaction", "provenance"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^failure_" },
+    "capturedAt": { "type": "string", "format": "date-time" },
+    "context": { "type": "object" },
+    "failure": { "type": "object" },
+    "environment": { "type": "array" },
+    "evidence": { "type": "array" },
+    "redaction": { "type": "object" },
+    "provenance": { "type": "object" }
+  },
+  "additionalProperties": false
+}

package/schemas/review-pack.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kujolang.ai/schemas/paperclip/review-pack-v1.json",
+  "type": "object",
+  "required": ["schemaVersion", "id", "generatedAt", "projectId", "workspaceId", "source", "footprint", "componentStatus", "stale", "provenance"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^review_" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "projectId": { "type": "string" },
+    "workspaceId": { "type": "string" },
+    "source": { "type": "object" },
+    "footprint": { "type": "object" },
+    "componentStatus": { "type": "object" },
+    "stale": { "type": "boolean" },
+    "provenance": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/skills/scoped-repository-context/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: scoped-repository-context
+description: Request a bounded, task-specific repository Context Pack before broad exploration.
+---
+
+Before broad repository exploration, request a focused Context Pack for the task.
+Start from the returned file list and selection reasons. Expand only when evidence
+shows that context is missing. Do not request broad context by default.
+