cartulary 0.3.0-alpha.1

The knowledge layer of your project — decisions, issues, docs, all in one place.
Documentation
---
summary: The 26-character lexicographically sortable identifier carried by every entry.
---

# ULID — entry identifier suffix

Every entry in a cartulary workspace carries a stable identifier of the
form `<KIND>-<ULID>`, for example `ISSUE-01J9ZK4T5M8N3QXA7BR2HVPMD0` or
`ADR-01J9ZK5R8X2NM4QH6BV3PTCRDA`.

The `<KIND>` prefix names the kind of entry (`ISSUE`, `ADR`, `DDR`, or
any custom kind registered in `cartulary.toml`). The 26-character
suffix is a **ULID** ([Universally Unique Lexicographically Sortable
Identifier](https://github.com/ulid/spec)), encoded in **Crockford
base32**.

## What you need to know in practice

- **Copy-paste, don't type.** Identifiers are designed to be unique and
  sortable, not memorable. Every command that takes an entry id
  accepts the full form copied from `cartu show` output, from a
  `Refs:` footer, or from a `links:` block.
- **Prefix matching works for lookup.** Any command that resolves an
  entry id accepts the first three or more characters of the suffix.
  Ambiguous prefixes return the candidate list instead of guessing.
- **Case does not matter on input.** `cartu show ISSUE-01J9zk4t…`
  resolves the same way as the canonical uppercase form. Output is
  always canonical uppercase. The Crockford alphabet excludes the
  visually ambiguous letters `I`, `L`, `O`, `U`; on input, `I` and
  `L` are accepted as `1` and `O` as `0`.
- **Identifiers sort chronologically.** Listing entries by id alone
  reflects creation order — useful when scanning event-log lines,
  filtering by recency, or piping to `sort`.

## Stability

Once assigned, an entry's id does not change. If a migration of the
workspace ever rewrites identifiers, the previous one is preserved in
the entry's `aliases:` so external references (commit messages, links
in other systems, frozen `Refs:` footers) keep resolving.