> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealmanac.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> This handbook preview targets personal CLI 0.11.1. Check installed command help and the matching backend schema before using examples with another release. Examples with named people and placeholder IDs are fictional.

# Edit knowledge

> Create and revise saved records without losing concurrent or existing information.

Edit the saved record after reading its current revision and the schema for its kind. A record update is guarded by `--expect REVISION`; a stale revision means someone changed it since your read. Read again and reconsider your proposed change rather than replaying it against the newer record.

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac schema describe person
almanac schema describe person --update
almanac read people/sam-fictional
```

The path is fictional. Use a real returned ID or canonical path. `--body` alone is not a sufficient edit preflight because it omits the revision and structured fields. A person or other authored record needs the fields required by its current schema, including a description. To create one, save a schema-valid JSON object and give the operation an explicit request key:

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac create person --input @person.json --request-key create-sam-1
```

## Choose the smallest complete update

`set` changes supplied structured fields, and `--unset` clears optional fields permitted by the schema. Its `--input` file is a flat field object. For example, `description.json` can contain `{"description":"An engineer at Meridian Labs."}`:

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac set people/sam-fictional --expect 3 --input @description.json \
  --request-key describe-sam-1
```

`patch` applies a contextual change to the Markdown body. Its file uses Codex patch syntax, including `*** Begin Patch`, `*** Update File: CANONICAL_PATH`, context lines and `*** End Patch`. The path in the patch must match the selected record. `write` replaces the entire body, so use it only when that complete replacement is intended.

```sh theme={"theme":{"light":"github-light","dark":"vesper"}}
almanac patch people/sam-fictional --expect 4 --patch-file person-body.patch \
  --request-key add-sam-note-1
almanac write people/sam-fictional --expect 5 --body-file complete-body.md \
  --request-key replace-sam-body-1
```

These commands illustrate successive example revisions; take each actual revision from the preceding response, and run only the operation that fits the record. `--patch-file -` and `--body-file -` read standard input. A body operation can also supply `--fields @fields.json` to update structured fields atomically with the body. The [email-to-citation example](/concepts/sources-pages-and-citations) shows that full shape.

Fields omitted from `set` or `--fields` stay unchanged. But a supplied array or map replaces its whole value. When updating roles, relationships, `citations` or `field_citations`, copy every existing entry you intend to keep, adjust indexed citation paths for the final array, and check that every `[@key]` in the resulting body has a binding. The CLI expects flat field JSON; its HTTP request builder adds the `set` envelope. Do not place `{"set":{...}}` in the input file.

Keep a request key for an identical retry if the response is uncertain. If you change the payload or read a new revision after a conflict, choose a new key. The service also checks typed references and cited sources against records owned by the authenticated person; schema-valid JSON alone cannot establish that an ID exists or is accessible. [Knowledge and work](/concepts/knowledge-and-work) explains record kinds and identity, while [sources and citations](/concepts/sources-pages-and-citations) explains evidence bindings.