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.

Goals, agent profiles, and runtimes

Org2 separates the outcome, worker, and execution mechanism. A goal is a portable org2:goal:v1 record under goals/. A named worker such as Customer Support or Product Research is an org2:agent-profile:v1 record under agent-profiles/. OpenClaw and Codex are runtimes: they execute work, but they are not themselves AGENT_REF values.

Profiles contain responsibilities, capabilities, skills, goal refs, and non-secret runtime bindings. A binding such as openclaw:customer-support connects the configured OpenClaw agent ID to the portable customer-support profile. codex:default may provide a default profile for a Codex chat, while a selected heading's existing AGENT_REF and GOAL_REF take precedence. Credentials, model selection, session IDs, and machine paths remain outside the profile.

org2 goal create customer-trust --title "Earn customer trust" \
  --measure "Support requests are resolved" --dir ~/notes          # preview
org2 goal create customer-trust --title "Earn customer trust" \
  --measure "Support requests are resolved" --dir ~/notes --apply
org2 agent-profile create customer-support --name "Customer Support" \
  --binding openclaw:customer-support --primary-goal-ref customer-trust \
  --responsibility "Resolve customer support requests" --dir ~/notes --apply
org2 agent-profile resolve --runtime openclaw \
  --runtime-agent-id customer-support --dir ~/notes --json

Durable runs and workflows accept --agent-ref and --goal-ref. todo assign accepts the same refs and writes :AGENT_REF: and :GOAL_REF: beside its readable :ASSIGNEE:. Do not replace the portable profile ID with openclaw, codex, a provider/model name, or a session ID. If resolution finds no active binding, omit the refs rather than guessing.

The Mac app exposes the same records under Agent Work → Goals and Agent Work → Agents. Selecting a row opens its canonical plain-text record in the detail pane. Owner, primary-goal, manager, and linked-run controls navigate between related records; the row menu applies supported goal or agent lifecycle changes through the shared CLI.

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

The unified approvals queue collapses legacy headline projections and repeated durable approvals that point to the same Gmail provider draft. Provider-backed items expose their deterministic decisionKeys. Preserve the exact Provider draft: PROVIDER:TOOL:DRAFT_ID line when requesting a replacement: the CLI reuses the current durable decision, supersedes older material without treating it as approved, and closes dedicated duplicate review runs when the newest decision is recorded. After a decision leaves the pending queue, run approval-resolve --decision-key KEY --json remains the authoritative lookup for an execution guard; private adapter metadata is only a cache.

Run-linked approval headings are projections, not additional decisions. When ORG2_RUN_ID plus an approval ID, unique title, or single pending boundary resolves a heading to a run approval, org2 approvals exposes only the canonical run item. A run with a pending approval stays in waiting-approval. Declaring a genuinely independent clarification or operational block requires run block --separate-from-approval, and approval-shaped reasons are rejected even with that override.

• Settle chat work without losing it: thread list/show reads corpus-owned OpenClaw thread history from .org2/openclaw-chat.json. thread settle/reopen previews a reversible state change; add --apply to commit it. thread configure --auto-settle never|SECONDS stores the shared inactivity policy, while thread auto-settle skips selected, pinned, unread, or pending threads and threads whose latest delivery is still sending, failed, or interrupted. Empty threads and threads that recovered from an earlier delivery failure remain eligible once inactive.

• Post a background result into AI Chat: thread post THREAD_ID --message TEXT --author NAME --agent-ref AGENT_REF --source run:RUN_ID --idempotency-key KEY previews an agent-attributed, no-turn delivery; add --apply to queue it. The Mac app drains .org2/ai-chat-inbox/ while running or when the corpus opens, then marks the thread unread and follows the normal notification path without invoking or steering either AI runtime. Use a stable, thread-scoped idempotency key for retryable jobs.

  The Mac workspace prompt exposes the selected destination as ORG2_AI_CHAT_THREAD_ID. A parent that explicitly wants a subagent, cron task, or other worker to report after the current turn must pass that marker, the active corpus root, readable author identity, source/run reference, and the instruction to post only after the reported state is durable. Foreground agents reply normally and must not mirror the same response through thread post. Embedded Codex exposes org2_thread_post as a native dynamic tool; MCP clients discover the same tool through tools/list. OpenClaw lifecycle workflow prompts carry the same conditional guidance but do not automatically duplicate every completed turn into chat.

