First minute

Ask the installed CLI what it can do instead of relying on model memory:

org2 agent capabilities
org2 --help
org2 agent --help

org2 agent capabilities emits the versioned JSON schema org2:capabilities:v1. It summarizes workflow families, write behavior, client roles, safety rules, and deeper documentation URLs. Use org2 COMMAND --help for the current flags of a specific command.

When working in a corpus, look for the nearest org2.json. It can define file selection, recursion, ignored paths, TODO vocabulary, data-source profiles, external-source intent, publishing projects, and roam/dailies locations. Do not assume a private database or app owns the canonical state.

Safe operating contract

1. Read normal files and deterministic compiler output before synthesizing an answer.

2. Prefer bounded JSON interfaces for automation and retain file/line citations, IDs, and source ranges.

3. Preview mutations. Most write commands require --apply; inspect the preview or JSON envelope first.

4. Keep generated work in views/ or compiled/ with provenance and review state before promoting it into canonical notes/.

5. Make small, inspectable text edits. Run targeted tests and org2 lint around writes when practical.

6. Never store credentials in Org2 notes. Config names environment variables or profiles; secret values remain external.

7. Treat multi-corpus reads as an explicit grant. Pass every --mount yourself; do not infer agent access from corpora remembered by a person's app.

Agent retrieval

Use the agent namespace for bounded, cited context:

org2 agent search --query "billing migration" --dir ~/notes --recursive
org2 agent context --query "billing migration risks" --dir ~/notes --recursive
org2 agent fetch --id NODE_ID --dir ~/notes --recursive
org2 agent bundle --query "billing migration" --scope project:billing --since 90d

The shorthand org2 context QUERY renders a cited Markdown/Org context pack for prompt assembly. org2 compile corpus emits a schema-versioned JSON or JSONL corpus artifact for larger downstream indexes and tools. org2 brief produces a human-facing synthesis from the same context substrate.

Common workflows

