Org-mode storage¶

nightwright does not invent a private database for ideas. It stores them as org-mode headlines in plain files you can open in Emacs, Neovim, VS Code, or any text editor. That is intentional: the same richness org already has for TODO states, properties, drawers, clocks, and outline nesting becomes nightwright’s durable record.

Agents and the CLI speak JSON; humans can still read and edit the files.

Official Org documentation¶

nightwright leans on plain Org syntax — it does not redefine Org. When you want the authoritative rules for headlines, TODO keywords, properties, drawers, or clocking, use the upstream manuals:

Resource	Use it for
Org mode home	Releases, overview, community links
Org Mode Compact Guide	Short intro to structure, TODO, and editing
The Org Manual (multi-page)	Full reference — start here for deep dives
The Org Manual (single page)	Same manual as one HTML file
Manuals index	HTML / PDF / Emacs-bundled variants
Worg	Community tutorials and FAQ

Topics that show up most in nightwright’s idea files:

Document structure — headlines and outline levels
TODO items — #+TODO: vocabularies and states
Properties — :PROPERTIES: drawers / :ID:
Drawers — drawers in general
Clocking work time — CLOCK: / :LOGBOOK:

Where files live¶

Config key	Default (typical)	Role
`org_files`	`~/work/org` (dir or list)	Read corpus — recursive `*.org`
`org_ideas_file`	`~/work/org/ai/ideas.org`	Write target for new captures
`org_ideas_archive_file`	`ideas-archive.org` next to `org_ideas_file`	Terminal ideas move here
`idea_rotation_max_lines`	`1200`	Rotate active ideas file when oversized

Capture always appends to org_ideas_file. Listing (nw ideas, desk, hub) scans everything under org_files, so rotated dated siblings and the archive stay visible without changing config paths.

File shape¶

Idea files declare their own TODO vocabularies:

#+TODO: IDEA INCUBATE SPECCED | PROMOTED EXPORTED SHIPPED DROPPED
#+TODO: OPEN | RESOLVED

The second line appears once questions are written (OPEN / RESOLVED under ** Open questions).

Headline + properties¶

Each idea is a level-1 headline with a stable :ID::

* INCUBATE Ship SVG captures for product docs
  :PROPERTIES:
  :ID: IDEA-001
  :CREATED: [2026-09-09 Wed 18:30]
  :UPDATED: [2026-09-09 Wed 18:30]
  :END:

Optional properties include :PROJECT:, :KIND:, :SPEC:, :EXPLORED:, …

Enrichment outline¶

Under the headline, nightwright keeps a fixed skeleton (order matters):

** Summary — durable prose; gates promotion
** Open questions — *** OPEN|RESOLVED … child headlines
** Log — *** [stamp] entries (CLI: nw idea log; formerly explore)

Supplemental wall-time uses org’s native :LOGBOOK: / CLOCK: beside that outline (not inside ** Log) — see Clock.

Full demo file¶

The capture script seeds this committed fixture (open it in an editor): ideas-demo.org.

#+TODO: IDEA INCUBATE SPECCED | PROMOTED EXPORTED SHIPPED DROPPED
#+TODO: OPEN | RESOLVED

* INCUBATE Ship SVG captures for product docs
  :PROPERTIES:
  :ID: IDEA-001
  :CREATED: [2026-09-09 Wed 18:30]
  :UPDATED: [2026-09-09 Wed 18:30]
  :END:
** Summary
Docs should show real CLI/TUI output and explain how org files hold the durable idea record.
** Open questions
*** OPEN Do we embed org excerpts as fenced code or SVG?
*** OPEN Should rotation knobs appear in the guide?
** Log
*** [2026-09-09 Wed 18:30]
Seeded demo enrichment for product-doc captures.
*** [2026-09-09 Wed 18:30]
Summary gates promote; Log holds the explore trail.
* IDEA Passive hours from transcripts
  :PROPERTIES:
  :ID: IDEA-002
  :CREATED: [2026-09-09 Wed 18:30]
  :UPDATED: [2026-09-09 Wed 18:30]
  :END:
* SPECCED Outbound export to partner repo
  :PROPERTIES:
  :ID: IDEA-003
  :CREATED: [2026-09-09 Wed 18:30]
  :UPDATED: [2026-09-09 Wed 18:30]
  :END:

What the CLI writes¶

Command	Mutates org?	Effect
`nw idea "…"`	Yes	Append headline + `:ID:` to `org_ideas_file` (may rotate first)
`nw idea summary`	Yes	Replace `** Summary` body
`nw idea log`	Yes	Append stamped entry under `** Log`; may `IDEA`→`INCUBATE`
`nw idea questions …`	Yes	Mutate `** Open questions`
`nw idea show`	No	Render the outline
`nw idea clock-in/out`	Yes	`:LOGBOOK:` CLOCK lines

nw idea show

Also from the same fixture:

nw ideas

nw next

nw ideas --tree

nw hub --json

Rotation¶

When org_ideas_file exceeds idea_rotation_max_lines, the next capture:

Renames the active file to ideas-YYYYMMDD.org (same directory; -N if needed)
Writes a fresh header-only file back at the configured org_ideas_file path

Config path never changes. Old windows remain loadable because they still sit under org_files. Example sibling: ideas-20260901.org.

flowchart LR
  Cap[nw idea capture] --> Check{lines > max?}
  Check -->|no| Append[Append to ideas.org]
  Check -->|yes| Ren[Rename ideas-YYYYMMDD.org]
  Ren --> Fresh[New empty ideas.org + header]
  Fresh --> Append
  Ren --> Still[Still under org_files]
  Still --> List[nw ideas / desk / hub]
  Append --> List

Archive¶

Moving to a terminal idea state (for example DROPPED, PROMOTED, SHIPPED) cuts the whole level-1 subtree into org_ideas_archive_file. When that key is unset, the archive is ideas-archive.org in the same directory as org_ideas_file, so moving the ideas file moves the archive with it. There is no separate nw idea archive verb — state transitions drive it.

Example stub: ideas-archive-demo.org.

Why this matters¶

Predictable structure — agents and skills know where Summary / questions / Log live.
Human-editable — fix a typo in your editor; nightwright re-reads on the next command.
History without a DB — rotation + archive keep the active file small while IDs stay stable across files.