Your AI, in your vault. Not the other way around.

Once Jotura is installed, confirm the CLI is on your PATH:

jotura --version

That's it — vaults are plain folders of markdown files, so every command works immediately. No passphrase, no unlock step, nothing to configure before your agent can read and edit notes.

On macOS, the installer ships the CLI inside Jotura.app — open Settings → Command-line tool and click Install to symlink it to /usr/local/bin/jotura. On Windows and Linux (deb), the installer puts it on PATH automatically. On the Linux AppImage, the first launch offers to copy it to ~/.local/bin.

---
name: jotura-vault
description: Use this skill to read, search, or edit notes in the user's Jotura markdown vault. Triggers on explicit mentions of "Jotura", "my vault", "my notes", "my journal", "daily note"; questions whose answer lives in personal notes ("what did I write about X", "find that meeting note", "add Y to today's note"); requests to create, rename, delete, tag, or modify any note. Vault files are plain .md files on disk and MAY be edited directly, but the `jotura` CLI is the preferred, safe interface — it provides hash-CAS conditional writes, strict unique-match replaces, frontmatter-preserving edits, and search/trash/sync-consistent operations that raw sed/awk edits cannot. Do NOT use this skill for editing files outside the user's vault.
---

# Jotura vault

The user keeps their notes in a Jotura markdown vault — a plain directory of `.md` files (plus imported documents). You access it through the `jotura` CLI binary (`~/.cargo/bin/jotura`), which uses the same Rust core as the Jotura desktop app and guarantees atomic writes, round-trip Markdown fidelity, and hash-based conflict detection. Cloud sync (when the user has enabled it) is end-to-end encrypted, but on disk everything is plaintext — there is nothing to unlock.

The user often runs the Jotura desktop app concurrently. The CLI and desktop coordinate automatically — the desktop's file watcher picks up any change you make within ~1 second, and the CLI's `--if-hash` checks protect you from clobbering the desktop's writes.

You MAY read vault files directly (`cat`, `grep`, editors), but prefer the CLI for every mutation: it enforces unique-match replaces, preserves frontmatter, writes atomically, and honors `--if-hash` concurrency checks.

## Before you do anything

Run `jotura status --json` first (or `jotura doctor --json` for a deeper health check). It returns one of:

```json
{"vault": "/path/to/vault", "noteCount": 247, "sync": {"enabled": true, "keyCached": true, "paused": false}}
{"error": {"code": "NoVault", ...}}
```

- A `vault` path → you can proceed. Data commands never need a password.
- `NoVault` → ask the user to set `JOTURA_VAULT=/path/to/vault` in their shell, pass `--vault` to commands, or open a vault in the desktop app first.
- The `sync` block is informational: `enabled: false` means the vault is local-only; `keyCached: false` on a sync-enabled vault means uploads are paused until the user provides their sync password (`jotura sync login`, or unlock in the desktop). Reads and writes always work regardless.

## The canonical safe-edit workflow

Every edit should follow this pattern. The `--if-hash` check stops you from clobbering work the user did in the desktop app, in another CLI invocation, or that arrived via sync.

```sh
# 1. Read with a hash
HASH=$(jotura read "<path>" --json | jq -r .hash)

# 2. Edit using the hash as a precondition
jotura edit "<path>" \
  --replace "<exact old text>" \
  --with "<new text>" \
  --if-hash "$HASH"
```

If exit code is 2 (`HashConflict`), the file changed under you. The error JSON now includes a `currentVsIntended` unified-diff between what's on disk *right now* and what you were about to write, so you can decide whether to retry, merge, or abandon without re-reading:

```json
{
  "code": "HashConflict",
  "path": "notes/today.md",
  "expectedHash": "...",
  "actualHash": "...",
  "currentVsIntended": "@@ -1,3 +1,3 @@\n line 1\n-current line\n+intended line\n line 3\n"
}
```

### Previewing edits with `--dry-run`

Every mutating command (`write`, `edit`, `create`, `rename`, `delete`, `frontmatter set/delete`, `tag add/remove`, `batch`) accepts `--dry-run`. The command computes exactly what it would write, prints a structured preview, and does NOT touch disk or manifest. Use this when you're not sure an edit will hit the right text:

```sh
jotura edit notes/today.md \
  --replace "TODO" --with "DONE" --dry-run --json
# → { "dryRun": true, "currentHash": "...", "newHash": "...",
#     "changes": 1, "preview": { "kind": "replace", "before": "TODO", "after": "DONE" } }
```

