First minute

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

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

celorga 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 transition logging, data-source profiles, external-source intent, publishing projects, and roam/dailies locations. Do not assume a private database or app owns the canonical state.

Deterministic chat recovery

On macOS, celorga thread repair --dir CORPUS --json previews native transcript reconciliation without an LLM. Add --apply to commit, optionally carrying the preview's --if-revision token. --watch --interval SECONDS --apply runs a serial worker with a configurable interval and skips unchanged chat storage. Build OpenOrgServer with npm run build:server first, or pass --executable PATH. Desktop AI Chat settings and celorga server chat-repair --interval off|SECONDS configure periodic background checks. See the tooling reference for integrity checks and recovery boundaries.

Native tooling and capability gaps

Use Celorga's native CLI by default for Org operations such as search, agenda, TODOs, links, tables, export, and validation. Prefer exposed Celorga workspace/MCP tools for operations they support; client-required effective-text reads and reviewed writes take precedence over shell access. Discover commands with celorga agent capabilities and org2 COMMAND --help before choosing a workaround. Celorga is an independent runtime: a .org file does not imply GNU Org semantics or an Emacs dependency.

Do not invoke emacs, emacsclient, batch Emacs Lisp, or an Emacs Org exporter as an implicit fallback. Do not assume Emacs is installed, probe for it, or install it for ordinary Celorga work. Use Emacs only when the user explicitly requests an Emacs-specific task. This does not prohibit other tools for work outside Celorga's scope.

If a native operation appears missing or broken, check the installed version, capabilities, and relevant help first. Distinguish a missing executable, permission restriction, or unavailable tool from a confirmed Celorga capability gap; do not bypass access or review boundaries. State the exact limitation and use a small, supported, reviewable alternative when available. Never silently substitute GNU Org behavior or execute preserved unsupported formulas or source blocks. If this is authorized Celorga development with repository access, reproduce and fix the shortcoming and add a focused regression test. Otherwise, suggest opening an issue at Celorga GitHub issues and prepare a sanitized report with the version, command/tool, minimal input, expected and actual behavior, and workaround. Do not publish an issue or private corpus content without the user's authorization. If shell execution is unavailable, use the exposed tools and explain any remaining limitation rather than inventing command results.

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 celorga lint around writes when practical.

6. Never store credentials in Org 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

Celorga 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, Codex, Claude Code, Pi, and OpenCode are runtimes: they execute work, but they are not themselves AGENT_REF values.

Profiles contain responsibilities, capabilities, skills, goal refs, an optional default runtime, and non-secret runtime bindings. defaultRuntime is a portable starting preference such as openclaw or codex; a person can still choose another runtime for a new chat. A binding such as openclaw:customer-support instead connects the configured OpenClaw agent ID to the portable customer-support profile for reverse identity resolution. Credentials, model selection, session IDs, destinations, and machine paths remain outside the profile.

celorga goal create customer-trust --title "Earn customer trust" \
  --measure "Support requests are resolved" --dir ~/notes          # preview
celorga goal create customer-trust --title "Earn customer trust" \
  --measure "Support requests are resolved" --dir ~/notes --apply
celorga agent-profile create customer-support --name "Customer Support" \
  --default-runtime openclaw \
  --binding openclaw:customer-support --primary-goal-ref customer-trust \
  --responsibility "Resolve customer support requests" --dir ~/notes --apply
celorga 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, linked-run, and default-runtime controls use the shared CLI rather than app-private profile state.

Agent retrieval

Use the agent namespace for bounded, cited context:

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

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

Use celorga checkbox --file FILE --line N to preview a three-state list-checkbox cycle, or checkbox set --status checked to choose a state. Add --fix-cookies to either action to refresh progress cookies in the same guarded edit. Use checkbox fix-cookies --file FILE to preview recalculation of stale [n/m] and [p%] cookies, including empty [/] and [%] placeholders, against their innermost heading totals. Add --apply to write; carry the JSON preview revision with --if-revision when applying later.

