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

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

That means you can start by pointing the CLI and editor tooling at your current notes directory, then 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

• LSP-powered 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

• 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 — shared editor backend

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