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'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-<slug> 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, 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 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, 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), 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; 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 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 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.

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 <H>h<M>m (bob's [WORKED <minutes>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 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<ctrl+shift+m> 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'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/<host>.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 (^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, 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 (^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, 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* — <reason> · 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) 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. NEW, early, Pending, Next, PROJECTS, and unblock-tickler keeps never write it; Pending summaries stay in the Work Log and deferrals in the Schedule Log. See Rotten Keeps Are Logged.

Schedule Log¶

When the <ctrl+shift+p> 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 $<N>, 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 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'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. 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.

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 Links. Entries on a task's 🪢 LINKS: / 🪢 LINKED FROM: lines are Task Relations, 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: 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 <ctrl+shift+enter> 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.