RogueAgenda/README.md

# Rogue Agenda

Rogue Agenda is a modern terminal reimagining of the ideas behind Lotus Agenda.
It captures information first and lets structure emerge later: enter a plain
sentence, then use categories, dates, saved views, notes, priorities, and live
filters to see it from different angles.

The interface deliberately recalls Agenda's dense blue-and-gray DOS workspace,
including the function-key command strip, while behaving like a current TUI:
it resizes fluidly, supports mouse selection and command clicks, understands
common keyboard conventions, and stores each document as an ordinary SQLite
database with the `.agnd` extension.

## Features

- Free-form items with multiline notes, priority, due dates, done dates, alarms,
  independent date and numeric category values, recurring schedules, and
  prerequisites. Completing a recurring item creates its next dated occurrence
  and carries its alarm and filing forward.
- Hierarchical categories with inherited membership and explicit many-to-many
  assignment and negative exclusions: an item exists once but can appear in many
  contexts.
- Automatic filing from category match phrases and natural date phrases such as
  `today`, `tomorrow`, `next friday`, `in 3 days`, and ISO dates.
- Live views for all items, tasks, upcoming work, completed work, and a datebook.
- Full-text search plus composable Boolean filters over text, notes, categories,
  dates, done state, priority, category-scoped numeric values, alarms, recurrence,
  and relative due windows.
- Agenda-style View Manager and Category Manager screens with editable live
  view definitions, hierarchy, category kinds, match phrases, and exclusivity.
- Persistent per-view columns, custom headings and widths, numeric aggregates,
  filtered multi-section layouts, collapsed sections, and view reordering.
- Lotus-style live conditions and persistent actions with match previews,
  reversible conditional assignments, category-scoped date/numeric ranges and
  values, assignment removal, completion, structured export, and discard.
- Marking and bulk completion, soft deletion with Trash recovery, sorting, and
  dependency visibility.
- View-scoped CSV, JSON, Markdown, HTML, and iCalendar export, text/iCalendar
  import (including standard recurrence rules), autosave, WAL journaling, and
  transactional SQLite persistence.
- Responsive compact/wide layouts, keyboard navigation, mouse selection,
  clickable function-key commands, and an in-app help screen.
- Application-wide Preferences plus per-document settings for themes, display and
  locale conventions, autosave, confirmations, dates, filing, Trash, and backups.
- Document-local Agenda-style macros: literal keystroke playback, brace commands,
  persistent variables, branches, loops, calls, prompts and menus, AUTOEXEC,
  key bindings, and a Learn recorder. The responsive macro editor adds syntax
  highlighting and key capture without sanding away the unusual original language.
- Six complete clean-room presets for account work, study cards, personal
  planning, recipes, bicycle logs, and people development. Each combines its own
  categories, views, rules, macros, and original sample records.

## Build and run

You need a current stable Rust toolchain and SQLite development libraries.

```sh
cargo run -- notes.agnd
```

If the path has no extension, Rogue Agenda appends `.agnd`. A new document is
initialized with useful categories and saved views. To explore a populated file:

```sh
cargo run -- demo.agnd --demo
```

For a richer example, initialize a new document with one of the six presets:

```sh
cargo run -- sales.agnd --preset accounts
cargo run -- learning.agnd --preset study
```

The available names are `accounts`, `study`, `planner`, `recipes`, `rides`, and
`people`. Presets only initialize new document paths and never replace an existing
file. See [PRESETS.md](PRESETS.md) for the supplied views, rules, macros, and demo
content in every workspace.

### Install for use from any directory

From the Rogue Agenda source directory, install the release binary under your
user-local prefix:

```sh
cargo install --path . --root "$HOME/.local"
```

This places the executable at `~/.local/bin/rogue-agenda`. Ensure
`~/.local/bin` is on your shell's `PATH`; for Bash or Zsh, add this line to the
appropriate startup file (`~/.bashrc` or `~/.zshrc`) if it is not already there:

