working prototype

README.md

@@ -0,0 +1,155 @@
+# 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.
+
+## 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
+```
+
+## 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, `Enter` accepts, and `Esc` cancels.
+Mouse clicks select rows, switch views, and activate the bottom command strip.
+
+## 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).