RogueAgenda/PROJECT.md

# Rogue Agenda project ledger

Last updated: 2026-08-20

## Product direction

Rogue Agenda is a Rust, Ratatui, and SQLite reimagining of Lotus Agenda 2.0.
The goal is functional fidelity to its information-management ideas and visual
rhythm, not binary or document compatibility. Documents use `.agnd`; each is a
self-contained SQLite database. Every product string uses **Rogue Agenda**.

The central principle is “capture first, organize later.” An item is stored once
and may participate in many category relationships and saved views. The TUI keeps
the original's high-information gray workspace, blue title bands, red selection,
columnar item view, and function-key strip, while adding dynamic layout, mouse
interaction, conventional shortcuts, UTF-8, and modern durability.

## Research basis

- Lotus Development Corporation, *Lotus Agenda User's Guide 2.0* (1989), scanned
  at Internet Archive. The contents identify items, notes, hierarchical and
  mutually exclusive categories, explicit/conditional assignments, sections,
  live views, datebook views, alarms, numeric categories, column calculations, filters, dependencies,
  bulk marking, sorting, automatic conditions/actions, import/export, printing,
  backups, managers, macros, and accessories.
- Lotus Development Corporation, *Starter Applications 2.0* (1990), scanned at
  Internet Archive. It documents Activities Planner, Account Manager, People
  Manager, priorities, contacts, expenses, weekly tracking, and status reports.
- Tavis Ormandy's hands-on “Lotus Agenda” article and animations. These establish
  the actual screen grammar: two-line blue file/view header, gray unboxed canvas,
  section and column headings, dot-prefixed category values, red selection,
  blue F1–F10 command tiles, and examples of natural-language extraction.
- Bob Newell's Agenda FAQ and James Fallows' contemporary account. These clarify
  the distinctive behavior: single-copy items, category inheritance, negative
  assignment, aliases/abbreviations, incremental structure, and named live views.
- Period reviews from the Los Angeles Times and HUMANIST archives corroborate
  long notes, free-form entry, priorities, Boolean reports, and automatic filing.
- The preserved Agenda 2.0 Help file documents the Macro Manager, Learn workflow,
  note-style Macro Editor, complete brace-command catalog, variables, special
  values, error/break handlers, key notation, macro menus, and manager indicators.
- The preserved Agenda 2.0 Help and User's Guide define the original computation
  and automation model precisely. Each item can hold an independent value for each
  numeric category. Numeric columns provide Count, Total, Average, Minimum, and
  Maximum, an optional `% of total` column, and calculation labels and results that
  can be displayed and printed. Conditions are Text, Assignment, Date, or Numeric.
  Actions are Assignment, Date, Numeric, or Special; Special means designate as
  done, export, or discard. Utilities `Execute` re-applies conditions and actions
  to existing items; it is not an action type and does not launch a command.
- Agenda macros provide numeric variables, arithmetic expressions (`+`, `-`, `*`,
  `/`), and special values including `#HIGHLIGHT_VALUE`, so procedural calculations
  can read and write values through the interface. The 2.0 documentation does not
  describe declarative or automatically recalculated formula columns that combine
  multiple numeric categories. Such spreadsheet-style formulas are therefore not
  a historical parity requirement.
- A 1990 Lotus support FAQ (ag2qanda) independently lists the numeric-column
  calculations as Count, Total, Average, Minimum, and Maximum.

Research URLs:

- https://archive.org/details/lotus-agenda-users-guide
- https://lock.cmpxchg8b.com/lotusagenda.html
- https://www.bobnewell.net/agenda/agfaq.txt.html
- https://www.bobnewell.net/agenda/atlantic.txt.html
- https://www.bobnewell.net/agenda/AgendaHelp.htm
- https://dhhumanist.org/archives/Virginia/v02/0410.html
- https://www.latimes.com/archives/la-xpm-1988-07-28-fi-9745-story.html
- https://www.bobnewell.net/agenda/ag2qanda.txt.html (1990 Lotus support FAQ; confirms the five column-calculation settings)

## Implemented in this prototype

- [x] `.agnd` SQLite documents, schema migration metadata, foreign keys, WAL,
  transactions, integrity-friendly soft deletion, and automatic checkpoints.
- [x] Items with free text, note, priority, When, Done, alarm, numeric value,
  recurring schedule, creation/update timestamps, manual order, and prerequisite
  links. Completion advances recurring work and carries alarms and filing forward.
- [x] Categories with hierarchy, inheritance in queries, kinds (standard, date,
  numeric), match phrases, mutually exclusive siblings, and many-to-many links.
- [x] Explicit assignment and automatic text-based assignment.
- [x] Explicit negative category assignments that override automatic filing.
- [x] Natural-language date extraction for common relative, weekday, and ISO forms.
- [x] Live saved views, datebook presentation, category/done/date/priority filters,
  search filtering, configurable sort, and responsive columns.
- [x] Interactive creation, editing, and deletion of saved live views and category
  definitions, including hierarchy, match phrases, kinds, and exclusivity.
