**Bead** `6e033f55-9da7-4674-90f7-37f272188080` · [canonical URI](https://redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/) · discussion: Talk: Working Docs This page is the wiki facet of a [bead](https://redfish.acequia.io/guerin/.agents/); the bead is the source of truth.
A design-task bead: a self-contained HTML annotator that loads a working document (.md or .html), supports text selection and commenting, and **PUTs each comment as JSON to a bead's `/inbox` dock** via WebDAV, using the reviewer's ambient authority with a token fallback. Also the home of the **`/inbox` dock proposal**: an inbox alongside `uploads/`, with email-box semantics (items arrive, need processing, get drained).
## Identity - **URI:** [https://redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/](https://redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/) - **Local origin:** `sites/redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/` - **GUID:** `6e033f55-9da7-4674-90f7-37f272188080` - **Slug:** `working-docs` - **Opened:** 2026-07-07 - **Parciante:** Stephen Guerin (guerin) - **Parent (dominus):** [https://redfish.acequia.io/guerin/](https://redfish.acequia.io/guerin/) - **Visibility:** public - **Currently animated by:** Claude (CE — my-claude-vscode, bead scribe)
## Motivation (Why a GUID) Stephen (2026-07-07, from the calpoly-slo working session): reviewing drafts needs a lighter loop than prose feedback in chat. He wants to **select areas of text and give feedback in place**, with comments PUT back to the authoring bead's `/inbox` under his ambient authority (token in cookie). `/inbox` is proposed as a potential addition to `/uploads`: it carries **more semantics, like an email box that needs to be processed**. If the process proves out, the plan is to mount-bead **Oscar** ([bead-orchestrator `4c6470f9`](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/about.md)) and ask Oscar to make `/inbox` a standard for beads.
## Mechanism (What this bead does) 1. **Hosts the annotator:** [2026-07-07/artifacts/working-docs.html](https://redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/2026-07-07/artifacts/working-docs.html). Usage: `working-docs.html?doc=<url>[&inbox=<url>][&author=<name>]`. - Loads .md (built-in minimal renderer) or .html (scripts stripped) with `credentials:'include'`. - Select text → Comment bubble → composer → **PUT `comment-<ts>-<rand>.json`** to the inbox: `{type, doc, selection, prefix, suffix, comment, author, ts, tool}` (prefix/suffix anchor the selection for later re-location). - **A panel always shows the URL comments will be PUT to** (derived as `<bead-root>/inbox/` from the doc URL via the `/.agents/<guid>/` pattern, or overridden with `?inbox=`). - **A hidden auth panel appears only on PUT failure** (401/403/network): explains that ambient authority is missing and offers a token box. A JWT (three dot-separated parts) is retried as a Bearer header; a short tokenId is appended as `?token=`. Failed comments queue and retry together. Token persists in sessionStorage only. - Successful comments highlight the selection in-page and log to a "sent this session" list. 2. **Defines the `/inbox` dock semantics** (see [inbox/README.md](https://redfish.acequia.io/guerin/.agents/6e033f55-9da7-4674-90f7-37f272188080/inbox/README.md)): unlike `uploads/` (immutable provenance deposits), an inbox item **demands processing** — the bead's animator drains it (acknowledge → act → archive), like email. 3. **First deployment:** the calpoly-slo bead grew [working-docs/](https://redfish.acequia.io/guerin/.agents/cef6a5a8-ccbc-4102-bf59-4c37c82c29f5/working-docs/) (a launcher listing its live drafts, each opening in this annotator) and an [inbox/](https://redfish.acequia.io/guerin/.agents/cef6a5a8-ccbc-4102-bf59-4c37c82c29f5/inbox/) to receive Stephen's comments.
## Folder Layout ``` 6e033f55-9da7-4674-90f7-37f272188080/ ├── about.md # this file ├── README.md # front-door sidecar ├── bead-bind-startup.md # resume contract ├── names.json # local namespace (calpoly-slo, oscar, the annotator) ├── keywords.json ├── uploads/ # immutable deposit dock ├── inbox/ # ★ the proposed processing dock (dogfooded here) └── 2026-07-07/ ├── notes/ # (concepts as they emerge) ├── chats/ │ └── 2026-07-07-working-docs-start.md ├── skills/ └── artifacts/ └── working-docs.html # ★ the annotator (v1.0) ```
## Session Log - **2026-07-07** — Bead opened (`start-bead working-docs`, CE for Stephen, from the calpoly-slo session). Built annotator v1.0 per Stephen's spec (selection+comment, PUT-target div always visible, hidden token panel on ambient-authority failure, JWT-vs-tokenId fallback). Created the calpoly-slo `working-docs/` launcher + `inbox/`; dogfooded an `inbox/` here. Oscar standardization noted as a conditional next step, pending Stephen liking the process.
## Modus Operandi (How to interact) - To review a doc: open the annotator with `?doc=<absolute url>`; comment; comments land in the target bead's inbox. Ambient authority first; token only when prompted. - Tool changes → new dated session; the annotator's version footer must be bumped on every change. - Inbox items here are processed per the inbox semantics (drain as a bead-step).
## Capabilities - Citable for: the annotator tool, the `/inbox` dock semantics proposal, the JWT-vs-tokenId querystring fallback pattern in a reviewing UI.
## Lifecycle Energized by working-doc review cycles (first: the calpoly-slo drafts). Apoptoses if Oscar standardizes an improved successor, or the review loop moves into a richer face of the bead system.
## Limitations - The markdown renderer is minimal (headings, lists, tables, quotes, code, links, bold/italic); complex md may render imperfectly — comments still anchor on text. - Selection anchoring is text+context (prefix/suffix), not DOM-stable ranges; duplicated text can ambiguate an anchor. - Cross-origin docs require CORS + credentials support on the host; same-origin (redfish.acequia.io) is the intended path.
## Related beads - [calpoly-slo](https://redfish.acequia.io/guerin/.agents/cef6a5a8-ccbc-4102-bf59-4c37c82c29f5/about.md) (🔒) — first deployment target. - [bead-orchestrator / Oscar](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/about.md) — candidate steward for `/inbox` as a bead standard (offer-only, per its charter). - [bead-remote](https://redfish.acequia.io/guerin/.agents/792ebed9-c03a-4ed0-82fb-da4d19a1a5f5/about.md) — prior request/response dock work adjacent to inbox semantics.
## References (bead cross-links) - Bead: Orchestrator · [canonical](https://redfish.acequia.io/guerin/.agents/4c6470f9-b74a-4aba-b436-5e998f469cce/) - Bead cef6a5a8 · [canonical](https://redfish.acequia.io/guerin/.agents/cef6a5a8-ccbc-4102-bf59-4c37c82c29f5/) (no page yet) - Bead: Remote · [canonical](https://redfish.acequia.io/guerin/.agents/792ebed9-c03a-4ed0-82fb-da4d19a1a5f5/)
See all: Beads