Exit codes still fire as expected — a dry-run that *would have* failed with `HashConflict` (code 2) or `Ambiguous` (code 4) returns the same error without writing anything.

### Seeing the diff with `--diff`

Every mutating command also accepts `--diff`. The JSON output gets an extra `"diff"` field containing a standard unified-diff between the current and new content (3 lines of context, `---`/`+++`/`@@` headers). Combine with `--dry-run` to preview without writing:

```sh
jotura edit notes/today.md --replace "TODO" --with "DONE" --diff --dry-run --json
# → { ..., "diff": "@@ -3,3 +3,3 @@\n line a\n-TODO\n+DONE\n line c\n" }
```

For `create`, `rename`, and `delete` the diff is structural (a `(file renamed)` / `(file created)` / `(file deleted)` marker block) rather than a real text diff — there's no old-vs-new body to compare.

## Reading

```sh
# Body only (most common)
jotura read inbox/today.md

# With line numbers — needed when planning a line-based edit
jotura read inbox/today.md --numbered

# Structured: { path, hash, frontmatter, body, lineCount }
jotura read inbox/today.md --json

# Include the YAML frontmatter block
jotura read inbox/today.md --with-frontmatter
```

## Finding notes

```sh
# Full-text search across all notes (uses Tantivy; rebuilds index per call)
jotura search "deadline next week" --json

# Restrict results to a path prefix
jotura search "deadline" --in projects/ --json

# Filename-only fuzzy match — much faster than search
jotura quick-open "meeting" --json

# List all notes
jotura ls --json

# List notes in a folder
jotura ls --folder projects --json
```

### Exact-match search with `grep`

`jotura grep <pattern>` runs a regex over every note body. It's the
right tool when you need exact, predictable matches — `search` is fuzzy /
ranked and `quick-open` only looks at filenames.

```sh
# basic regex match — output is path:line:matched-text per match
jotura grep 'TODO[:\s]'

# case-insensitive
jotura grep --ignore-case 'unicorn'

# whole-line match
jotura grep --line-regexp '^# Daily'

# whole-word match
jotura grep --word-regexp 'jot'

# restrict to a folder via include glob
jotura grep 'TODO' --include 'inbox/*'

# only paths that contain a match
jotura grep 'TODO' --files-with-matches

# count matches per file
jotura grep 'TODO' --count

# stop after N matches per file
jotura grep 'TODO' --max-count 3

# JSON output: [{ path, line, lineText, matchedText }]
jotura grep 'TODO' --json
```

Flags: `-i`/`--ignore-case`, `-x`/`--line-regexp`, `-w`/`--word-regexp`,
`-c`/`--count`, `--max-count N`, `--include GLOB`, `--exclude GLOB`,
`-l`/`--files-with-matches`, `-L`/`--files-without-match`.

Templates (`.jotura/templates/`) and trashed notes are excluded
automatically. Cost: every note matching `--include` is read and
scanned — sub-second for a few thousand notes, several seconds for 10k+.
For fuzzy/ranked text search use `search`; for filename lookup use
`quick-open`.

## Finding links between notes

```sh
# List notes that link TO this path (backlinks)
jotura backlinks inbox/today.md --json

# List links inside a note (outgoing)
jotura links projects/x.md --json

# Cap results
jotura backlinks inbox/today.md --limit 20
```

Two link syntaxes are recognized:

- **Wikilinks:** `[[target]]` and `[[target|display text]]`
- **Markdown links:** `[display](target.md)` (the target must end in `.md`)

`#anchor` suffixes (`[[foo#heading]]`, `[foo](foo.md#h)`) are stripped
before matching.

Target resolution rules, tried in order:

1. **Exact path match.** `[[inbox/today.md]]` and `[[inbox/today]]` both
   match the note at `inbox/today.md`.
2. **Filename match.** `[[today]]` matches every note whose filename is
   `today.md`, regardless of folder. If two notes share a filename in
   different folders, *both* show up as backlinks for either one.

Title-based resolution (matching frontmatter `title:`) is **not**
implemented in v1.

Implementation: both commands scan every note per invocation —
brute force, no persistent index. Sub-second for typical vaults; expect
seconds for 10k+ notes.

## Working with documents

