214 lines
9.1 KiB
Markdown
214 lines
9.1 KiB
Markdown
# 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,
|
|
numeric 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, numeric value, 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.
|
|
- User-authored category rules with a live match preview and deterministic actions
|
|
for assignments, exclusions, priority, value, dates, and completion.
|
|
- 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.
|
|
|
|
## 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
|
|
```
|
|
|
|
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, run the complete gate:
|
|
|
|
```sh
|
|
./scripts/quality-gate.sh
|
|
```
|
|
|
|
It requires clean `cargo fmt --check` output, runs Clippy across every target and
|
|
feature with `-D warnings`, executes all tests, builds warning-free documentation,
|
|
and produces the release binary. Any warning, formatting difference, test failure,
|
|
or build failure stops the gate.
|
|
|
|
## Essential keys
|
|
|
|
| Key | Action |
|
|
| --- | --- |
|
|
| Arrows or `h j k l` | Move selection / scroll |
|
|
| `Insert` or `n` | Add a free-form item |
|
|
| `F2` or `e` | Edit the selected item |
|
|
| `F3` or `c` | Assign categories |
|
|
| `F4` or `d` | Toggle done |
|
|
| `F5` | Edit the item's note |
|
|
| `F6` or `p` | Edit item properties |
|
|
| `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 |
|
|
| `[` / `]` | Previous / next saved view |
|
|
| `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`, `nord`, `solarized-dark`, `solarized-light`, 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
|
|
|
|
Nord, both Solarized variants, 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.
|
|
|
|
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.
|
|
|
|
## 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`, `value>100`,
|
|
`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. Fields are
|
|
`item`, `categories`, `when`, `priority`, `note`, `value`, `done`, `alarm`,
|
|
`recurrence`, `created`, and `updated`; aggregates are `none`, `sum`, `avg`,
|
|
`count`, `min`, or `max`.
|
|
|
|
```text
|
|
item:55:Action:none,when:25:Due:none,value:20:Cost:sum
|
|
```
|
|
|
|
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 rule condition and an
|
|
action. The form previews how many existing items match before saving.
|
|
|
|
Actions use `action:value`: `assign:Category`, `exclude:Category`, `priority:1`,
|
|
`value:125.50`, `when:tomorrow at 3pm`, `alarm:tomorrow at 2pm`,
|
|
`repeat:weekdays`, or `done:true`. `assign:` with no value assigns the category
|
|
being edited. Rules are reapplied to existing information and whenever an item
|
|
changes.
|
|
|
|
## 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, numeric value, recurrence, and explicit category
|
|
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).
|