journal add

Stage a new journal entry locally. It will live in ~/.doraval/pending/<project>/ until you run sync.

The absolute lowest-effort form (the happy path for humans and for agents calling dora) is just the title:

doraval journal add "We decided to always use 'update' for cache refreshes"

pushback, tags, and rationale are now optional. When omitted, journal add supplies sensible defaults (pushback=5, tags=[], rationale seeded from the title). A warning is printed for the relaxed fields so you know.

Three ways to add (pick the one that matches your situation)

1. Minimal / magic (recommended for quick capture) — just the title. If you ran dora init and configured a coding agent, dora will use that agent on the fly (via its native prompt tool + a documented scaffold) to produce rich pushback/tags/rationale. Otherwise it uses the defaults above.

   doraval journal add "Task that just happened"

2. Agent / structured (the 90% agent use case) — give dora a JSON blob (or pipe it). This is what the “on the fly” internal call ultimately does, and what you use when you have an outer agent produce the entry via its own claude -p ... --output-format json + the prompt scaffold.

   doraval journal add --json '{
     "title": "Use update not refresh for cache",
     "pushback": 6,
     "tags": ["cli", "docs"],
     "rationale": "Keeps the mental model consistent with sync being the publisher.",
     "author": "agent:claude-code"
   }'

   Or via stdin / pipe:

   echo '{"title":"...","pushback":5,"tags":["ux"],"rationale":"..."}' | doraval journal add --json -

3. Explicit / power-user — full flags (still fully supported, no magic, no agent call).

   doraval journal add "Use 'update' not 'refresh' for cache pulls" \
     --pushback 6 \
     --tags cli,docs \
     --rationale "Keeps the mental model consistent with 'sync' being the publisher."

Options (all optional except in the explicit style)

Flag	Description
TITLE (positional)	The decision in one sentence. The only thing most callers need to type.
-b, --pushback	1–10. Optional (default 5 when using the relaxed path).
-t, --tags	Comma-separated tags (renamed from —scope). Optional (default [] in relaxed path). Useful for both decisions and general notes. Valid: naming, cli, architecture, testing, ux, api, docs. (Legacy —scope still accepted for CLI compat.)
-a, --author	Default “human” (agents should use “agent:yourname”).
--status	active (default)
-r, --rationale	Short one-line rationale on the CLI. For long/rich markdown bodies use --raw-markdown <file-or-> (or --json).
-p, --project	Project name (defaults to directory mapping from config).
-j, --json	Full entry as JSON (or ”-” for stdin). Highest precedence.
--raw-markdown	Path to a raw markdown file (or ”-” for stdin) to use as the entry body after the YAML metadata block. Title can be supplied positionally or extracted from the first ”# Heading”. Bypasses agent enrichment. Perfect for long-form notes and rich documents.

The entry is written as a single Markdown file with a ## Title heading, a fenced YAML block, and the body (rationale or raw markdown you provided). The YAML always reflects the final values that were used (defaults, agent output, or explicit flags). Long bodies supplied via —raw-markdown or —json are preserved exactly.

What happens next

• The file is placed in ~/.doraval/pending/<project>/.
• Run doraval journal sync to publish it to the remote repo (and clear the pending directory).
• Until synced, it is invisible to list and other machines.

See journal sync and the single-writer pattern explanation.

Long-form / raw markdown notes

For long notes, research write-ups, design documents, or any rich markdown you want to capture “as is”, use --raw-markdown:

# File that starts with a heading (title is auto-extracted)
dora journal add --raw-markdown ./research/long-note.md --tags notes,research --pushback 1

# Explicit title + raw body from file
dora journal add "Meeting notes 2026-06" --raw-markdown ./notes/meeting.md --tags notes

# From stdin (great with heredoc or pipes)
cat <<'MD' | dora journal add --raw-markdown -
# Architecture Decision: Use raw-markdown for long notes

This note contains **rich** formatting, lists, and code.

- Point one
- Point two

```ts
// example
const x = 1;

MD

The provided markdown becomes the body after the journal's YAML metadata block. The entry remains a first-class journal item (with tags, pushback, author, etc.) while the long content is stored verbatim.

(For fully structured control from scripts/agents, `--json` with a long `"rationale"` string is still available.)

## Related

- [journal list](/commands/journal-list)
- [journal sync](/commands/journal-sync)
- [journal update](/commands/journal-update)

Full mental model: [How the Agent Journal Works](/concepts/journal-rationale).