The vault holds two kinds of files: **notes** (`.md`, edited directly) and
**documents** (PDFs, Word docs, spreadsheets, images, anything else). Documents
are stored as plain files just like notes, but their bytes aren't searchable
on their own. So each document gets a **searchable markdown mirror** in the
md_store at `.md_store/<original-path>.<ext>.md` — produced by a bundled
converter. The mirror is a normal note carrying the converted text; the
original document stays untouched.

The md_store is excluded from `ls`, `quick-open`, and plain `search`, so it
never clutters note-level results.

```sh
# Import a document. Defaults to attachments/, then generates the md_store mirror.
jotura import ~/Downloads/contract.pdf --json
# → { "path": "attachments/contract.pdf", "contentHash": "...", "size": 12345,
#     "mdStorePath": ".md_store/attachments/contract.pdf.md", "converted": true }

# Choose a folder, or an explicit full vault path:
jotura import ~/Downloads/contract.pdf --folder projects/acme --json
jotura import ~/Downloads/contract.pdf --as projects/acme/signed-contract.pdf --json

# Import bytes from stdin (--as is required):
cat report.pdf | jotura import - --as attachments/report.pdf --json

# Skip mirror generation (store only the document itself):
jotura import data.bin --no-convert --json

# List documents with their conversion status:
jotura ls-documents --json
# → [{ "path": "attachments/contract.pdf", "size": 12345,
#      "hasMdStore": true, "conversionOk": true }]

# Regenerate mirrors (after editing a document, or to retry a failed conversion):
jotura regenerate-md-store attachments/contract.pdf --json
jotura regenerate-md-store --all --json
jotura regenerate-md-store --stale-only --json   # only the ones that need it
```

If the converter isn't installed yet, `import` still succeeds: it writes a stub
mirror with `converted: false` and a `note` field saying conversion was
deferred. The mirror self-heals once a converter is present (`regenerate-md-store
--stale-only`).

Need the raw bytes of a document? It's a plain file — read it straight from
the vault directory (`<vault>/attachments/contract.pdf`).

## Searching documents

When the user asks to search their documents (PDFs, Word docs, spreadsheets,
etc.) — as opposed to their notes — use `jotura search-documents <query>`. It
searches the markdown representations in the md_store and returns the ORIGINAL
document paths. Do NOT use plain `jotura search` for documents; that searches
notes and excludes the md_store. Do NOT try to read PDF/docx bytes directly;
read the converted markdown via `jotura read .md_store/<path>.<ext>.md` or rely
on search-documents snippets.

```sh
jotura search-documents "quarterly revenue" --json
# → [{ "documentPath": "attachments/q3-report.pdf",
#      "mdStorePath": ".md_store/attachments/q3-report.pdf.md",
#      "title": "q3-report", "snippet": "...quarterly <mark>revenue</mark>...",
#      "score": 0.92 }]
jotura ls-documents --json
jotura read ".md_store/attachments/q3-report.pdf.md"   # read the converted text
```

`search-documents` returns the original `documentPath` (e.g.
`attachments/q3-report.pdf`), not the `.md_store/...` mirror path — so you can
hand it straight back to the user or read the file directly.

## Editing — string-based (preferred)

This is the safest primitive. Strict by default: fails if the old text isn't unique. Mirrors Claude Code's own `Edit` tool semantics.

```sh
# Single targeted change — fails with code 4 if "TODO: reply to alice" appears more than once
jotura edit notes/today.md \
  --replace "TODO: reply to alice" \
  --with "DONE: replied to alice" \
  --if-hash "$HASH"

# Replace every occurrence (use when you mean it)
jotura edit notes/today.md --replace "TODO" --with "DONE" --all

# Replace the Nth occurrence (1-indexed) — use when --replace returns code 4 (Ambiguous)
jotura edit notes/today.md --replace "TODO" --with "DONE" --nth 2
```

When `--replace` fails with exit code 4 (`Ambiguous`), stderr JSON includes `lineHits: [12, 47, 83]`. Use those numbers to pick the right `--nth`, or extend the old-text to include enough surrounding context that it becomes unique.

## Editing — line-based (when string matching doesn't fit)

Get the line numbers from `jotura read --numbered` first. Line numbers are 1-indexed and refer to the **body** of the note (frontmatter is stripped from the count).

