Compiler workflow

The central loop is:

1. capture raw source material and working notes in plain files,

2. parse headings, tasks, links, drawers, properties, timestamps, blocks, tables, and source ranges,

3. resolve IDs, backlinks, planning state, artifact roles, provenance, and graph relationships,

4. compile that corpus into useful outputs: agendas, diagnostics, graph views, entity pages, agent context, editor intelligence, HTML pages, and published sites.

Because every output comes from the same semantic model, Org2 can support planning, knowledge management, data-backed reports, publishing, and automation without locking you into one app.

Core workflow surface

What already works well today:

• Headings, drawers, properties, planning lines, TODO keywords, links, blocks, tables, and timestamps

• Agenda views across many files

• TODO / planning edits from CLI and VS Code

• Capture, archive, and refile workflows

• Canonical formatting

• HTML export and multi-file publishing

• Cited workspace search/query for asking factual questions against source notes

• Roam-style IDs, backlinks, dailies, node creation, linkify previews with semantic/alias-aware suggestions, AI-assisted review reports, and graph reports

• Durable agent-thread and data-link metadata for Workspace clients and external agents

• Org-crypt subtree encryption/decryption workflows, including per-subtree multi-recipient encryption for user/device/agent access without putting plaintext in a vendor database

• Shared editor backend features, including LSP where an editor benefits from it

Workspace and context records

Org2 Workspace is the product direction for focused clients over the same local corpus. The macOS app now exists as an alpha client for agenda review, file navigation, search, rendered block editing, meeting capture, OpenClaw handoff, agent-thread browsing, daily notes, knowledge-node creation, and org-crypt workflows. Entity pages, richer meeting memory, capture/refile workflows, and data-backed reports should continue to use parser/compiler output, so clients share a source of truth.

The format already has the building blocks for that direction:

• TODOs, scheduled/deadline timestamps, priorities, effort, and tags for agenda surfaces,

• IDs, aliases, backlinks, and file links for entity and graph navigation,

• KIND: agent-thread records with selected context, session/transcript references, status, and durable outputs,

• KIND: warehouse-query, dataset, data-link, sql-view, event-stream, and timeline-link records for report evidence,

• event/timeline metadata such as stream IDs, event types, entities, actors, cursors, change IDs, and occurred/captured timestamps,

• artifact role/provenance metadata for generated drafts, compiled views, and published outputs.

This keeps Org2 useful both as a personal knowledge base and as an organizational context layer over notes, meetings, tickets, repos, files, metrics, and agent work.

Agent collaboration

Org2 is a good medium for collaborating with agents because the handoff state lives in the corpus. A task can carry selected context, source refs, transcript links, review status, policy gates, generated artifacts, and durable outputs in a form that humans can inspect and tools can fetch.

The useful properties are concrete:

• agents receive scoped context packs with file and line citations,

• agent threads are durable headings with status and attachments,

• generated drafts live under reviewable artifact metadata,

• provenance links raw sources, drafts, promoted notes, and published output,

• policy fields can mark work that needs approval before external side effects.

That gives Codex, OpenClaw, local models, scripts, and future workspace clients a shared way to coordinate around the same notes.

Scoped encryption for agents

Org2 can use GPG-backed :crypt: subtrees as a local access-control layer for agent workflows. You can encrypt selected entries to an agent's public key while other encrypted entries remain readable only to their own recipients.

This is especially useful for mixed personal/team/agent corpora:

• keep most private notes encrypted only to your own device keys,

• share a specific task, meeting note, or research subtree with one agent by adding its recipient file,

• sync the same encrypted files through ordinary file infrastructure,

• revoke future access by removing the agent recipient and re-encrypting the subtree.

The boundary is explicit in the note itself and travels with the file.

Planning + agenda

Org2's planning workflow is already pretty serious.

Highlights:

• Scheduled + deadline items across many files

• Rich date-window controls

• Filter dimensions for status, kind, date/time, tags, IDs, properties, priority, effort, file, headline text, and more

• Sort and group controls for daily planning views

• Practical handling of real-world TODO vocabularies (for example WAIT/HOLD/PAUSED normalize into in-progress-style buckets)

The agenda work goes beyond “show me tasks due today.” It is becoming a real backend for keyboard-driven planning, including an interactive terminal agenda:

npm run org2 -- agenda --dir ~/notes --recursive --tui

Use the TUI when you want a live, scannable planning surface without leaving the terminal; use --format json when another tool should consume the same agenda model.

