Commit `469ca131b7`

469ca131b7689cdf7e795c1fd49462b95c56d6f1

parent: d7844b8e4e

Verified · cmc

cmc <hello@cleberg.net> · 2026-10-09 06:00 UTC

Update the manual for the agenda redesign and widgets

Agenda rows, statuses, the Overdue group, the now line, hidden empty
days, day/week/month views and the new agenda keys; calendar events;
capture onto an agenda day; new settings and theme keys; iOS agenda
bar, swipes, Calendar settings, widgets, the clock Live Activity and
orgstar:// links.

Layout: unified · split

docs/manual/guide/03-keys.org +9 −1

 | Key | Does |
 |-+-|
-| =RET= | Opens the selected entry. |
+| =n=, =p=, =C-n=, =C-p=, =↓=, =↑= | Next or previous line. |
+| =RET=, =TAB= | Opens the selected entry, or a calendar event in Calendar. |
+| =SPC= | Shows the selected entry in the main window, keeping the agenda in front. |
 | =f=, =b= | Next or previous span (agenda views). |
 | =.= | Back to today (agenda views). |
+| =j= | Go to a date (agenda views). |
+| =v d=, =v w=, =v m= | Day, week or month view (agenda views). |
+| =d=, =w= | Day or week view (agenda views). |
+| =k= | Capture an entry scheduled on the selected line's day (agenda views). |
+| =s= | Save every file. |
 | =/= | Filter by tags, categories, effort and regexp (=+cat-tag<0:10-/regexp/=). |
 | =\= | Tag filter (=+tag-tag=). |
 | ~=~ | Regexp filter (=-re= drops matches). |
 | =g=, =r= | Rebuilds the views. |
 | =t= | Cycle TODO State. |
 | =+=, =-= | Raise or lower priority. |
+| =,= | Set priority. |
 | =:= | Set tags. |
 | =S-<right>=, =S-<left>= | Moves the entry's timestamp a day later or earlier. |
 | =I=, =O=, =X= | Clock in, clock out, cancel the clock. |

docs/manual/guide/07-agenda.org +162 −66

 #+TITLE: The agenda
-#+DESCRIPTION: The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board.
+#+DESCRIPTION: The agenda window, its rows, calendar events, the TODO list, tag and property matches, saved views, filters, reminders and the board.
 #+LEDE: The agenda collects dated entries and TODO items from your agenda files into one list you can act on.
 * Opening the agenda
 If no agenda file exists, the window says so.
