---
summary: A project directory that cartulary recognises via a `cartulary.toml` at its root.
---
# Workspace
A **workspace** is a project directory that cartulary recognises
because it contains a `cartulary.toml` at its root. Every command
runs in the context of a workspace; the binary refuses to do
anything useful outside one.
## Shape
A workspace has three on-disk parts:
- `cartulary.toml` at the root — declares the configured decision-
record kinds, the issues directory, optional status workflows,
optional tag descriptors, and optional external sources.
- One directory per decision-record kind (e.g. `docs/adr/`,
`docs/ddr/`) — each holds one `<id>-<slug>/` subdirectory per
record.
- One issues directory (`docs/issues/` by default) — same shape,
one subdirectory per issue.
The `--root-dir <PATH>` flag, accepted by every command, locates
the workspace; without it, the current directory is assumed.
Both decision-record directories and the issues directory are
created lazily — the first time a record is added.
## Configuration
`cartu init` writes a minimal `cartulary.toml` declaring one ADR
kind under `docs/adr/` and an issues directory at `docs/issues/`.
Everything else (additional kinds, status workflows, tag
descriptors, sources) is opt-in.
The schema version of `cartulary.toml` is bumped when the on-disk
format changes; `cartu migrate` brings an older workspace forward
in place. The current schema version is encoded in the binary —
re-running `cartu migrate` on an up-to-date workspace is a no-op.
## Validation
`cartu check` validates the workspace as a whole:
- `cartulary.toml` exists and parses.
- Every entry under the configured directories has valid
[frontmatter](concept://frontmatter).
- Every cross-reference in `links:` resolves to a real entry.
- Every record's id matches its directory's TSID prefix.
## Commands
- **Bootstrap**: `cartu init` — write the default `cartulary.toml`.
- **Migrate**: `cartu migrate` — bring frontmatters and config to
the current schema version.
- **Inspect**: `cartu check` (consistency), `cartu search <query>`
(fuzzy across all entries).
- **Publish**: `cartu site build --out <dir>` — render the
workspace as a self-contained static site.
- **Read**: `cartu man <topic>` (this command).