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

		@@ -656,9 +656,16 @@ The Agenda window has its own keys, modelled on =org-agenda-mode=, which =keymap
656	656
657	657	\| Key \| Does \|
658	658	\|-+-\|
659		\| =RET= \| Opens the selected entry. \|
	659	\| =n=, =p=, =C-n=, =C-p=, =↓=, =↑= \| Next or previous line. \|
	660	\| =RET=, =TAB= \| Opens the selected entry, or a calendar event in Calendar. \|
	661	\| =SPC= \| Shows the selected entry in the main window, keeping the agenda in front. \|
660	662	\| =f=, =b= \| Next or previous span (agenda views). \|
661	663	\| =.= \| Back to today (agenda views). \|
	664	\| =j= \| Go to a date (agenda views). \|
	665	\| =v d=, =v w=, =v m= \| Day, week or month view (agenda views). \|
	666	\| =d=, =w= \| Day or week view (agenda views). \|
	667	\| =k= \| Capture an entry scheduled on the selected line's day (agenda views). \|
	668	\| =s= \| Save every file. \|
662	669	\| =/= \| Filter by tags, categories, effort and regexp (=+cat-tag<0:10-/regexp/=). \|
663	670	\| =\= \| Tag filter (=+tag-tag=). \|
664	671	\| ~=~ \| Regexp filter (=-re= drops matches). \|
		@@ -669,6 +676,7 @@ The Agenda window has its own keys, modelled on =org-agenda-mode=, which =keymap
669	676	\| =g=, =r= \| Rebuilds the views. \|
670	677	\| =t= \| Cycle TODO State. \|
671	678	\| =+=, =-= \| Raise or lower priority. \|
	679	\| =,= \| Set priority. \|
672	680	\| =:= \| Set tags. \|
673	681	\| =S-<right>=, =S-<left>= \| Moves the entry's timestamp a day later or earlier. \|
674	682	\| =I=, =O=, =X= \| Clock in, clock out, cancel the clock. \|

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

		@@ -1,5 +1,5 @@
1	1	#+TITLE: The agenda
2		#+DESCRIPTION: The agenda window, the TODO list, tag and property matches, saved views, filters, reminders and the board.
	2	#+DESCRIPTION: The agenda window, its rows, calendar events, the TODO list, tag and property matches, saved views, filters, reminders and the board.
3	3	#+LEDE: The agenda collects dated entries and TODO items from your agenda files into one list you can act on.
4	4
5	5	* Opening the agenda
		@@ -43,70 +43,153 @@ An entry's category is the nearest =CATEGORY= property on it or an ancestor, els
43	43
44	44	If no agenda file exists, the window says so.
45	45
46		* The day and week view
	46	* The day, week and month view
47	47
48		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).
	48	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.
49	49
50	50	\| Setting \| Default \| =config.toml= \| Range in Settings \|
51	51	\|------------------------------+---------+-----------------------------------+-------------------\|
52	52	\| Days shown \| 10 \| =org-agenda-span = 10= \| 1 to 366 \|
53	53	\| First day, relative to today \| 3 days before \| =org-agenda-start-day = "-3d"= \| 0 to 14 days before \|
54	54
55		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.
	55	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"=.
	56
	57	** Day, week and month
	58
	59	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.
	60
	61	To return to the configured span, choose Agenda from the view menu.
	62
	63	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=.
56	64
57	65	** Moving through days
58	66
59		\| Key \| Toolbar \| Does \| Org command \|
60		\|-----+-----------+-----------------------------------+--------------------------\|
61		\| =f= \| Later (›) \| Moves forward by a whole span \| =org-agenda-later= \|
62		\| =b= \| Earlier (‹) \| Moves back by a whole span \| =org-agenda-earlier= \|
63		\| =.= \| Today \| Returns to the span around today \| =org-agenda-goto-today= \|
64		\| =g=, =r= \| \| Refreshes, and reloads =views.toml= \| =org-agenda-redo= \|
	67	\| Key \| Toolbar \| Does \| Org command \|
	68	\|----------+----------------------+-------------------------------------------------------------------------------+-------------------------\|
	69	\| =f= \| Later (›) \| Moves forward by the days shown; in the month view, to the next month \| =org-agenda-later= \|
	70	\| =b= \| Earlier (‹) \| Moves back by the days shown; in the month view, to the month before \| =org-agenda-earlier= \|
	71	\| =.= \| Today \| Returns to the days around today, keeping a day, week or month view \| =org-agenda-goto-today= \|
	72	\| =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= \|
	73	\| =g=, =r= \| \| Refreshes, and reloads =views.toml= \| =org-agenda-redo= \|