• 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. Every CLI/MCP mutation is an atomic guarded write; run show ID --with-revision --json returns its SHA-256 source revision, and --if-revision prevents a client carrying old state from overwriting a newer edit. Concurrent writers, duplicate creates, and readable headers that diverge from machine state fail closed and remain diagnosable through org2 doctor. org2 approvals is the unified pending-decision queue: run-backed items carry their exact run and approval IDs, an immutable SHA-256 review-material fingerprint, deterministic provider decisionKeys when available, and the remaining blocker count, while standalone heading items carry their source file, line, and heading ID. Decide run-backed items through run approval-decide --fingerprint FINGERPRINT; a stale or substituted action fails closed, and the decision event retains the same fingerprint. Decisions are item-scoped: rejecting or canceling one action leaves unrelated sibling approvals pending, and a fully decided boundary resumes with rejected or canceled actions excluded. A --decision revised request keeps the workflow open for replacement material and must include --note "Requested changes" so the agent has durable direction. Request every replacement on the existing run and retain its provider-draft identity; approval-request is idempotent for matching material and supersedes earlier pending versions, while approval-decide reconciles older dedicated projections. Do not duplicate run approval state in a separate heading. 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 an unfinished run's 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/signal/gate/package converts a completed run into a versioned recipe with inputs, capabilities, outputs, checks, approval boundaries, and event/fresh-work gates. Triggered executions share a stable logical-work identity while each scheduler tick has its own numbered attempt.

• Scale recurring account work: ledger create/update/event/list/show/resolve stores one guarded canonical account per file under notes/LEDGER/accounts/ with stable identity keys and idempotent history. Resolve all known names, emails, domains, and source IDs before creating an account. Approval events link the canonical run decision, sent outreach requires an external receipt, and ledger list --eligible excludes pending or not-yet-executed approved work plus recently contacted accounts.

• Review and evaluate: doctor --dir CORPUS --json audits contradictory run, approval, recurring-attempt, and linked-heading state without writing; 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: doctor checks the agentic workspace boundary; fmt --check, lint, and graph audit check source formatting, metadata, and graph integrity.

• 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; export beamer derives reviewable LaTeX or a compiled presentation PDF from an Org/Org2 talk.

• 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 continuation 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 Agent Work; substantial main-agent work, subagents, and cron executions receive correlated durable run records. Any correlated run that requests approval remains open, and approving its complete current boundary in the Mac app continues the same durable run in its correlated chat session; a reusable workflow definition is optional. Continuation is keyed to the exact approval boundary so repeated requests do not enqueue it twice. Reply & Resume records a clarification through the Gateway and continues the correlated session; when a legacy run lacks session correlation, the app carries the same run ID and recorded answer into a fresh thread instead of only flipping its status.

The same plugin registers the Mac app's optional local-edit node policy. When Read and apply Org2 edits on this Mac is enabled, approve the app's separate node-role pairing and enable the nodes tool for the selected agent. Corpus mutations must then use org2.workspace.read, org2.workspace.patch.preview, and org2.workspace.patch.apply. Read returns the effective local document, including an unsaved selected-editor draft; preview binds a whole-file replacement to SHA-256 inputs; apply rechecks that preview, remains inside the active corpus, and returns the exact per-turn change set. The Mac node does not expose a generic shell.

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.

For a Codex machine already connected through Codex's built-in remote management, add a Managed Remote Codex destination instead of maintaining a WebSocket tunnel. The destination stores the existing Codex or ~/.ssh/config host alias and the workspace path on that machine, then attaches to the managed daemon with codex app-server proxy over a private SSH stdio stream. ChatGPT authentication remains owned by Codex; Org2 stores neither that credential nor a bearer token.

New Mac AI-chat threads expose an OpenClaw/Codex runtime picker beside the composer controls. The choice remains editable while the thread is empty and locks after its first message. Model and reasoning pickers beside it load the selected runtime's supported catalog, store optional per-thread overrides, and use Default to inherit the runtime configuration. The native Settings window can inject persistent user-authored chat instructions and authorize reads from either the current corpus or every loaded corpus. Each turn captures those authorized roots; secondary corpora remain read-only and the active corpus remains the only preview/apply target. OpenClaw applies overrides through the live Gateway session; Codex sends them through the local App Server. A turn that is already running retains its originating corpus context, transcript, authorized read roots, and local-edit write root while the visible workspace switches away or back. OpenClaw threads use the configured Gateway and lifecycle adapter. Codex threads launch one local codex app-server process, use Codex-managed Sign in with ChatGPT rather than an Org2-owned token, and store only the external Codex thread ID beside the local transcript. Settings → AI Chat selects Read Only, Workspace Write (the default), or opt-in Full Access for Codex turns. Full Access is required for workflows that write Codex-owned state such as the lease database under ~/.codex and should be used only with trusted threads. Regardless of sandbox mode, client-provided org2_workspace_read, org2_workspace_patch_preview, and org2_workspace_patch_apply tools keep corpus edits on the same turn-origin, unsaved-editor, SHA-bound preview/apply transaction as the OpenClaw local-edit node. A direct OpenAI API key is not used for this subscription-backed path.

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. User-invocable skills under the active corpus's .agents/skills/*/SKILL.md are also available in autocomplete without a Gateway connection and are forwarded to the selected OpenClaw or Codex runtime. With a live OpenClaw Gateway, the app additionally 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.