# Notes workflow

Capture HVAC field notes from the terminal, search project records, and synchronize queued notes with idempotent retries using VentilatePro CLI.

Canonical: https://ventilatepro.com/exam/cli/notes/

Documentation version: VentilatePro CLI 0.8.4

## Create notes

A note has a kind: `note` for reference material and quick captures, `meeting`, `call`, `site_visit`, or `agent_session`. Titles may be provided explicitly or derived from the first non-empty body line.

```text
ventilatepro notes create --project 123 --body "Captured from terminal"
```

```text
cat site-walk.md | ventilatepro notes create --project 123 --stdin --tags field,urgent
```

- `--project` is required because notes are project-scoped.
- `--title` is optional.
- `--body` and `--stdin` are mutually exclusive.
- `--tags` stores tags on the note and also powers filtering.
- `--kind` sets the kind; `--pinned` marks a key reference agents always load.
- `--occurred-at` records when it happened (`--captured-at` still works).

## Read notes

`notes list` and `notes show` read notes and decisions together, pinned notes first. `notes update` can re-kind, pin, or archive a note.

```text
ventilatepro notes list --project 123
```

```text
ventilatepro notes show note:42 --project 123
```

```text
ventilatepro notes list --project 123 --json
```

| Field | Meaning |
| --- | --- |
| `note_ref` | `note:42` or `decision:7`. Older `general-info:` and `design-minute:` references still resolve. |
| `type` | `note` or `decision`; notes also carry `kind`, `pinned`, and `archived`. |
| `source` | Origin of the note, currently `cli` or `web`. |
| `tags` | Tag list used for filtering and search. |
| `metadata` | Extra fields for note types like meeting minutes and decisions. |

## Filter and search

Use structured filters to narrow the note feed without building a second local index.

| Option | Behavior |
| --- | --- |
| `--type` | Filter to `note` or `decision`; `--kind`, `--pinned`, and `--include-archived` narrow further. |
| `--source` | Filter by `cli` or `web` origin. |
| `--tags` | Comma-separated tags; all listed tags must be present. |
| `--query` | Searches note ref, title, body, tags, and metadata strings. |

```text
ventilatepro notes list --project 123 --kind meeting --source cli --tags field,urgent --query terminal
```

## Offline queue and sync

`notes create` safely queues the note locally on network failures and server 5xx responses. Later, `notes sync` retries the queued payload using the same idempotency key.

```text
ventilatepro notes sync
```

```text
ventilatepro notes sync --project 123
```

- Network errors and 5xx responses are queueable.
- 4xx validation errors and auth errors are not queued.
- A successfully queued note still returns exit code 0 so capture workflows do not fail unnecessarily.
- `notes sync` returns non-zero when queued items still fail after retry.