65	74
66		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.
	75	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.
67	76
68	77	** What appears on each day
69	78
70		The entries follow =org-agenda-get-day-entries= with Org's default entry types, in the formats Org prints.
	79	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:
71	80
72		\| Entry \| Where it appears \| Leader \|
	81	\| Entry \| Where it appears \| Left column \|
73	82	\|-----------------------------------------+-------------------------------------------------------------------------------------------------------+--------------------------------\|
74		\| =DEADLINE= on that day \| On its day \| =Deadline:= \|
75		\| =DEADLINE= in the future \| On today, from the warning period before it \| =In 3 d.:= \|
76		\| =DEADLINE= in the past, not done \| On today \| =2 d. ago:= \|
77		\| =SCHEDULED= on that day \| On its day \| =Scheduled:= \|
78		\| =SCHEDULED= in the past, not done \| On today \| =Sched. 3x:= \|
79		\| Active timestamp =<2026-10-05 Mon>= \| On its day; also in property drawers \| none \|
80		\| Repeating timestamp =<… +1w>= \| On each occurrence within the span \| none \|
81		\| Date range =<…>--<…>= \| On every day of the range \| =(2/5):= (day 2 of 5) \|
82		\| Diary sexp =%%(…)= line or =<%%(…)>= \| On each day the sexp applies; see [[*Diary sexps][Diary sexps]] \| none \|
83		\| Habit (=STYLE: habit=) \| On today only, while not done; see [[*Habits][Habits]] \| none, with a consistency graph \|
	83	\| =DEADLINE= on that day \| On its day \| =Due today= on today, =Due= on other days \|
	84	\| =DEADLINE= in the future \| On today, from the warning period before it \| =Due in 3d= \|
	85	\| =DEADLINE= in the past, not done \| On today, in the Overdue group \| =2d late= \|
	86	\| =SCHEDULED= on that day \| On its day \| =Scheduled= \|
	87	\| =SCHEDULED= in the past, not done \| On today, in the Overdue group \| =3d ago= \|
	88	\| Active timestamp =<2026-10-05 Mon>= \| On its day; also in property drawers \| =All day= \|
	89	\| Repeating timestamp =<… +1w>= \| On each occurrence within the span \| =All day= \|
	90	\| Date range =<…>--<…>= \| On every day of the range \| =Day 2/5= (day 2 of 5) \|
	91	\| Diary sexp =%%(…)= line or =<%%(…)>= \| On each day the sexp applies; see [[*Diary sexps][Diary sexps]] \| =All day= \|
	92	\| Habit (=STYLE: habit=) \| On today only, while not done; see [[*Habits][Habits]] \| =Habit=, with a consistency graph \|
	93
	94	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.
84	95
85	96	Details:
86	97
87	98	- 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.
88	99	- A =-Nd= cookie on a =SCHEDULED= timestamp delays it: the entry first shows N days after the scheduled date.
89	100	- Repeaters on =SCHEDULED= and =DEADLINE= timestamps (=+1w=, =++1w=, =.+1d=) make the entry show on the next occurrence on future days, as in Org.
90		- A done entry shows only on the day of its deadline or scheduled date, not as overdue.
	101	- 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.
91	102	- Inactive timestamps (=[…]=) never appear, except in log mode.
92	103	- Ranges in comment lines and inside source blocks are ignored, as in Org.
93	104
94		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.
	105	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=.
	106
	107	** Today, overdue entries and empty days
	108
	109	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=:
95	110
96		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=.
	111	#+BEGIN_SRC toml
	112	org-agenda-show-all-dates = true
	113	#+END_SRC
	114
	115	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.
	116
	117	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.
97	118
98	119	** Sorting
99	120
100		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.
	121	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.
101	122
102	123	** Log mode
103	124
104	125	Press =l= to turn log mode (=org-agenda-log-mode=) on or off. Each day then also shows:
105	126
106		- =Closed:= entries whose =CLOSED:= timestamp is on that day;
107		- =Clocked: (1:30)= for each =CLOCK:= line that starts on that day, with the clock's range and duration.
	127	- =Closed= entries whose =CLOSED:= timestamp is on that day;
	128	- =Clocked= entries for each =CLOCK:= line that starts on that day, with the clock's start and end times in the left column.
	129
	130	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.
	131
	132	* Rows
