Org files

Samaya keeps everything in a folder of Org files that you own. Other tools, Emacs included, can read and edit them, and Samaya picks up their changes within a moment.

Choose it in Settings → Org files. Calendar sync writes into the same folder.

With no folder set, Samaya shows an empty planner and makes no changes.

org/
├── Inbox.org         where new tasks go
├── work.org          a channel: its tasks
├── website.org       a channel nested under work
├── calendar.org      generated by calendar sync
├── data/             images attached to tasks, as org-attach keeps them
├── goals/
│   ├── 2026.org      the year's goals
│   └── archive/
│       └── 2025.org  archived goals
└── archive/
    ├── 2025.org      archived tasks, still shown
    ├── trashed.org   deleted tasks, for 14 days
    └── calendar.org  generated: notes from past calendar events

• Every top-level .org file is a channel, named after the file. New tasks go to Inbox.org, created when needed.

• Files under archive/ are read, but don't create channels. Being in a subfolder, they stay out of an org-agenda-files pointed at the folder.

• No channel can be named trashed or calendar.

• calendar.org and archive/calendar.org belong to calendar sync. See Google Calendar → The calendar file.

Settings → Channels adds, renames, nests, recolours and archives channels. It writes these keywords at the top of the channel's file:

#+SAMAYA_TONE: sky
#+SAMAYA_PARENT: work
#+SAMAYA_ARCHIVED: t
#+SAMAYA_CONTEXT: work
#+SAMAYA_PUBLIC: t

Renaming a channel renames its file.

#+TITLE: Work
#+SAMAYA_TONE: sky
#+TODO: TODO NEXT WAIT | DONE CANCELLED

* TODO [#A] Review the timeline widget
SCHEDULED: <2026-09-28 Mon 10:30-11:00>
:PROPERTIES:
:ID: 5f0c...
:EFFORT: 0:30
:END:
:LOGBOOK:
CLOCK: [2026-09-27 Sun 09:00]--[2026-09-27 Sun 09:25] =>  0:25
:END:
Notes about the review go here, as the headline's body.
** TODO Check the drag ghost

A headline without a keyword is a plain heading: it is kept, but not shown as a task. Samaya gives a headline an :ID: the first time it edits it.

Deleting a task moves it, with its subtasks and notes, to the end of archive/trashed.org, stamped with when and where from:

* TODO Check the drag ghost
:PROPERTIES:
:ID: 9a41...
:TRASHED: [2026-09-28 Mon 14:05]
:TRASHED_FROM: work
:TRASHED_PARENT: 5f0c...
:END:

:TRASHED_PARENT: appears only on a subtask deleted on its own. The file is tagged :ARCHIVE:, so org-agenda leaves it out.

Settings → Trash lists deleted tasks.

• Restore puts a task back under its parent if that still exists, else at the end of its channel, else in the Inbox, without the :TRASHED...: lines.

• Delete forever removes it, with its attached images.

• Anything in the trash for 14 days is deleted forever.

Each year's goals live in goals/<year>.org. Samaya creates the file with the year's first goal. Being in a subfolder, goal files stay out of an org-agenda-files pointed at the Org folder.

#+TITLE: Goals 2026
#+TODO: ACTIVE | DONE ENDED

* ACTIVE Read 24 books
:PROPERTIES:
:ID: 3b1c...
:SAMAYA_COLOR: #63b376
:SAMAYA_CHANNEL: personal
:SAMAYA_MEASURE: Books read
:SAMAYA_MEASURE_START: 0
:SAMAYA_MEASURE_TARGET: 24
:SAMAYA_MEASURE_BY: <2026-12-31 Thu>
:END:
:MEASURE:
- 9 [2026-06-30 Tue]
- 14 [2026-09-30 Wed] Two on holiday
:END:
Why it matters goes here.
** ACTIVE Finish the reading list
:PROPERTIES:
:ID: a71f...
:SAMAYA_QUARTER: Q4
:SAMAYA_FEATURES: steps habits time
:SAMAYA_TIME_BUDGET: 3:30
:END:
*** Read for 30 minutes
:PROPERTIES:
:ID: c4d9...
:SAMAYA_HABIT_DAYS: Mon Wed Fri Sun
:END:

Other headlines in a goal file, such as notes, are kept but not shown. Closing a year goal closes its active quarter goals too.

A year goal can track one measure: a name, a start, a target and, optionally, a date to reach it by. Values are numbers or H:MM:SS. A target below the start means lower is better. Each logged value is a line in the :MEASURE: drawer, with its date and an optional note.

A quarter goal with habits among its features puts a task on each of its habits' days left this week, in the year goal's channel or the Inbox. Moving the task keeps it counting for its day. Skipping a day leaves it out of the week; a past day whose task is not done is missed.

Archiving a goal moves it, with what is beneath it, to goals/archive/<year>.org. Unarchiving puts it back beneath its year goal.

Deleting a goal moves it to archive/trashed.org, like a task. Restoring puts it back in its year's file, and it is deleted forever after 14 days. Tasks linked to a deleted goal keep their link, so restoring the goal reconnects them.

In the task editor, + Image attaches an image, and Ctrl+V attaches the one on the clipboard. Samaya stores them where org-attach does, so C-c C-a in Emacs sees them: a task with the ID 5f0c... keeps its images in data/5f/0c.../. The first image tags the headline :ATTACH:, and each is linked on its own line at the end of the notes:

* TODO Review the timeline widget :ATTACH:
Notes about the review go here.
[[attachment:screenshot.png]]

The editor shows a thumbnail for each link. Click one to open it; ‹ › or the arrow keys step through the rest, and ✕ or Esc closes it. A thumbnail's ✕ deletes the file and its link. Deleting a link by hand only hides the thumbnail; the file stays.

Samaya edits only what a change touches and leaves the rest of the file as it was: tags, deadlines, repeaters, other keywords such as WAIT, and properties and drawers it doesn't know. It never overwrites an edit made since it read the file.