Corpus TODO defaults live in org2.json under todo.sequences; inspect or preview changes with todo-config show/set. Per-file overrides belong in file-local #+TODO:, #+SEQ_TODO:, or #+TYP_TODO: declarations. Respect | terminal states and use todo set --keyword STATE for exact custom state names; inspect the preview before applying.

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, celorga 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 the corpus-owned AI chat transcript, including the sharded store and pending operations while retaining legacy .org2/openclaw-chat.json compatibility. thread settle/reopen previews a reversible state change; add --apply to queue an immutable operation under .org2/ai-chat-inbox/operations/. thread configure --auto-settle never|SECONDS and thread auto-settle use the same operation journal instead of rewriting transcript files from the CLI. Celorga drains operations while running or when the corpus opens, persists each result into the authoritative transcript, and removes its journal file only after that commit is durable. Auto-settlement 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.

• Explain and wait on agent work: activity explain [--thread|--run|--workflow ID] --json reports why each item is working or needs attention, which host/runtime reported it, the last heartbeat or transition, live/cached/uncertain confidence, and the exact blocking approval or question. activity events --follow --json streams run, approval, thread, workflow, and host transitions as NDJSON. thread wait ID --until reply|needs-you|idle|working and run wait ID --until approval|blocked|completed|terminal check durable state first and exit 0 matched, 2 unreachable, or 124 timed out, so prompt-and-wait coordination is race-free.

• 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. In a shared room, add --request-turn @AGENT (repeatable) when the post should ask a room agent to respond; without it, a post never starts a turn.

• Hand off between agents in a shared room: an agent reply that @mentions another agent in the room starts that agent's turn, with the reply as its request. Mention an agent inside verbatim or code to refer to it without starting a turn. thread configure ROOM_ID --agent-turn-limit N|default caps back-to-back agent-requested turns (default 4, 0 turns hand-offs off) before a person must reply.

  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 celorga doctor. celorga 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. Recording that one approval was completed elsewhere cancels only that approval with an external receipt; it never completes the containing run. 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. If that whole-run action was mistakenly used on one approval, run reopen-external RUN_ID --summary "Corrected open-run outcome" --actor NAME restores the same run and its retained approval IDs to waiting-approval.

• Schedule a plain prompt: workflow create stores a name, prompt, symbolic AI destination reference, optional exact model and reasoning effort, optional agent profile, and interval or cron schedule in workflows/. workflow due reports the latest missed occurrence and suppresses overlap with an active attempt. While the chosen Mac app or headless server is running, Celorga creates a durable run and dispatches each occurrence through the same destination-neutral path as AI Chat. Missing model/reasoning fields use destination/runtime defaults; pinned values never inherit from an interactive chat. workflow delete is preview-first, removes only the definition when applied, and preserves prior run history.

• Teach and replay a fuller 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 scheduled occurrence 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.

• Keep a host available: celorga server runs the existing chat relay and scheduler without a desktop window on macOS. It can also expose a bearer-authenticated, read-only Streamable HTTP MCP endpoint with bounded cited corpus retrieval. Pair iOS over Tailscale, create one hash-only MCP token per external client, and use preview-first server assign --host-ref HOST to choose one corpus scheduler owner. See Headless server setup.

• Use portable tools and models: runtime select resolves capability/privacy policies, mcp serve exposes cited search, stable-ID fetch, bounded context, corpus resources, and run tools, and mcp snapshot preserves external results with provenance.

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

• Batch agent-state reads: celorga workspace agent-state --dir CORPUS --json returns the normal run, workflow, goal, and agent-profile list envelopes in one process. Each section has its own value or error and elapsed time.

• 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/schedule/import/sync orchestrates slacrawl and notcrawl. source import previews bounded raw captures and review-required Org packets; source sync PROFILE --ingest --apply refreshes and stages them. Portable profiles may declare validated interval or daily schedules. source schedule and the Mac Sources controls edit their cadence or pause/resume them; the app executes enabled schedules while running with wake/launch catch-up, while 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. browser-clip import --file CLIP.org2clip --dir CORPUS previews browser article/selection imports; apply with both returned --if-revision and --if-clip-revision. Raw source stays immutable in raw/browser/ and reviewable notes go to views/browser-clips.org.

• Spatial boards: canvas show|targets|create|edit|import|export operates on open JSON Canvas files. Mutations preview by default; canvas edit --stdin consumes a JSON operation array and requires --if-revision before --apply. File resources stay inside the active corpus; org2Ref: "id:ID" resolves stable note and heading sources.

