1) Install Org2

git clone https://github.com/aviaviavi/org2.git
cd org2
npm ci
npm run build

Sanity check:

npm run org2 -- --help
npm run org2 -- agenda --help

2) Start with your existing Org files as compiler input

You do not need to convert everything first.

Org2 is designed to work with existing .org files right away.

Example:

npm run org2 -- agenda --dir /path/to/your/notes --recursive

For a keyboard-driven planning view, add the agenda TUI:

npm run org2 -- agenda --dir /path/to/your/notes --recursive --tui

That means you can start by pointing Org2 at your current notes directory and treating it as input to the compiler pipeline: raw files → structured notes → compiled semantics → views and published outputs. Adopt .org2 for new files when you want to.

3) Use VS Code if you want the best editor experience today

VS Code is currently the strongest Org2 editor target.

High-value workflows already available there:

• agenda UI

• TODO / planning edits

• capture / archive / refile

• formatter preview + apply flows

• roam backlinks / IDs / dailies

• HTML export

• shared navigation and editing features

See VS Code for the current command/keybinding surface.

4) Prefer .org2 for new files

For new files, using .org2 is a good default.

Why:

• clearer intent,

• easier editor/tool targeting,

• cleaner long-term migration path.

But .org remains a first-class input format for current workflows.

5) Learn the core CLI workflows

The most useful commands to know first are:

• agenda: inspect scheduled/deadline items across files; add --tui for the interactive terminal agenda

• todo / plan: edit task state and planning metadata

• capture: append quick entries

• archive / refile: reorganize trees

• fmt: canonical formatting

• roam ... / id / query / backlinks: linked-note workflows

• export html / publish: produce docs and sites

• lsp: optional shared editor backend for clients that use the protocol

6) Generate the docs site locally

The repository includes a docs site authored in Org files under docs/site/ and published with Org2 itself.

npm run org2 -- publish docs-site --config org2.json

7) What to expect right now

8) Next docs

• Features

• Tooling reference

• Editor integrations

• Language reference

• Semantics and status

• Migration guidance