108	133
109		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.
	134	Each row shows, from left to right:
	135
	136	- 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.
	137	- The category, with a colored dot, above the title. For a calendar event this is the calendar's name, with the event's location.
	138	- 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.
	139	- 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.
	140	- The habit's consistency graph, for habits.
	141	- The TODO keyword as a colored badge, and the priority as a colored letter in a circle.
	142
	143	The status sets the color of the left column:
	144
	145	\| Status \| When \| Theme key \|
	146	\|----------+-------------------------------------------------------------------------+-------------------\|
	147	\| Overdue \| Not done, with a deadline or scheduled date before today \| =agenda-overdue= \|
	148	\| Due soon \| Not done, a deadline listed on today: due today or within its warning \| =agenda-due-soon= \|
	149	\| Done \| A done keyword \| =done= \|
	150	\| Normal \| Everything else \| =agenda-time= \|
	151
	152	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.
	153
	154	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.
	155
	156	* Calendar events
	157
	158	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:
	159
	160	- On the Mac, turn on Settings ▸ Agenda ▸ Show events from Calendar, and check the calendars to show.
	161	- On iOS, turn on Settings ▸ Calendar ▸ Show Calendar Events, and tap the calendars to show.
	162	- Or set the keys in =config.toml=:
	163
	164	#+BEGIN_SRC toml
	165	[orgstar]
	166	calendar-events = true
	167	calendar-event-calendars = "Work, Family"
	168	#+END_SRC
	169
	170	=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.
	171
	172	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.
	173
	174	Events appear only in the day, week and month view:
	175
	176	- All-day events come first on their day, as calendars show them.
	177	- Timed events go among the timed entries by start time, after entries with the same start and before untimed entries and habits.
	178	- 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.
	179	- The dot and the icon take the calendar's color, or =agenda-event= when the calendar has none.
	180	- Filters don't hide events.
	181
	182	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.
	183
	184	* Done keywords the agenda doesn't know
	185
	186	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 ~\|~:
	187
	188	#+BEGIN_SRC toml
	189	org-todo-keywords = "TODO(t) PROJ(p) LOOP(r) STRT(s) WAIT(w) HOLD(h) IDEA(i) \| DONE(d) KILL(k) SKIPPED"
	190	#+END_SRC
	191
	192	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.
110	193
111	194	* Diary sexps
112	195
		@@ -160,7 +243,7 @@ SCHEDULED: <2026-10-05 Mon .+2d/4d>
160	243
161	244	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.
162	245
163		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:
	246	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:
164	247
165	248	\| Color \| Meaning \| Theme key \|
166	249	\|--------+--------------------------------------------+-----------------\|
		@@ -169,7 +252,7 @@ A habit appears only on today's agenda and not once it is done for the day. Its
169	252	\| Yellow \| Last day of the interval \| =habit-alert= \|
170	253	\| Red \| Overdue \| =habit-overdue= \|
171	254
172		Future days use lighter shades. Hover a cell to see its date. Habits sort after other entries.
	255	Future days use lighter shades. On the Mac, hover a cell to see its date. Habits sort after other entries.
173	256
174	257	* The TODO list
175	258
		@@ -177,6 +260,8 @@ The built-in view TODO List is =org-todo-list=: every heading with a TODO keywor
177	260
178	261	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.
179	262
	263	The TODO list and the match views use the same rows as the day view (see [[*Rows][Rows]]), without the left column.
	264
180	265	* Tag and property matches
181	266
182	267	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.
		@@ -300,7 +385,9 @@ Not supported: block agendas (several views in one), per-view settings such as =
300	385
301	386	* Filters
302	387
303		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: …=.
	388	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: …=.
	389
	390	The Filter button in the toolbar asks for a combined filter, as =/= does; its menu has each of the filters below and Remove Filters.
304	391
305	392	\| Key \| Does \| Org command \|
306	393	\|------+---------------------------------------------------------------+-----------------------------------\|
		@@ -330,45 +417,40 @@ The =/= prompt starts with the whole current filter written in this form, every
330	417
331	418	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=.
332	419
333		* The prefix and line layout
	420	* Prefix format and colors
334	421
335		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.
	422	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.
336	423
337		To change what comes before the heading, set =org-agenda-prefix-format= in =config.toml=:
338
339		#+BEGIN_SRC toml
340		[org-agenda-prefix-format]
341		agenda = " %i %-12:c%?-12t% s"
342		todo = " %i %-12:c"
343		tags = " %i %-12:c"
344		#+END_SRC
	424	The agenda's colors come from these theme keys (see [[file:13-configuration.org][Configuration]]):
