@macintacos/caret 1.0.0 → 1.0.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "caret",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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,80 +1,53 @@
-# 🥕 caret
+# 🥕 `caret`
 
-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
-browser so you can read it as rendered HTML, **annotate passages inline** (Google-Docs
-style), and **approve** or **request changes** — your feedback flows straight back to the
-agent. A single local daemon is shared across concurrent sessions, so several in-flight
-plans can be reviewed from one browser tab via a switcher.
+`caret` is a plugin that replaces the terminal plan-approval prompt with a local web UI.
+When your agent presents a plan, `caret` opens it in your browser so you can read it as
+rendered HTML, **annotate passages inline** (Google-Docs style), and **approve** or
+**request changes**. Your feedback flows straight back to the agent. A single local daemon
+is shared across concurrent sessions, so several in-flight plans can be reviewed from one
+browser tab via a switcher.
 
-Want to develop caret rather than use it? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
+Want to develop `caret` rather than use it? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Screenshots
 
-![caret review UI with an inline annotation, stitched across four themes](doc/assets/caret-review-ui.png)
-
 [Check out a short demo here!](https://youtu.be/zesv5AunUW4)
 
-## Install
-
-caret needs [`bun`](https://bun.sh) on your `PATH` — it runs from a `bun` bundle.
+![caret review UI with an inline annotation, stitched across four themes](doc/assets/caret-review-ui.png)
 
-> [!NOTE]
-> caret supports macOS and Linux, where the review UI can run as a login service (launchd
-> or systemd). Windows is best-effort and runs caret on demand only. See
-> [`doc/CONFIGURING.md`](doc/CONFIGURING.md#platform-support) for what differs on each
-> platform and what to fall back on.
+## Install
 
 ```sh
 bunx --no-cache @macintacos/caret@latest install
 ```
 
-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.
+> [!NOTE]
+> `caret` supports macOS and Linux, where the review UI can run as a long-lived login
+> service. Windows is best-effort and runs `caret` on demand only. See
+> [`doc/CONFIGURING.md`](doc/CONFIGURING.md#platform-support) for what differs on each
+> platform and what to fall back on.
 
-Every install at a terminal also asks whether to keep caret's review UI running all the
-time, and doesn't remember the answer. Keeping it running registers a service that starts
-at login and serves the UI at `http://caret.localhost:42718`; the other answer is
-[running caret yourself](#running-caret-yourself). Off a terminal it doesn't ask, and
-leaves the service however it finds it. To turn the service off later, run `caret install`
-and answer **I'll run it myself**, or use `--uninstall` — see
-[turning caret off](doc/RUNNING.md#turning-caret-off) and
-[the caret service](doc/RUNNING.md#the-caret-service).
+Assuming that you installed it as a long-lived service (the default), you can navigate to
+<http://caret.localhost:42718> to see the `caret` UI.
 
-Two steps finish the job:
+After installing:
 
 1. **Restart the agent.** OpenCode installs the plugin package on its next start.
 2. **Run `/caret:demo`.** It presents a short demo plan that points at files in the repo
    you run it from, so you can exercise the whole flow before a real one arrives.
 
-| Flag          | What it does                                          |
-| ------------- | ----------------------------------------------------- |
-| `--dry-run`   | Preview the run without changing anything.            |
-| `--refresh`   | Update an existing install.                           |
-| `--uninstall` | Remove caret from every agent, and from this machine. |
+### Running `caret` yourself
 
-### Running caret yourself
-
-If you'd rather caret not start at login, answer **I'll run it myself** when
+If you'd rather `caret` not start at login, answer **I'll run it myself** when
 `caret install` asks. That removes the service if one is registered. Then, whenever you
 want the review UI up, run:
 
 ```sh
-bunx --no-cache @macintacos/caret@latest serve
+bunx @macintacos/caret@latest serve
 ```
 
-It keeps the UI up at `http://caret.localhost:42718` until you press Ctrl+C. If caret
-already started on demand, `serve` stops that copy and takes the port; if caret's service
-still holds it, `serve` says so and exits. Without `serve`, caret still works: it starts
-when your agent submits a plan, and stops about a minute after the last review is
-resolved.
-
-After updating caret, run `caret serve` again yourself: the first plan from the new
-version stops the old one, and nothing brings it back.
+This will keep the UI up at `http://caret.localhost:42718` until the process is
+terminated.
 
 ### Updating and uninstalling
 
@@ -85,36 +58,27 @@ bunx --no-cache @macintacos/caret@latest install --refresh    # update
 bunx --no-cache @macintacos/caret@latest install --uninstall  # remove
 ```
 
-An update picks its agents exactly as a fresh install does — the chooser at a terminal,
-detection otherwise — and at a terminal asks the review-UI question again; an uninstall
-takes every agent. Where caret's service stays registered, `--refresh` also cycles it onto
-the new version, and restarting each agent loads that agent's own updated copy. 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.
-
-caret's daemon runs the same check for itself, at most once a day. The call is
-unauthenticated and sends nothing about you — just a request to npm or GitHub, depending
-on how caret was installed, for the newest published version. When a newer caret is out,
-the review UI says so once: a toast on load, a mark on the settings button, and a
+`caret`'s UI is designed to check for updates, at most once a day. When a newer `caret` is
+out, the review UI says so once: a toast on load, a mark on the settings button, and a
 **Settings → Updates** pane naming the version and the exact command to take it.
 
-Turn the check off from that same pane, or by setting `updates.check` to `false` in
-`prefs.json` (`~/.local/state/caret/prefs.json`, or under `$XDG_STATE_HOME/caret`):
+Turn the check off from that same pane, or by hand in
+[`config.toml`](doc/CONFIGURING.md#the-updates-table):
 
-```json
-{ "updates": { "check": false } }
+```toml
+[updates]
+check = false
 ```
 
 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.
+covers the hooks `caret` registers there.
 
-## Using caret
+## Using `caret`
 
-Whenever your agent presents a plan — Claude Code's `ExitPlanMode`, or the Plan agent in
-OpenCode — caret intercepts it and opens it in your browser instead of the terminal
-prompt. There you:
+Whenever your agent presents a plan, `caret` should intercept it and opens the plan in
+your browser instead of the terminal prompt. There you:
 
 - **Read** the plan as rendered HTML.
 - **Annotate** — select any passage to attach an inline comment.
@@ -123,7 +87,7 @@ prompt. There you:
   and re-present.
 
 > [!TIP]
-> You don't have to wait to be intercepted: caret gives both agents a plan-review tool
+> You don't have to wait to be intercepted: `caret` gives both agents a plan-review tool
 > they can call directly — `review_plan` in Claude Code (from the plugin's MCP server) and
 > `caret_review_plan` in OpenCode — so a skill of your own can route its plan through the
 > same review UI. The tool is for plans only; see
@@ -131,22 +95,11 @@ prompt. There you:
 
 ## Configuration
 
-caret runs with sensible defaults and needs no configuration. To tune it — the daemon
+`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).
 
-## Diagnostics
-
-- `/caret:discovery` prints a one-shot, read-only diagnostics snapshot of your install —
-  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.
-
-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.
-
 ## Documentation
 
 [`doc/README.md`](doc/README.md) maps the `doc/` directory — start there and it routes you
@@ -154,11 +107,18 @@ to the reference page that answers your question.
 
 Two more live at the repo root:
 
-- [CONTRIBUTING.md](CONTRIBUTING.md) — develop caret locally: setup, the `mise` workflow,
-  and where tests live.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — develop `caret` locally: setup, the `mise`
+  workflow, and where tests live.
 - [CLAUDE.md](CLAUDE.md) — for coding agents: routes a change to the rules-of-the-road
   that govern it.
 
+## Diagnostics
+
+- `/caret:discovery` prints a one-shot, read-only diagnostics snapshot of your install —
+  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.
+
 ## License
 
 MIT — see [LICENSE](LICENSE). Vendored third-party assets (the Lucide icons) are itemized

package/bin/caret-launcher

@@ -154,7 +154,7 @@ stop_agent() {
 # anything when there is no `service` record — nothing here installed a
 # supervisor, so this launcher cannot know what still names it, and deleting
 # itself would leave whatever does respawning on ENOENT. Deleting only bin/ and
-# the records leaves prefs and review state for a reinstall.
+# the records leaves review state for a reinstall.
 evict() {
   local service unit
   service="$(read_record "$records/service" || true)"