-* The day and week view
+* The day, week and month view
-The default view is =org-agenda-list=: a run of days, each with a header such as =Monday      5 October 2026 W41= (the ISO week number appears on Mondays).
+The default view is =org-agenda-list=: a run of days, each under a header with its date, such as =Monday 5 October= (with the year when it isn't the current year). Today, tomorrow and yesterday are named before the date: =Today · Thursday 8 October=. Today's header is in the =agenda-today= color and days before today are grey. Each header stays at the top of the window while you scroll through its day.
 | Setting                      | Default | =config.toml=                     | Range in Settings |
 |------------------------------+---------+-----------------------------------+-------------------|
 | Days shown                   | 10      | =org-agenda-span = 10=            | 1 to 366          |
 | First day, relative to today | 3 days before | =org-agenda-start-day = "-3d"= | 0 to 14 days before |
-Both mirror the Emacs variables of the same name. The defaults are Doom's values, not plain Emacs's (a week starting today). =org-agenda-start-day= takes only day offsets such as ="-3d"= or ="+0d"=. There are no day, week or month view keys (=d=, =w=, =m= in Emacs) and no =org-agenda-start-on-weekday=: the span is a number of days and always begins at the configured offset.
+Both mirror the Emacs variables of the same name. The defaults are Doom's values, not plain Emacs's (a week starting today). =org-agenda-start-day= takes only day offsets such as ="-3d"= or ="+0d"=.
+** Day, week and month
+The Day, Week and Month control in the toolbar, or =v d=, =v w= and =v m=, shows one day, one week or one calendar month, as =org-agenda-day-view=, =org-agenda-week-view= and =org-agenda-month-view= do. =d= and =w= also show a day and a week. The view is the one around the selected line's day, else around today when today is shown, else around the first day shown. Weeks start on Monday; there is no =org-agenda-start-on-weekday= setting.
+To return to the configured span, choose Agenda from the view menu.
+The window's title names the days shown: =Thursday 8 October 2026= for a day, =Week of 5 Oct 2026=, =October 2026=, or the first and last day for the configured span, =5 Oct – 14 Oct 2026=.
 ** Moving through days
-| Key | Toolbar   | Does                              | Org command              |
+| Key      | Toolbar              | Does                                                                          | Org command             |
-|-----+-----------+-----------------------------------+--------------------------|
+|----------+----------------------+-------------------------------------------------------------------------------+-------------------------|
-| =f= | Later (›) | Moves forward by a whole span     | =org-agenda-later=       |
+| =f=      | Later (›)            | Moves forward by the days shown; in the month view, to the next month         | =org-agenda-later=      |
-| =b= | Earlier (‹) | Moves back by a whole span      | =org-agenda-earlier=     |
+| =b=      | Earlier (‹)          | Moves back by the days shown; in the month view, to the month before          | =org-agenda-earlier=    |
-| =.= | Today     | Returns to the span around today  | =org-agenda-goto-today=  |
+| =.=      | Today                | Returns to the days around today, keeping a day, week or month view          | =org-agenda-goto-today= |
-| =g=, =r= |      | Refreshes, and reloads =views.toml= | =org-agenda-redo=      |
+| =j=      | Go to Date (calendar) | Picks a date in a calendar and shows the days from it, or its day, week or month | =org-agenda-goto-date= |
+| =g=, =r= |                      | Refreshes, and reloads =views.toml=                                           | =org-agenda-redo=       |
-The agenda also refreshes on its own when files change, when you edit an open buffer, and once a minute so the time grid and the current day stay correct.
+The agenda also refreshes on its own when files change and when you edit an open buffer. The now line (see below) moves each minute, and at midnight the agenda refreshes so that Today, the overdue entries and the statuses move to the new day.
 ** What appears on each day
-The entries follow =org-agenda-get-day-entries= with Org's default entry types, in the formats Org prints.
+The entries follow =org-agenda-get-day-entries= with Org's default entry types. The left column of each row shows the time, or for an untimed entry a short status:
-| Entry                                   | Where it appears                                                                                      | Leader                         |
+| Entry                                   | Where it appears                                                                                      | Left column                    |
 |-----------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------|
-| =DEADLINE= on that day                  | On its day                                                                                            | =Deadline:=                    |
+| =DEADLINE= on that day                  | On its day                                                                                            | =Due today= on today, =Due= on other days |
-| =DEADLINE= in the future                | On today, from the warning period before it                                                           | =In   3 d.:=                   |
+| =DEADLINE= in the future                | On today, from the warning period before it                                                           | =Due in 3d=                    |
-| =DEADLINE= in the past, not done        | On today                                                                                              | =2 d. ago:=                    |
+| =DEADLINE= in the past, not done        | On today, in the Overdue group                                                                        | =2d late=                      |
-| =SCHEDULED= on that day                 | On its day                                                                                            | =Scheduled:=                   |
+| =SCHEDULED= on that day                 | On its day                                                                                            | =Scheduled=                    |
-| =SCHEDULED= in the past, not done       | On today                                                                                              | =Sched. 3x:=                   |
+| =SCHEDULED= in the past, not done       | On today, in the Overdue group                                                                        | =3d ago=                       |
-| Active timestamp =<2026-10-05 Mon>=     | On its day; also in property drawers                                                                  | none                           |
+| Active timestamp =<2026-10-05 Mon>=     | On its day; also in property drawers                                                                  | =All day=                      |
-| Repeating timestamp =<… +1w>=           | On each occurrence within the span                                                                    | none                           |
+| Repeating timestamp =<… +1w>=           | On each occurrence within the span                                                                    | =All day=                      |
-| Date range =<…>--<…>=                   | On every day of the range                                                                             | =(2/5):= (day 2 of 5)          |
+| Date range =<…>--<…>=                   | On every day of the range                                                                             | =Day 2/5= (day 2 of 5)         |
-| Diary sexp =%%(…)= line or =<%%(…)>=    | On each day the sexp applies; see [[*Diary sexps][Diary sexps]]                                       | none                           |
+| Diary sexp =%%(…)= line or =<%%(…)>=    | On each day the sexp applies; see [[*Diary sexps][Diary sexps]]                                       | =All day=                      |
-| Habit (=STYLE: habit=)                  | On today only, while not done; see [[*Habits][Habits]]                                               | none, with a consistency graph |
+| Habit (=STYLE: habit=)                  | On today only, while not done; see [[*Habits][Habits]]                                               | =Habit=, with a consistency graph |
+An entry with a time of day shows the time instead of the status: =08:00=, or =13:50–14:30= with an end time.
 Details:
 - Deadline warnings use =org-deadline-warning-days=, fixed at 14 days. A =-Nd= cookie in the timestamp (=<2026-10-20 Tue -3d>=) changes the warning for that deadline; =w=, =m= and =y= units work too.
 - A =-Nd= cookie on a =SCHEDULED= timestamp delays it: the entry first shows N days after the scheduled date.
 - Repeaters on =SCHEDULED= and =DEADLINE= timestamps (=+1w=, =++1w=, =.+1d=) make the entry show on the next occurrence on future days, as in Org.
-- A done entry shows only on the day of its deadline or scheduled date, not as overdue.
+- A done entry shows only on the day of its deadline or scheduled date, not as overdue. With =org-agenda-skip-scheduled-if-done= or =org-agenda-skip-deadline-if-done= set to =true= in =config.toml=, a done entry's scheduled date or deadline doesn't show on that day either. Both are =false= by default, as in Org.
 - Inactive timestamps (=[…]=) never appear, except in log mode.
 - Ranges in comment lines and inside source blocks are ignored, as in Org.
-Entries with a time of day sort into the day by time. On today, and on any day when the span is one day, a time grid is added when at least one entry has a time: lines at 8:00, 10:00, 12:00, 14:00, 16:00, 18:00 and 20:00, and on today a "now" line at the current time. The grid times are not configurable.
+A time can come from the timestamp (=<2026-10-05 Mon 14:00-15:30>=) or from the heading text (=Call Ada 9:30am=), as =org-agenda-search-headline-for-time= allows. Times past 24:00, such as =25:30=, show as the time on the next day, =01:30=.
+** Today, overdue entries and empty days
+Days without entries are left out. Today always shows, with =Nothing scheduled= when it has no entries. To show every day of the span, as Org does by default, turn on Settings ▸ Agenda ▸ Show days without entries, or set this in =config.toml=:
-A time can come from the timestamp (=<2026-10-05 Mon 14:00-15:30>=) or from the heading text (=Call Ada 9:30am=), as =org-agenda-search-headline-for-time= allows. Times past 24:00, such as =25:30=, show as =+1:30=.
+#+BEGIN_SRC toml
+org-agenda-show-all-dates = true
+#+END_SRC
+Today's past deadlines and entries scheduled on earlier days, habits excepted, go in a group headed =Overdue= with their count, above today's other entries. The oldest date comes first; entries with the same date keep Org's order. Click or tap the header to collapse or expand the group.
+On today, a line marked with the current time sits between the timed entries: before the first entry that starts later, or after the last one when all have started. It shows only when today has timed entries, as Org's =now= line does. Org's time grid (the lines at 8:00, 10:00 and so on) isn't shown.
 ** Sorting
-Days are sorted as =org-agenda-sorting-strategy= sorts them by default for the agenda: =(habit-down time-up urgency-down category-keep)=. Habits go last; timed entries come first, earliest first; the rest by urgency, which combines priority with how overdue an entry is; ties keep file order. The TODO list and match views sort by urgency, then file order. The sorting is not configurable.
+Days are sorted as =org-agenda-sorting-strategy= sorts them by default for the agenda: =(habit-down time-up urgency-down category-keep)=. Habits go last; timed entries come first, earliest first; the rest by urgency, which combines priority with how overdue an entry is; ties keep file order. Calendar events go among them as described in [[*Calendar events][Calendar events]]. The TODO list and match views sort by urgency, then file order. The sorting is not configurable.
 ** Log mode
 Press =l= to turn log mode (=org-agenda-log-mode=) on or off. Each day then also shows:
-- =Closed:= entries whose =CLOSED:= timestamp is on that day;
+- =Closed= entries whose =CLOSED:= timestamp is on that day;
-- =Clocked: (1:30)= for each =CLOCK:= line that starts on that day, with the clock's range and duration.
+- =Clocked= entries for each =CLOCK:= line that starts on that day, with the clock's start and end times in the left column.
+A note under a clock line (a list item directly below it) is added to the title after a =-=. These are the default =org-agenda-log-mode-items=, =(closed clock)=; state changes are not shown and there is no setting for that.
+* Rows
-A note under a clock line (a list item directly below it) is added to the line after a =-=. These are the default =org-agenda-log-mode-items=, =(closed clock)=; state changes are not shown and there is no setting for that.
+Each row shows, from left to right:
+- The time or status described above, with an icon below it on the Mac and before it on iOS: a calendar for scheduled entries, a flag for deadlines, arrows in a circle for habits, a clock or a calendar for timestamps, and a dot or a calendar for calendar events. An overdue entry shows a warning sign instead, and on the Mac a done entry shows a check mark.
+- The category, with a colored dot, above the title. For a calendar event this is the calendar's name, with the event's location.
+- The title: the heading without its TODO keyword, priority cookie, statistics cookies, timestamps and tags, with links shown as their descriptions. A done entry's title is struck through.
+- The value of the first statistics cookie (=1/3=, =50%=) and the tags, inherited tags first, as small capsules. iOS shows at most three tags.
+- The habit's consistency graph, for habits.
+- The TODO keyword as a colored badge, and the priority as a colored letter in a circle.
+The status sets the color of the left column:
+| Status   | When                                                                    | Theme key         |
+|----------+-------------------------------------------------------------------------+-------------------|
+| Overdue  | Not done, with a deadline or scheduled date before today                | =agenda-overdue=  |
+| Due soon | Not done, a deadline listed on today: due today or within its warning   | =agenda-due-soon= |
+| Done     | A done keyword                                                          | =done=            |
+| Normal   | Everything else                                                         | =agenda-time=     |
+Ages and distances are written compactly: days up to 13 (=3d=), then whole weeks up to 59 days (=2w=), then months of 30 days up to a year (=4mo=), then years with any remaining months (=1y=, =1y 4mo=). They round down.
+The keyword's color comes from =[theme.todo]=, else from its class: =todo-next= for keywords of work under way such as =NEXT= and =STRT=, =todo-waiting= for =WAIT=, =HOLD= and similar, =todo-cancelled= for done keywords such as =KILL= and =CANCELLED=, and otherwise =todo= or =done=. Priorities =A=, =B= and =C= use =priority-a=, =priority-b= and =priority-c=; others use =priority=. A category's dot takes its color from =[theme.category]=, else a hue worked out from the category's name, the same on every device. See [[file:13-configuration.org][Configuration]] for the keyword lists and the theme keys.
+* Calendar events
+The agenda can show events from the system Calendar app (EventKit) among your entries. They are read-only: Orgstar never changes your calendars. It is off by default. To turn it on:
+- On the Mac, turn on Settings ▸ Agenda ▸ Show events from Calendar, and check the calendars to show.
+- On iOS, turn on Settings ▸ Calendar ▸ Show Calendar Events, and tap the calendars to show.
+- Or set the keys in =config.toml=:
+#+BEGIN_SRC toml
+[orgstar]
+calendar-events = true
+calendar-event-calendars = "Work, Family"
+#+END_SRC
+=calendar-event-calendars= names calendars by title or identifier, separated by commas; =""= (the default) shows every calendar, including calendars added later. While every calendar is checked in Settings, the key stays empty.
+The first time events are turned on, Orgstar asks for access to your calendars. The system asks for full access, because Calendar has no read-only level of access. If you declined, allow it in System Settings ▸ Privacy & Security ▸ Calendars on the Mac, or in the Settings app on iOS.
+Events appear only in the day, week and month view:
+- All-day events come first on their day, as calendars show them.
+- Timed events go among the timed entries by start time, after entries with the same start and before untimed entries and habits.
+- An event over several days shows its start time on its first day, =Until 02:00= on its last day, and =All day= on the days between.
+- The dot and the icon take the calendar's color, or =agenda-event= when the calendar has none.
+- Filters don't hide events.
+On the Mac, double-click an event, or select it and press =RET=, to open it in Calendar; its context menu has Show in Calendar. Entry commands such as =t= don't apply to events.
+* Done keywords the agenda doesn't know
+A keyword that isn't in =org-todo-keywords= or the file's =#+TODO= lines is not a keyword to Orgstar, as to Org: it is part of the title. A heading such as =SKIPPED Call the bank= with a =SCHEDULED= date last week is therefore an open entry, and shows as overdue. To make such a word a done state, add it after the ~|~:
+#+BEGIN_SRC toml
+org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) | DONE(d) KILL(k) SKIPPED"
+#+END_SRC
+Done entries leave the Overdue group. With =org-agenda-skip-scheduled-if-done= and =org-agenda-skip-deadline-if-done= on, they leave their own day too.
 * Diary sexps
 The repeater can be =+=, =++= or =.+=, with an optional =/Nd= maximum interval. Days the habit was done are read from =- State "DONE" … [date]= lines (for any done keyword) and =CLOSING NOTE [date]= lines in the entry.