```sh
jotura edit notes/today.md --replace-line 12 --with "new content for line 12"
jotura edit notes/today.md --replace-lines 12:15 --with "new\nmulti-line\ncontent"
jotura edit notes/today.md --insert-after 12 --content "new line inserted"
jotura edit notes/today.md --insert-before 1 --content "new first line of body"
jotura edit notes/today.md --delete-lines 12:15
jotura edit notes/today.md --append --content "appended at end"
jotura edit notes/today.md --prepend --content "prepended after frontmatter"
```

`--content` is also readable from stdin: `echo "stuff" | jotura edit ... --insert-after 5`.

## Editing — multi-edit in one call

`jotura edit ... --apply <FILE>` (or `-` for stdin) takes a JSON array of edit ops and applies them **sequentially to the evolving content**. One `--if-hash` precondition covers the whole batch; the final result is committed in a single atomic write.

```sh
cat > /tmp/edits.json <<'JSON'
[
  {"kind": "replace", "old": "TODO: x", "new": "DONE: x"},
  {"kind": "replace", "old": "TODO: y", "new": "DONE: y", "all": true},
  {"kind": "replace-line", "line": 12, "content": "new line 12"},
  {"kind": "insert-after", "line": 20, "content": "after 20"},
  {"kind": "delete-lines", "start": 25, "end": 27},
  {"kind": "append", "content": "end"}
]
JSON

jotura edit notes/today.md --apply /tmp/edits.json --if-hash "$HASH" --json
# or via stdin:
jotura edit notes/today.md --apply - --if-hash "$HASH" --json < /tmp/edits.json
```

Supported `kind` values: `replace`, `replace-line`, `replace-lines`, `insert-before`, `insert-after`, `delete-lines`, `append`, `prepend`. Field names match the matching CLI flag (`new` instead of `with`).

**Important — line numbers shift as ops apply.** Each op observes the state produced by every prior op. If op 0 deletes lines 1–3, then op 1's `line: 5` refers to what was originally line 8. Plan your edits with this in mind, or use string-based replaces which are stable across shifts.

**Atomic on failure.** If any op fails (`NotFound`, `Ambiguous`, `OutOfRange`), the whole batch aborts with **exit code 11** (`MultiEditOpFailed`) and nothing is written. The error names the op that failed:

```json
{
  "code": "MultiEditOpFailed",
  "opIndex": 2,
  "underlyingCode": "Ambiguous",
  "underlying": { "code": "Ambiguous", "data": { "needle": "...", "lineHits": [12, 47] } }
}
```

## Atomic multi-note changes — `jotura batch`

`jotura batch <FILE>` (or `-`) applies a JSON array of file-level operations across multiple notes. Use this when you want several notes updated together — e.g. "retag five notes and rename one folder" — and want all-or-nothing semantics on the most common failure (hash conflict).

```sh
cat > /tmp/ops.json <<'JSON'
[
  {"path": "inbox/a.md", "op": {"kind": "write",      "content": "...", "ifHash": "..."}},
  {"path": "inbox/b.md", "op": {"kind": "edit",       "apply": [{"kind":"replace","old":"x","new":"X"}], "ifHash": "..."}},
  {"path": "inbox/c.md", "op": {"kind": "create",     "parent": "inbox", "name": "c.md"}},
  {"path": "old/d.md",   "op": {"kind": "rename",     "to": "archive/d.md"}},
  {"path": "trash/e.md", "op": {"kind": "delete"}},
  {"path": "inbox/f.md", "op": {"kind": "frontmatter-set", "key": "status", "value": "done"}},
  {"path": "inbox/g.md", "op": {"kind": "tag-add",    "tag": "project-x"}}
]
JSON

jotura batch /tmp/ops.json --diff
```

Always emits JSON to stdout (the global `--json` flag is implied):

```json
{
  "opsApplied": 7,
  "results": [
    {"path": "inbox/a.md", "kind": "write", "newHash": "...", "diff": "..."},
    {"path": "inbox/b.md", "kind": "edit",  "newHash": "...", "diff": "..."},
    ...
  ]
}
```

### Atomicity guarantee

1. **Plan phase**: the CLI reads current content for every path, runs body-modifying ops against it in-memory, and surfaces any `NotFound`/`Ambiguous`/`OutOfRange` errors **before** writing anything. Exit code `11` (`MultiEditOpFailed`) on failure; disk untouched.
2. **Precondition phase**: every `ifHash` is verified against current on-disk state in one pass. Any mismatch produces a `HashConflict` error with **all** conflicting paths and their per-path `currentVsIntended` diffs. Exit code `2`. Disk untouched.
3. **Apply phase**: the batch executes through the existing per-op core API, each op committing in its own SQLite transaction. The plan phase eliminates the common failure modes, but if an unrelated error (filesystem, manifest corruption, AlreadyExists) hits mid-batch, prior ops in that same batch have already committed and will NOT be rolled back.