345	425
346		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.
	426	\| Key \| Colors \|
	427	\|---------------------+---------------------------------------------------------------------------\|
	428	\| =agenda-background= \| the Mac window's background, and the iOS widgets' background \|
	429	\| =agenda-date= \| headers of days after today (Mac) \|
	430	\| =agenda-today= \| today's header, the now line, and on iOS the widgets' date \|
	431	\| =agenda-time= \| the left column of rows with the normal status \|
	432	\| =agenda-overdue= \| the left column of overdue rows, and the Overdue group's header \|
	433	\| =agenda-due-soon= \| the left column of deadlines due today or coming up \|
	434	\| =agenda-event= \| calendar events whose calendar has no color \|
	435	\| =agenda-category= \| category names (Mac) \|
	436	\| =todo=, =todo-next=, =todo-waiting=, =done=, =todo-cancelled= \| TODO keyword badges, by class \|
	437	\| =priority-a=, =priority-b=, =priority-c=, =priority= \| priority letters \|
	438	\| =tags= \| tag capsules (Mac) \|
347	439
348		\| Field \| Shows \|
349		\|-------+-----------------------------------------------------------------------\|
350		\| =%c= \| The category \|
351		\| =%t= \| The time of day, or the time range \|
352		\| =%s= \| The leader: =Scheduled:=, =Deadline:=, =In 3 d.:= and so on \|
353		\| =%e= \| The =Effort= property \|
354		\| =%l= \| One space per heading level \|
355		\| =%b= \| The outline path above the heading, each title followed by =->= \|
356		\| =%T= \| The item's last tag, counting inherited tags \|
357		\| =%i= \| The category icon; always empty in Orgstar \|
358
359		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.
360
361		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]]).
	440	=[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.
362	441
363	442	* Acting on entries
364	443
365		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=.
	444	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=.
366	445
367	446	\| Key \| Does \| Org command \|
368	447	\|-------------------------+--------------------------------------------------------------+------------------------------\|
369		\| =RET= or double click \| Shows the entry in the main window \| =org-agenda-switch-to= \|
	448	\| =n=, =p= \| Moves to the next or previous line \| =org-agenda-next-line=/=-previous-line= \|
	449	\| =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= \|
	450	\| =SPC= \| Shows the entry in the main window, keeping the agenda in front \| =org-agenda-show-and-scroll-up= \|
370	451	\| =t= or =C-c C-t= \| Changes the TODO state, as in the editor \| =org-agenda-todo= \|
371	452	\| =+=, =-= \| Raises or lowers the priority \| =org-agenda-priority-up=/=-down= \|
	453	\| =,= \| Sets the priority \| =org-agenda-priority= \|
372	454	\| =:= or =C-c C-q= \| Sets tags \| =org-agenda-set-tags= \|
373	455	\| =C-c C-s= \| Schedules \| =org-agenda-schedule= \|
374	456	\| =C-c C-d= \| Sets a deadline \| =org-agenda-deadline= \|
		@@ -378,6 +460,12 @@ Select a line with the arrow keys or the mouse. These keys work in the agenda wi
378	460	\| =X= \| Cancels the clock \| =org-agenda-clock-cancel= \|
379	461	\| =C-c C-w= \| Refiles \| =org-agenda-refile= \|
380	462	\| =$=, =C-c $=, =C-c C-x C-s= \| Archives \| =org-agenda-archive= \|
	463	\| =k= \| Captures an entry scheduled on the selected line's day \| =org-agenda-capture= \|
	464	\| =s= \| Saves every file \| =org-save-all-org-buffers= \|
	465
	466	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]].
	467
	468	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.
381	469
382	470	=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.
383	471
		@@ -391,7 +479,7 @@ Each action finds the entry again by its heading line before it changes anything
391	479
392	480	\| Key \| Does \| Org command \|
393	481	\|-----+------------------------------------------+--------------------------------\|
394		\| =m= \| Marks the selected entry (shown with =›=) \| =org-agenda-bulk-mark= \|
	482	\| =m= \| Marks the selected entry (shown with a bar at its left) \| =org-agenda-bulk-mark= \|
