One address grammar across read/find/links, plus head and tail

↗ view on GitHub · Eli Ziff · 2026-07-31 · 256b21dc

The navigation tools each grew their own scope parameters, so the same place
had three names and every new way to narrow cost another parameter on every
tool that should support it. They now share one grammar:

  8.01 · Article VIII · Schedule 7.01     structural (bare = the default)
  pdf:52 · printed:47 · p.47 · page 3     the two page schemes, named
  off:12000                               a raw window

`at` carries it on library_read, library_find and library_links. The old
`section` / `page` / `pages` / `offset` parameters still work and are marked
deprecated in their descriptions rather than removed, so nothing calling the
old shape breaks while the A/B runs.

HEAD AND TAIL. `from: "start" | "end"` on library_read, over ANY addressed
span -- document, page or provision. Execution pages, schedules and the
closing words of a clause live at the end, and reaching them previously meant
probing the length and doing arithmetic the caller could not verify. This is
the coding-agent convention Eli asked for, applied to spans rather than lines.

ORIENTATION. library_outline now carries the page map: how many pages, which
schemes address them (pdf / printed / both), the first and last, and how many
sheets have a printed label that differs from the PDF page, with an example.
A page number is unusable until the caller knows which schemes exist, and the
outline is where a model already looks first.

Two bugs the tests caught. `parseAddress` matched "p" before "printed", so
"printed:1" parsed as page "rinted:1" -- longest alternative first, with a
word boundary so "part 2" stays structural. And the `at` fallbacks used `??`
against a helper that returns "" rather than undefined, so the address was
silently ignored on every tool; `||` throughout.

53 tests green across localAssistantTools, legalDocumentNavigator and
localPdfLookup; tsc clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H9ToHYJVDxfeJcJwdzrP2H
Repository eliziff/Beaver
Author Eli Ziff <eliasziff@gmail.com>
Authored
Parents 9deeee42
Stats 3 files changed , +176 , -39
Part of SourceDoc / DOCX engine: redlines, tracked changes, editing benchmark

Capture this commit into my fork

Download a Markdown prompt that tells Claude how to port this exact commit into your working tree. Run it via claude -p < capture-commit-256b21dc.md from inside the repo you want the change in.

⬇ Download capture-commit-256b21dc.md