wowbagger 0.1.0-alpha.8 → 0.1.0-alpha.9

package/CHANGELOG.md

@@ -7,6 +7,26 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.1.0-alpha.9 - 2026-08-23
+
+### Added
+
+- **A public Wowbagger brand asset.** The repository now carries an optimized
+  1024px image of Bowerick Wowbagger directing robotic agent cats at consoles
+  with a circuit-lit shepherd's staff. The asset is included in the npm
+  package for README and GitHub presentation.
+
+### Changed
+
+- **Public product prose now describes the current engine.** README, npm
+  metadata, Claude plugin metadata, marketplace metadata, and the installed
+  skill now explain report sequencing dashboards, named views, facets, graph
+  filtering, guarded CAS mutations, claims, fencing, reconciliation, and the
+  separation between core and host responsibilities.
+- **Agent onboarding is explicit.** The README and skill include a concise
+  agent TL;DR, exact core setup checks, the separate plugin/skills installer
+  routes, and the response-loss rule.
+
 ## 0.1.0-alpha.8 - 2026-08-23
 
 ### Added

package/README.md

@@ -2,6 +2,16 @@
 
 **The backlog may be infinite. The next item should not be ambiguous.**
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/lstutzman/wowbagger/main/assets/wowbagger-v5-typing-cats-circuit-staff.jpg" alt="Bowerick Wowbagger directing robotic agent cats typing at consoles with a circuit-lit shepherd's staff">
+</p>
+
+**Don't Panic!** The books that helped shape my childhood taught me to meet
+absurd systems with curiosity, humor, and a reliable way to find the next
+step. [Douglas Adams's Hitchhiker's Guide creations](https://douglasadams.com/creations/hhgg.html)
+are part of that inspiration; Wowbagger is an independent work, not an
+official or affiliated project.
+
 Wowbagger is a work ledger for coding agents. Every backlog item is one
 Markdown file in your repository; every lifecycle change is a reviewable Git
 diff. There is no database, no hosted service, and no private agent memory to
@@ -20,8 +30,8 @@ agent to use those guarantees instead of hand-editing your Markdown.
 
 **Start here:** [install the core and set up a ledger](#start-here).
 
-> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.8` is on npm under
-> the `next` tag and on this repository's `v0.1.0-alpha.8` tag. It is the
+> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.9` is on npm under
+> the `next` tag and on this repository's `v0.1.0-alpha.9` tag. It is the
 > version this repository runs its own backlog on. The API is not frozen and the
 > version will move before a stable release.
 >
@@ -31,17 +41,25 @@ agent to use those guarantees instead of hand-editing your Markdown.
 > older build — but `@next` is the documented install and the explicit
 > statement that you accept a prerelease.
 >
-> **What is proved.** The core validates a Markdown ledger, selects a
-> deterministic ready queue, renders a self-contained HTML report, and
-> implements guarded `inspect`, `create`, `transition`, and `patch`, plus
-> `mint-id`, `capabilities`, `provision`, the `claim` lifecycle,
-> `publish-claimed`, `claim-verify`, and `claim-adopt`. The core contract
-> version is **3**. Three adapter packages ship — Claude Code, Codex, and
-> OpenCode — on one shared engine at adapter contract version 2. Only the Claude
-> Code adapter declares a `supported` platform, Darwin, from a native run of all
-> 212 conformance assertions across all 16 cases. Every other adapter and
-> platform declaration is `unverified`; do not infer support because the CLI
-> starts.
+> **What is proved.** Contract version **5** validates the complete Markdown
+> ledger, selects a deterministic ready queue, exposes bounded `list` and
+> lossless `inspect` projections, and publishes guarded `create`, `transition`,
+> `patch`, `parent-migrate`, and `snooze` mutations. Mutations use exact-byte
+> compare-and-swap, atomic no-clobber publication, and explicit reconciliation
+> when a response is lost. Claims, fencing, adoption, prospective merge
+> verification, and publication finalization coordinate cooperating writers
+> without pretending to be an exclusive dispatch lock.
+>
+> `report` is a self-contained sequencing dashboard: **Work next**, **Attention**,
+> facet filters, inline evidence, terminal history, area-diverse batches, and a
+> 3D dependency graph. Version 2 report configurations add named custom views
+> whose statistics, readiness, attention, evidence, graph, and drill-down all
+> describe one filtered subset. Reports remain derived output, not mirrored
+> ledger state.
+>
+> The core ships Claude Code, Codex, and OpenCode adapter packages on one shared
+> engine. Read `capabilities --json` before relying on a target-specific claim;
+> platform support is evidence-based, not inferred from whether a CLI starts.
 >
 > **What is not a lock.** A work claim is not an exclusive dispatch lease. On a
 > provisioned Git-backed ledger, claims coordinate cooperating agents through a
@@ -53,31 +71,82 @@ agent to use those guarantees instead of hand-editing your Markdown.
 > filesystem writes, hostile processes, other clones, and non-claim-aware tools
 > still bypass the protocol.
 
+## TL;DR for agents
+
+Wowbagger is the core authority for a Git-native work ledger. Use it instead
+of editing ledger Markdown by hand.
+
+```sh
+wowbagger --version                 # require 0.1.0-alpha.9
+wowbagger capabilities --json       # require contract_version: 5
+wowbagger validate --ledger ledger --json
+wowbagger ready --ledger ledger --as-of YYYY-MM-DD --json
+wowbagger inspect --ledger ledger --number N --json
+```
+
+For a write, inspect immediately before dispatch, send the returned exact-byte
+revision as the compare-and-swap witness, use the explicit core mutation, and
+validate again. Commit each provisioned-ledger mutation before the next one.
+Never replay a lost write: reconnect, re-read current state, and treat the
+outcome as unknown until the core or a human resolves it. Numbers are the
+human-facing item identity; `wb_...` ULIDs are internal identities.
+
+The core owns validation, ready selection, projections, lifecycle, CAS,
+publication, claims, fencing, and reconciliation. The harness or host owns
+dispatch, process safety, routing, and human approval. Claims coordinate
+cooperating writers; they are not exclusive locks.
+
 ## Start here
 
-Install the core CLI, then verify it:
+Install the core CLI, then verify it. The core requires Node.js 20 or later:
 
 ```sh
-npm install -g wowbagger@next   # public npm registry
+npm install -g wowbagger@0.1.0-alpha.9   # exact plugin-matched release
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.8
-wowbagger --version         # 0.1.0-alpha.8
-wowbagger capabilities --json
+# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9
+wowbagger --version         # 0.1.0-alpha.9
+wowbagger capabilities --json              # must report contract_version: 5
+```
+
+In Claude Code, install the managed plugin:
+
+```sh
+claude plugins install wowbagger
+```
+
+Or, from inside a Claude Code session:
+
+```
+/plugin install wowbagger
 ```
 
-In Claude Code, add the plugin:
+This route is available after Wowbagger is listed in Claude Code's official
+marketplace. Until then, or when installing a fork or unreleased revision, use
+the direct repository marketplace:
 
 ```
 /plugin marketplace add lstutzman/wowbagger
 /plugin install wowbagger@wowbagger
 ```
 
-The plugin drives the installed core rather than bundling one, so a mismatch is
-detectable instead of silent. Its skill reads `wowbagger --version` and
-`capabilities`; it requires the same distribution version as the plugin and core
-`contract_version: 5`. It refuses an absent or incompatible core. It will not
-fall back to editing ledger files by hand, because that would bypass validation
-and atomic publication.
+For Codex and other agents, install the editable skill with `skills`:
+
+```sh
+npx skills@latest add lstutzman/wowbagger --skill wowbagger
+```
+
+Choose one route. Do not install both the managed Claude plugin and the
+editable skill, or the skill will be loaded twice.
+
+The plugin and `skills` installer drive the separately installed core rather
+than bundling one, so a mismatch is detectable instead of silent. The skill
+reads `wowbagger --version` and `capabilities`; it requires the same
+distribution version as the plugin and core `contract_version: 5`. It refuses
+an absent or incompatible core. It will not fall back to editing ledger files
+by hand, because that would bypass validation and atomic publication.
+
+Neither installer adds an MCP server, remote service, hook, or background
+process. The plugin and skill operate on the ledger through the installed core.
 
 ### Set the ledger up before the first item
 
@@ -253,7 +322,7 @@ two supported install routes:
   registry requires a `latest` tag), so a bare install resolves to the same
   bytes.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.8` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -325,7 +394,7 @@ Upgrade the pieces you installed:
 
 ```sh
 npm install -g wowbagger@next                  # public npm registry
-npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.8  # immutable Git release
+npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.9  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wowbagger",
-  "version": "0.1.0-alpha.8",
-  "description": "Plain-Markdown, Git-native work ledger for coordinating agents — validate, ready-select, and mutate a task ledger from the CLI.",
+  "version": "0.1.0-alpha.9",
+  "description": "Git-native work ledger for coding agents: deterministic ready queues, guarded CAS mutations, claims and fencing, and self-contained HTML reports.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -21,6 +21,10 @@
     "backlog",
     "coordination",
     "agent",
+    "multi-agent",
+    "reports",
+    "work-claims",
+    "compare-and-swap",
     "markdown",
     "git",
     "cli"
@@ -46,6 +50,7 @@
     "adapters",
     "vendor",
     "schemas",
+    "assets",
     "docs/adapter-contract.md",
     "docs/host-contract.md",
     "docs/mutation-contract.md",

package/skills/wowbagger/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wowbagger
-description: Use when coordinating work through a wowbagger ledger — reading the ready queue, inspecting or filing an item, generating an HTML ledger report, transitioning one through its lifecycle, taking a work claim, or publishing claimed work. Triggers on "ready queue", "ledger report", "backlog report", "what should I work on", "file a ledger item", "close this item", "claim this work", "publish claimed work", or any mention of a wowbagger ledger. Not for general backlog talk where no wowbagger ledger exists.
+description: Use when coordinating work through a Wowbagger ledger — reading deterministic ready work, inspecting lossless revisions, generating HTML reports and named views, filing or mutating items, taking a work claim, or publishing claimed work. Triggers on "ready queue", "ledger report", "report view", "backlog report", "what should I work on", "file a ledger item", "close this item", "claim this work", "publish claimed work", or any mention of a Wowbagger ledger. Not for general backlog talk where no Wowbagger ledger exists.
 ---
 
 # Wowbagger
@@ -9,6 +9,19 @@ A work ledger that is plain Markdown in Git. Every item is a file; every change
 is a reviewable diff. The core is read-only unless you explicitly ask it to
 publish something.
 
+## Setup
+
+Install the core separately before using this skill:
+
+```sh
+npm install -g wowbagger@0.1.0-alpha.9
+```
+
+The core requires Node.js 20 or later. This plugin ships only agent
+instructions; it does not bundle the core, an MCP server, a remote service, a
+hook, or a background process. It operates on the ledger and its Git working
+copy through the core's validated CLI.
+
 ## Before anything else: check the core
 
 This skill does **not** bundle the wowbagger core. It drives an installed one,
@@ -21,9 +34,9 @@ wowbagger capabilities --json
 
 Read the plain distribution version from the first command and the top-level
 `contract_version` from the second. **This skill requires distribution version
-`0.1.0-alpha.8` and core `contract_version: 5`.**
+`0.1.0-alpha.9` and core `contract_version: 5`.**
 
-The distribution pin names the published `0.1.0-alpha.8` release; the cut that
+The distribution pin names the published `0.1.0-alpha.9` release; the cut that
 publishes core `contract_version: 5` moves it. Earlier cores report
 `contract_version: 3` or lower and lack behavior this skill requires, including
 the bounded item source, so the version check refuses them. Do not soften