395	483	\| =u= \| Unmarks it \| =org-agenda-bulk-unmark= \|
396	484	\| =U= \| Unmarks everything \| =org-agenda-bulk-unmark-all= \|
397	485	\| =B= \| Asks for an action on every marked entry \| =org-agenda-bulk-action= \|
		@@ -409,7 +497,7 @@ Orgstar can post a notification before each timed entry, as =org-agenda-to-appt=
409	497
410	498	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.
411	499
412		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.
	500	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.
413	501
414	502	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.
415	503
		@@ -441,10 +529,18 @@ The board is not available on iOS.
441	529
442	530	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:
443	531
444		- 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.
	532	- 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.
	533	- 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.
	534	- The title names the days shown: =Thu 8 Oct=, =Week of 5 Oct=, =October 2026=, or =5 Oct – 14 Oct=.
	535	- 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.
445	536	- Pull down to refresh.
446	537	- 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.
447		- 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.
448		- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
449		- There are no keyboard commands, time grid lines, habit graphs, log mode, bulk marks or custom prefix formats.
	538	- Tap an entry to open it. Calendar events don't open.
	539	- 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.
	540	- 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.
	541	- Touch and hold an entry for TODO State…, Reschedule (Tomorrow, Next Week, Pick Date…), Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile… and Archive….
	542	- Marking an entry done and rescheduling one give haptic feedback.
	543	- There are no keyboard commands, log mode or bulk marks.
450	544	- 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.
	545
	546	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	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	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	63	* Capture templates
47	64
48	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	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	309	The sheet works as on the Mac, in a form:
293	310

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

		@@ -104,6 +104,9 @@ See Themes and Fonts below.
104	104	\| Agenda shows N days \| 1 to 366 \| 10 \| =org-agenda-span= \|
105	105	\| Agenda starts N days before today \| 0 to 14 days before \| 3 days \| =org-agenda-start-day= \|
106	106	\| Include files in subfolders \| On or off \| Off \| =agenda-include-subfolders= \|
	107	\| Show days without entries \| On or off \| Off \| =org-agenda-show-all-dates= \|
	108	\| Show events from Calendar \| On or off \| Off \| =calendar-events= \|
	109	\| A checkbox for each calendar \| On or off \| All on \| =calendar-event-calendars= \|
107	110	\| Notify before timed agenda entries \| On or off \| On \| =reminders= \|
108	111	\| N minutes before \| 0 to 120 \| 12 \| =appt-message-warning-time= \|
109	112	\| Ask what to do with idle time while clocked in \| On or off \| Off \| =org-clock-idle-time= \|
		@@ -112,6 +115,8 @@ See Themes and Fonts below.
112	115
113	116	An entry's =APPT_WARNTIME= property overrides the lead time. The agenda is covered in [[file:07-agenda.org][The agenda]].
114	117
	118	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.
	119
115	120	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]].
116	121
117	122	** Capture
		@@ -145,6 +150,8 @@ These settings have no control in the Settings window. Some are in the View menu
145	150	\| =tab-bar= \| View ▸ Show Tab Bar \|
146	151	\| =show-markup= \| View ▸ Show Markup (=⇧⌘M=) \|
147	152	\| =ignored-folders= \| \|
	153	\| =org-agenda-skip-scheduled-if-done= \| \|
	154	\| =org-agenda-skip-deadline-if-done= \| \|
148	155	\| =[org-agenda-prefix-format]= \| \|
149	156	\| =theme-file= \| \|
150	157
		@@ -183,6 +190,9 @@ A key you remove from the file goes back to its default. A key that isn't in the
183	190	\| =display-line-numbers-type= \| boolean \| =true= \| Line numbers in the editor's gutter. Orgstar numbers lines absolutely; there is no relative or visual mode. \|
184	191	\| =org-agenda-span= \| integer \| =10= \| Days the agenda shows. Mirrors =org-agenda-span=. \|
185	192	\| =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=. \|
	193	\| =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=. \|
	194	\| =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=. \|
	195	\| =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=. \|
186	196	\| =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=. \|
187	197	\| =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=. \|
188	198	\| =org-clock-history-length= \| integer \| =5= \| How many recently clocked entries Orgstar remembers. Mirrors =org-clock-history-length=. \|
		@@ -203,7 +213,7 @@ The startup settings (=org-startup-*=, =org-hide-leading-stars=, =org-cycle-hide
203	213	\| =todo= \| string \| =" %i %-12:c"= \| Prefix of lines in the TODO list \|
204	214	\| =tags= \| string \| =" %i %-12:c"= \| Prefix of tag and property matches \|
205	215
206		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]].
	216	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]].
