@macintacos/caret 0.8.2 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "description": "Review, annotate, and approve Claude Code plans in a local web UI.",
   "author": { "name": "macintacos" },
   "homepage": "https://github.com/macintacos/caret",

package/README.md

@@ -1,8 +1,9 @@
 # 🥕 caret
 
-> ⚠️ **Prototype.** caret is an early prototype and may change substantially over the next
-> little while — interfaces, hooks, storage, and the install flow are all still settling.
-> Expect rough edges and breaking changes.
+> [!WARNING]
+> caret is an early prototype and may change substantially over the next little while —
+> interfaces, hooks, storage, and the install flow are all still settling. Expect rough
+> edges and breaking changes.
 
 caret is a Claude Code (and OpenCode) plugin that replaces the terminal plan-approval
 prompt with a local web UI. When your agent presents a plan, caret opens it in your
@@ -21,44 +22,53 @@ Want to develop caret rather than use it? Start with [CONTRIBUTING.md](CONTRIBUT
 
 caret needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle.
 
+> [!NOTE]
+> caret is **macOS-first**; Linux and Windows are best-effort. See
+> [`doc/CONFIGURING.md`](doc/CONFIGURING.md#platform-support) for what differs on each
+> platform and what to fall back on.
+
 ```sh
 bunx --no-cache @macintacos/caret@latest install
 ```
 
-That one command is the whole install. It detects which agents you have —
-[Claude Code](https://claude.com/claude-code), [OpenCode](https://opencode.ai), or both —
-asks which of them to install into, and registers the _published_ caret with each:
-prebuilt artifacts, the `/caret:*` slash commands, and the rumdl plan formatter, with no
-`git clone` and no compile step. Where it can't ask — off a terminal — it installs into
-every agent it detected. `--target claude` or `--target claude,opencode` pins the agents
-non-interactively, and `--dry-run` previews the run without changing anything.
-
-Restart the agent afterward — OpenCode installs the plugin package on its next start —
-then try `/caret:demo`, which presents a short fake plan to exercise the flow.
+That is the whole install — no `git clone`, no compile step. It detects which agents you
+have — [Claude Code](https://claude.com/claude-code), [OpenCode](https://opencode.ai), or
+both — asks which of them to install into, and registers the _published_ caret with each:
+prebuilt artifacts, the `/caret:*` slash commands, and the [rumdl](https://rumdl.dev/)
+plan formatter. Where it can't ask — off a terminal — it installs into every agent it
+detected.
 
-### Updating and uninstalling
+Two steps finish the job:
 
-**Update.** One command for every agent:
+1. **Restart the agent.** OpenCode installs the plugin package on its next start.
+2. **Run `/caret:demo`.** It presents a short fake plan, so you can exercise the whole
+   flow before a real one arrives.
 
-```sh
-bunx --no-cache @macintacos/caret@latest install --refresh
-```
+| Flag                | What it does                                                      |
+| ------------------- | ----------------------------------------------------------------- |
+| `--target <agents>` | Skip the chooser: `claude`, `opencode`, or both, comma-separated. |
+| `--dry-run`         | Preview the run without changing anything.                        |
+| `--refresh`         | Update an existing install.                                       |
+| `--uninstall`       | Remove caret, offering the same agent chooser.                    |
 
-`--target` pins the agents the same way it does on install, and restarting each one
-applies the update. In OpenCode, caret toasts you at startup when a newer release is out;
-a plain `install` at a terminal runs its own check against npm and asks before taking it.
-See [`doc/ADVANCED.md`](doc/ADVANCED.md#how-it-works) for the by-hand equivalents and for
-pinning a version in OpenCode's config.
+### Updating and uninstalling
 
-**Uninstall.** The same command, one flag:
+Both are the install command with one flag:
 
 ```sh
-bunx --no-cache @macintacos/caret@latest install --uninstall
+bunx --no-cache @macintacos/caret@latest install --refresh    # update
+bunx --no-cache @macintacos/caret@latest install --uninstall  # remove
 ```
 
-It offers the same chooser in reverse, and `--target` pins it the same way. See
-[`doc/ADVANCED.md`](doc/ADVANCED.md#how-it-works) for what each agent's install touches
-and how the integrations work.
+`--target` pins the agents on both, exactly as it does on a fresh install. Restarting each
+agent applies an update. In OpenCode, caret toasts you at startup when a newer release is
+out; a plain `install` at a terminal runs its own check against npm and asks before taking
+it.
+
+See [the OpenCode adapter](doc/ARCHITECTURE.md#the-opencode-adapter) for the by-hand
+equivalents, for pinning a version in OpenCode's `plugin` array, and for what each agent's
+install touches; [the Claude Code adapter](doc/ARCHITECTURE.md#the-claude-code-adapter)
+covers the hooks caret registers there.
 
 ## Using caret
 
@@ -72,39 +82,41 @@ prompt. There you:
   auto mode) or **Request changes**, which sends your comments back to the agent to revise
   and re-present.
 
-A single local daemon serves every session, so concurrent plans queue up in one tab behind
-a switcher.
+> [!TIP]
+> **In OpenCode**, you don't have to wait to be intercepted: caret registers a
+> `caret_review_plan` tool your agent can call directly, so a skill of your own can route
+> its approval step through the same review UI. Claude Code has no equivalent — see
+> [`doc/ARCHITECTURE.md`](doc/ARCHITECTURE.md#calling-the-review-tool-from-your-own-skill).
 
 ## Configuration
 
-caret runs with sensible defaults and needs no configuration. To tune it, it reads an
-optional `config.toml` and `CARET_*` environment variables (for example the daemon port or
-the review timeout); logs are written raw by default. The full list of keys, their
-defaults, and the environment variables is in
-[`doc/ADVANCED.md`](doc/ADVANCED.md#configuration).
+caret runs with sensible defaults and needs no configuration. To tune it — the daemon
+port, the review timeout, the log level — it reads an optional `config.toml` and `CARET_*`
+environment variables. Every key, every variable, and their defaults are in
+[`doc/CONFIGURING.md`](doc/CONFIGURING.md).
 
-## Reporting bugs
+## Diagnostics
 
 - `/caret:discovery` prints a one-shot, read-only diagnostics snapshot of your install —
-  ready to paste into a bug report.
+  always redacted, and it never contains plan, prompt, or feedback bodies, nor any log
+  contents.
 - `/caret:debug` reviews the current session's plans and recent errors.
 
-Details, plus how to scrub logs with `caret redact`, are in
-[`doc/ADVANCED.md`](doc/ADVANCED.md#logging--debugging).
+Logs are written raw by default. `caret redact` writes scrubbed `*.redacted.log` copies
+alongside them — paste one of those into a chat, a gist, or an AI assistant, never the
+original. [`doc/RUNNING.md`](doc/RUNNING.md#logging--debugging) says where they live.
 
-## Platform support
+## Documentation
 
-caret is **macOS-first**; Linux and Windows are best-effort. See
-[`doc/ADVANCED.md`](doc/ADVANCED.md#platform-support) for the details.
+[`doc/README.md`](doc/README.md) maps the `doc/` directory — start there and it routes you
+to the reference page that answers your question.
 
-## Documentation
+Two more live at the repo root:
 
-- [`doc/ADVANCED.md`](doc/ADVANCED.md) — the deep reference: build-from-source,
-  architecture, the agent adapters, the full configuration surface, and the development
-  workflow.
 - [CONTRIBUTING.md](CONTRIBUTING.md) — develop caret locally: setup, the `mise` workflow,
   and where tests live.
-- [`doc/`](doc/) — contributor rules-of-the-road, routed from [CLAUDE.md](CLAUDE.md).
+- [CLAUDE.md](CLAUDE.md) — for coding agents: routes a change to the rules-of-the-road
+  that govern it.
 
 ## License
 

package/commands/discovery.md

@@ -1,5 +1,5 @@
 ---
-description: Gather a redacted diagnostics snapshot of this caret install and present it ready to paste into a bug report
+description: Gather a redacted diagnostics snapshot of this caret install and present it ready to share
 ---
 
 caret's `discovery` subcommand prints a one-shot, read-only snapshot of the local install
@@ -12,7 +12,7 @@ or feedback bodies, nor any log contents — it exists to be shared.
 
 First ask the user (via `AskUserQuestion`) which format they want:
 
-- **JSON** — for pasting into a bug report or feeding to tooling.
+- **JSON** — for feeding to tooling.
 - **Human-readable** — for scanning in the conversation.
 
 Then run the matching invocation:
@@ -24,8 +24,8 @@ Then run the matching invocation:
 
 End your output with the command's stdout **verbatim** in a fenced code block —
 ` ```json ` for the JSON format, plain ` ``` ` for the human-readable one — so the user
-can copy it straight into a bug report. Add nothing inside the block and do not summarize
-away sections; the report is already redacted and complete. A degraded section (e.g.
+can copy it out in one piece. Add nothing inside the block and do not summarize away
+sections; the report is already redacted and complete. A degraded section (e.g.
 `daemon error: …` or `"error": "…"`) is normal when the daemon is down — present it as-is
 rather than treating it as a failure of this command.