Spec map

Use this mapping when deciding where behavior is defined:

• Language overview and construct requirements: SPEC.org

• Normative surface grammar: GRAMMAR.ebnf

• Parsing precedence, grouping, and AST construction: PARSING.org

• Canonical AST and executable conformance: canonical-ast.schema.json and parsing-cases.json

• Roam semantics (IDs, links, backlinks model): spec/v0/ROAM.org

• CLI/editor workflow behavior: Tooling reference

Headings

• Syntax: one or more stars, a space, then title text.

• Example:

* Project
** Subproject
*** Task

• Heading level is the number of stars.

• Level skips are accepted in v0.

TODO keywords

Headline TODO states parsed into the canonical AST:

• TODO

• IN_PROGRESS

• DONE

• CANCELLED / CANCELED

Workflow tools may accept aliases such as PROG or WAITING and normalize them to one of the canonical TODO keywords above.

Corpus defaults live in org2.json under todo.sequences, for example {"todo":{"sequences":["TODO WAITING | DONE SKIPPED"]}}. Celorga exposes these under Settings → General → TODO States. Each corpus sequence needs an active state and a terminal state; state names must be unique across the corpus sequences. An empty array restores built-in defaults.

Files may also declare their own Org-compatible vocabulary with #+TODO:, #+SEQ_TODO:, or #+TYP_TODO:. Fast-selection suffixes such as WAITING(w) are recognized and omitted from the stored headline state:

#+TODO: IDEA(i) WAITING(w) | SHIPPED(s)
* WAITING Publish the package

File-local declarations replace the corpus sequences for that file. Without a file-local declaration, parsing, editing, agendas, and compiled context use the nearest corpus configuration.

States before | are active; states after it are terminal (no further action required). Without |, the last keyword is terminal. Multiple declarations define independent sequences. Keywords retain their spelling and case. Built-in states remain available. Declarations inside source/example blocks and drawers do not change the workflow.

Custom states work in TODO mutations, agenda filtering, and Celorga heading controls. Terminal states do not become overdue tasks; reopening clears CLOSED. Shortcut and logging annotations are accepted, but their Emacs-specific interactive prompts/keybindings are not implemented.

Example:

* TODO Ship docs
* IN_PROGRESS Implement parser tests
* DONE Publish changelog

Priority cookies