-A habit appears only on today's agenda and not once it is done for the day. Its line carries the consistency graph: one cell per day for the 21 days before today and the 7 after (=org-habit-preceding-days= and =org-habit-following-days=), with =*= on days it was done and =!= on today. Cell colors follow org-habit's faces:
+A habit appears only on today's agenda and not once it is done for the day. Its row carries the consistency graph: one cell per day for the 21 days before today and the 7 after (=org-habit-preceding-days= and =org-habit-following-days=). On the Mac the graph is at the right of the row, with =*= on days the habit was done and =!= on today; on iOS it is a strip under the title, with a dot on days it was done and today outlined. Cell colors follow org-habit's faces:
 | Color  | Meaning                                    | Theme key       |
 |--------+--------------------------------------------+-----------------|
 | Yellow | Last day of the interval                   | =habit-alert=   |
 | Red    | Overdue                                    | =habit-overdue= |
-Future days use lighter shades. Hover a cell to see its date. Habits sort after other entries.
+Future days use lighter shades. On the Mac, hover a cell to see its date. Habits sort after other entries.
 * The TODO list
 A saved view can list specific keywords instead, done ones included, with =keywords = "WAIT|HOLD"= (see [[*Views][Views]]). This mirrors =C-u M-x org-todo-list= with a keyword argument.
+The TODO list and the match views use the same rows as the day view (see [[*Rows][Rows]]), without the left column.
 * Tag and property matches
 Choose Match… from the view menu to list entries matching a match string, as =org-tags-view= (=m=) does, or TODO Match… to list only entries with an open TODO keyword (=M=). Type the match in the toolbar field and press Return.
 * Filters
-Filters hide lines without changing the view, as =org-agenda-filter= does. Time grid lines always stay. The active filter shows in the status line at the bottom of the window as =Filter: …=.
+Filters hide lines without changing the view, as =org-agenda-filter= does. Calendar events always stay. The active filter shows in the status line at the bottom of the window as =Filter: …=.
+The Filter button in the toolbar asks for a combined filter, as =/= does; its menu has each of the filters below and Remove Filters.
 | Key  | Does                                                          | Org command                       |
 |------+---------------------------------------------------------------+-----------------------------------|
 The =\= prompt reads every word as a tag, whether or not a line has it; there, ={regexp}= matches any tag that matches the regexp. The === prompt takes one regexp, with a leading =-= to drop matches. The =_= prompt takes one comparison such as =<0:30=.