• Find and connect knowledge: search, query, id, backlinks, entity, index, and roam .... Use roam connections --dir CORPUS --id ID --format json for a bounded local neighborhood and incoming exact unlinked mentions; roam mention-link previews one explicit target/occurrence and requires its --if-revision before --apply.

• Check corpus health: doctor checks the agentic workspace boundary; fmt --check, lint, and graph audit check source formatting, metadata, and graph integrity.

• Edit saved views: property-view list/suggest/query/save/edit shares the Mac Saved Views semantics. Portable views/ID.org2-view.json definitions select note/heading rows, columns, filters (including matches regex, on/before/after dates and query-time variables such as {today} or {today-7d}), sort and grouping. Plain-language suggestions are inspectable drafts; queries return inherited values, document titles, source locations and revisions. Preview source edits and carry --if-revision before --apply.

• Work with data: table recalculate previews or atomically applies safe #+TBLFM: spreadsheet formulas; 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: publish document produces a disclosure-safe web bundle, safe Beamer PDF, Google Doc, Google Slides deck, Google Sheet, or Google Drive PDF from one document or subtree; export html and project publish derive ordinary HTML, while export beamer derives author-controlled reviewable LaTeX or a compiled presentation PDF from an Org talk. Publishing previews by default and never grants access to 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.

For an MCP-capable or skill-aware client, continue to MCP and agent skills. That page documents the exact eight-tool stdio and five-tool read-only HTTP surfaces, common client setup, the packaged general Celorga skill, and the boundary where an agent should fall back to bounded CLI JSON.

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 Celorga 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.

The OpenClaw integration also fails closed on direct gog gmail drafts create|update calls. Use integrations/openclaw/bin/gmail-draft-safe.mjs for automated Gmail drafts: it creates fluid multipart/alternative MIME with a plain-text fallback, rejects hard-wrapped prose, anchors replies to a surviving non-draft message, and verifies provider readback before the draft reaches its Celorga approval boundary.

Durable delegation example

celorga run create --title "Prepare a cited launch briefing" \
  --goal "Prepare the briefing with source citations and a reviewed PDF" \
  --accept "A reviewed briefing and PDF exist" \
  --context notes/launch.org --capability agent-context --capability publish \
  --owner avi --dir ~/notes --json
celorga run start RUN_ID --dir ~/notes
celorga run artifact RUN_ID --path views/launch-brief.org --role view \
  --review-status review-required --dir ~/notes
celorga review list --status pending --dir ~/notes --json
celorga 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
celorga workflow save RUN_ID --id launch-briefing --dir ~/notes

The durable record is ordinary Org 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 automation and 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 Automations and workflows.

Install and execute the built-in flagship recipe with:

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

Write examples

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

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

Create a cited generated view without silently rewriting canonical notes:

celorga context "launch risks" --dir ~/notes --recursive --format json > compiled/launch-context.json
celorga 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.

After enabling the default-off Experimental features toggle in Settings → General, direct-provider destinations can opt into Workspace tools (experimental), a bundled TypeScript foreground executor using the app's existing Node runtime. Its host-provided tools are bounded corpus search, effective-text reads, SHA-bound patch previews, and application of an exact preview after native user review. Tool calls are bound to the originating turn; secondary authorized corpora remain read-only. The helper owns no corpus database, scheduler, or canonical run state. It uses existing chat history; an interrupted in-flight loop is not automatically resumed. The prototype is text-only, buffers each model response, and requires a tool-capable model. See the Mac setup and limits.

For a Codex machine reachable through SSH, add a Remote Codex over SSH destination. The destination stores the existing Codex or ~/.ssh/config host alias and the writable Celorga corpus checkout on that machine, starts Codex's managed app-server daemon, and attaches to its private Unix socket through SSH. A path beginning with ~/ is expanded on the remote Mac, not on the Mac running Celorga. Codex uses that checkout as its working directory and edits corpus files with its normal filesystem tools, so an automation can continue after the Celorga client sleeps or disconnects and does not need client-hosted edit callbacks. ChatGPT authentication remains owned by Codex; Celorga stores neither that credential nor a bearer token. If the SSH stream drops after a turn starts, the remote daemon keeps owning the turn. Celorga reconnects and reads that exact turn after wake instead of submitting the message again. Legacy WebSocket Codex destinations continue to work but are no longer offered as a separate normal setup choice.