• Delegate durable work: run create/list/show/start/resume/cancel/fork keeps goals, cited context, plans, assignments, runtime metadata, artifacts, approvals, validation, and event history in .org2/runs/*.org2. Use run runtime for observable provider/model and usage fields. If work cannot continue, run block ID --reason "Specific question or next action" records an actionable clarification; a generic reasonless blocked state is rejected. Runs with review-required artifacts remain open until run artifact-review RUN_ID ARTIFACT_ID --status reviewed|rejected --actor NAME records the human decision in both the run and a linked Org artifact. When a person confirms that a blocked outcome was already achieved elsewhere, run complete-external RUN_ID --summary "Where or how it was completed" --actor NAME closes that run with an explicit audit event while retaining its unresolved workflow metadata as history.

• Teach and replay a process: workflow save/run/triggers/package converts a completed run into a versioned recipe with inputs, capabilities, outputs, checks, and approval boundaries.

• Review and evaluate: review list/show unifies pending run approvals, review-required artifacts, clarifications, and failed checks; eval run/fixture checks observable outcomes and creates sanitized regression fixtures.

• Use portable tools and models: runtime select resolves capability/privacy policies, mcp serve exposes corpus resources and run tools, and mcp snapshot preserves external results with provenance.

• Plan and act: agenda, todo, approvals, plan, and clock.

• Read across identified corpora: workspace agenda and workspace search combine canonical per-corpus JSON results without creating a merged database or a workspace-wide write target.

• Refresh external mirrors: source list/doctor/status/bind/import/sync orchestrates slacrawl and notcrawl. source import previews bounded raw captures and review-required Org2 packets; source sync PROFILE --ingest --apply refreshes and stages them. Portable profiles may declare validated interval or daily schedules, which the Mac app executes while running with wake/launch catch-up; execution state remains machine-local. Profiles contain no secrets; every machine supplies its own binding or Keychain credential outside the corpus.

• Capture and organize: capture, archive, and refile.

• Find and connect knowledge: search, query, id, backlinks, entity, index, and roam ....

• Check corpus health: fmt --check, lint, and graph audit.

• Work with data: query-data materializes explicit dataset/SQL blocks; render-chart renders deterministic chart declarations. Remote refresh is always explicit.

• Create reviewed AI artifacts: ai validate-job, ai run, ai review, ai suggest-links, and ai promote preserve the review boundary.

• Publish: export html and publish derive HTML without replacing the source corpus.

• Use editor semantics: lsp exposes shared navigation, completion, diagnostics, formatting, and refactoring behavior.

See Tooling reference for commands, Language reference for syntax, Corpus flow for artifact zones and trust boundaries, and Features for how the pieces fit together.

Native OpenClaw lifecycle bridge

Install the checked-out integration with openclaw plugins install --link ./integrations/openclaw. The org2-lifecycle plugin must be enabled, permitted to use its typed conversation hooks, and configured with the target corpusDir. Verify the live Gateway surface with openclaw plugins inspect org2-lifecycle --runtime --json after restarting the Gateway. The adapter is a single-corpus write boundary: Mac workflow requests include the active portable corpus ID and fail before execution if it differs from the configured corpus. Ordinary conversation and personal TODOs stay out of Run Center; substantial main-agent work, subagents, and cron executions receive correlated durable run records. Workflow turns that request approval remain open, and a Mac approval continues the same durable run in its correlated chat session.

Durable delegation example

org2 run create --goal "Prepare a cited launch briefing" \
  --accept "A reviewed briefing and PDF exist" \
  --context notes/launch.org2 --capability agent-context --capability publish \
  --owner avi --dir ~/notes --json
org2 run start RUN_ID --dir ~/notes
org2 run artifact RUN_ID --path views/launch-brief.org2 --role view \
  --review-status review-required --dir ~/notes
org2 review list --status pending --dir ~/notes --json
org2 run complete RUN_ID \
  --summary "Prepared the cited launch briefing and reviewed PDF; no follow-up is required." \
  --highlight "Launch claims retain source citations" --dir ~/notes
org2 workflow save RUN_ID --id launch-briefing --dir ~/notes

The durable record is ordinary Org2 text under .org2/runs/. Its human-readable sections and versioned JSON machine-state block describe the same run. Completion requires a concise --summary written for the person reviewing the result; repeat --highlight and --next-action when those details matter. Authored workflow files use the same pattern under the visible top-level workflows/. Apps and agents may provide tooling around these files, but they are not allowed to replace them with private state. See Workflows.

Install and execute the built-in flagship recipe with:

org2 workflow install-builtin meeting-to-controlled-execution --dir ~/notes
org2 workflow run meeting-to-controlled-execution \
  --input meeting=raw/meetings/2026-07-14.org2 \
  --input output=views/meetings/2026-07-14 --dir ~/notes

Write examples

Preview a planning change, then apply the same operation after review:

org2 plan set --file projects.org2 --line 42 --kind scheduled --date 2026-07-20 --format diff
org2 plan set --file projects.org2 --line 42 --kind scheduled --date 2026-07-20 --apply

Create a cited generated view without silently rewriting canonical notes:

org2 context "launch risks" --dir ~/notes --recursive --format json > compiled/launch-context.json
org2 lint --dir ~/notes --recursive --format json

Agents embedded in the macOS Workspace should still use shared CLI/parser semantics for IDs, links, source ranges, agenda behavior, data queries, and context. App presentation state is not the language implementation.

The Mac chat's user-facing slash commands follow that rule: local commands such as /search, /related, /lint, /spellcheck, /export, and /publish call shared compiler/runtime behavior, while /brief and /summarize hand the selected source context to the configured agent. With a live OpenClaw Gateway, the app also discovers the selected agent's runtime command inventory through commands.list and forwards those invocations unchanged to chat.send. Gateway commands are not routed through HTTP compatibility. The app does not expose a separate /context command; source selection and cited context assembly remain internal agent plumbing.

For a completely new local workspace, the Mac app can initialize an empty folder with a minimal org2.json, inbox, welcome note, and notes/, daily/, views/, and compiled/ zones. Those generated starter files are ordinary corpus text and should be treated like any other user-owned source.