In practice this means: **safe for "hash conflict" and "op planning errors" (the common cases). Best-effort for unrelated errors mid-write.** Always pass `ifHash` where the user might be editing concurrently.

### Batch op kinds

| `kind` | Required fields | Optional |
|---|---|---|
| `write` | `content` | `full`, `ifHash` |
| `edit` | `apply` (array of edit ops) | `ifHash` |
| `create` | `parent`, `name` | — |
| `rename` | `to` | — |
| `delete` | — | — |
| `frontmatter-set` | `key`, `value` | `ifHash` |
| `frontmatter-delete` | `key` | `ifHash` |
| `tag-add` | `tag` | `ifHash` |
| `tag-remove` | `tag` | `ifHash` |

`--dry-run` and `--diff` work on `batch` just like on single commands.

## Frontmatter

The `edit` command **never touches frontmatter**. Use these dedicated operations instead. Frontmatter changes are isolated so YAML can't accidentally be mangled.

```sh
# Read
jotura frontmatter get notes/today.md          # full YAML block
jotura frontmatter get notes/today.md status   # one key

# Write
jotura frontmatter set notes/today.md status "in-progress"
jotura frontmatter delete notes/today.md draft

# Tag helpers (operate on the `tags:` array)
jotura tag add notes/today.md project-x
jotura tag remove notes/today.md old-tag
jotura tag list notes/today.md
```

The frontmatter editor handles top-level scalars and `tags:` arrays. Complex nested YAML (anchors, multi-line scalars, nested maps) is preserved verbatim but can't be edited from the CLI — for those, ask the user to edit in the desktop.

## Daily notes

```sh
# Print today's daily-note path (auto-creates if missing)
jotura today --json
# → { "path": "daily/2026/05/26.md", "hash": "...", "created": true }

# Print today's body
jotura today --read

# Append a line (also reads from stdin if --append has no value)
jotura today --append "took a 20-minute walk after lunch"

# Operate on a different date
jotura today --date 2026-05-20 --read

# Override the folder (default `daily`)
jotura today --folder Journal
```

Convention: `<folder>/YYYY/MM/YYYY-MM-DD.md`. The CLI's `today` is path computation + auto-create — once you know the path, `edit` and `read` work the same as for any other note.

## Reacting to vault changes

`jotura watch` streams change events as newline-delimited JSON. Useful when scripting against the vault while the desktop or another agent is also editing.

```sh
jotura watch
# {"kind":"Created","path":"inbox/new.md","ts":"2026-05-26T17:50:00Z"}
# {"kind":"Modified","path":"daily/2026/05/26.md","ts":"..."}

# Filter to a glob of paths
jotura watch --paths "daily/**"

# Filter event kinds (C,M,D,R)
jotura watch --kinds C,M

# Exit after the first matching event
jotura watch --once
```

Events are detected by polling the file tree about once per second; renames surface as a Deleted + Created pair.

## File operations

```sh
jotura create inbox "meeting-notes"   # creates inbox/meeting-notes.md (auto-suffixes (2) on collision)
jotura rename old/path.md new/path.md
jotura trash inbox/old.md             # SOFT-DELETE (recoverable, recommended)
jotura delete inbox/old.md            # PERMANENT delete — escape hatch only

# `jotura delete --trash <path>` is an alias for `jotura trash <path>`.
```

For agent use, prefer `jotura trash` — it's reversible. `jotura delete`
permanently removes the file with no recovery path.

## Soft-delete with `trash`

Soft-deletion moves the file into `<vault>/.jotura/trash/`, keeping its
relative path and a small metadata sidecar. The note becomes invisible to
`ls`, `read`, `search`, `quick-open`, and `grep`, but it can be restored at
any time. The desktop app uses the same trash directory.

```sh
# Soft-delete a note
jotura trash inbox/old.md

# List everything in the trash (sorted newest-first)
jotura trash list --json
# → [{ "originalPath": "...", "isFolder": false, "size": 123, "trashedAt": 1716... }]

# Restore at the original path (fails if a note now exists there)
jotura trash restore inbox/old.md

# Restore at a different path
jotura trash restore inbox/old.md --rename-to archive/old.md

# Permanently delete one trashed item
jotura trash purge inbox/old.md

# Permanently delete every trashed item (requires --force)
jotura trash empty --force
```