New Mac AI-chat threads expose a named AI destination picker beside the composer controls. Configured destinations can include local Codex, Claude Code, Pi, or OpenCode; SSH-hosted Pi, OpenCode, or Codex; OpenClaw; OpenAI-compatible providers; Anthropic; OpenRouter; or Ollama. Settings shows only configured destinations: Add Destination creates a draft that becomes available after Save, and Delete removes an unused destination after confirmation. The choice remains editable while the thread is empty and locks after its first message. Model and reasoning controls load the selected destination's supported catalog where applicable, store optional per-thread overrides, and use Default to inherit its configuration. OpenCode's catalog comes from its own CLI on the destination; an empty background-service result is reloaded and retried once. 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. 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 uses the configured Gateway and lifecycle adapter. Codex launches or connects to App Server and can use Codex-managed Sign in with ChatGPT. Claude Code, Pi, and OpenCode use their owning CLI authentication and native session history. SSH destinations run the selected harness in the configured remote corpus path without copying credentials into Celorga. Provider credentials remain in Keychain or their owning harness, never in corpus files.

When iOS relays through a paired Mac, local-agent filesystem permissions come from that Mac's Celorga setting. A headless Celorga server is a separate execution host with its own machine-local localAgentFilesystemAccess configuration; use celorga server permissions to preview or change it, then restart the server. This prevents a desktop Full Access selection from being mistaken for the policy of a different host.

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 compatible harness destination. 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.

Celorga also offers a default-off experimental Paste as Org command in the document Source editor, with local conversion, an editable preview, optional tiny-model structure suggestions, and explicit insertion. See macOS workspace.

The iOS Files tab can resolve local note and heading searches directly, including fuzzy title matches and entry-body matches. It opens rendered entries or complete notes using the bundled shared Celorga runtime, without requiring an agent turn or a paired Mac.

Project notes

Use celorga project list --dir CORPUS --json to discover project notes and celorga project show ID --dir CORPUS --json for a bounded brief and source revision. Projects are ordinary files marked #+ORG2_KIND: project with a file-level :ID:, optional #+PROJECT_COLOR:, and #+PROJECT_THREADS: containing space-separated Celorga chat UUIDs. Their body holds normal actions, decisions, and links. They are independent of agent profiles and goals.

celorga project create --title NAME --dir CORPUS --json previews a new note. Add --description TEXT for a starting brief; empty sections and tasks are not generated. Apply the reviewed result with its --id and --file plus --apply. celorga project adopt PATH --title NAME preserves an existing note's body and file ID. Use --if-revision when adopting or updating across requests. celorga project update ID --thread UUID links a chat; add --remove to unlink. All writes preview by default. Linked source files are not eagerly included; read them through the normal authorized corpus tools when needed.

Live source references

Use celorga embed resolve --target id:STABLE-ID --file notes/host.org --dir CORPUS --json to validate a live note or heading reference. The read-only response supplies a portable #+EMBED: directive and source citation, without copying canonical content. file:relative/note.org embeds a whole note; ID resolution preserves compiled corpus semantics and rejects duplicates. Celorga renders and refreshes these references inside the active corpus. HTML and reading-layout PDF exports keep references without fetching source content, and publish document emits a target-free omission marker. See the Mac workspace guide for the insertion UI and bounded rendering behavior.

Interactive HTML in Celorga

For a diagram, game board, simulation, calculator, or other interactive view directly in AI chat, reply with a completed #+begin_src html block containing HTML, CSS, inline SVG, and inline <script>. The app runs it as a live preview with expandable source, sized to its content; #+begin_src html :height 480 fixes the height instead. Scripts may load libraries, styles, fonts, images, and data over HTTPS. The preview runs in an opaque-origin sandbox, so it cannot read or script the chat, the corpus, local files, or the app; put any corpus data the page needs inline. To keep a page as a durable file, use the reviewed workspace tools to create a .html, .htm, or .xhtml file and link it from chat. Existing files still require a read and SHA-bound replacement preview.