# Agent text selection

## 2026-09-26

The CLI adds `notes select --text` while preserving positional CSS lookup.
Matching is literal, unique by default, optionally scoped by section and occurrence (`-o`/`--occurrence`). Positive
values count from the start and negative values from the end; zero is invalid. The CLI suppresses attributed read highlights during resolution and
publishes one `seek` with the snapshot hash. The existing presence route rejects
stale ranges and uses the normal collaboration ACL. No content mutation occurs.

Section responses retain UTF-16 `start`/`end` and add a code-point `range` plus
whole-source `hash`. This avoids downloading a prefix just to translate offsets.
The CLI fails closed on older section responses. Existing RTC awareness and
remote-cursor rendering require no protocol or UI changes.

Affected public skills: `dreamlake-cli` and `dreamlake-notes`. Sources are CLI
Notes collaboration docs and workspace Notes docs; regenerate both and synchronize
the public repository after committing source. CLI release, server deployment,
docs, public skills and fresh native/npm installed readback are recorded below.

### Validation

- CLI full suite: 1,393 passed, one existing skip; docs tests: two passed.
- Selection tests cover exact Unicode ranges, missing/duplicate refusal,
  occurrence, scoped requests, identity, stale source, old server metadata,
  invalid receipts and compatible CSS lookup.
- Server body/presence/relay tests: 65 passed; the optional subprocess check
  additionally executes the real CLI against Fastify HTTP and confirms no source
  writes. Run it with the companion CLI source:

```bash
DREAMLAKE_SELECT_CLI=/absolute/path/to/dreamlake-cli/src/cli/index.ts pnpm -C dreamlake-server exec vitest run src/routes/notesBody.test.ts
```

- Native skill packaging passed isolated binary build/install/readback/conflict/update.
- Existing UI cursor/activity tests: five passed. A local served fixture replayed
  the accepted HTTP receipt (timestamps refreshed for inspection) through the
  production awareness-to-cursor renderer. The matched passage highlighted with
  the agent label, expired, and left the human cursor at 0:0. This is component
  acceptance, not a live authenticated RTC end-to-end check. No user note was used.

Release order: server section metadata before or with CLI publication, then
matching docs and public skill source synchronization. Before publication,
regenerate skills against combined current docs to preserve concurrent changes.
The initial local checks above preceded deployment. Current release receipts follow.

### Negative occurrence follow-up

`-o -1` selects the last match; `-o -2` selects the second-last in the selected
scope. Receipts retain a positive resolved occurrence. Focused tests cover negative
bounds, Unicode section offsets and real CLI argument parsing into the HTTP route.

Receipts now return the exact matched text, scope and resolved match number/count
in plain text and JSON, so callers can confirm what was selected without a reread.

### Plain-text default

Notes guides now explicitly require plain text for ordinary human and coding-agent
workflows, including selection receipts and examples. JSON remains opt-in for
explicit structured consumers; scripted revision/concurrency examples retain it
where parsing is required. Regenerate the public Notes and CLI references from
these source docs. No command behavior or release status changes.

### Release receipts — 2026-09-26

- Workspace #788 merged at `13b781e29a70015e94349000ff1bb0856e64543c`; full server CI passed.
- CLI #152 merged at `53ddc4e76eb6a5c3c71b46dbe892788bfbd0b1d4` (0.32.0).
- Staging deployment `36286624357` succeeded. Live acceptance verified scoped `-o -1` selecting match 3 of 3, ambiguity/bounds/stale refusal, real RTC presence, visible highlighting and expiry, and unchanged source/hash/revision. The dedicated staging fixture was cleaned up.
- Docs 0.1.29 deployed as `6ab8779284f6d68e90619a79`; production and permanent version pages matched generated source exactly.
- CLI docs 0.32.0 deployed as `6ab8767768ad7d5a3ab2cc9f`; live pages matched generated source exactly.
- Public skills #63 merged at `766c740`; a fresh public clone matched all 46 generated files and committed source revisions.
- Production server deployment `36287150511` and CLI 0.32.0 publication `36287434262` completed successfully; final live and downloaded-package verification is recorded below.

Production acceptance passed at 2026-09-27T02:07Z against `13b781e`:
scoped `--section next-steps -o -1` selected the last `simulation`, match 3 of 3,
at global code-point range `[108,118)`. The CLI refused ambiguity, no match,
out-of-range negative occurrence and stale hashes. Live authenticated RTC/browser
highlighting matched the receipt, and source/hash/revision stayed unchanged.
Production deployment `36287150511` and staging deployment `36286624357` both
completed successfully at the same `13b781e29a70015e94349000ff1bb0856e64543c`
commit. Health checks passed, and production highlight expiry was also verified.
CLI 0.32.0 publication `36287434262` completed successfully from
`53ddc4e76eb6a5c3c71b46dbe892788bfbd0b1d4`. Fresh native and npm installs both
reported 0.32.0 and matched all 44 bundled skill files; the native checksum and
size matched the public manifest. The downloaded native binary repeated the live
production selection/RTC/browser/expiry checks with unchanged source/hash/revision.
The distribution check passed for `latest`, `stable`, the installer, and all eight
platform binaries. Both synthetic notes returned 404 after soft deletion, the
temporary share was revoked, and test tabs/worktrees were cleaned up.