-* The prefix and line layout
+* Prefix format and colors
-Each line shows the category, the time, the leader (=Deadline:=, =In   3 d.:=, =(2/5):=), the heading with its TODO keyword colored, the habit graph if any, and the tags.
+The rows look the same whatever =org-agenda-prefix-format= says. Orgstar reads the =[org-agenda-prefix-format]= table in =config.toml= (see [[file:13-configuration.org][Configuration]]), but the only effect is on times written in heading text: when the =agenda= format contains =%t=, as the default =" %i %-12:c%?-12t% s"= does, a time such as =9:30am= in =Call Ada 9:30am= moves out of the title into the left column, as =org-agenda-remove-times-when-in-prefix= does. Without =%t=, the title keeps it.
-To change what comes before the heading, set =org-agenda-prefix-format= in =config.toml=:
+The agenda's colors come from these theme keys (see [[file:13-configuration.org][Configuration]]):
-#+BEGIN_SRC toml
-[org-agenda-prefix-format]
-agenda = " %i %-12:c%?-12t% s"
-todo = " %i %-12:c"
-tags = " %i %-12:c"
-#+END_SRC
-These are the defaults. =agenda= applies to the day view, =todo= to the TODO list, and =tags= to match views. When a format differs from its default, the agenda shows the prefix as Emacs prints it, in a monospaced font, instead of its own columns.
+| Key                 | Colors                                                                    |
+|---------------------+---------------------------------------------------------------------------|
+| =agenda-background= | the Mac window's background, and the iOS widgets' background               |
+| =agenda-date=       | headers of days after today (Mac)                                         |
+| =agenda-today=      | today's header, the now line, and on iOS the widgets' date                 |
+| =agenda-time=       | the left column of rows with the normal status                            |
+| =agenda-overdue=    | the left column of overdue rows, and the Overdue group's header           |
+| =agenda-due-soon=   | the left column of deadlines due today or coming up                        |
+| =agenda-event=      | calendar events whose calendar has no color                               |
+| =agenda-category=   | category names (Mac)                                                      |
+| =todo=, =todo-next=, =todo-waiting=, =done=, =todo-cancelled= | TODO keyword badges, by class               |
+| =priority-a=, =priority-b=, =priority-c=, =priority= | priority letters                                     |
+| =tags=              | tag capsules (Mac)                                                        |
-| Field | Shows                                                                 |
+=[theme.todo]= colors keywords by name and =[theme.category]= colors categories by name. =agenda-deadline=, =agenda-upcoming=, =agenda-scheduled= and =agenda-scheduled-past= are accepted in a theme but not used.
-|-------+-----------------------------------------------------------------------|
-| =%c=  | The category                                                          |
-| =%t=  | The time of day, or the time range                                    |
-| =%s=  | The leader: =Scheduled:=, =Deadline:=, =In 3 d.:= and so on           |
-| =%e=  | The =Effort= property                                                 |
-| =%l=  | One space per heading level                                           |
-| =%b=  | The outline path above the heading, each title followed by =->=       |
-| =%T=  | The item's last tag, counting inherited tags                          |
-| =%i=  | The category icon; always empty in Orgstar                            |
-Each field takes Org's modifiers: =%-12c= pads to 12 columns on the right (=%12c= on the left); =%-12.6c= limits a category to 5 characters; =%?t= leaves the field out entirely when empty; a punctuation character after the width (=%-12:c=) is added after a non-empty value. When the format contains =%t=, times move out of the heading text into the prefix, as =org-agenda-remove-times-when-in-prefix= does. =%(…)= Lisp forms are accepted but always empty.
-Colors come from the theme keys =agenda-background=, =agenda-date=, =agenda-today=, =agenda-time=, =agenda-category=, =agenda-deadline=, =agenda-upcoming=, =agenda-scheduled= and =agenda-scheduled-past= (see [[file:13-configuration.org][Configuration]]).
 * Acting on entries
-Select a line with the arrow keys or the mouse. These keys work in the agenda window in every keymap preset; they are fixed and are not read from =keymap.toml=.
+Select a line with the mouse, or move the selection with =n= and =p=, =C-n= and =C-p=, or =↓= and =↑=. These keys work in the agenda window in every keymap preset; they are fixed and are not read from =keymap.toml=.
 | Key                     | Does                                                         | Org command                  |
 |-------------------------+--------------------------------------------------------------+------------------------------|
-| =RET= or double click   | Shows the entry in the main window                           | =org-agenda-switch-to=       |
+| =n=, =p=                | Moves to the next or previous line                           | =org-agenda-next-line=/=-previous-line= |
+| =RET=, =TAB= or double click | Shows the entry in the main window; opens a calendar event in Calendar | =org-agenda-switch-to=, =org-agenda-goto= |
+| =SPC=                   | Shows the entry in the main window, keeping the agenda in front | =org-agenda-show-and-scroll-up= |
 | =t= or =C-c C-t=        | Changes the TODO state, as in the editor                     | =org-agenda-todo=            |
 | =+=, =-=                | Raises or lowers the priority                                | =org-agenda-priority-up=/=-down= |
+| =,=                     | Sets the priority                                            | =org-agenda-priority=        |
 | =:= or =C-c C-q=        | Sets tags                                                    | =org-agenda-set-tags=        |
 | =C-c C-s=               | Schedules                                                    | =org-agenda-schedule=        |
 | =C-c C-d=               | Sets a deadline                                              | =org-agenda-deadline=        |
 | =X=                     | Cancels the clock                                            | =org-agenda-clock-cancel=    |
 | =C-c C-w=               | Refiles                                                      | =org-agenda-refile=          |
 | =$=, =C-c $=, =C-c C-x C-s= | Archives                                                 | =org-agenda-archive=         |
+| =k=                     | Captures an entry scheduled on the selected line's day       | =org-agenda-capture=         |
+| =s=                     | Saves every file                                             | =org-save-all-org-buffers=   |
+Without a selected line, =k= captures onto today when today is shown, else onto the first day shown. The + at the right of each day's header captures onto that day; see [[file:08-capture.org][Capture]].
+Right-click a line for Open, Cycle TODO State, Set Priority…, Set Tags…, Schedule…, Set Deadline…, Clock In, Mark or Unmark, and Archive. A calendar event's menu has Show in Calendar.
 =t= follows =org-todo=: with fast-selection keys in your TODO keywords it asks for the state, otherwise it cycles (see [[file:05-todos-and-tags.org][TODOs and tags]]). Questions an action needs, such as a date for =C-c C-s= or a note on a state change, appear in the agenda window. Dates take the same input as in the editor (see [[file:06-dates-and-clocking.org][Dates, scheduling and clocking]]). =S-<right>= and =S-<left>= work only on deadline, scheduled and timestamp lines; they change the timestamp the line comes from.
 | Key | Does                                     | Org command                    |
 |-----+------------------------------------------+--------------------------------|
-| =m= | Marks the selected entry (shown with =›=) | =org-agenda-bulk-mark=        |
+| =m= | Marks the selected entry (shown with a bar at its left) | =org-agenda-bulk-mark= |
 | =u= | Unmarks it                               | =org-agenda-bulk-unmark=       |
 | =U= | Unmarks everything                       | =org-agenda-bulk-unmark-all=   |
 | =B= | Asks for an action on every marked entry | =org-agenda-bulk-action=       |
 Both are in Settings ▸ Agenda. An entry's =APPT_WARNTIME= property, in minutes, overrides the warning time for that entry. If the warning time has already passed but the entry hasn't started, the reminder fires at once.
-The notification's title is the heading; its body is the time, the leader if any, and the category, such as =14:00 · Scheduled: · work=. Clicking it shows the entry in the main window.
+The notification's title is the heading; its body is the time, Org's leader text (=Scheduled:=, =Deadline:=) if any, and the category, such as =14:00 · Scheduled: · work=. Clicking it shows the entry in the main window.
 On the Mac, reminders are updated two seconds after edits stop, when files change, and every hour. At most 64 are set, the earliest first. The agenda's status line says how far ahead they are set, or that notifications are off for Orgstar in System Settings. Turning reminders off removes the pending ones.
 The Agenda tab shows the same views from the same files, using the settings in the synced =config.toml= and the views in =views.toml= (see [[file:14-ios.org][iOS]]). Differences from the Mac:
-- The Views menu lists the built-in views, your saved views, and Tags and Properties…, which asks for a match string. There is no TODO-only match from the menu; use =/!= in the match or a =todo-match= view. Today, Earlier and Later are in the same menu.
+- The Views menu, at the top left, lists the built-in views, your saved views, and Tags and Properties…, which asks for a match string. There is no TODO-only match from the menu; use =/!= in the match or a =todo-match= view.
+- A bar floats at the bottom of the screen with Earlier, Filter, Today, Go to Date, the span and Later. The span menu switches between Day, Week, Month and the configured span (=10 Days= by default). Weeks start on the first day of the week in the device's region settings. In the TODO list and match views the bar has Filter and Agenda, which returns to the day view. Messages show above the bar; tap one to dismiss it.
+- The title names the days shown: =Thu 8 Oct=, =Week of 5 Oct=, =October 2026=, or =5 Oct – 14 Oct=.
+- Day headers read =Today · Thu 8 Oct= or =Fri 9 Oct=, with a + that captures onto that day. The Overdue group stays collapsed or expanded as you left it.
 - Pull down to refresh.
 - The Filter button opens a sheet: type a filter as for =/=, or tap a tag or category to cycle between Keep, Leave out and no filter.
