RogueAgenda/PROJECT.md

# Rogue Agenda project ledger

Last updated: 2026-08-16

## 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 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.

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

## 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: per-item numeric values and view total/average are
  supported; arbitrary category formula programs are intentionally represented
  by the safer aggregate model.
- [x] Conditions/actions: category match phrases and date parsing run on item
  changes; assignments are immediately re-evaluated. Shell-executing actions are
  omitted by design, while deterministic filing actions are supported.
- [x] Printing: view-aware Markdown and styled HTML reports are the portable
  print/preview path, alongside CSV and JSON data exports.
- [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.

## Delayed / unsupported

These are the few features that either depend on obsolete DOS integration or need
a larger follow-on implementation:

- [ ] Arbitrary formula columns that reference several numeric categories. Current
  view columns support `sum`, `avg`, `count`, `min`, and `max` aggregates.
- [ ] Rich-text/font markers, printer control sequences, page-layout preview, and
  named printer configurations.
- [ ] Lotus Metro/List Manager/STF compatibility, DOS accessories, and import of
  external legacy `.MAC` files (outside the project's format-compatibility goal).
- [ ] Historic macro protection, hidden-list indicators, external source-file
  attachment, and per-screen run restrictions. Macro source, Learn recording,
  execution, key binding, AUTOEXEC, and persistent variables are already native.
- [ ] DOS macro single-stepping/speed/frozen-window effects and an internal
  clipboard bridge. Their command syntax and `#CLIPBOARD` value are recognized;
  screen-pacing directives are safe no-ops and the clipboard currently reads empty.
- [ ] Password encryption. A description field is supported by schema metadata;
  weak historic password protection will not be imitated without real encryption.
- [ ] Desktop notifications while the application is closed. Due alarms are shown
  prominently while Rogue Agenda is running.

## Near-term plan

1. Add desktop alarm integration and in-application snooze controls.
2. Add encrypted documents and secure unlock handling.
3. Add property-based tests for complex hierarchy and rule combinations.
4. Add a structured text definition-file importer for unusual legacy datasets.