• Syntax: [#A] style cookie after TODO keyword (or at headline start when no TODO keyword).

* TODO [#A] Critical task

Priority is stored as the dedicated priority headline field. Org's COMMENT headline marker is stored as commented: true while all source bytes still round-trip unchanged.

Tags

• Tags are suffixes at headline end: :tag: or :tag1:tag2:

* TODO Draft docs :docs:website:

Drawers

:PROPERTIES:
:ID: 123e4567-e89b-12d3-a456-426614174000
:EFFORT: 45
:END:

Planning lines

Recognized planning keywords:

• SCHEDULED:

• DEADLINE:

• CLOSED:

SCHEDULED: <2026-02-21 Sat>
DEADLINE: <2026-02-25 Wed>
CLOSED: [2026-02-20 Fri]

Timestamps

Supported timestamp forms:

• Active: <2026-02-21 Sat>

• Inactive: [2026-02-21 Sat]

• With time: <2026-02-21 Sat 09:30>

• Ranges: <2026-02-21 Sat>--<2026-02-23 Mon>

• Repeaters (agenda projection): +1w, ++1m, .+2d

Lists

• Unordered markers: -, +, *

• Ordered markers: 1., 1)

• Checkboxes: [ ], [X], [x], [-]

• Cycle a list checkbox with celorga checkbox --file FILE --line N --apply: [ ] → [-] → [X] → [ ]. The CLI and LSP code action change only the selected marker; see Tooling reference.

• Checkbox progress cookies: [n/m] and [p%] may appear in headings or list items; [/] and [%] are empty placeholders. Compile output and lint compare each cookie with its innermost containing heading total. Checked items count as completed; unchecked and indeterminate items count only toward the total. celorga checkbox fix-cookies --file FILE --apply writes corrected values, while celorga checkbox cycle --file FILE --line N --fix-cookies --apply changes a marker and refreshes cookies atomically.

• Nested lists via indentation.

• Counter cookies such as [@3] are stored separately from the written ordered-list marker.

• Descriptive items use term :: definition and render as description lists.

Links

Supported link forms:

• Bracket links: [[https://example.com][label]]

• Plain URLs: https://example.com

• File links: [[file:path/to/file.org]]

• ID links: [[id:UUID][label]] (roam-style link)

• Wiki links: [[Node Title]] (roam-style link)

• Angle links: <mailto:hello@example.com>

• Targets: <<name>> and radio targets <<<name>>>

Both ID links and Wiki links are first-class in Celorga roam workflows.

Link abbreviations are supported with built-ins, config, and #+LINK directives.

Built-in abbreviations:

• gh: → https://github.com/%s

• gl: → https://gitlab.com/%s

• yt: → https://www.youtube.com/watch?v%s=

• wiki: → https://en.wikipedia.org/wiki/%s

You can add/override abbreviations in org2.json:

{
  "links": {
    "linearTeam": "acme",
    "abbreviations": {
      "linear": "https://linear.app/acme/issue/%s",
      "gh": "https://github.example.com/%s"
    }
  }
}

And define file-local abbreviations with Org-compatible syntax:

• Define: #+LINK: linear https://linear.app/acme/issue/%s

• Use: [[linear:APP-3718][APP-3718]] or [[linear:APP-3718]]

Precedence (highest to lowest):

1. file-local #+LINK

2. org2.json links.abbreviations

3. built-ins

Celorga expands abbreviation targets when rendering/exporting and for LSP document-link targets.

Corpus identity

The root org2.json may identify the corpus independently of its local path:

{
  "corpus": {
    "schema": "org2:corpus:v1",
    "id": "team-operations",
    "name": "Team Operations",
    "kind": "shared"
  }
}

id is a stable lowercase slug, name is the human-facing label, and kind is personal, shared, or project. This record is portable. Local mount paths, credentials, and membership stay outside the corpus. See Shared corpora and collaboration and spec/v0/corpus.schema.json.

Inline emphasis

• Bold: *bold*

• Italic: /italic/

• Underline: _underline_

• Strike: +strike+

• Verbatim: =verbatim=

• Code: ~code~, with Markdown-style `code` accepted as shorthand

Rich inline objects

Celorga also parses the everyday publishing and scholarly inline objects used by Org:

• Footnote references: [fn:label], [fn:label:inline definition], and [fn::anonymous definition]

• Citations: [cite:@key] and multi-reference/style forms such as [cite/t:@doe; see @roe p. 4]

• Entities: \alpha, \copy, \rarr, and other common Org entities

• LaTeX fragments: $x_2$, $$x = y$$, \(...\), and \[...\]

• Export snippets: @@html:<mark>highlighted</mark>@@

• Subscripts and superscripts: H_2O and x^{2}

• Explicit line breaks: two backslashes at the end of a line

These are first-class canonical AST objects and render in the CLI, published HTML, and Mac/iOS document views. Export snippets are emitted as raw HTML only by the publishing renderer; app previews escape their payload.

Footnote definitions use the ordinary Org form:

The claim has a source.[fn:source]

[fn:source] Supporting detail.

Blocks

Recognized block forms include:

• Source blocks: #+begin_src ... #+end_src

• Example blocks: #+begin_example ... #+end_example

• Quote blocks: #+begin_quote ... #+end_quote

• Verse blocks: #+begin_verse ... #+end_verse

• Center blocks: #+begin_center ... #+end_center

• Comment blocks: #+begin_comment ... #+end_comment

• Arbitrary special blocks: #+begin_NAME ... #+end_NAME

• Dynamic blocks: #+begin: NAME ... #+end: (parsed and preserved; Celorga does not execute dynamic-block writers)

• LaTeX environments: \begin{equation} ... \end{equation}

• Fixed-width lines beginning with a colon followed by one space

• Horizontal rules of five or more hyphens

• Diary sexps beginning with %%(

```ts
const x = 1
```

#+begin_src ts
const x = 1
#+end_src

celorga fmt --stdin --canonical-org
celorga fmt --file note.org --apply

Tables

• Pipe table rows: | a | b |

Celorga defines the custom link type color: as explicit, non-navigating presentation markup. Use [[color:red][urgent]] for foreground color, [[color:bg=yellow][review]] for background color, or [[color:fg=white;bg#b42318][blocked]]= for both. Keys may be abbreviated as fg=bg= or written as =foreground=background; text is also accepted for foreground. Values may be supported names or three/six-digit hex literals.

The portable named palette is black, blue, brown, gray/grey, green, indigo, mint, orange, pink, purple, red, teal, white, and yellow. Hex literals provide exact custom colors without allowing arbitrary CSS.

The binding works anywhere links are parsed, including prose, headings, and table cells. In ordinary inline content, background color applies to the labeled span. When one color binding occupies an entire table cell, rendered clients apply its foreground and background to the whole cell. It remains a normal bracket link in the canonical AST and round-trips byte-for-byte, so standard Org tools preserve the label even when they do not interpret the color: type. Invalid color declarations remain ordinary links rather than accepting arbitrary CSS.

• Horizontal separator rows: |---+---|

• Table content is parsed and preserved. Each row retains compatible raw cells strings and also exposes parallel structured contents inline objects.

Org table formulas are attached to their preceding table as structured TableFormulaLine nodes and can be recalculated safely:

| item | qty | price | total |
|------+-----+-------+-------|
| A    |   2 |  3.50 |       |
| B    |   4 |  2.00 |       |
#+TBLFM: $4=$2*$3;%.2f

celorga table recalculate --file report.org previews the changed cells; add --apply to write them atomically. The Mac rendered view evaluates supported formulas for display and offers the same explicit recalculation action for editable files. HTML export uses the shared evaluator without rewriting source.

The safe formula subset includes field, row, column, and rectangular-range assignments; absolute and relative @row$column references; A1 references; arithmetic, comparisons, and boolean operators; vsum, vmean, vmin, vmax, vmedian, vcount, common numeric functions; printf/Calc-style numeric formats; and T, U, and t duration modes. Later assignments override earlier assignments for the same cell. Empty-field N mode is supported. Formula lines, including unsupported forms, remain lossless.

Celorga deliberately does not execute Emacs Lisp formulas, remote-table references, or arbitrary Calc extensions. An unsupported or invalid formula produces a diagnostic and leaves the source unchanged rather than partially updating a table.

Deliberate compatibility boundary

Celorga now covers most Org syntax used for notes, planning, publishing, linking, and scholarly prose. It deliberately does not implement macro expansion, Babel execution, inline source/call evaluation, or dynamic-block execution. Inline tasks remain ordinary deep headlines rather than a separate execution construct. Unsupported execution-oriented forms remain losslessly preserved as text or directives.

Tables, source blocks, and common blocks can carry adjacent affiliated keyword metadata:

#+name: quarterly_revenue
#+chart: line x=quarter y=revenue
#+dataset: finance.revenue
| quarter | revenue |
|---------+---------|
| 2026-Q1 | 1200    |

Recognized affiliated keys include NAME, CAPTION, PLOT, CHART, DATASET, VIEW, RESULTS, HEADER/HEADERS, and ATTR_* keys. The parser preserves them on the following table or block as affiliatedKeywords for chart renderers, dataset indexes, SQL views, and exporters.

Canonical .org documents use an adjacent chart source block:

#+name: fetch_buckets
| bucket | fetches |
|--------+---------|
| 0-10   | 14      |
| 11-50  | 32      |

#+begin_src chart histogram
x: bucket
y: fetches
sort: y-desc
source: previous-table
#+end_src

This is chart metadata over the preceding table. Chart source blocks may also point at a named table or materialized result elsewhere in the same note; fenced chart input remains accepted as typing sugar:

#+name: package_fetches_result
#+results: query-fetches-by-company
| day        | fetches |
|------------+---------|
| 2026-06-10 | 84      |

#+name: package_fetches_chart
#+begin_src chart line
x: day
y: fetches
source: package_fetches_result
size: compact
height: 300
interactive: true
#+end_src

The current renderer supports bar, line, and bucketed histogram charts over the previous table or a named table source. Add sort: x-asc, sort: x-desc, sort: y-asc, or sort: y-desc when the visual should order marks independently of the table's source row order. size accepts compact, medium, or wide. height accepts 220–720 pixels and defaults according to the size preset. interactive defaults to true; in the Mac app's documents and AI chat it enables nearest-point hover, exact-value tooltips, a crosshair, keyboard navigation between marks, and legend toggling that hides or shows a series (the last visible series stays). Static SVG remains the canonical CLI and export fallback.

A chart block may also carry its own data: table rows written inside the block are used instead of the previous table, which keeps a chart self-contained in a chat reply or a short note. An explicit source: still wins.

#+begin_src chart bar
x: package
y: downloads
| package | downloads |
|---------+-----------|
| alpha   | 1200      |
| beta    | 800       |
#+end_src

Line and bar charts may render multiple numeric columns against the same x-axis. List the columns in y (or series inside a chart source block), separated by commas:

#+name: quarterly_metrics
| quarter | revenue | cost | profit |
|---------+---------+------+--------|
| 2026-Q1 | 1200    | 700  | 500    |
| 2026-Q2 | 1500    | 825  | 675    |

#+begin_src chart line
x: quarter
y: revenue, cost, profit
source: quarterly_metrics
#+end_src

Each line receives a stable color from the --org2-chart-mark and --org2-chart-series-2 … --org2-chart-series-8 style variables, which Celorga sets from the selected light or dark theme, and grouped bar charts place each series beside the others within its x-axis category. Multi-series charts include a legend, series-aware accessibility labels, and series names in interactive tooltips. A y-asc or y-desc sort uses the first listed series. Histograms remain single-series because each row already represents one bucket.

Charts are drawn in a clean, modern style. Lines are smooth (monotone, so they never overshoot the data); a one- or two-series line chart gets a soft gradient fill; and each line ends in a dot labeled with its latest value, with the series name when there are several. Line charts fit the value axis to the data rather than always starting at zero, while bar charts always include zero and label each bar when there is room. Axis labels stay horizontal: long category names are shortened (the full name stays available as a tooltip) or thinned out. Values use compact units such as 95.9k or 24M; a currency prefix appears when every cell starts with $ or the column name contains usd, and a percent suffix appears when every cell ends in % or the name contains pct or percent. Cells such as $1,200 and 12% are read as numbers. Tooltips show the full value, for example $95,880.

The Mac app treats chart interaction as app-owned presentation behavior. Notes cannot provide arbitrary JavaScript. Chart cards can also be resized horizontally in the rendered view; use size and height when the desired dimensions should remain deterministic in source.

Chart SVG uses CSS custom properties with opinionated defaults: --org2-chart-mark, --org2-chart-series-2 through --org2-chart-series-8, --org2-chart-surface, --org2-chart-axis, --org2-chart-grid, --org2-chart-label, and --org2-chart-title. The first series retains --org2-chart-mark for compatibility. Set them on .org2-chart in a published stylesheet or the Mac app's .org2/app.css to customize the visual theme without changing the data declaration.

The CLI can render chart-affiliated tables directly:

celorga render-chart --file report.org --block-id quarterly_revenue --format svg

Local datasets and SQL views

Celorga can describe local/ad hoc data workflows with dataset and sql source blocks. Equivalent fences remain accepted as typing sugar. This is intended for notebook-like reports over explicit local files, read-only URLs, and named Org tables, with DuckDB as the first execution bridge:

#+begin_src dataset fetches
type: csv
path: ./data/package-fetches.csv
engine: duckdb
#+end_src

#+begin_src sql results=fetches_by_state artifact=views/fetches_by_state.org freshness=24h
SELECT state, count(*) AS fetches
FROM fetches
GROUP BY state
ORDER BY fetches DESC
#+end_src

#+begin_src chart bar
source: fetches_by_state
x: state
y: fetches
#+end_src

celorga query-data reads these blocks, creates DuckDB views for local files, URL-backed sources, named celorga tables, or configured remote analytics datasets, creates declared SQL views, runs a selected SQL result block through the local DuckDB CLI, and materializes the returned rows as a named org table or JSON envelope. Materialized org tables include a #+query-data: provenance line with the result id, row count, optional freshness token, selected SQL hash, full DuckDB script hash, and ran_at timestamp:

celorga query-data --file report.org --results fetches_by_state --out report.fetches.org
celorga query-data --file report.org --results fetches_by_state --apply
celorga query-data --file report.org --line 42 --format json
celorga query-data --file report.org --inspect --include-script
cat report.org | celorga query-data --stdin --results fetches_by_state --format json

Use --stdin when an editor, agent, or notebook-style client wants to run the current buffer without saving it first. Use --line N to select the SQL result block containing or after the cursor line. JSON output includes resultBlocks with each available SQL result id and source range. Use --inspect to return parsed datasets, SQL views, result metadata, diagnostics, and selected-query provenance without running DuckDB; --include-script also returns generated DuckDB SQL. Relative file paths are resolved from the working directory for stdin input. SQL result ids must be unique, and dataset ids and SQL view ids must be distinct because they become DuckDB relation names. Local URL/table datasets may carry metadata-only credential/config references such as env:SCARF_API_TOKEN or profile:product-analytics; remote analytics datasets use their named profile operationally but never insert credentials into generated SQL. Inline bearer tokens, passwords, and other literal secrets are rejected. SQL result blocks can include artifact=PATH and freshness=24h / ttl=24h / max-age=24h metadata. Executed results stamp ranAt so clients can evaluate freshness.

Use sql view=NAME when a report needs a reusable local projection before the final result table:

#+begin_src sql view=california_fetches
SELECT state, fetches
FROM fetches
WHERE state = 'CA'
#+end_src

#+begin_src sql results=fetches_by_state
SELECT state, sum(fetches) AS fetches
FROM california_fetches
GROUP BY state
#+end_src

Use url: instead of path: when DuckDB should read a declared HTTP(S) or file: URL directly:

#+begin_src dataset remote_fetches
type: csv
url: https://data.example.test/package-fetches.csv
engine: duckdb
credential: env:SCARF_API_TOKEN
config: profile:product-analytics
#+end_src

#+begin_src sql results=remote_fetches_by_state
SELECT state, count(*) AS fetches
FROM remote_fetches
GROUP BY state
#+end_src

{
  "dataSources": {
    "scarf-clickhouse": {
      "type": "clickhouse",
      "url": "https://clickhouse.example.com/",
      "database": "analytics",
      "userEnv": "SCARF_CLICKHOUSE_USER",
      "passwordEnv": "SCARF_CLICKHOUSE_PASSWORD",
      "timeoutMs": 300000,
      "maxRows": 10000
    },
    "scarf-metabase": {
      "type": "metabase",
      "url": "https://metabase.example.com/",
      "apiKeyEnv": "SCARF_METABASE_API_KEY",
      "databaseIdEnv": "SCARF_METABASE_DATABASE_ID",
      "timeoutMs": 300000,
      "maxRows": 10000
    }
  }
}

#+begin_src dataset package_fetches
type: clickhouse
profile: scarf-clickhouse
query: |
  SELECT toDate(timestamp) AS day, count() AS fetches
  FROM package_downloads
  WHERE timestamp >= now() - INTERVAL 30 DAY
  GROUP BY day
  ORDER BY day
#+end_src

#+begin_src dataset revenue
type: metabase
profile: scarf-metabase
question: 123
parameters: |
  []
#+end_src

#+begin_src dataset recent_organizations
type: metabase
profile: scarf-metabase
query: |
  SELECT name, billing_email, created_at
  FROM organizations
  ORDER BY created_at DESC
  LIMIT 25
#+end_src

#+begin_src sql results=recent_organizations sources=recent_organizations_source freshness=24h
SELECT * FROM recent_organizations_source
ORDER BY created_at DESC
#+end_src

#+name: raw_fetches
| state | fetches |
|-------+---------|
| CA    | 42      |
| NY    | 24      |

#+begin_src dataset fetches
type: table
source: raw_fetches
engine: duckdb
#+end_src

#+begin_src sql results=fetches_total
SELECT sum(fetches) AS fetches
FROM fetches
#+end_src

Presentations

Celorga can compile an Org-shaped outline into a backend-neutral presentation model and render that model as Beamer LaTeX or PDF:

celorga export beamer --file talk.org
celorga export beamer --file talk.org --out talk.tex --apply
celorga export beamer --file talk.org --out talk.pdf --pdf --apply

Export previews by default. --pdf invokes pdflatex twice; use --latex-engine COMMAND to select another installed LaTeX engine.

For pdfLaTeX compatibility, common Unicode arrows, comparison operators, checkmarks, bullets, dashes, and related symbols are translated to equivalent LaTeX commands in prose, headings, metadata, and literal/source blocks. This includes symbols such as →, ↘, ≥, and ✓ that pdfLaTeX's default UTF-8 layer does not define directly.

The frame level defaults to 2 and follows the familiar Org convention in #+OPTIONS: H:2: level-one headlines become sections and level-two headlines become slides. #+ORG2_SLIDE_LEVEL:, #+SLIDE_LEVEL:, and legacy #+BEAMER_FRAME_LEVEL: can set the level explicitly. toc:t adds an outline frame.

A minimal talk is ordinary Org-shaped text:

#+TITLE: Shipping a local-first compiler
#+AUTHOR: Example Speaker
#+OPTIONS: H:2 toc:t
#+BEAMER_THEME: Madrid

* Why
** Plain text is the interface
- Reviewable in Git
- Editable anywhere
- One source → slides, sites, and agent context

* How
** Shared semantics
The compiler parses once and renders each target from the same structure.

Document metadata and Beamer compatibility keywords include:

• #+TITLE:, #+AUTHOR:, #+DATE:

• #+LATEX_CLASS_OPTIONS:

• #+BEAMER_THEME:, #+BEAMER_COLOR_THEME:, #+BEAMER_FONT_THEME:

• #+BEAMER_INNER_THEME:, #+BEAMER_OUTER_THEME:

• repeatable #+LATEX_HEADER: and #+BEAMER_HEADER:

Headlines below a slide become presentation groups. Legacy properties remain accepted so existing Org Beamer talks can move over incrementally:

The :B_note: tag is also accepted for legacy notes. Source blocks make their frame fragile. Lists, nested blocks, quotes, tables, links, inline emphasis, images, and #+ATTR_LATEX image sizing render through the shared syntax tree. A #+RESULTS: image immediately following a source block is omitted from Beamer output, matching Org's default code-export behavior.

Backend-specific escape hatches remain explicit and reviewable:

#+LATEX: \pause

#+BEGIN_EXPORT beamer
\vfill
#+END_EXPORT

Relative image paths resolve from the source file's directory during PDF compilation. Unknown slide environments produce warnings rather than being silently discarded.

The macOS Workspace exposes the same pipeline as an embedded View → Slides PDF preview, including live compilation from an unsaved source-editor draft, and through File → Export Slides as PDF… and File → Export Slides as LaTeX…. See macOS Workspace → Slide preview and export for the application workflow and troubleshooting.

Keyword/directive lines

Celorga parses keyword lines in #+KEY: VALUE form.

Commonly used in export/publish:

• #+TITLE:

• #+SUBTITLE:

• #+AUTHOR:

• #+DATE:

• #+DESCRIPTION:

• #+KEYWORDS:

• #+LANGUAGE:

• #+HTML_HEAD:

• #+LATEX_CLASS_OPTIONS:

• #+LATEX_HEADER:

• #+BEAMER_THEME:

• #+ID:

Unknown directives are preserved for round-tripping.

Comments

• Line comments: lines beginning with #.

• Comment blocks are also supported (see Blocks).

Losslessness goal

Celorga aims for practical round-tripping of supported constructs. When behavior is ambiguous, defer to the current implementation and spec fixtures.