- [x] Persistent per-view fields, headings, widths, order, numeric aggregates,
  filtered multi-section layouts, collapsed sections, and view reordering.
- [x] Parsed Boolean expressions with `and`/`or`/`not`, parentheses, text/note/
  category matching, numeric comparisons, state predicates, and relative due dates.
- [x] User-authored category conditions with live match preview and deterministic
  assign, exclude, priority, numeric value, When, alarm, recurrence, and Done
  actions. Rules apply iteratively, respect explicit overrides, and detect
  non-convergence.
- [x] Default All Items, Tasks, Upcoming, Recently Done, and Datebook views.
- [x] Agenda-style item workspace, View Manager, Category Manager, command menu,
  item editor, property editor, notes, category chooser, help, and status messages.
- [x] Marking and bulk completion; Trash view, soft discard, and recovery.
- [x] Responsive wide/compact rendering and mouse row/command/view interaction.
- [x] Vi-style `h`/`l` saved-view navigation with wraparound and legacy
  `[`/`]` aliases.
- [x] Application Preferences persisted as typed TOML at
  `~/.config/rogue-agenda/preferences.toml`: theme, command bar, rule/return/item
  markers, autosave, confirmations, date/time display, and number separators;
  predefined values use Space-open keyboard/mouse choice popovers.
- [x] Six bundled palettes: Lotus-inspired Classic, Mono, Amber, Greenscreen,
  Nord, and Catppuccin Mocha. The three additional themes enforce at least 7:1
  selected-row contrast without changing the original three.
- [x] Dedicated, contrast-checked canvas-heading colors across all themes for
  column titles, sections, Datebook dates, aggregates, and empty-view messages.
- [x] Transactional per-document settings embedded in `.agnd`: description,
  backup-on-open, Trash and completed-item policies, automatic filing, numeric
  date order, week boundary, natural-language named times, and note tab width.
- [x] Consistent manual/startup `.agnd.bak` backups, timed WAL checkpoints,
  configurable Trash maintenance, and confirmations for permanent operations.
- [x] Text and iCalendar import; view-scoped CSV, JSON, Markdown, styled HTML,
  and iCalendar export with notes, categories, dates, priority, completion, and
  recurring `RRULE` schedules.
- [x] Document-local Agenda macro programs with raw keystroke playback; named and
  modified key commands; local and persistent global variables; arithmetic and
  string expressions; branches, loops, cross-macro calls, error/break handlers;
  input boxes, messages, horizontal/vertical menus; special context variables;
  AUTOEXEC; and attachable keyboard shortcuts.
- [x] Agenda-inspired Macro Manager (`Ctrl-G`, with legacy `Alt-F3` alias) with
  add/edit/run/delete/key binding
  and replace/append Learn recording. Recordings operate across the live TUI,
  show a LEARN indicator, and stop/save from anywhere with `Ctrl-G`; plain `a`
  replaces the unreliable modified-function-key append gesture.
- [x] Responsive full-screen Macro Editor with original-style `F5` return/save,
  `Esc` cancellation and terminal-safe `Ctrl-V` key capture, plus modern cursor editing and
  syntax highlighting for commands, labels, variables, values, comments,
  delimiters, and malformed source.
- [x] Demo data, CLI help, README, MIT license, and unit/integration tests.
- [x] Six clean-room, version-tagged preset workspaces selected with `--preset`:
  Accounts, Study, Planner, Recipes, Rides, and People. Each safely initializes
  only a new document and supplies tailored categories, views, sections, rules,
  macros, relative-date sample records, and user documentation in `PRESETS.md`.

## Supported with a modern interpretation

- [x] Numeric calculations currently use one optional `numeric_value` per item and
  expose five named aggregate modes: `sum`, `avg`, `count`, `min`, and `max`
  (`model/enums.rs` `Aggregate`, `ui.rs` `aggregate_value`). Sum, average, minimum,
  and maximum operate on the populated values in a section. Count currently counts
  every item in the section, whereas Lotus Count counted populated entries in the
  numeric column. The names therefore align with Lotus, but the data model,
  category scoping, Count semantics, formatting, and presentation do not yet have
  full parity.
- [x] Conditions / actions: each `CategoryRule` pairs a parsed condition
  expression (`filter.rs` `Predicate`: text/note containment, category membership,
  priority and numeric-value comparison, done / has-note / has-date / due-within /
  overdue / alarm / recurring) with a deterministic action (`RuleActionKind`:
  assign, exclude, priority, value, when, alarm, repeat, done). This is a useful
  modern predicate-to-mutation engine, but it is not yet a faithful implementation
  of Lotus conditions and actions. Re-evaluation on item change is currently tied
  to automatic filing, and a conditional assignment is not withdrawn when its
  predicate becomes false. `Done` overlaps one Lotus Special action; rule-driven
  export and discard are missing.
