Add the agents usage bar widget

docs/install.md

@@ -16,6 +16,7 @@ with `--check`.
 | `install/steps/directories.sh` | the directories the shell and scripts expect |
 | `install/steps/packages.sh` | repo and AUR packages, and the yay bootstrap |
 | `install/steps/config.sh` | the `BLOB_PATH` symlink, everything under `~/.config`, and the login shell profile |
+| `install/steps/shell.sh` | the executable bit on `bin/` scripts, and new bar widgets added to an existing `shell.json` |
 | `install/steps/services.sh` | system services, systemd drop-ins, user units |
 | `install/steps/boot.sh` | the Plymouth boot splash, GRUB, and other-OS detection |
 | `install/steps/theme.sh` | the wallpaper link, the first theme, the first background |
@@ -42,7 +43,8 @@ with `--check`.
 2. **`BLOB_PATH`** is symlinked to the checkout at `~/.local/share/blob`. Nothing
    under `bin/`, `shell/`, `themes/` or `default/` is ever copied. `ln` does not
    create the parent of a link, so this step makes `~/.local/share` itself rather
-   than assuming step 1 ran.
+   than assuming step 1 ran. Any script in `bin/` that lost its executable bit
+   gets it back.
 3. **Packages** come from `packages/blob.packages` and
    `packages/blob-aur.packages`. Repo packages go in with a full
    `pacman -Syu`, never a partial upgrade. A machine with no AUR helper gets
@@ -59,6 +61,11 @@ with `--check`.
    panels come up full of blanks. `fonts.conf` binds `monospace` to
    `JetBrainsMono Nerd Font`; `blob font set` rewrites the same file, and the
    installer then reports it as a local change and keeps your choice.
+   A `shell.json` you already have is kept, but widgets listed in
+   `bar_widgets` in `install/steps/shell.sh` are added to it when missing, each
+   after the widget it names (or at the start of the right section), with a
+   `.bak` of the previous file. That is how `blob.agents` reaches an existing
+   bar.
    Launcher entries in `applications/desktop/` go to `~/.local/share/applications`
    and their icons in `applications/icons/` to `~/.local/share/icons/hicolor/32x32/apps`;
    that is how the Draw web app is installed.

docs/shell.md

@@ -17,6 +17,7 @@ shell/
     menu/              both menus
     notifications/     daemon, popups, DND, history
     notification-center/
+    agents/            Claude Code usage limits and token stats
     lock/  polkit/  osd/  background/  clipboard/  emojis/
     image-picker/  reminders/
     panels/            audio bluetooth clock disk-speedtest monitor network
@@ -49,7 +50,7 @@ entirely rather than merging.
 | --- | --- |
 | left | `blob.menu`, `blob.workspaces` |
 | center | `blob.clock` (anchored), `blob.system-update` |
-| right | `blob.tray`, `blob.bluetooth`, `blob.network`, `blob.audio`, `blob.monitor`, `blob.power`, `blob.notifications` |
+| right | `blob.tray`, `blob.agents`, `blob.bluetooth`, `blob.network`, `blob.audio`, `blob.monitor`, `blob.power`, `blob.notifications` |
 
 `blob.clock` and `blob.notifications` are `type: "command"` modules, which is how
 they carry their own click actions: the clock opens quick settings on left click,
@@ -61,6 +62,33 @@ notifications are silenced.
 The centre module named by `centerAnchor` cannot be dragged out of the centre.
 Every other widget still reorders.
 
+## Agents
+
+`blob.agents` is Omarchy's agents panel (quattro branch), trimmed to Claude
+Code. The panel shows the plan, a line per limit window (session, weekly, and
+any model-scoped weekly allowance as a tick on the weekly meter) with the time
+until it resets, and a rotating summary of local token stats: tokens this week
+and today, the most used model, the busiest day, and today's prompts and
+sessions. The exact percentage is on hover.
+
+| Input | Action |
+| --- | --- |
+| left click | open the panel |
+| right click, Enter, the hero button | start Claude Code in a terminal |
+| middle click, `r` | refresh |
+| Tab | move to the neighboring bar panel |
+
+The icon turns urgent when a window reaches 90%. Records refresh every
+`refreshIntervalSec` (900 by default) and the limits again whenever the panel
+opens.
+
+`blob-agent-usage-claude` builds the record. Limits come from Anthropic's OAuth
+usage endpoint with the token in `~/.claude/.credentials.json`; token stats
+come from the transcripts in `~/.claude/projects`, with `stats-cache.json` and
+`history.jsonl` as fallbacks. Scans and probes are cached in
+`~/.cache/blob/agent-usage`. When the access token has lapsed, starting Claude
+Code refreshes it.
+
 ## Calendar
 
 The clock's calendar popup and the Quick Settings card share one component,
@@ -103,8 +131,8 @@ so it cannot paint over the shell.
 This shell was forked from Omarchy 4.0.4 and is not tracked against it. The
 changes beyond renaming:
 
-- `agents`, `tailscale`, `dropbox`, and `dev-gallery` plugins removed, about
-  7,000 lines.
+- `tailscale`, `dropbox`, and `dev-gallery` plugins removed. `agents` was
+  removed too, then ported back from the quattro branch with only Claude Code.
 - The `Dictation` bar indicator removed with voice typing.
 - Persistent workspaces 1-9 instead of 1-5.
 - Menu cards 440 wide instead of 300, with the Blob icon on the bar button.