/capture

name: capture
description: Save any thought or content into the brain via one CLI command. The single human-facing entrypoint that replaces "put_page vs commit-then-sync vs autopilot-wait" with one command that just works.
triggers:
  - "capture this"
  - "save this thought"
  - "remember this"
  - "ingest this into my brain"
  - "drop this in the inbox"
  - "save to brain"
writes_pages: true
writes_to:
  - inbox/

capture — the single ingestion entrypoint

When the user wants to save a thought, an article snippet, a transcript fragment, or any text into their brain, run `gbrain capture`. Don't reach for `gbrain put` or commit-then-sync — `capture` is the front door and it handles both local and thin-client installs the same way.

Contract

• **Input:** the content to save (inline arg, `--file PATH`, or `--stdin`).
• **Output:** a page in the brain DB AND a markdown file on disk under

`<sync.repo_path>/<slug>.md`. Receipt printed to stdout.

• **Side effect:** the page becomes immediately queryable via `gbrain query`,

`gbrain search`, or any MCP-bound agent.

• **Idempotency:** same content → same `inbox/YYYY-MM-DD-<hash8>` slug. The

daemon's 24h content-hash dedup catches re-captures.

• **Trust:** all captures via this skill are local-CLI trust (`remote: false`).

Untrusted webhook ingestion goes through `POST /ingest`, not this verb.

When to invoke

• "Capture this thought" / "save this" / "drop this into my brain" / "remember this"
• The user pastes content and asks to keep it
• After a meeting summary, a research note, or any synthesis that should land as a brain page

What it does

`gbrain capture` resolves to a `put_page` call (local) or a remote MCP call (thin-client). Either way the page lands in the DB AND on disk in one move via the v0.38 write-through plumbing. The default slug is `inbox/YYYY-MM-DD-<hash8>` so captures cluster in a predictable triage location.

How to use

gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
gbrain capture "..." --slug daily/2026-05-21
gbrain capture "..." --type idea --source voice-whisper
gbrain capture "..." --quiet          # script-friendly: prints just the slug
gbrain capture "..." --json           # structured output for agents

Defaults

• **Slug:** `inbox/YYYY-MM-DD-<hash8>` (stable for same content; the daemon's 24h dedup catches re-captures).
• **Type:** `note` (override with `--type idea` etc.).
• **Frontmatter stamps:** `captured_via: capture-cli`, `captured_at: <ISO>`.
• **Title:** first non-empty line of the body, capped at 80 chars (truncation appends `…`).

Output Format

Default prints a 5-line receipt:

captured:
  slug:          inbox/2026-05-21-abcdef12
  status:        created_or_updated
  content_hash:  f3a7b9c0d1e2f3a4…
  file:          /Users/you/brain/inbox/2026-05-21-abcdef12.md
  captured_at:   2026-05-21T04:15:00.000Z

`--quiet` prints only the slug (use for `SLUG=$(gbrain capture "..." --quiet)`). `--json` prints structured output for downstream tools.

When it fails

Follow the [agent operator protocol](../conventions/agent-operator-protocol.md) for any gbrain error `code`, exit code, `[AGENT]` block or notice block. Specific to this skill:

• Exit 10 (`write_pending`): the thought was accepted and may still commit. Tell the user it is saved and pending, and poll `gbrain write-request <request_id>`; never capture it a second time.
• A secret-scan or slug-fence refusal: nothing was saved. Tell the user what was refused; do not edit the content to sneak past the scanner.
• `source_binding_required` or `insufficient_scope` over MCP: this connection cannot write the target source; tell the user which source needs a grant from the brain host's operator.

Anti-Patterns

• **Don't reach for `gbrain put`.** That's the old per-page primitive that

doesn't know about default slug generation, content-type heuristics, or the receipt block. `capture` is the human-facing wrapper.

• **Don't try to bulk-import dozens of files by looping over `gbrain capture`.**

That's what `gbrain sync` (or `gbrain import`) is for. Capture is for single thoughts, single notes, single transcripts.

• **Don't pre-format the content yourself with frontmatter if you don't need to.**

Capture wraps plain prose in sensible frontmatter (type + title + captured_via + captured_at). The body becomes `# Title\n\n<your prose>`. Pass `--file PATH` if you already have a fully-formatted markdown file.

• **Don't pass secrets as inline content.** Inline args land in shell

history. Use `--file` or `--stdin` instead.

When NOT to use this skill

• Bulk ingestion of many files → `skills/media-ingest/SKILL.md` or `gbrain sync` instead
• Article/link with author + publication metadata → `skills/idea-ingest/SKILL.md` (it knows to build the people page)
• Meeting transcripts → `skills/meeting-ingestion/SKILL.md` (attendee enrichment)

This skill is for the simple "I have a thought, save it" case. Specialized ingestion paths handle their own slugging + cross-referencing.