207	217
208	218	** [theme]
209	219
		@@ -230,6 +240,8 @@ Any other key in =[theme]= is a color; see Themes below.
230	240	\| =ignored-folders= \| string \| see below \| Folder names never listed or searched, separated by spaces. \|
231	241	\| =agenda-include-subfolders= \| boolean \| =false= \| The agenda reads org files in subfolders too. \|
232	242	\| =reminders= \| boolean \| =true= \| Notify before timed entries. \|
	243	\| =calendar-events= \| boolean \| =false= \| Show events from Calendar in the agenda, read-only. \|
	244	\| =calendar-event-calendars= \| string \| =""= \| The calendars whose events show, by title or identifier, separated by commas; =""= for all. \|
233	245	\| =global-capture-hotkey= \| boolean \| =true= \| =⌃⌥Space= opens Capture from any app. \|
234	246
235	247	The default =ignored-folders= is:
		@@ -443,7 +455,7 @@ Key bindings are imported when the command is one Orgstar has a counterpart for,
443	455
444	456	* Themes
445	457
446		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.
	458	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.
447	459
448	460	Colors are strings in the form ="#rrggbb"= or ="#rrggbbaa"=. They go in these tables:
449	461
		@@ -453,6 +465,7 @@ Colors are strings in the form ="#rrggbb"= or ="#rrggbbaa"=. They go in these ta
453	465	\| =[theme.light]= \| Sets a color for light appearance only \|
454	466	\| =[theme.dark]= \| Sets a color for dark appearance only \|
455	467	\| =[theme.todo]= \| Colors TODO keywords by name, in both appearances, as =org-todo-keyword-faces= \|
	468	\| =[theme.category]= \| Colors agenda categories by name, in both appearances \|
456	469
457	470	#+BEGIN_SRC toml
458	471	[theme]
		@@ -465,15 +478,30 @@ foreground = "#d4d4d4"
465	478	[theme.todo]
466	479	WAIT = "#bf8700"
467	480	PROJ = "#8250df"
	481
	482	[theme.category]
	483	work = "#0a66d8"
468	484	#+END_SRC
469	485
470		A keyword without its own color uses =todo= or =done=.
	486	A keyword without its own color takes its class's color. Case doesn't matter in these lists:
	487
	488	\| Class \| Key \| Keywords \|
	489	\|--------------+------------------+----------------------------------------------------------------------------------\|
	490	\| Under way \| =todo-next= \| =NEXT=, =STRT=, =START=, =STARTED=, =DOING=, =ACTIVE=, =INPROGRESS=, =IN-PROGRESS= \|
	491	\| On hold \| =todo-waiting= \| =WAIT=, =WAITING=, =HOLD=, =ONHOLD=, =BLOCKED=, =DEFERRED=, =SOMEDAY=, =MAYBE= \|
	492	\| Cancelled \| =todo-cancelled= \| Done keywords =KILL=, =KILLED=, =CANCELLED=, =CANCELED=, =CANCEL=, =SKIPPED=, =SKIP=, =ABORTED=, =NO=, =WONTFIX= \|
	493	\| Other open \| =todo= \| Any other keyword that isn't done \|
	494	\| Other done \| =done= \| Any other done keyword \|
	495
	496	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.
	497
	498	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.
471	499
472	500	=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.
473	501
474	502	** Theme files
475	503
476		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=:
	504	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=:
477	505
478	506	#+BEGIN_SRC toml
479	507	[theme]
		@@ -493,8 +521,14 @@ The colors stack in this order, each over the one before: the default theme, the
493	521	\| =heading-1= … =heading-7= \| headings of that level \|
494	522	\| =heading-8= \| level 8 and deeper headings \|
495	523	\| =todo= \| TODO keywords not yet done \|
	524	\| =todo-next= \| keywords of work under way: =NEXT=, =STRT= and the others above \|
	525	\| =todo-waiting= \| keywords of work on hold: =WAIT=, =HOLD= and the others above \|