```sh
export PATH="$HOME/.local/bin:$PATH"
```

After opening a new shell, Rogue Agenda can be launched from anywhere:

```sh
rogue-agenda notes.agnd
rogue-agenda demo.agnd --demo
rogue-agenda week.agnd --preset planner
```

Noninteractive transfer commands are also available:

```sh
cargo run -- notes.agnd --import inbox.txt
cargo run -- notes.agnd --export csv --output notes.csv
cargo run -- notes.agnd --export json --output notes.json
cargo run -- notes.agnd --export markdown --view Tasks --output tasks.md
cargo run -- notes.agnd --export html --view Datebook --output agenda.html
cargo run -- notes.agnd --export ics --output tasks.ics
cargo run -- imported.agnd --import tasks.ics
```

## Development quality gate

Compiler warnings are denied by project configuration. Before accepting any
change, install the pinned Antislop release and run the complete gate:

```sh
cargo install antislop --version 0.3.0 --locked
./scripts/quality-gate.sh
```

It requires clean `cargo fmt --check` output, runs Clippy across every target and
feature with `-D warnings`, rejects Antislop findings, executes all tests, builds
warning-free documentation, and produces the release binary. Any finding, warning,
formatting difference, test failure, or build failure stops the gate.

## Essential keys

| Key | Action |
| --- | --- |
| Up/Down or `j`/`k` | Move between item rows |
| Left/Right | Move between cells/columns |
| `Insert` or `n` | Add a free-form item |
| `F2` or `e` | Edit the selected item or bound value cell |
| `F3` or `c` | Assign categories |
| `F4` or `d` | Toggle done |
| `F5` | Edit the item's note |
| `F6` or `p` | Edit priority, When, alarm, and recurrence |
| `F7` or `Space` | Mark for bulk operations |
| `F8` or `v` | View Manager |
| `F9` | Category Manager |
| `F10` or `m` | Command menu |
| `r` | Edit prerequisites for the selected item |
| `/` | Search the current view |
| `Ctrl-G` | Macro Manager / stop and save a Learn recording |
| `h` / `l` | Previous / next saved view (`[` / `]` are aliases) |
| `Ctrl-S` | Save/checkpoint |
| `?` or `F1` | Help |
| `q` | Quit |

Inside forms, `Tab` moves between fields, `Space` opens a choice popover for
predefined settings, `Enter` accepts, and `Esc` cancels. Choice popovers support
arrow keys, `j`/`k`, `Enter`/`Space`, and mouse clicks.
In the `F5` note editor, `Enter` inserts a line, arrows/Home/End move the cursor,
and `Ctrl-S` saves. Mouse clicks select rows, switch views, and activate the
bottom command strip.

## Preferences and document settings

Press `F10`, then `p` for application-wide Preferences. Rogue Agenda saves these
as typed TOML at `~/.config/rogue-agenda/preferences.toml`. The screen controls:

- `classic`, `mono`, `amber`, `greenscreen`, `nord`, and `catppuccin-mocha`
  themes
- function-key command bar and category-rule detail visibility
- carriage-return and item markers
- autosave checkpoint interval and destructive-action confirmations
- ISO, US, European, or long date display and 12/24-hour time
- decimal and thousands separators for legacy unbound numeric displays; bound
  numeric columns carry their own portable report formatting

Greenscreen, Nord, and Catppuccin Mocha use dedicated selected-row
foreground/background pairs with at least 7:1 relative-luminance contrast.
Every theme also defines a contrast-checked canvas-heading color for column
titles, sections, dates, aggregate rows, and empty-view messages.

The file is created when Preferences are first saved. It can also be edited with
a text editor while Rogue Agenda is closed; unknown keys and invalid values are
reported instead of silently ignored.

Press `F10`, then `d` for settings stored in the current `.agnd` document. These
travel with the document and include its description, backup-on-open, Trash
retention (`on-demand`, `on-close`, `end-of-day`, or `immediate`), completed-item
policy, automatic filing, numeric date order, first day of the week, default and
named times, and note-editor tab width. `this week` and `next week` honor the
chosen week boundary; `morning`, `afternoon`, and `evening` honor their configured
times, plus whether Markdown/HTML reports include document/view headers and
footers.