The original path is the key for `restore` and `purge` — pass the same
logical path the note had before it was trashed. `jotura trash list` shows
those keys.

Restoring into a path that's already occupied returns `InvalidArgs` (exit
code 9) with a message suggesting `--rename-to`. Folders can be trashed and
restored whole.

## Templates

Reusable note bodies live at `.jotura/templates/<name>.md` inside the
vault (plain files, but excluded from `ls`/`search`/`quick-open`/`grep`).

```sh
# List available templates
jotura templates list

# Print a template's body
jotura templates show meeting

# Create a template from stdin
echo "# {{title}}\n\nDate: {{date}}\n" | jotura templates create meeting

# Create a template from an existing note's body
jotura templates create from-current --from inbox/current.md

# Delete a template
jotura templates delete meeting
```

### Using a template

Pass `--template <name>` to `create` or `today` to initialize the new
note's body from a template. Existing notes are never overwritten — the
flag only affects newly-created notes.

```sh
jotura create inbox meeting-notes --template meeting
jotura today --template daily
```

### Template variables

Simple find-replace (no conditionals, loops, or partials). Both the
frontmatter block and the body have variables substituted.

| Variable | Substitution |
|---|---|
| `{{date}}` | today's date, `YYYY-MM-DD` (UTC) |
| `{{datetime}}` | current ISO 8601 timestamp |
| `{{filename}}` | the new note's filename without `.md` |
| `{{title}}` | the filename with `-`/`_` turned to spaces, title-cased |

`{{date}}` always reflects the **current** date, even when `today --date
<past>` is used — that flag controls the path, not the variable.

## Whole-body writes (rare — prefer `edit`)

Only use this when the user genuinely wants to replace a note's entire body. Reading-then-editing with `edit --replace` is almost always better because it preserves any content the user added that you might not have anticipated.

```sh
echo "new body content" | jotura write notes/today.md --if-hash "$HASH"

# --full replaces frontmatter too. Almost never the right move.
echo "---\nfoo: bar\n---\nbody" | jotura write notes/today.md --full --if-hash "$HASH"
```

## Exit codes — handle these by reading the JSON error on stderr

| Code | Name | Recovery |
|---|---|---|
| 0 | success | proceed |
| 2 | `HashConflict` | error includes `currentVsIntended` unified diff; inspect it to decide retry / merge / abandon. For `batch`, comes as a `conflicts: [...]` array of per-path entries |
| 3 | `NotFound` | the string you tried to replace isn't there, or the path is wrong — re-read and check |
| 4 | `Ambiguous` | parse `lineHits` from the JSON error; pick `--nth N` or extend `--replace` text for uniqueness |
| 5 | `OutOfRange` | line number exceeds `lineCount`; re-read with `--numbered` |
| 6 | `NoVault` | ask the user to set `JOTURA_VAULT` or open a vault in the desktop |
| 8 | `PermissionDenied` | surface the message to the user |
| 9 | `InvalidArgs` | bad flag combination; re-check `--help` |
| 11 | `MultiEditOpFailed` | one op in a `--apply` or `batch` failed; check `opIndex` + `underlyingCode` to identify which op and why; the whole batch was aborted with no writes |
| 12 | `SyncNotEnabled` | `sync login`/`sync logout` on a vault without sync configured; only relevant to sync key management |

Errors are emitted as a single-line JSON object on stderr, e.g.:
```
{"code":"Ambiguous","message":"...","needle":"TODO","occurrences":3,"lineHits":[5,12,47]}
```

## What the CLI deliberately does NOT do

Delegate these to the desktop app:

- Create a new vault (any folder works — but the desktop is the usual flow)
- Enable sync / set or rotate the sync password / restore from the server
  (the CLI only manages the local key cache: `sync status|login|logout`)