496	526	\| =done= \| DONE keywords \|
497		\| =priority= \| =[#A]= cookies \|
	527	\| =todo-cancelled= \| done keywords that cancel: =KILL=, =CANCELLED= and the others above \|
	528	\| =priority= \| =[#A]= cookies; in the agenda, priorities other than A, B and C \|
	529	\| =priority-a= \| agenda: priority A \|
	530	\| =priority-b= \| agenda: priority B \|
	531	\| =priority-c= \| agenda: priority C \|
498	532	\| =tags= \| =:tags:= \|
499	533	\| =link= \| links \|
500	534	\| =timestamp= \| timestamps \|
		@@ -528,15 +562,18 @@ The colors stack in this order, each over the one before: the default theme, the
528	562	\| =state-normal= \| the NORMAL tag (Doom keys) \|
529	563	\| =state-insert= \| the INSERT tag \|
530	564	\| =state-visual= \| the VISUAL and V-LINE tags \|
531		\| =agenda-background= \| the agenda and board \|
532		\| =agenda-date= \| agenda day headers \|
533		\| =agenda-today= \| today's header and the current time \|
534		\| =agenda-time= \| times and the time grid \|
	565	\| =agenda-background= \| the agenda and board; the iOS widgets \|
	566	\| =agenda-date= \| agenda day headers after today \|
	567	\| =agenda-today= \| today's header and the now line \|
	568	\| =agenda-time= \| times and statuses of agenda rows with the normal status \|
535	569	\| =agenda-category= \| categories \|
536		\| =agenda-deadline= \| deadlines due \|
537		\| =agenda-upcoming= \| deadlines coming up \|
538		\| =agenda-scheduled= \| scheduled items \|
539		\| =agenda-scheduled-past= \| items scheduled on an earlier day \|
	570	\| =agenda-overdue= \| agenda: the status of entries past their deadline or scheduled date, and the Overdue group \|
	571	\| =agenda-due-soon= \| agenda: the status of deadlines due today or coming up \|
	572	\| =agenda-event= \| agenda: calendar events whose calendar has no color \|
	573	\| =agenda-deadline= \| accepted, not used \|
	574	\| =agenda-upcoming= \| accepted, not used \|
	575	\| =agenda-scheduled= \| accepted, not used \|
	576	\| =agenda-scheduled-past= \| accepted, not used \|
540	577	\| =habit-clear= \| habit graph: not due yet \|
541	578	\| =habit-ready= \| habit graph: due \|
542	579	\| =habit-alert= \| habit graph: due today, last chance \|

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

		@@ -1,5 +1,5 @@
1	1	#+TITLE: iPhone and iPad
2		#+DESCRIPTION: The iOS app: folders, reading and editing, search, the agenda, capture, clocking, reminders, export and settings.
	2	#+DESCRIPTION: The iOS app: folders, reading and editing, search, the agenda, widgets, capture, clocking, reminders, export and settings.
3	3	#+LEDE: Orgstar for iPhone and iPad reads and edits the same org files as the Mac, with the agenda, capture and search.
4	4
5	5	* Overview
		@@ -61,7 +61,7 @@ Files that aren't valid UTF-8 open read-only; commands that would change them sa
61	61
62	62	** Themes and display
63	63
64		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.
	64	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.
65	65
66	66	- Font :: =font= when that family is installed on the device, otherwise the system's monospaced font.
67	67	- 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.
		@@ -152,17 +152,55 @@ Tap a result to open it in the reader. A heading result opens at that heading.
152	152
153	153	* The agenda
154	154
155		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.
	155	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.
156	156
157		- 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.
158		- 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.
159		- Tap an entry to read it, at its heading.
160		- 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).
161		- Touch and hold an entry for TODO State…, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
	157	- 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"~).
	158	- The bar at the bottom :: Earlier, Filter, Today, Go to Date, the span (Day, Week, Month or the configured span) and Later.
	159	- 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.
	160	- + on a day's header :: captures an entry scheduled on that day (see [[file:08-capture.org][Capture]]).
	161	- Tap :: an entry to read it, at its heading.
	162	- Swipe left :: on a TODO entry for Done, which sets the first done keyword of its sequence, or Next State.
	163	- Swipe right :: for Tomorrow, Next Week or Pick Date, which move the entry's scheduled date, or its deadline on a deadline row.
	164	- Touch and hold :: an entry for TODO State…, Reschedule, Schedule…, Deadline…, Tags…, Priority…, Clock In, Refile…, and Archive….
162	165
163	166	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.
164	167
165		See [[file:07-agenda.org][The agenda]] for the views and matches.
	168	With =calendar-events= on, the agenda also shows events from the Calendar app; see Settings below.
	169
	170	See [[file:07-agenda.org][The agenda]] for the rows, the views and matches, and the differences from the Mac.
	171
	172	* Widgets and the Live Activity
	173
	174	** Widgets
	175
	176	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.
	177
	178	\| Widget \| Sizes \| Shows \|
	179	\|--------+----------------------------------------------+---------------------------------------------------------------------------------------------\|
	180	\| 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. \|
	181	\| 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) \|
	182
	183	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.
	184
	185	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.
	186
	187	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.
	188
	189	** The clock's Live Activity
	190
	191	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.
	192
	193	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).
	194
	195	** orgstar:// links
	196
	197	The widgets and the Live Activity open the app with these links, which also work from Shortcuts, Safari or a note:
	198
	199	\| Link \| Opens \|
	200	\|----------------------------------------+--------------------------------------------\|
	201	\| =orgstar://agenda= \| The Agenda tab \|
	202	\| =orgstar://clock= \| The entry of the running clock \|
	203	\| ~orgstar://entry?path=/path/file.org&offset=N~ \| The file in the reader, at offset N \|