Enumerated preferences and document settings use choice popovers, so values such
as themes, yes/no switches, policies, date formats, and week boundaries cannot be
mistyped. Free-form values such as times and marker characters remain text fields.

Use `F10`, then `b` to create a consistent sibling backup named
`document.agnd.bak`, or enable backup-on-open. Use `F10`, then `t` to empty Trash.
Permanent operations request confirmation unless that preference is disabled.

## Macros and Learn recording

Press `Ctrl-G` to open the Macro Manager. Its layout and primary keys follow
Agenda 2.0: `Insert` adds, `F2` edits, `Enter` runs, `F7` starts Learn recording,
plain `a` appends a recording, `F6` attaches a key, and `F4`/`Delete` removes.
Clicking a macro selects it. While Learn is active, Rogue Agenda shows a `LEARN`
indicator and records the real keys you use throughout the application; press
`Ctrl-G` anywhere to stop and save. The historical `Alt-F3` and `Shift-F7`
combinations remain aliases when a terminal can transmit them.

The first command names the macro. Everything outside braces is played as literal
typing, while entries inside braces represent keys or commands. For example:

```text
{capturetask}
n
{inputtext;What needs doing?;%task}
{type;%task}
{enter}
```

This opens New Item, asks a question, types the answer into the still-open item
editor, and saves it. Newlines and indentation in macro source are for readability
and are not played. The language is case-insensitive.

The implementation covers the original command families:

- Keys and highlight control, including repeat counts: `{enter;2}`, `{altf6}`,
  `{ctlpgup}`, `{shftab}`, and `{selection;setting}`.
- Variables and strings: `{defstr}`, `{defint}`, `{deffloat}`, `{let}`, `{clear}`,
  `{undef}`, `{append}`, `{find}`, `{length}`, `{leftstr}`, `{midstr}`, and
  `{rightstr}`. Local names begin with `%`; persistent document globals use `%%`.
- Control flow: `{branch}`, `{call}`, `{for}`, `{goto}`, `{if}`, `{ifeq}`,
  `{ifkey}`, `{ifnoteq}`, `{label}`, `{onbreak}`, `{onerror}`, `{return}`, and
  `{quit}`.
- Interaction: `{alert}`, `{getkey}`, `{inputcat}`, `{inputfile}`, `{inputtext}`,
  `{largebox}`, `{lotusmenu}`, and `{rollmenu}`.
- Agenda special variables such as `#DATE`, `#TIME`, `#FILENAME`, `#VIEWNAME`,
  `#HIGHLIGHT_VALUE`, `#MARK_COUNT`, `#ARGCOUNT`, and `#ASCII(nnn)`.

The DOS screen-pacing directives (`DEBUGON`/`DEBUGOFF`, `SPEED`, and the
`WINDOWS*` commands) are accepted but have no visual effect in the continuously
redrawn TUI. `#CLIPBOARD` is reserved but remains empty until Rogue Agenda gains
an application-owned copy/cut buffer.

`AUTOEXEC` runs automatically when its document opens. Global `%%` variables are
stored in the `.agnd` database. `Ctrl-C` interrupts a running macro or invokes its
`{onbreak}` handler. Macro-created prompts and menus support both keyboard and
mouse operation.

The editor is a responsive, near-full-screen reinterpretation of Agenda's note-
style Macro Editor. `Enter` adds a line, `F5` or `Ctrl-S` saves, `Esc` cancels,
and `Ctrl-V` captures the next pressed key as source notation. The same `Ctrl-V`
shortcut captures a key in the F6 binding field. `Alt-=` remains an optional
historical alias. Commands, labels,
local/global/special variables, numbers, comments, delimiters, and syntax errors
have distinct colors.

## Designing live views