-- Tap an entry to open it. Swipe left on an open TODO to mark it done with the first done keyword of its sequence, as the file defines its keywords: the default keywords from =config.toml=, the file's own =#+TODO= lines, and those of its setup files, with unsaved edits in an open buffer included.
+- Tap an entry to open it. Calendar events don't open.
-- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
+- Swipe left on an open TODO entry for Done, which sets the first done keyword of its sequence, and Next State, which moves to the next keyword. The sequence is the one the file defines: the default keywords from =config.toml=, the file's own =#+TODO= lines, and those of its setup files, with unsaved edits in an open buffer included.
-- There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.
+- Swipe right on a scheduled entry, a deadline, a habit or a TODO entry, when it isn't done, for Tomorrow, Next Week and Pick Date. Tomorrow and Next Week are one day and seven days after today. On a deadline row these move the deadline; on other rows they set the scheduled date. A timed row keeps its times.
+- Touch and hold an entry for TODO State…, Reschedule (Tomorrow, Next Week, Pick Date…), Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
+- Marking an entry done and rescheduling one give haptic feedback.
+- There are no keyboard commands, log mode or bulk marks.
 - Reminders are set while the app is open. iOS allows at most 64 pending notifications and the app can't add more while it isn't running, so the agenda's footer says how far ahead they go and asks you to open Orgstar to set later ones.
+The Today and Up Next widgets show the agenda on the Home Screen and the Lock Screen; see [[file:14-ios.org][iPhone and iPad]].

docs/manual/guide/08-capture.org +18 −1

	@@ -43,6 +43,23 @@ Limits compared with Emacs:
43	- There is no refile from the capture window (=C-c C-w= in an Emacs capture buffer). Capture to an inbox heading and refile from the agenda or the editor.	43	- There is no refile from the capture window (=C-c C-w= in an Emacs capture buffer). Capture to an inbox heading and refile from the agenda or the editor.
44	- The target is not shown while you edit (the capture buffer in Emacs is narrowed to the new entry in the target file).	44	- The target is not shown while you edit (the capture buffer in Emacs is narrowed to the new entry in the target file).
45		45
		46	* Capturing onto an agenda day
		47
		48	The + at the right of a day's header in the agenda, or =k= in the Mac agenda (=org-agenda-capture=), starts a capture for that day; see [[file:07-agenda.org][The agenda]]. Choose a template as usual. The day then stands in for today, as =org-overriding-default-time= makes it do in Org:
		49
		50	- =%t=, =%T=, =%u= and =%U= give that day. The escapes with a time use the current time of day.
		51	- An empty answer to a date prompt (=%^t= and the others) is that day.
		52	- With =datetree = true=, the entry goes under that day in the date tree.
		53
		54	When the filled template is a heading without an active timestamp, Orgstar adds =SCHEDULED:= with that day on the line after the heading, or at the end of the planning line when the template has one:
		55
		56	#+BEGIN_SRC org
		57	,* TODO Call the bank
		58	SCHEDULED: <2026-10-09 Fri>
		59	#+END_SRC
		60
		61	The line is part of the text you edit, so you can change or remove it before filing. A template with an active timestamp of its own, such as =%t= or =%^t=, gets no =SCHEDULED= line. On the Mac, the window's header names the day, as =Capture, scheduled Fri 9 Oct=.
		62
46	* Capture templates	63	* Capture templates
47		64
48	Templates live in =capture.toml= in the configuration folder (=~/.config/orgstar/capture.toml= by default; see [[file:13-configuration.org][Configuration]]). Settings ▸ Capture shows its path. Each template is a =[[template]]= table:	65	Templates live in =capture.toml= in the configuration folder (=~/.config/orgstar/capture.toml= by default; see [[file:13-configuration.org][Configuration]]). Settings ▸ Capture shows its path. Each template is a =[[template]]= table:
	@@ -287,7 +304,7 @@ On the Mac, the action opens Orgstar if it isn't running and waits up to five se
287		304
288	* Capture on iOS	305	* Capture on iOS
289		306
290	The Capture button (a square with a pencil) at the top of the Agenda and Folders tabs opens the capture sheet. The templates come from the =capture.toml= in your synced configuration folder (see [[file:14-ios.org][iOS]]).	307	The Capture button (a square with a pencil) at the top of the Agenda and Folders tabs opens the capture sheet. The + on a day's header in the Agenda tab opens it for that day, as described in [[*Capturing onto an agenda day][Capturing onto an agenda day]]; date prompts then show that day as their default. The templates come from the =capture.toml= in your synced configuration folder (see [[file:14-ios.org][iOS]]).
291		308
292	The sheet works as on the Mac, in a form:	309	The sheet works as on the Mac, in a form:
293		310

docs/manual/guide/13-configuration.org +50 −13

 | Agenda shows N days                 | 1 to 366               | 10           | =org-agenda-span=           |
 | Agenda starts N days before today   | 0 to 14 days before    | 3 days       | =org-agenda-start-day=      |
 | Include files in subfolders         | On or off              | Off          | =agenda-include-subfolders= |
+| Show days without entries           | On or off              | Off          | =org-agenda-show-all-dates= |
+| Show events from Calendar           | On or off              | Off          | =calendar-events=           |
+| A checkbox for each calendar        | On or off              | All on       | =calendar-event-calendars=  |
 | Notify before timed agenda entries  | On or off              | On           | =reminders=                 |
 | N minutes before                    | 0 to 120               | 12           | =appt-message-warning-time= |
 | Ask what to do with idle time while clocked in | On or off   | Off          | =org-clock-idle-time=       |
 An entry's =APPT_WARNTIME= property overrides the lead time. The agenda is covered in [[file:07-agenda.org][The agenda]].
+The calendar checkboxes appear once Show events from Calendar is on and Orgstar may read your calendars; turning the switch on asks for that access. While every calendar is checked, =calendar-event-calendars= is empty, so calendars you add later show too. The last checked calendar can't be unchecked; turn off Show events from Calendar instead.
 Turning on the idle question sets =org-clock-idle-time= to 15 minutes; turning it off sets it to =0=. The minutes stepper is disabled while the question is off. Idle time and the clock history are covered in [[file:06-dates-and-clocking.org][Dates and clocking]].
 ** Capture
 | =tab-bar=                        | View ▸ Show Tab Bar        |
 | =show-markup=                    | View ▸ Show Markup (=⇧⌘M=) |
 | =ignored-folders=                |                            |
+| =org-agenda-skip-scheduled-if-done= |                         |
+| =org-agenda-skip-deadline-if-done=  |                         |
 | =[org-agenda-prefix-format]=     |                            |
 | =theme-file=                     |                            |
 | =display-line-numbers-type=          | boolean | =true=  | Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode.    |
 | =org-agenda-span=                    | integer | =10=    | Days the agenda shows. Mirrors =org-agenda-span=.                                                               |
 | =org-agenda-start-day=               | string  | ="-3d"= | The agenda's first day relative to today, as ="-3d"= or ="+0d"=. Only day offsets are accepted. Mirrors =org-agenda-start-day=. |