- Sync push / pull loops
- Daily-notes auto-creation flow (just `create` with a `YYYY-MM-DD.md` name if you need one)
- Task list views (the desktop has UI for this; CLI doesn't expose it)
- Recently-opened note list (UI feature)
- Move-to-OS-trash (the CLI's `trash` keeps soft-deleted notes inside the
  vault so they're available across machines)
- Opening files in external apps

## Common mistakes to avoid

1. **Prefer `jotura` over `sed`/`awk`/direct writes for mutations.** Vault files are plain `.md` and direct edits won't corrupt anything, but they skip the safety rails: no `--if-hash` protection against concurrent desktop/sync edits, no unique-match strictness, no frontmatter preservation guarantees, no atomic write.
2. **Never write into `<vault>/.jotura/`** (except templates via the `templates` commands). It holds the sync database, search index, and trash — the CLI and desktop manage it.
3. **Always use `--if-hash` on writes** of notes the user might be actively editing. Without it, you can silently clobber their desktop work.
4. **Always use `--json` for structured output** when you'll act on the result programmatically. Default output is human-readable.
5. **Don't use `--replace --all` defensively.** Strict mode catches "I thought there was one but there were five" mistakes. Use `--all` only when the user explicitly asked for "every occurrence."
6. **Don't whole-body-write when you mean to edit a section.** `jotura write` replaces the body wholesale. Use `jotura edit --replace` to surgically change one place.
7. **Don't run `jotura sync login` yourself.** It needs the user's sync password. If sync uploads are paused for a missing key, tell the user to run it (or unlock in the desktop) — your reads and edits work fine regardless.

## Shell completion

The CLI ships completion scripts for bash, zsh, fish, elvish, and powershell:

```sh
# zsh — install once
jotura completion zsh > "${fpath[1]}/_jotura"

# bash
jotura completion bash > /usr/local/etc/bash_completion.d/jotura

# fish
jotura completion fish > ~/.config/fish/completions/jotura.fish
```

After install, `jotura <TAB>` completes subcommands and flags. For path arguments, completion delegates to `jotura __complete-paths <prefix>`, which walks the vault's file tree. When no vault is selected the completer returns nothing silently (no error).

## Troubleshooting with `doctor`

`jotura doctor` runs a sequence of health checks — CLI on PATH, vault detected and readable, sync state, document conversion health, desktop app version, etc. Use this first when something feels off:

```sh
jotura doctor --json
```

Each check returns `{ name, status: pass|warn|fail|info, detail }`. Doctor never mutates state.

## Installing this skill in other agents

```sh
jotura skill install claude    # ~/.claude/skills/jotura-vault/SKILL.md
jotura skill install codex     # ~/.codex/AGENTS.md (frontmatter stripped)
jotura skill install gemini    # ~/.gemini/GEMINI.md (frontmatter stripped)
jotura skill install all       # all three
jotura skill list              # show which are installed and up-to-date
jotura skill show              # print canonical SKILL.md to stdout
```

If the target file exists with different content the command prompts before overwriting (or use `--force`).

## Quick reference (memorize this)

```
status / doctor   → vault + sync state / full health
sync status|login|logout → sync key cache management
ls --json         → list notes
search Q --json   → full-text search
search Q --in P   → full-text search scoped to a path prefix
quick-open Q      → filename search
import FILE [--folder F | --as P] [--no-convert]  → add a document + md_store mirror
search-documents Q → search documents (md_store); returns original paths
ls-documents [--folder F]  → list documents + conversion status
regenerate-md-store [P...] [--all] [--stale-only]  → rebuild document mirrors
read P --numbered → read with line numbers
read P --json     → read with hash for --if-hash
edit P --replace OLD --with NEW --if-hash H   → safe targeted edit
edit P --apply FILE --if-hash H               → multi-op edit, sequential, atomic
edit ... --dry-run / --diff                   → preview / unified diff
edit P --replace-line N --with C              → line-based edit
batch FILE [--dry-run] [--diff]               → atomic multi-file ops
frontmatter get/set/delete P [K] [V]          → YAML ops
tag add/remove/list P [T]                     → tags
create PARENT NAME [--template T]              → new note (optionally from template)
rename A B / delete P                          → rename / permanent delete
trash P                                        → soft-delete (recoverable)
trash list / restore P [--rename-to N]         → list / restore trashed
trash purge P / trash empty --force            → permanent removal
templates list/show/create/delete              → manage templates
today [--read] [--append T] [--date D] [--template T] → daily-note helper
backlinks P [--limit N]                        → notes linking TO P
links P [--limit N]                            → links inside P (outgoing)
grep PAT [-i -x -w -c -l -L]                   → regex search across bodies
                [--include G --exclude G]
                [--max-count N]
watch [--paths G] [--kinds CMDR] [--once]      → stream events
completion <shell>                             → emit shell completion
skill install <agent>                          → install this skill
```