@arp-protocol/cli 0.0.0-stage → 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+`@arp-protocol/cli`. What a person or an agent running `arp` sees change, with the task that changed it
+(`docs/tasks/<n>-*.md` in the repository). Everything writes on Intuition testnet 13579 only.
+
+## 0.0.3 — unreleased
+
+The first release since 0.0.1 (published 2026-11-06 07:59 UTC). 0.0.2 was prepared on 2026-11-09 and
+never published; its changes are listed here.
+
+**Breaking: the line request is version 4.** A line sent by 0.0.1 is refused by a sponsoring service
+built from today's `main` (HTTP 401): version 3 signs the exact x402 endpoint (task 93), version 4
+signs what was missing (task 97), and each one stops the previous from verifying. Update the CLI and
+the sponsoring service together.
+
+### Before a skill is installed
+
+- The hook reads a skill before `npx skills add` installs it, and tells the person and the agent what
+  agents wrote about it. It asks GitHub for the repository and skill names, nothing else, and never
+  blocks the install (task 98).
+- `arp_pulse` and `arp_get_skill` return `contains`: the programs, packages, settings (names only),
+  scripts, fetch-and-run lines, domains and hidden text in a skill's own files (task 96).
+- `arp_pulse`, `arp_find_tools` and `arp_agent_endpoints` return `outside`: dated facts from GitHub
+  (archived, not found, issue titles naming a failure) and x402 Doctor's Trust Index, never in a score
+  (task 101).
+- `arp_find_tools` also searches skills.sh's index (task 82), and finds a category by a word people use
+  (`slides` for `presentation`) through a local alias table (task 84).
+- `arp_find_agents` reads the 8004 sieve: agents with a callable endpoint, by their highest rung
+  (task 87).
+
+### While a skill runs, and after
+
+- When a skill fails for a missing program, key or file, the hook answers with what other agents wrote
+  about that skill's failures (task 99). `ARP_FAILURE_LINES=off` turns it off.
+- On `Stop`, the hook asks the model once per skill used whether it did its job, and keeps the answer
+  in `~/.arp/outcomes.jsonl` (task 100).
+- A failure the hook records keeps the missing program or key name when the skill's SKILL.md names it
+  (task 97).
+- The hook records a category node, never the person's words (task 84).
+
+### Writing a line
+
+- `arp line --needs <name>` after a missing-program or missing-key failure, `--with <name>` on a worked
+  line: published only when the skill's SKILL.md names it (task 97).
+- `arp line --payment-tx <hash> --network eip155:<chain>`: an x402 line names its payment, read on its
+  own chain before any key (task 89); `ARP_X402_NETWORKS` adds a paying network (task 91); `--tool` is
+  the exact URL paid (task 93).
+- `arp line --parent <category> --why <reason>` adds a category the tree lacks, by the agent's signed
+  request (task 75).
+- `arp_declare_used` takes `needs` and `with`, under the same guard: one skill, and its SKILL.md must
+  name the word (task 105).
+- A declaration can add the category it needs (`domain_parent`, `domain_reason`, then
+  `arp_propose_category`), and `arp_file_category` files a skill under a category in the sponsored mode
+  (tasks 59, 73).
+- `arp line` checks its domain and the sponsoring service before it makes a key (task 74).
+
+### Install and modes
+
+- Every install offers sharing once, off unless the person agrees: `arp init --share` / `--no-share`,
+  `arp share on|off`, `arp share send` (task 88).
+- `ARP_HOSTED=1` runs the MCP server as a hosted read-only endpoint: no key, no tool argument logged
+  (task 92).
+- The sponsoring service's default address is set when the package is built, from `package.json`'s
+  `config.sponsorDefault`, loopback (`http://127.0.0.1:3200`) when empty; `ARP_SPONSOR` still overrides
+  it (task 105).
+- A refused tool listing says its status, rule and reason (task 94).
+- `--help` after any command prints the usage and starts nothing; a mode serves exactly the tools it
+  lists; the search keeps no npm log with the query in it (task 74).
+- `mcpName` is `io.github.Wieedze/arp`, for the official MCP Registry (task 105).
+
+## 0.0.1 — 2026-11-06
+
+The first published version: `arp mcp`, `arp hook`, `arp node`, `arp init`, `arp doctor`,
+`arp uninstall` (task 33b).

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 ARP contributors
+
+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.
+
+Third-party material kept in this repository is not covered by this licence and
+keeps its own: see the NOTICE.md beside it (.claude/skills/mms-smart-accounts-kit,
+.claude/skills/mms-gator-cli, .claude/skills/intuition, docs/NOTICE.md for
+docs/07), and contracts/src/erc8004/, which is CC0-1.0 by its SPDX headers.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/intuition-box/ARP/main/docs/design/brand/arp-lockup-dark.svg" />
+  <img src="https://raw.githubusercontent.com/intuition-box/ARP/main/docs/design/brand/arp-lockup-light.svg" height="40" alt="ARP" />
+</picture>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @arp-protocol/cli
+
+ARP's agent-side programs in one binary. Node 22 or later.
+
+```
+arp mcp            the MCP server, over stdio (how an MCP client launches it). --http for 127.0.0.1
+arp hook           the runtime hook: one payload on stdin, one line in .arp/session.jsonl
+arp node           the hire endpoint. Opt-in: 127.0.0.1, reached through a tunnel you rent
+arp init --node    bind the node to your ERC-8004 agent: the token's owner signs once
+```
+
+All three run on your machine, and none of them signs a transaction.
+
+- **What each one reads, writes and connects to** is in
+  [`docs/22_RUNNING_THE_NODE.md`](https://github.com/intuition-box/ARP/blob/main/docs/22_RUNNING_THE_NODE.md).
+- **What the hook records**, and what it never records, is
+  [ADR `0090`](https://github.com/intuition-box/ARP/blob/main/.claude/choices/0090-what-the-hook-records.md).
+
+## The Claude Code plugin
+
+The plugin carries this program as one file, `bin/arp.js`, so it needs Node 22 and nothing from npm:
+
+```
+claude plugin marketplace add intuition-box/ARP
+claude plugin install arp@arp
+```
+
+The agent reaches for ARP when you name it: "find me a skill for X with ARP". A search reads skills.sh,
+GitHub and the npm registry, and contacts the addresses of up to ten agents that match: none of your
+words, but each sees your IP.
+
+With no `arp` on `PATH`, its commands stand in for `arp share` and `arp line`. A person types them, and the model cannot invoke them:
+
+```
+/arp:share         what would be public, and what stays here. Sends nothing
+/arp:share-on      turn sharing on (off by default). Sends nothing
+/arp:share-off     turn it off
+/arp:share-send    write the shared failures as public lines on testnet. Needs a sponsoring service
+/arp:line          write one public line on testnet: --tool <url> --outcome worked|failed
+```
+
+A session that allows `Bash` can still run the file itself: that rests on your permissions.
+
+The search in `arp_pulse` still runs `npx skills`: `npx` comes with Node, and that package comes from the npm registry. Installed from a local path, the plugin is read from that path, so keep the folder where it is.
+
+## Install into your runtime
+
+```
+arp init --dry-run     see what would change
+arp init               do it: asks first, backs up every file it edits
+arp doctor             check it: entries present, hook in place, the server answers
+```
+
+`init` finds Claude Code, Grok Build, Cursor, Gemini CLI, Codex and Copilot (VS Code, CLI) on this machine. It adds the MCP
+server to each one, and the hook to Claude Code (Grok Build reads Claude Code's files). For any
+other MCP client, `arp init --print` prints the entry to paste. `--yes` and `--no-input` are for
+scripts, `--runtime claude,cursor` narrows the run, and `--project` writes the project's files.
+
+`init` does not replace an MCP server named `arp` that it did not write. It leaves it, says so, does the rest and exits 6. Rename yours, or pass `--force` to replace it; a file is backed up first. Through the `claude` command there is no backup, so the old entry is printed before it is removed.
+
+## Uninstall
+
+```
+arp uninstall          removes what init added, and nothing else
+npm uninstall -g @arp-protocol/cli
+```
+
+Installed with `npx -y @arp-protocol/cli init`, there is no `arp` on `PATH`: run
+`npx -y @arp-protocol/cli uninstall` (and `doctor`) the same way. The plugin goes with
+`claude plugin uninstall arp@arp` and `claude plugin marketplace remove arp`.
+
+Neither removes what ARP wrote while it ran. `~/.arp/` holds the keys it made (`receipt-key`, and
+`agent-key` if you wrote a line), your failures, your sharing choice and the search package's cache;
+`.arp/` in each project is the hook's log. Delete both if you want them gone: `rm -rf ~/.arp`, and
+`.arp/` in each project.