# Glossary Bob's shared vocabulary, generated from the glossary memory web. ### Annotation Section *Aliases: section tag, section card.* A named group of Highlights annotations inside a [Reference Note](<#reference-note>)'s managed `## Highlights` region. A `# Name` line declares it: the first line of a sticky note (its later lines become the section's description) or of a highlight, underline, or image comment (that annotation joins the section). Trailing `@alias` or `#alias` tokens add match keys. An annotation joins by carrying `@name` or `#name` as a whole token at the start or end of a line. Matching ignores case and punctuation, and a matched tag is consumed, so a tag that still shows did not group. Mid-sentence tokens, `#task` lines, and `\` escapes never join. The space matters: `# Memory` declares, `#memory` joins. Each displayed block has one home, and a comment declaration beats tags. Each section renders as `### Name`, then a `[!summary|section]` card captioned `@tag · N highlights · Pages`, its `^s-` block, and its members under `####` page captions, ahead of Other highlights and Removed highlights. `bob ref show` and the Mac Refs panel group the same way. Membership is re-derived from the sidecar on every scan and nothing new is stored. Tag edits never change `^h-` IDs, and a PDF with no declaration renders unchanged. Not a Markdown `##` heading or a `bob capture` target section. See `docs/highlights-ref-sync.md`. ### Area Note A Bob vault Markdown file with frontmatter `type: "[[area]]"` for an ongoing sphere of responsibility with no end state, such as `cash`, `job`, or `dev`. Unlike a [Project Note](<#project-note>), it has no `^prj` task and no done/canceled lifecycle, so Bob always treats it as open. Its `parent` names the area it sits under (`"[[area]]"` for a top-level area); sub-areas and projects point `parent` at the area (or, for a sub-project, the project) they belong to. Every `#task` belongs in exactly one area or project note by residence, the file holding its checkbox line; a [Task Link](<#task-link>) or embed elsewhere never moves it. Area notes hold the ongoing tasks, usually under `## Tasks`, that belong to no finite project; the inboxes (`inbox`, `mac_inbox`, `gkeep_inbox`) are area notes whose tasks await triage. The only exceptions are a reference note's own [Reference Task](<#reference-task>), each daily note's templated `^gtd` task, and closed tasks that `bob task archive` moved into `done/`; move any other stray task with Ctrl+Shift+M. Root-level area notes are `@route` capture targets, and every area note gets the per-note Ready cap and `## Tasks` status grouping. ### Bulk Capture *Aliases: multi-item capture, batch capture.* A bulk capture holds multiple items: blank-line items, bare-URL lists, chained session operators, or one item per row from a `@@template:` draft. Template rows are later nonblank physical lines, one capture per line (a template using only `{0}` takes one capture per space-separated or quoted value, so several can share a line), never blank-line-separated items; capturing the draft is exactly capturing its `bob capture -E` expansion. Blank or whitespace-only lines separate items; a blank-line-free block of two or more bare-URL lines splits into one item per URL, and a line chaining session operators (`+2 x`, `x =`) into one item per operator. Authored child bullets never start an item. Each item is still judged alone, with its own markers and whole-item forms, so bulk linking (several `@route:id` items) and bulk completion (one `!note:id` per item) work. The draft-wide `@@route` form routes otherwise-unrouted items across a blank-line batch; the draft-wide `@@template:` form declares and expands before parsing. One staged planner (`CaptureBatchPlanner`) runs the items in order, so each item sees the edits planned before it (insertion points, block-ID checks, Pomodoro lineup numbers) exactly as sequential captures would, and any item's failure rolls the whole draft back. JSON output puts the first result in the legacy top-level fields plus an ordered `captures` array (`capture-parse` adds `items`), and human output numbers items `1/N`. Bob Mac Capture still submits one `bob capture` call: the preview stacks items under a count, the footer stays **Capture** instead of a single-item verb such as Link, Start, Close, Complete, or Queue, the notification is titled with the count, and Shift-Return in the `!` picker appends a blank line plus `!` for the next completion. Docs and code also say "batch" for any capture's staged writes, even a single item's. ### Capture One `bob capture` run over one draft: its arguments, piped stdin, or Bob Mac Capture's panel, which submits the whole draft as exactly one `bob capture` call and hides only once bob reports success (see [Bob Mac Capture Is A Thin Client Of bob]()). bob splits the draft into capture items, each a parent line plus optional authored child bullets, and each item's markers decide what it does. That is far more than GTD inbox capture: an item may create a task (default `mac_inbox.md`, an [Inbox File](<#inbox-file>)), bullet, sub-bullet, or project note; queue a bare public URL as a background reference job, never touching the network; link, start, complete, or relate existing tasks (`@route:id`, `!note:id`, `&`, `*`); or start, adjust, shift, or close today's Pomodoro (`=`, `+N`, `++N`, `x`). bob plans every edit against in-memory snapshots of the target notes and today's daily note, then writes all or nothing: a note changed on disk since planning, or any failed item, aborts the run and rolls back anything already written. `--dry-run` runs the same planner without writing; the app's live preview is `bob capture --dry-run --no-clip`. An unfinished picker query (`:dee`, `/fix`, `!fix`, `&`, `Call the bank +`) is refused, never captured as prose. The editor-facing `capture-*` companion commands are not captures, nor are `bob gkeep pull`, `bob ref create`, or Obsidian keymaps. A draft with two or more items is a [Bulk Capture](<#bulk-capture>); the grammar lives in `docs/capture.md`. ### Inbox File *Aliases: inbox note.* A Bob vault Markdown file whose tasks await triage: `inbox.md` at the vault root, or an [Area Note](<#area-note>) whose frontmatter `parent` resolves to `inbox.md` (today `mac_inbox.md` and `gkeep_inbox.md`). Only direct area children count, and the filename is irrelevant: a [Project Note](<#project-note>) filed under one (`gkeep_gdocs_inbox_dump`) or an untyped child (`inbox_overflow`) is not an inbox file. Classification reads live frontmatter on every gesture, and `inbox.md` counts by design though it holds no `#task` lines today. By default, `bob capture` and Bob Mac Capture file new tasks in `mac_inbox.md`, and `bob gkeep pull` drains Google Keep into `gkeep_inbox.md`. New tasks carry no `fresh` stamp, so most surface for triage in the NEW tier of the `]s` walk. On an open task in an inbox file, every non-closing Ctrl+Shift+P answer and a Ctrl+Shift+Enter toggle on the task line ask where the task goes just before writing, apply the action in place, then move the task without following it; the route picker never offers another inbox file, and `⇧↵` applies the answer without moving. Ctrl+Shift+M also moves it, following it to the destination. A non-closing capture that changes an existing inbox task's status asks the same question in Bob Mac Capture's route card, and bob moves the task in that capture's batch (`bob capture -i/--inbox-route`); otherwise a closed task leaves through `bob task archive`. The current inbox files set `ready_cap: off`. bob-plugins and `docs/projects.md` ("Inbox routing") say "inbox note" (`api.inboxRoute.isInboxNote`); that is not a Google Keep inbox note, the Keep item `bob gkeep` drains. bob-cli capture's `INBOX_FILE` constant and `kind: inbox` target mean only `mac_inbox.md`, the default capture route. ### Keep Streak *Aliases: keeps.* The count of consecutive due reviews at which a human confirmed a due Ready task as written, stored as `[keeps:: N]` (1–999; absence means 0) right after the task's `fresh`/`refresh` fields. Only an exact due Ready rotten/tickler target increments, once per review through the single keep helper; a keep on an unblock tickler (`returned_by: unblocked`) leaves the streak unchanged; every other human stamp clears it, and automation never touches it. At the configured limit the next due confirmation asks an explicit approved-decision question instead of stamping; see [Rotten Keeps Decay Through The Priority Ladder](), [Unblocked Tasks Resurface As Ticklers](), and [Task Freshness](<#task-freshness>). ### Mac Menu Bar Pomodoro Indicator *Aliases: mac pom.* The Hammerspoon status item in the macOS menu bar on Bryan's MacBook that shows the current Pomodoro at a glance. It is a read-only consumer of `bob pomodoro --show-stale --worked`: it re-syncs when today's daily note changes and polls every 60 seconds (15 seconds without the file watcher), on wake and unlock, from its Refresh menu item, and once when the countdown crosses zero; it ticks the countdown locally in between and never writes the vault. A running session reads `NAME (50m) · 🍅 12:34`, where NAME is the Pomodoro's `— NAME`. Each known, non-exempt theme component prefixes NAME with a colored `■` using the hue reported by `bob themes list -a -f json`; unknown or exempt themes and a failed catalog call have no swatch. An unnamed session with linked tasks shows its derived home label (`sase (50m) · 🍅 12:34`); `UNTITLED` only appears when there is nothing to derive. Once overdue, a `→ HH:MM` stop time joins the title and the `+MM:SS` count turns red; from ten minutes overdue the count becomes an `OVERDUE` badge flashing red at 1 Hz, and `--show-stale` holds it there rather than letting it read as idle. Without a session it shows today's worked total `hm` (bob's `[WORKED m]`, closed Pomodoros only) in green with no tomato, flashing as a green pill on Fibonacci-spaced 10-second steps that append `φ Nm`, re-anchored when the label reappears or the Mac wakes or unlocks; empty output falls back to `NO POMODORO`. A failed or unparsable run hides the item. It is neither the `bob pomodoro tmux` status line nor Bob Mac Capture's menu-bar item. It lives in the linked `chezmoi` repo under `home/dot_hammerspoon/` (`init.lua` runtime, `pomodoro_countdown.lua` presentation policy); that repo's README "Pomodoro menu bar" section is its spec, so coordinate `bob pomodoro` output changes with it. ### Morning GTD Review Footer *Aliases: review footer.* The bob-ledger-tools item in Obsidian's desktop status bar that keeps the morning GTD review — the tiered `]s` walk over the shared [Task Freshness](<#task-freshness>) queue — in view while you work through it. It answers three questions at a glance: how much is still due, where the cursor sits in the walk, and whether the commitment tiers are done (after them come ROTTEN upkeep, which is fine to stop partway, and the POST closeout). Off a queue row it reads `⟳ Review N due · K commitments` (or `Commitments done` / `Upkeep budget met`) with a `]s next` hint; on a queue row it reads `⟳ Review r/N · TIER i/M` plus that row's detail and, when the row has a recommended roll, the `Alt+P` preview in the hint slot (for example `Alt+P roll P2 1/1`). The other nonempty tier groups follow in walk order, then the `✓ upkeep/budget today` meter. To fit the status bar it uses short tier labels — `WIP` for PENDING (WIP is an official alias of the Pending status), `TICKS` for TICKLER, `REFS` for REFERENCES — explained in its tooltip, and it drops groups, then detail, hint, and meter as space runs out. Clicking jumps to the next due task like `]s`. It is a read-only projection: it never stamps or changes tasks, its numbers are queue positions rather than progress, and it hides when nothing is due or Tasks is unavailable. `]s` notices and `bob freshness list` keep full tier names, and dashboard ROTTEN chips fold TICKLER into ROTTEN where the footer splits them; see [Review Walk Is Tiered With Daily Lane Review](). ### Pomodoro A Pomodoro is a column-0 checkbox item under `## Pomodoros` in an Obsidian daily file, representing one work session. Its body is either a timespan such as `(**0920-0950** [t:: 30m])` or an empty `()` placeholder; an optional `— NAME` suffix (em dash plus ALL-CAPS name) makes it a named Pomodoro. Past Pomodoros are closed with timespans, current Pomodoros are open with timespans, and planned Pomodoros are open placeholders. Child bullets log the session's work, usually with a task link. On a sub-bullet, `N` moves it and the next N siblings into another open Pomodoro, or into a new named one below. ### Pomodoro Theme *Aliases: theme.* One `+`-separated component of a [Pomodoro](<#pomodoro>)'s `— NAME` suffix, keyed by the plan budget's component normalization and displayed in the most recently authored spelling. Pomodoro names are written in ALL CAPS: `— BOB + DECKS` is one name with two themes. `plan.max_themes` counts distinct non-exempt components across today's open entries; components in `plan.exempt` (default `[GTD]`) do not count. The Stats `theme` dimension splits a named session into the same components. The catalog is derived from canonical daily notes plus `.bob/themes/.jsonl`; `bob themes` lists, hides/unhides from Recent suggestions, pins/unpins colors, and renames components through one previewed Bob transaction. Hiding removes a theme from history suggestions only. Hue priority is pin, exempt mute, matching top-level area, then stable hash. Each theme wears a tint or rounded swatch, never an area's ● dot. Not a Pomodoro home, an Obsidian appearance theme, or `(unnamed)`. See `docs/pomodoro-themes.md`. ### Project Note *Aliases: prj note.* A Bob vault Markdown file with frontmatter `type: "[[project]]"` that holds a project's context and work. Its [Project Task](<#project-task>) (`^prj`) states the completion criteria and represents the project's overall status; ordinary tasks describe work toward that outcome. A closed project remains a project note if its `^prj` task is archived. See `docs/projects.md`. ### Project Task *Aliases: prj task.* The single project-level `#task` checkbox in a [Project Note](<#project-note>), identified by the exact trailing block ID `^prj`. Its description states what must be true for the project to be complete. The `^prj` line carries the project's date (inline `scheduled`) and dep links (its Depends-On line); while either blocks it, every open task in the note is Blocked and tagged `#prj_is_blocked`. `bob projects sync` maps checked to `status: done`, canceled to `status: canceled`, and reopening a terminal project to `status: wip`; an open nonterminal project's status is preserved. New lines include `#prj`; legacy lines without that tag remain recognized. See `docs/projects.md` and [Projects Block Their Tasks From The ^prj Line](). ### Reference Note *Aliases: ref note.* A Bob vault Markdown file with frontmatter `type: "[[ref]]"` for a particular piece of external reference material, such as a book, article, or captured conversation. It gathers source links, notes or highlights, and any follow-up work. Its [Reference Task](<#reference-task>) (`^ref`) represents progress through that material. Highlights sync generates this form; legacy notes may lack the task. See `docs/highlights-ref-sync.md`. ### Reference Task *Aliases: ref task.* The single source-level `#task` checkbox in a [Reference Note](<#reference-note>), identified by the exact trailing block ID `^ref`, that tracks progress through the external material. In Highlights-generated notes it links to the PDF: `[ ]` means `ready`, `[*]` means `next`, `[/]` means `wip`, `[x]`/`[X]` means `read`, and `[-]` means `abandoned`. Highlights sync reconciles this with note and PDF status. New lines include `#ref`; legacy lines without that tag remain recognized. Follow-up tasks track separate work. See `docs/highlights-ref-sync.md`. ### Rotten Log *Aliases: keep log.* A task-local history of rotten keeps, stored as a `🥀 **ROTTEN LOG**` direct child with newest-first `*YYYY-MM-DD* — · kept N×` entries. Alt+F or Ctrl+Alt+F on an exact due Ready ROTTEN or scheduled TICKLER row (the same keep that increments the [Keep Streak](<#keep-streak>)) and Keep on the approved-decay card first ask "Why keep it as written?": the reason is optional (blank logs `🤷 no reason given`) but the entry is not, and Esc writes nothing. N is the streak after that keep. The entry count is the number of keeps logged since rollout: unlike `[keeps:: N]` it never resets, and nothing reads it to change decay, lanes, Today, schedule, priority, or [Task Freshness](<#task-freshness>). NEW, early, Pending, Next, PROJECTS, and unblock-tickler keeps never write it; Pending summaries stay in the [Work Log](<#work-log>) and deferrals in the [Schedule Log](<#schedule-log>). See [Rotten Keeps Are Logged](). ### Schedule Log When the `` Obsidian keymap is used to add the `scheduled` or `priority` dataview property to a task — Task Card `1`–`4` picks a P-level and its frozen date, Enter opens explicit Schedule, and classic search (`/` or type to filter) reaches the same properties — or when `bob capture` uses `$`, we add a `SCHEDULE LOG` bullet that contains one sub-bullet for each scheduling. Log grammar, opt-in markers, and blank-reason `🤷 no reason given` are unchanged. ### Successor Offer # Successor Offer *Requested · project* aka offer, pull-in offer A task that a managed Done gesture recovered and may link under the Pomodoro destination is a successor offer. Offers are grouped as direct hand-offs, residents of a recovered project, or project-finished pull-ins. They are not linked until explicitly picked; a pick links the task, raises it to Next, and stamps it fresh. See [Unblocked Tasks Are Offered, Never Auto-Linked](). ### Task Dependency Link *Aliases: task dep link, dep link.* A plain (never transcluded) [Task Link](<#task-link>) to a prerequisite of another Obsidian task. A task's dep links all sit on its Depends-On line, its first direct child: `⛓️ **DEPENDS ON:** [[#^a]] • [[note#^b]]`. That line is the source of truth: Bob derives the task's `[dependsOn::]` field and each target's `[id::]` from it, and the task stays Blocked `[?]` while any target is open. Each open prerequisite carries a generated `🧱 **BLOCKS:**` line listing its open dependents, which Bob maintains from Depends-On lines and never reads back. Dependencies are always stored on the dependent's line, but can be edited from either end: Ctrl+Shift+B (Depends on) on the dependent or Ctrl+Shift+Alt+B (Blocks…) on the prerequisite. A [Project Task](<#project-task>)'s dep links sit on its own Depends-On line like any task's; while they are open, or its inline `scheduled` is future, every open task in its note is Blocked. A Blocked task keeps no Task Links under today's open Pomodoros: linking one raises its open prerequisites instead, and `bob task reconcile` removes such links. Add or remove dep links with Ctrl+Shift+P → Depends on, which fuzzy-searches open tasks across the vault, or by editing the line. A dep link is a prerequisite, not a sub-task: closing the dependent never closes its targets, and dep links never count as Pomodoro Task Links. See [Task Dependencies Are Links On One Depends-On Line]() and [Projects Block Their Tasks From The ^prj Line](); syntax details live in `docs/task-dependencies.md`. ### Task Freshness *Aliases: freshness.* The local calendar date a human last confirmed that an open task still needs doing as written, stored as `[fresh:: YYYY-MM-DD]` before the task's trailing Tasks fields. Supported Bob keymaps, Alt+F, and `bob capture` edits of existing tasks stamp it; creation and automation never do. A visible, non-recurring Ready task is due for review when it is new (no stamp), a tickler (its `scheduled` date arrived after the stamp, or it was automatically unblocked (`[unblocked::]`); machine state `resurfaced`), or rotten (the stamp is at least its interval old; machine `ROTTEN` since schema 2). The interval comes from `[refresh:: N]`, then the note's `task_refresh`, then `freshness.interval` (7 days) — except a Pending (WIP) or Next task in a walked lane, whose lane interval (`pending_interval` / `next_interval`, default 1 day; `false` walks that lane off) overrides the whole chain. The `]s` walk visits one shared queue in tiers PRE → NEW → PROJECTS → PENDING → NEXT → TICKLER → REFERENCES → ROTTEN → POST; only due tasks walk (a task stamped today drops out). PRE/POST `#gtd` checklist rows (often recurring) resolve by completion, never by a stamp. NEW holds unconfirmed tasks on `dash`, READY holds only confirmed/exempt tasks, and `rotten.md` holds TICKLER plus expired ROTTEN; see [Review Walk Is Tiered With Daily Lane Review](), [READY Is Freshness-Gated With NEW and ROTTEN Review](), [Today Is Read From The Ledger, Never Written To Tasks](), and [Unblocked Tasks Resurface As Ticklers](). Freshness never changes a lane, Today, schedule, or priority. Its status-bar view is the [Morning GTD Review Footer](<#morning-gtd-review-footer>). It is not Zorg `@FRESHNESS`, `bob vault-sync` freshness, or P-level scheduling windows. Freshness itself still never changes priority or schedule; the approved decision card invokes separate existing writers, and only on explicit approval — see [Rotten Keeps Decay Through The Priority Ladder]() and [Keep Streak](<#keep-streak>). ### Task Link *Aliases: task block link.* A block link to an Obsidian task. These can be located anywhere but, when they are the only contents of a sub-bullet on a pomodoro, they are treated as logged/planned tasks for that pomodoro. Task Links on a task's Depends-On line are [Task Dependency Link](<#task-dependency-link>)s. Entries on a task's 🪢 **LINKS:** / 🪢 **LINKED FROM:** lines are [Task Relation](<#task-relation>)s, never Pomodoro Task Links. ### Task Relation *Aliases: relation, LINKS line, LINKED FROM line.* *Requested · project* A directed, optionally labelled, inert link from one task to another. It is authored on the source task's 🪢 **LINKS:** line and mirrored on the target task's generated 🪢 **LINKED FROM:** line. Add one with Capture `~` / `~~` or the Task Card `l` / `⇧L` gestures. A relation is distinct from a Pomodoro [Task Link](<#task-link>): it never blocks a task, counts as a Pomodoro Task Link, or changes its status, schedule, priority, or freshness. ### Work Log A task-local history of work performed, stored as a `🛠️ **WORK LOG**` direct child with newest-first summary sub-bullets. When `` unlinks an In Progress (`[/]`) task, its nonblank work summary is prepended; a blank summary leaves the log untouched, and the task stays In Progress. Alt+N releasing an In Progress task prompts for the same optional summary.