# Add Documents

## Create a document

```bash
ctx add nodes/api-design --title "API Design Guide" --tags "engineering,api"
```

This creates `nodes/api-design.md` from a frontmatter template as **version 1**, and regenerates the index. Tags accept a comma- or space-separated list; you can also pass the body inline with `--body`, and set a node type with `--type` (default: `document`).

```bash
ctx add nodes/api-design \
  --title "API Design Guide" \
  --tags "engineering,api" \
  --type reference \
  --body "Your markdown content here"
```

## The write receipt

Every write **asks for confirmation first** and then prints the exact list of files it created, modified, or deleted — nothing is overwritten silently. To see what a command *would* do without touching disk, add `--dry-run` (it runs against a temp copy of the vault and reports the real file list). In a non-interactive shell, pass `--yes` to skip the prompt or `--force` to allow overwriting.

```bash
ctx add nodes/api-design --title "API Design Guide" --dry-run
```

## Single vs. bulk import

- **Single document** — `ctx add <path>` as above, one file at a time.
- **Bulk** — drop or copy a folder of markdown under the vault's data root, then bring it in as a nest, or publish everything already present in one batch with `ctx publish --all` (publishes every unpublished document at once).

## Document format

Every Context Nest document is a Markdown file with YAML frontmatter:

```markdown
---
title: "API Design Guide"
type: document
tags: ["#engineering", "#api"]
status: published
version: 1
created_at: "2026-03-15T12:00:00Z"
---

# API Design Guide

Your content here. Plain Markdown with GFM support.

## Context Links

Reference other documents: [[API Design Guide]] or by id [Architecture](contextnest://nodes/architecture-overview)
```

## Update a document

```bash
ctx update nodes/api-design --title "API Design Standards" --body "Updated content here"
```

Updates **auto-publish**: the version is bumped, a new checkpoint is recorded, and the index is regenerated. Options: `--title`, `--tags` (replaces existing), `--status`, `--body`.

## Delete a document

```bash
ctx delete nodes/api-design
```

Removes the document **and its full version history**. This is a destructive write, so it prompts for confirmation (or needs `--yes`/`--force` non-interactively).

## List documents

```bash
ctx list                          # All documents
ctx list --type reference         # Filter by type
ctx list --status published       # Filter by status
ctx list --tag engineering        # Filter by tag
ctx list --limit 20               # Cap the results
ctx list --json                   # JSON output
```