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

• .agnd SQLite documents, schema migration metadata, foreign keys, WAL, transactions, integrity-friendly soft deletion, and automatic checkpoints.
• Items with free text, note, priority, When, Done, alarm, independent category-scoped numeric/date values, recurring schedule, creation/update timestamps, manual order, and prerequisite links. Completion advances recurring work and carries alarms and filing forward.
• Categories with hierarchy, inheritance in queries, kinds (standard, date, numeric), match phrases, mutually exclusive siblings, and many-to-many links.
• Explicit assignment and automatic text-based assignment.
• Explicit negative category assignments that override automatic filing.
• Natural-language date extraction for common relative, weekday, and ISO forms.
• Live saved views, datebook presentation, category/done/date/priority filters, search filtering, configurable sort, and responsive columns.
• Interactive creation, editing, and deletion of saved live views and category definitions, including hierarchy, match phrases, kinds, and exclusivity.
• Persistent per-view fields, headings, widths, order, numeric aggregates, filtered multi-section layouts, collapsed sections, and view reordering.
• Parsed Boolean expressions with and/or/not, parentheses, text/note/ category matching, numeric comparisons, state predicates, and relative due dates.
• 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.
• Default All Items, Tasks, Upcoming, Recently Done, and Datebook views.
• Agenda-style item workspace, View Manager, Category Manager, command menu, item editor, property editor, notes, category chooser, help, and status messages.
• Marking and bulk completion; Trash view, soft discard, and recovery.
• Responsive wide/compact rendering and mouse row/command/view interaction.
• Vi-style h/l saved-view navigation with wraparound and legacy [/] aliases.
• 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.
• 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.
• Dedicated, contrast-checked canvas-heading colors across all themes for column titles, sections, Datebook dates, aggregates, and empty-view messages.
• 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.
• Consistent manual/startup .agnd.bak backups, timed WAL checkpoints, configurable Trash maintenance, and confirmations for permanent operations.
• Text and iCalendar import; view-scoped CSV, JSON, Markdown, styled HTML, and iCalendar export with notes, categories, dates, priority, completion, and recurring RRULE schedules.
• 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.
• 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.
• 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.
• Demo data, CLI help, README, MIT license, and unit/integration tests.
• 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

• Numeric calculations use independent item–numeric-category values and category-bound view columns. Count, Total, Average, Minimum, and Maximum follow populated-cell semantics per section; formatting and % of total are column properties. The retired items.numeric_value column remains only as a migration bridge for version-4 documents and older API callers.
• Conditions and actions follow separate Lotus lifecycles. Conditions maintain reversible conditional assignments to their own categories; actions fire once on source-category entry and make explicit persistent changes. Category-scoped date/numeric ranges and actions, removal, Done/export/discard Special actions, scoped Utilities Execute, and inspectable non-convergence state are supported.
• Printing: view-aware Markdown and styled HTML reports are the portable print/preview foundation, alongside CSV and JSON data exports. Markdown and HTML include live-view aggregate rows, percentage-of-total columns, portable numeric formatting, relative widths/alignment, print CSS, metadata, and optional headers and footers.
• 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.
• Clipboard/accessory capture: terminal paste into the new-item form replaces the DOS resident accessory.
• 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 rather than relying on the legacy 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.
• 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. 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, rule, and numeric combinations.