Open the View Manager with `F8`. Press `n` to create a view, `e` to edit one,
`Ctrl-Up`/`Ctrl-Down` to reorder it, or `Delete` to remove it.

Boolean filters use `and`, `or`, `not`, and parentheses. Available predicates
include `text~rust`, `note~budget`, `category=Work`, `priority<=2`,
`numeric:Hours>7`, `numeric:Cost inside 100..500`,
`date:"Review Date" outside 2026-08-01..2026-08-31`,
`done`, `open`, `dated`, `undated`, `due<=7d`, `overdue`, `has-note`, `alarm`,
`recurring`, and `nonrecurring`.
For example:

```text
category=Work and open and (priority<=2 or due<=3d)
```

Columns use `field:width:heading:aggregate`, separated by commas. Ordinary fields
are `item`, `categories`, `when`, `priority`, `note`, `done`, `alarm`,
`recurrence`, `created`, and `updated`. Category values use `numeric[Category]`
or `date[Category]`; aggregates are `none`, `sum`, `avg`, `count`, `min`, or
`max`. A view may sort by a bound field such as `numeric[Hours]`.

```text
item:55:Action:none,when:25:Due:none,numeric[Cost]:20:Cost:sum
```

Numeric columns accept optional formatting fields after the aggregate:
`label:decimals:decimal-separator:thousands:negative:percent:alignment`.
Decimal separator is `dot` or `comma`; thousands is `comma`, `dot`, `space`, or
`none`; negative style is `minus`,
`parentheses`, or `trailing`; use `percent` to add a non-editable `% of total`
companion column.

```text
numeric[Cost]:20:Cost:sum:$:2:dot:comma:parentheses:percent:right
```

Count counts populated numeric cells, not section rows. Total, Average, Minimum,
and Maximum use only the bound category's populated values. Left/Right selects a
cell; `F2` edits a bound numeric or date value. `#HIGHLIGHT_VALUE` and
`#HIGHLIGHT_TYPE` follow that cell for macro arithmetic.

Sections use `heading|filter`, separated by semicolons. Add `|collapsed` to make
a section initially collapsed.

```text
Urgent|priority=1;Upcoming|due<=7d;Someday|undated|collapsed
```

## Automatic category rules

Open the Category Manager with `F9`, then create or edit a category. In addition
to simple match phrases, each category can have a Boolean condition and an
action. The form previews how many existing items match before saving. A true
condition creates a live conditional assignment to the category being edited;
that assignment is withdrawn when the condition becomes false, without removing
an explicit assignment. This lifecycle is independent of automatic text filing.

An action fires once when an item enters the category and creates a persistent
change. Actions use `action:value`: `assign:Category`, `exclude:Category`,
`remove:Category`, `priority:1`, `numeric:Hours=7.5`,
`date:Review Date=tomorrow`, `when:tomorrow at 3pm`,
`alarm:tomorrow at 2pm`, `repeat:weekdays`, `done:true`,
`export:jsonl|archive.jsonl`, or `discard:true`.

Use `F10`, then `u`, for Utilities Execute. It reapplies conditions and actions
to the current item, marked items, current section, current view, or whole
document. `F10`, then `f`, shows circular/non-converging rule conflicts.

## Recurring work

Open item properties with `F6` and set a recurrence to `daily`, `weekdays`,
`weekly`, `monthly`, `yearly`, or a rule such as `every 2 weeks`. The item must
have a When date. Marking it done preserves the completed occurrence and creates
the next open occurrence. Rogue Agenda shifts its alarm by the same interval and
copies its note, priority, recurrence, explicit category assignments, and
category-scoped date/numeric values
assignments. iCalendar import and export maps these schedules to `RRULE`.

## Design notes

Rogue Agenda is not file-format compatible with Lotus Agenda and uses no Lotus
code. It reinterprets the interaction model around items, categories, views,
automatic assignment, and information sifting. See [PROJECT.md](PROJECT.md) for
the research record and detailed implementation matrix.

## License

MIT. See [LICENSE](LICENSE).