- [x] Printing: view-aware Markdown and styled HTML reports are the portable
  print/preview foundation, alongside CSV and JSON data exports. Markdown and HTML
  currently omit aggregate rows, percentage-of-total columns, numeric formatting,
  and other report-layout fidelity listed below.
- [x] Backups: SQLite durability is supplemented by explicit/manual and
  backup-on-open `.agnd.bak` snapshots after a full WAL checkpoint. Ordinary
  filesystem backup tools also work on `.agnd` files.
- [x] Clipboard/accessory capture: terminal paste into the new-item form replaces
  the DOS resident accessory.
- [x] Macros retain Agenda's compact hybrid of literal keystrokes and `{COMMAND}`
  entries while applying those actions to Rogue Agenda's modern TUI.

## Fidelity TODOs

These are the still-missing capabilities that matter to a full modern reimagining
of Agenda. Obsolete DOS integration, hardware-specific printer control, and legacy
file-format compatibility are not parity goals.

### Numeric data and calculations

- [ ] Store a separate value for every item–numeric-category assignment instead of
  the current single `items.numeric_value` scalar. Preserve explicit, automatic,
  and conditional assignment provenance while doing so.
- [ ] Bind numeric view columns to a specific numeric category so several values,
  such as Hours, Rate, Cost, and Budget, can coexist on one item and be displayed,
  filtered, sorted, edited, and aggregated independently.
- [ ] Scope numeric conditions and numeric actions to a chosen numeric category,
  with inside/outside minimum and maximum ranges and assignment removal.
- [ ] Match Lotus aggregate semantics per numeric column and per section: Count
  populated numeric entries rather than rows, and calculate Total, Average,
  Minimum, and Maximum from that column's values only.
- [ ] Add per-numeric-column display properties: label or currency symbol, decimal
  places, thousands separator, negative-number style, and full-precision storage
  independent of rounded display.
- [ ] Implement `Display % of total` as a derived, non-editable companion column
  calculated within each section.
- [ ] Make macro highlight context cell-aware. `#HIGHLIGHT_VALUE` must expose the
  highlighted numeric, date, text, category, or item value so Agenda-style macro
  arithmetic can operate on document data rather than only on item text.

### Conditions and actions

- [ ] Separate Lotus-style conditions from actions. A condition creates a live
  conditional assignment to its own category; an action creates an explicit,
  persistent assignment or value change after an item enters its source category.
- [ ] Withdraw conditional assignments automatically when their Text, Assignment,
  Date, or Numeric condition becomes false, while preserving explicit assignments.
- [ ] Re-evaluate affected rules whenever their inputs change, independently of the
  automatic text-filing preference.
- [ ] Implement category-scoped Assignment, Date, and Numeric conditions with the
  original positive/negative and inside/outside-range behavior.
- [ ] Implement Assignment, Date, and Numeric actions with explicit persistence,
  including assignment removal and category-specific date and numeric values.
- [ ] Complete Special actions: designate as done, export to a selected structured
  destination, and discard. `Done` exists today; export and discard do not.
- [ ] Add a user-facing re-evaluation command equivalent to Utilities `Execute`,
  scoped to the current item, marked items, section, view, or whole document. This
  means applying rules to existing data, not executing an external process.
- [ ] Surface circular or conflicting rules as inspectable document state instead
  of only returning a non-convergence error.

### Markdown, HTML, and modern printing

- [ ] Emit calculation-label footer rows and results for every configured aggregate
  in every Markdown and HTML section, using the same values as the live view.
- [ ] Emit `% of total` companion columns when enabled and keep percentage values
  consistent between the TUI, Markdown, and HTML.
- [ ] Apply each numeric column's label/currency, decimal, separator, and negative
  formatting consistently in Markdown and HTML reports.
- [ ] Preserve configured column alignment and relative widths in HTML and use
  appropriate Markdown alignment markers where Markdown can represent them.
- [ ] Add print-focused HTML styling: repeated table headers, sensible page breaks,
  section continuity, note wrapping, and optional document/view headers and footers.
- [ ] Include report metadata needed to understand an export: document description,
  view name, active filters, and generation time, without changing data-only CSV
  and JSON exports into presentation formats.

### Other modern-relevant fidelity

- [ ] Add rich-text emphasis markers and a modern print/PDF preview and page-layout
  workflow without reproducing DOS printer drivers or control sequences.
- [ ] Connect macros to the system clipboard and support useful modern equivalents
  of per-context run restrictions, source attachment, and single-step debugging.
- [ ] Add secure encrypted documents and unlock handling instead of reproducing the
  original weak password protection.
- [ ] Add desktop alarm delivery while the application is closed and in-application
  snooze controls.

## Near-term plan

1. Implement per-numeric-category values and category-bound numeric columns.
2. Correct conditional-assignment lifecycle and separate conditions from explicit
   actions.
3. Complete aggregate, percentage, numeric-formatting, Markdown, and HTML report
   parity.
4. Add desktop alarm integration and in-application snooze controls.
5. Add encrypted documents and secure unlock handling.
6. Add property-based tests for complex hierarchy, rule, and numeric combinations.