+| =org-agenda-show-all-dates=          | boolean | =false= | Show days without entries in the agenda; today always shows. Emacs's default is =t=. Mirrors =org-agenda-show-all-dates=. |
+| =org-agenda-skip-scheduled-if-done=  | boolean | =false= | Leave a done entry's scheduled date out of the agenda, even on its own day. Mirrors =org-agenda-skip-scheduled-if-done=. |
+| =org-agenda-skip-deadline-if-done=   | boolean | =false= | Leave a done entry's deadline out of the agenda, even on its own day. Mirrors =org-agenda-skip-deadline-if-done=. |
 | =appt-message-warning-time=          | integer | =12=    | Minutes of warning before timed entries. An entry's =APPT_WARNTIME= property overrides it. Mirrors =appt-message-warning-time=. |
 | =org-clock-idle-time=                | integer | =0=     | Minutes without keyboard or mouse input, with a clock running, before Orgstar asks what to do with the idle time. =0= never asks (Emacs's =nil=). Mac only. Mirrors =org-clock-idle-time=. |
 | =org-clock-history-length=           | integer | =5=     | How many recently clocked entries Orgstar remembers. Mirrors =org-clock-history-length=.                     |
 | =todo=   | string | =" %i %-12:c"=           | Prefix of lines in the TODO list    |
 | =tags=   | string | =" %i %-12:c"=           | Prefix of tag and property matches  |
-These mirror the entries of =org-agenda-prefix-format=. In the format, =%c= is the category, =%t= the time, =%s= the scheduled or deadline note, =%e= the effort, =%l= the level, =%b= the outline path, =%T= the item's last tag (inherited tags included), and a number such as =%-12= pads. See [[file:07-agenda.org][The agenda]].
+These mirror the entries of =org-agenda-prefix-format=. The agenda's rows don't show a prefix, so the formats don't change how the agenda looks. The one effect left is that a time written in heading text leaves the title when the =agenda= format contains =%t=. See [[file:07-agenda.org][The agenda]].
 ** [theme]
 | =ignored-folders=           | string  | see below     | Folder names never listed or searched, separated by spaces.                            |
 | =agenda-include-subfolders= | boolean | =false=       | The agenda reads org files in subfolders too.                                           |
 | =reminders=                 | boolean | =true=        | Notify before timed entries.                                                            |
+| =calendar-events=           | boolean | =false=       | Show events from Calendar in the agenda, read-only.                                     |
+| =calendar-event-calendars=  | string  | =""=          | The calendars whose events show, by title or identifier, separated by commas; =""= for all. |
 | =global-capture-hotkey=     | boolean | =true=        | =⌃⌥Space= opens Capture from any app.                                                   |
 The default =ignored-folders= is:
 * Themes
-Orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes. You change it by setting colors in =config.toml=, or by keeping a theme in its own file.
+Orgstar has one built-in theme, the default theme, with light and dark colors after GitHub's light and dark themes for text and code. TODO keywords, priorities and the agenda's statuses use the system's red, orange, blue and green, as iOS and macOS show them. You change it by setting colors in =config.toml=, or by keeping a theme in its own file.
 Colors are strings in the form ="#rrggbb"= or ="#rrggbbaa"=. They go in these tables:
 | =[theme.light]= | Sets a color for light appearance only                                |
 | =[theme.dark]= | Sets a color for dark appearance only                                  |
 | =[theme.todo]= | Colors TODO keywords by name, in both appearances, as =org-todo-keyword-faces= |
+| =[theme.category]= | Colors agenda categories by name, in both appearances               |
 #+BEGIN_SRC toml
 [theme]
 [theme.todo]
 WAIT = "#bf8700"
 PROJ = "#8250df"
+[theme.category]
+work = "#0a66d8"
 #+END_SRC
-A keyword without its own color uses =todo= or =done=.
+A keyword without its own color takes its class's color. Case doesn't matter in these lists:
+| Class        | Key              | Keywords                                                                         |
+|--------------+------------------+----------------------------------------------------------------------------------|
+| Under way    | =todo-next=      | =NEXT=, =STRT=, =START=, =STARTED=, =DOING=, =ACTIVE=, =INPROGRESS=, =IN-PROGRESS= |
+| On hold      | =todo-waiting=   | =WAIT=, =WAITING=, =HOLD=, =ONHOLD=, =BLOCKED=, =DEFERRED=, =SOMEDAY=, =MAYBE=   |
+| Cancelled    | =todo-cancelled= | Done keywords =KILL=, =KILLED=, =CANCELLED=, =CANCELED=, =CANCEL=, =SKIPPED=, =SKIP=, =ABORTED=, =NO=, =WONTFIX= |
+| Other open   | =todo=           | Any other keyword that isn't done                                                |
+| Other done   | =done=           | Any other done keyword                                                           |
+The classes color keywords in the agenda and its widgets on both platforms, and in the iOS editor and reader. The Mac editor colors keywords with =todo= and =done= only.
+A category without its own color gets a hue worked out from its name, the same on every run and device, at a lightness that reads on the appearance's background.
 =default-theme.toml= in the configuration folder lists every color key with the default theme's values, light and dark. Settings ▸ Appearance ▸ Show Default Theme opens it. Copy lines from it into =config.toml=; edits to =default-theme.toml= itself are overwritten at the next launch.
 ** Theme files
-To keep a theme in its own file, put it in the configuration folder with the same tables (=[theme]=, =[theme.light]=, =[theme.dark]=, =[theme.todo]=) and name it in =config.toml=:
+To keep a theme in its own file, put it in the configuration folder with the same tables (=[theme]=, =[theme.light]=, =[theme.dark]=, =[theme.todo]=, =[theme.category]=) and name it in =config.toml=:
 #+BEGIN_SRC toml
 [theme]
 | =heading-1= … =heading-7= | headings of that level                                     |
 | =heading-8=             | level 8 and deeper headings                                  |
 | =todo=                  | TODO keywords not yet done                                   |
+| =todo-next=             | keywords of work under way: =NEXT=, =STRT= and the others above |
+| =todo-waiting=          | keywords of work on hold: =WAIT=, =HOLD= and the others above |
 | =done=                  | DONE keywords                                                |
-| =priority=              | =[#A]= cookies                                               |
+| =todo-cancelled=        | done keywords that cancel: =KILL=, =CANCELLED= and the others above |
+| =priority=              | =[#A]= cookies; in the agenda, priorities other than A, B and C |
+| =priority-a=            | agenda: priority A                                           |
+| =priority-b=            | agenda: priority B                                           |
+| =priority-c=            | agenda: priority C                                           |
 | =tags=                  | =:tags:=                                                     |
 | =link=                  | links                                                        |
 | =timestamp=             | timestamps                                                   |
 | =state-normal=          | the NORMAL tag (Doom keys)                                   |
 | =state-insert=          | the INSERT tag                                               |
 | =state-visual=          | the VISUAL and V-LINE tags                                   |
-| =agenda-background=     | the agenda and board                                         |
+| =agenda-background=     | the agenda and board; the iOS widgets                        |
-| =agenda-date=           | agenda day headers                                           |
+| =agenda-date=           | agenda day headers after today                               |
-| =agenda-today=          | today's header and the current time                          |
+| =agenda-today=          | today's header and the now line                              |
-| =agenda-time=           | times and the time grid                                      |
+| =agenda-time=           | times and statuses of agenda rows with the normal status     |
 | =agenda-category=       | categories                                                   |
-| =agenda-deadline=       | deadlines due                                                |
+| =agenda-overdue=        | agenda: the status of entries past their deadline or scheduled date, and the Overdue group |
-| =agenda-upcoming=       | deadlines coming up                                          |
+| =agenda-due-soon=       | agenda: the status of deadlines due today or coming up       |
-| =agenda-scheduled=      | scheduled items                                              |
+| =agenda-event=          | agenda: calendar events whose calendar has no color          |
-| =agenda-scheduled-past= | items scheduled on an earlier day                            |
+| =agenda-deadline=       | accepted, not used                                           |
+| =agenda-upcoming=       | accepted, not used                                           |
+| =agenda-scheduled=      | accepted, not used                                           |
+| =agenda-scheduled-past= | accepted, not used                                           |
 | =habit-clear=           | habit graph: not due yet                                     |
 | =habit-ready=           | habit graph: due                                             |
 | =habit-alert=           | habit graph: due today, last chance                          |

docs/manual/guide/14-ios.org +59 −13

 #+TITLE: iPhone and iPad
-#+DESCRIPTION: The iOS app: folders, reading and editing, search, the agenda, capture, clocking, reminders, export and settings.
+#+DESCRIPTION: The iOS app: folders, reading and editing, search, the agenda, widgets, capture, clocking, reminders, export and settings.
 #+LEDE: Orgstar for iPhone and iPad reads and edits the same org files as the Mac, with the agenda, capture and search.
 * Overview
 ** Themes and display
-The editor and the reader use the theme set in the configuration folder's =config.toml=, stacked as on the Mac: the default theme, then the theme file named by =theme-file=, then the colours in =[theme]=, =[theme.light]=, =[theme.dark]= and =[theme.todo]=. Colours follow the system's light or dark appearance. Problems in the theme show in the Settings tab with the other problems. A change to =config.toml= or the theme file applies as it syncs, to open editors too. See [[file:13-configuration.org][Configuration]] for the colour keys.
+The editor and the reader use the theme set in the configuration folder's =config.toml=, stacked as on the Mac: the default theme, then the theme file named by =theme-file=, then the colours in =[theme]=, =[theme.light]=, =[theme.dark]=, =[theme.todo]= and =[theme.category]=. A TODO keyword without a colour in =[theme.todo]= takes its class's colour: =todo-next= for =NEXT= and =STRT=, =todo-waiting= for =WAIT= and =HOLD=, =todo-cancelled= for =KILL= and =CANCELLED=, and so on (see [[file:13-configuration.org][Configuration]] for the lists). Colours follow the system's light or dark appearance. Problems in the theme show in the Settings tab with the other problems. A change to =config.toml= or the theme file applies as it syncs, to open editors too. See [[file:13-configuration.org][Configuration]] for the colour keys.
 - Font :: =font= when that family is installed on the device, otherwise the system's monospaced font.
 - Size :: =font-size= is the size at the default Dynamic Type setting, 13 pt by default. Text grows and shrinks with the text size chosen in the system Settings app.
 * The agenda
-The Agenda tab shows the agenda over all your folders, with the span and start day from the settings (10 days from 3 days ago by default). Pull down to refresh it.
+The Agenda tab shows the agenda over all your folders, with the span and start day from the settings (10 days from 3 days ago by default). Each day lists its entries in rows: the time or a status such as =Due today= or =3d late= on the left, the category and the keyword above the title. Days without entries are hidden, except today. Today's overdue entries are in a group of their own, and a line marks the current time between timed entries. Pull down to refresh.
-- Views (the calendar icon) :: the built-in views and those in =views.toml=, Tags and Properties… (a match such as =+work-home= or =TODO="WAIT"=), and in the day view, Today, Earlier and Later.
+- Views (top left) :: the built-in views and those in =views.toml=, and Tags and Properties… (a match such as =+work-home= or ~TODO="WAIT"~).
-- Filter :: keep or leave out tags and categories of the entries shown, or type a filter as Org's =/= takes it: =+keep= and =-drop= tags or categories, =<0:30= for effort, =/regexp/=. The status line shows the filter in use.
+- The bar at the bottom :: Earlier, Filter, Today, Go to Date, the span (Day, Week, Month or the configured span) and Later.
-- Tap an entry to read it, at its heading.
+- Filter :: keep or leave out tags and categories of the entries shown, or type a filter as Org's =/= takes it: =+keep= and =-drop= tags or categories, =<0:30= for effort, =/regexp/=. The filter in use shows above the bar.
-- Swipe a TODO entry to the left to mark it done with the first done keyword of its sequence, as the file defines its keywords (with the default keywords, its =#+TODO= lines and its setup files).
+- + on a day's header :: captures an entry scheduled on that day (see [[file:08-capture.org][Capture]]).
-- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
+- Tap :: an entry to read it, at its heading.
+- Swipe left :: on a TODO entry for Done, which sets the first done keyword of its sequence, or Next State.
+- Swipe right :: for Tomorrow, Next Week or Pick Date, which move the entry's scheduled date, or its deadline on a deadline row.
+- Touch and hold :: an entry for TODO State…, Reschedule, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
 Commands from the agenda change the file directly when it isn't open, and through the editor when it is. If the heading changed since the agenda was built, nothing runs.
-See [[file:07-agenda.org][The agenda]] for the views and matches.
+With =calendar-events= on, the agenda also shows events from the Calendar app; see Settings below.
+See [[file:07-agenda.org][The agenda]] for the rows, the views and matches, and the differences from the Mac.
+* Widgets and the Live Activity
+** Widgets
+Orgstar has two widgets. Add them as any widget: touch and hold the Home Screen or the Lock Screen, and choose Orgstar in the widget gallery.
+| Widget | Sizes                                        | Shows                                                                                       |
+|--------+----------------------------------------------+---------------------------------------------------------------------------------------------|
+| Today  | Small, medium and large (Home Screen)        | The date, the count of open entries, and what's left of today: 3 rows (small), 4 rows (medium), or 6 rows and tomorrow's entries (large). Medium and large also count overdue entries. |
+| Up Next | Rectangular, inline and circular (Lock Screen) | The next entry's time or status and title (rectangular, inline), or the count of open entries today (circular, and inline when nothing is left) |
+What's left of today is today's entries and calendar events that aren't done, without timed ones that have ended (or started, when they have no end), followed by the overdue entries. The open count is today's entries not done, overdue ones included, without calendar events. The widgets use the theme's colours for the status, the keyword, the priority and the category.
+Tapping a row in the medium or large Today widget opens that entry; tapping elsewhere opens the agenda. Tapping Up Next opens the next entry, or the agenda when there is none.
+Widgets can't read your folders, so the app writes the next seven days of the agenda (today included) for them to read: while it is open, when files, edits or settings change, when you return to the app, and every hour. Between those times the widgets move on by themselves as timed entries end and at midnight, but they show nothing new until you open Orgstar. Until the app has written the agenda once, they say =Open Orgstar to show your agenda here.= The widgets ignore the agenda's filter and show no days without entries.
+** The clock's Live Activity
+While a clock runs, it shows on the Lock Screen and in the Dynamic Island: the heading, the time so far, and a Clock Out button. Clock Out stops the clock as Clock Out does in the app, and saves the file. Tapping the Live Activity opens the clocked entry.
+The Live Activity starts when you clock in in the app and ends when the clock stops, however it stops. It needs Live Activities allowed for Orgstar in the Settings app (Settings ▸ Orgstar ▸ Live Activities).
+** orgstar:// links
+The widgets and the Live Activity open the app with these links, which also work from Shortcuts, Safari or a note:
+| Link                                   | Opens                                      |
+|----------------------------------------+--------------------------------------------|
+| =orgstar://agenda=                     | The Agenda tab                             |
+| =orgstar://clock=                      | The entry of the running clock             |
+| ~orgstar://entry?path=/path/file.org&offset=N~ | The file in the reader, at offset N |
 * Capture
 * Clocking
-Clock in from the editor (More ▸ Clock In, or Clock In in Commands) or from an agenda entry's menu. While a clock runs, a bar above the tab bar shows the entry and the time so far as =H:MM=, updated every 30 seconds. Tap the bar for:
+Clock in from the editor (More ▸ Clock In, or Clock In in Commands) or from an agenda entry's menu. While a clock runs, a bar above the tab bar shows the entry and the time so far as =H:MM=, updated every 30 seconds, and a Live Activity shows it on the Lock Screen and in the Dynamic Island (see [[*Widgets and the Live Activity][Widgets and the Live Activity]]). Tap the bar for:
 - Clock Out
 - Cancel Clock
 * Settings
-The iOS app has no settings of its own. It reads them from a configuration folder: a folder holding =config.toml= and =capture.toml=, such as a copy of the Mac's =~/.config/orgstar= synced through iCloud Drive or another app.
+The iOS app reads its settings from a configuration folder: a folder holding =config.toml= and =capture.toml=, such as a copy of the Mac's =~/.config/orgstar= synced through iCloud Drive or another app.
 1. Open the Settings tab.
 2. Tap Choose Folder… and choose the folder.
 Stop Using This Folder returns every setting to its default.
+The Calendar section is the one place the app changes a setting itself:
+- Show Calendar Events :: turns on =calendar-events=, and asks for access to your calendars. iOS asks for full access, as Calendar has no read-only level; Orgstar only reads. While access is missing the section shows Allow Access to Calendars…; if you declined, allow it in the Settings app under Privacy & Security ▸ Calendars.
+- The calendars :: tap one to show or hide its events (=calendar-event-calendars=). With every calendar checked the setting is empty, so calendars added later show too.
+These write =config.toml= in the configuration folder, as the Mac's Settings window does, so the Mac sees the change too. Without a configuration folder they are kept on the device.
 The In use section shows the TODO keywords, the agenda span and start (for example =10 days, starting 3 days before today=), the reminder lead time, the capture template keys, the theme (=Default=, or the theme file's name), and the font with its size. When =font= names a family that isn't installed on the device, Font shows the system's font with a note, as =System monospaced, 13 pt (JetBrains Mono isn't installed)=.
 These settings from =config.toml= apply on iOS:
 - =org-tags-column=, =org-insert-heading-respect-content=, =org-M-RET-may-split-line=, =fill-column=
 - =org-hide-emphasis-markers= and =org-pretty-entities=, for what hidden markup shows and for how tag and table alignment and filling measure text, as on the Mac
 - =show-markup=, =org-startup-indented=, =org-hide-leading-stars=, =org-startup-with-inline-images=, =org-startup-align-all-tables=, =org-startup-truncated=, =org-cycle-hide-drawer-startup=, =org-cycle-hide-block-startup=
-- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=
+- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=, =[theme.category]=
 - =org-log-done=, =org-log-reschedule=, =org-log-redeadline=, =org-log-into-drawer=
 - =org-use-speed-commands=, with a hardware keyboard
 - =electric-pair-mode=, =spell-check=
-- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=
+- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=, =org-agenda-show-all-dates=, =org-agenda-skip-scheduled-if-done=, =org-agenda-skip-deadline-if-done=
+- =calendar-events=, =calendar-event-calendars=
 - =reminders=, =appt-message-warning-time=
 - =org-clock-history-length=

docs/manual/guide/15-alongside-emacs.org +10

 | =electric-pair-mode=                 | =true=                              | off                             |
 | =org-agenda-span=                    | 10 days                             | a week                          |
 | =org-agenda-start-day=               | ="-3d"=                             | today                           |
+| =org-agenda-show-all-dates=          | =false=                             | =t=                             |
 =org-hide-emphasis-markers= and =org-pretty-entities= matter for files you also edit in Emacs: Orgstar aligns tags and tables, and fills paragraphs, by the width text has on screen in your Emacs. If they don't match your Emacs, tags and tables that Orgstar aligns look misaligned in Emacs.
 These behave as Emacs's defaults and can't be changed: =org-log-repeat= is =time=, fast TODO selection is on when keywords have keys, priorities are =A= to =C= with =B= as default unless =#+PRIORITIES= says otherwise, and =org-use-sub-superscripts= is ={}= for display (only =x_{1}= and =x^{2}= are lowered and raised).
+** How the agenda looks
+The agenda selects the same entries as Org's, but shows them its own way (see [[file:07-agenda.org][The agenda]]):
+- Rows have their own layout: the time or a status such as =Due in 2d= on the left, the category above the title, and the keyword and priority as badges. =org-agenda-prefix-format= doesn't change it; only =%t= in its =agenda= entry still decides whether a time in the heading text leaves the title.
+- Days without entries are hidden unless =org-agenda-show-all-dates= is =true=.
+- Today's past deadlines and past scheduled entries are gathered in an Overdue group, oldest first, rather than sorted among today's entries by urgency.
+- The time grid isn't shown. The now line is, between today's timed entries.
 ** Known differences from Emacs Org
 Orgstar refuses some things with a message rather than doing something different from Emacs. These are the ones found in the current version.

docs/manual/install.org +3 −3

	@@ -35,13 +35,13 @@ The iOS app (iOS 26 or later) is built with Xcode from =ios/Orgstar.xcodeproj=:
35		35
36	1. Open =ios/Orgstar.xcodeproj=.	36	1. Open =ios/Orgstar.xcodeproj=.
37	2. Select the Orgstar iOS target, then Signing & Capabilities, and choose your team.	37	2. Select the Orgstar iOS target, then Signing & Capabilities, and choose your team.
38	Change the bundle identifiers (=sh.krz.orgstar= and the two extensions' =.share= and	38	Change the bundle identifiers (=sh.krz.orgstar= and the three extensions' =.share=,
39	=.quicklook=) and the App Group (=group.sh.krz.orgstar=) to ones your team can register.	39	=.quicklook= and =.widgets=) and the App Group (=group.sh.krz.orgstar=) to ones your team can register.
40	3. Choose your iPhone or iPad (or a Simulator) as the destination and Run (=⌘R=).	40	3. Choose your iPhone or iPad (or a Simulator) as the destination and Run (=⌘R=).
41		41
42	On a device, Developer Mode must be on (Settings ▸ Privacy & Security ▸ Developer Mode).	42	On a device, Developer Mode must be on (Settings ▸ Privacy & Security ▸ Developer Mode).
43		43
44	For the Simulator without opening Xcode:	44	For the Simulator without opening Xcode (this build has no widgets):
45		45
46	#+BEGIN_SRC sh	46	#+BEGIN_SRC sh
47	scripts/build-ios-app.sh	47	scripts/build-ios-app.sh

Commit 469ca131b7

Commit `469ca131b7`