Knowledge management / roam workflows

Org2 has first-class support for linked-note workflows:

• Stable IDs

• Backlinks

• Wiki links and id: links

• Node creation

• Dailies navigation

• Link insertion helpers

• Cited search/query output for answering questions with source file + line references

• Workspace graph operations via Roam DB sync and graph reports

• Linkify preview/apply flows for safely strengthening exact weak text references into links

• Review-only represented-node suggestions that explain semantic/alias matches with confidence, evidence tokens, and source ranges

• AI-assisted link/entity suggestion reports that rank compiler candidates with the mock adapter while preserving the review-only boundary

This matters because Org-style notes get dramatically better once links, references, dailies, and fact lookup stop feeling bolted on.

Example usage patterns

A few concrete ways Org2 fits into a real workflow:

• Daily planning: keep TODOs, scheduled dates, deadlines, priorities, effort, and tags in plain files; derive agenda views in the CLI, VS Code, or the agenda TUI.

• Mac workspace: open a corpus in the native macOS app, review agenda items, quick-open files, edit rendered blocks, record/import meetings, and hand selected context to OpenClaw without moving the source of truth out of plain files.

• Meeting pipeline: store transcripts as raw evidence, curate summaries/TODOs/Linear candidates into notes, then run backlinking and lint to keep the result connected and auditable.

• Research corpus: capture source material, assign IDs, strengthen weak references into links, query with file/line citations, and publish selected pages.

• Automation boundary: let scripts and agents read compiled corpus artifacts from stable outputs, while generated outputs remain reviewable under views/ or compiled/.

macOS Workspace

The native Mac app lives in apps/macos/Org2Workspace. It is early, but it is already more than a parser demo:

• corpus picker and file scanner,

• agenda surface with filtering, modes, keyboard navigation, and task/planning mutations,

• quick-open and daily-note navigation,

• search and backlinks-backed detail navigation,

• ID-backed knowledge-node creation from Search,

• rendered document view with structured block editors,

• meeting recording/import with local-first transcription artifacts,

• OpenClaw chat with selected workspace context,

• GPG-backed org-crypt configuration and encrypt/decrypt actions.

The next major app milestone should lead with real capture and refiling: system-wide capture or a global capture panel, fast TODO/note capture, refile into existing files/headings, and scheduling/deadline/priority/tag/effort controls that preserve clean Org2 source. Meeting-to-action, knowledge-browser, and packaging/first-run work can proceed in parallel, landing in their natural product surfaces.

See macOS Workspace for the current app surface and build/run notes.

VS Code experience

VS Code is currently the most complete Org2 editor story.

That includes:

• Syntax highlighting and folding

• Agenda UI

• TODO / planning commands

• Capture / archive / refile commands

• Formatter commands with preview/apply flows

• HTML export commands

• Workspace search/query commands for cited note lookup

• Roam commands for IDs/backlinks/dailies/linkify/graph reports, including semantic suggestion previews and AI-assisted link/entity reports

• Power-keymap shortcuts for fast workflows

If you want to use Org2 today instead of just admire the idea, this is the path.

Editor backend capabilities

Org2 exposes editor capabilities through shared parser and CLI surfaces, with LSP support where the protocol is a good fit.

Current highlights include:

• Definitions / declarations / references for file and ID links

• Hover, completion, signature help, and highlights

• Rename + linked editing for IDs and file-link targets

• Workspace file-rename support for updating Org file links

• Formatting, range formatting, and on-type table-aware formatting

• Semantic tokens, inlay hints, code lens, document colors

• Call hierarchy for Org ID/file links

The strategic point is the shared backend: editor features should come from the corpus model, whether a client reaches it through LSP, direct CLI calls, or a native Workspace surface.

Publishing

Publishing is already a first-class workflow.

• Single-file HTML export

• Recursive workspace export

• Project-level publish definitions via org2.json

• TOC / heading-numbering / stylesheet / file-link-rewrite support

• This docs site is generated by Org2 itself

Positioning

Org2 keeps the parts of Org-shaped plain text that matter and aims at a portable compiler/runtime for knowledge work. The bet is that a personal knowledge base should behave like a local compiler target:

• keep raw notes portable and inspectable,

• compile them into explicit semantics,

• generate many views and artifacts from one corpus model,

• meet users where they already work, including VS Code, CLI automation, and publishing pipelines.

Compatibility matters because existing notes matter. It is secondary to making the corpus computable.