166	204
167	205	* Capture
168	206
		@@ -200,7 +238,7 @@ See [[file:08-capture.org][Capture]] for the template format.
200	238
201	239	* Clocking
202	240
203		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:
	241	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:
204	242
205	243	- Clock Out
206	244	- Cancel Clock
		@@ -264,7 +302,7 @@ See [[file:15-alongside-emacs.org][Working alongside Emacs and other tools]] for
264	302
265	303	* Settings
266	304
267		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.
	305	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.
268	306
269	307	1. Open the Settings tab.
270	308	2. Tap Choose Folder… and choose the folder.
		@@ -273,6 +311,13 @@ Changes to the files apply as they sync, and again each time you return to the a
273	311
274	312	Stop Using This Folder returns every setting to its default.
275	313
	314	The Calendar section is the one place the app changes a setting itself:
	315
	316	- 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.
	317	- 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.
	318
	319	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.
	320
276	321	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)=.
277	322
278	323	These settings from =config.toml= apply on iOS:
		@@ -281,11 +326,12 @@ These settings from =config.toml= apply on iOS:
281	326	- =org-tags-column=, =org-insert-heading-respect-content=, =org-M-RET-may-split-line=, =fill-column=
282	327	- =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
283	328	- =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=
284		- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=
	329	- =[theme]= (=font=, =font-size=, =line-spacing=, =heading-size-step=, =theme-file= and colours), =[theme.light]=, =[theme.dark]=, =[theme.todo]=, =[theme.category]=
285	330	- =org-log-done=, =org-log-reschedule=, =org-log-redeadline=, =org-log-into-drawer=
286	331	- =org-use-speed-commands=, with a hardware keyboard
287	332	- =electric-pair-mode=, =spell-check=
288		- =org-agenda-span=, =org-agenda-start-day=, =agenda-include-subfolders=
	333	- =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=
	334	- =calendar-events=, =calendar-event-calendars=
289	335	- =reminders=, =appt-message-warning-time=
290	336	- =org-clock-history-length=
291	337

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

		@@ -192,11 +192,21 @@ Orgstar's defaults follow a common Doom Emacs setup rather than plain Emacs in s
192	192	\| =electric-pair-mode= \| =true= \| off \|
193	193	\| =org-agenda-span= \| 10 days \| a week \|
194	194	\| =org-agenda-start-day= \| ="-3d"= \| today \|
	195	\| =org-agenda-show-all-dates= \| =false= \| =t= \|
195	196
196	197	=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.
197	198
198	199	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).
199	200
	201	** How the agenda looks
	202
	203	The agenda selects the same entries as Org's, but shows them its own way (see [[file:07-agenda.org][The agenda]]):
	204
	205	- 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.
	206	- Days without entries are hidden unless =org-agenda-show-all-dates= is =true=.
	207	- 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.
	208	- The time grid isn't shown. The now line is, between today's timed entries.
	209
200	210	** Known differences from Emacs Org
201	211
202	212	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	36	1. Open =ios/Orgstar.xcodeproj=.
37	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
39		=.quicklook=) and the App Group (=group.sh.krz.orgstar=) to ones your team can register.
	38	Change the bundle identifiers (=sh.krz.orgstar= and the three extensions' =.share=,
	39	=.quicklook= and =.widgets=) and the App Group (=group.sh.krz.orgstar=) to ones your team can register.
40	40	3. Choose your iPhone or iPad (or a Simulator) as the destination and Run (=⌘R=).
41	41
42	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	46	#+BEGIN_SRC sh
47	47	scripts/build-ios-app.sh

Commit 469ca131b7

Commit `469ca131b7`