cartulary

The knowledge layer of your project — decisions, issues, docs, all in one place.

⚠️ Status: Alpha — cartulary is under active development. The CLI surface and cartulary.toml schema may change in incompatible ways before 1.0. Pin a specific version (--version "0.7.0-alpha.1") and watch CHANGELOG.md before upgrading.

cartulary is a CLI tool to manage everything that gives context to your project: Architecture Decision Records (ADR), Design Decision Records (DDR), issues, and project documentation. Everything lives as plain Markdown in your repository.

---

📚 Documentation

• Concepts — the domain vocabulary, one page per concept: docs/pages/concepts/. Same content offline via cartu man <name>.
• CLI reference — every subcommand and flag: docs/pages/reference/cli/.
• Configuration — the cartulary.toml schema: docs/pages/reference/config/.
• Workflows — built-in status presets and the decision-record lifecycle: docs/pages/reference/workflows/.

You can also find all the documentation pages online at this address: crazy-crafters.gitlab.io/cartulary

---

🚀 Installation

Pre-built binary (recommended)

Download the archive for your platform from the GitLab Releases page. One-liner for Linux x86_64:

VERSION="0.7.0-alpha.1"
TARGET="x86_64-unknown-linux-gnu"
curl -fsSL "https://gitlab.com/crazy-crafters/cartulary/-/releases/v${VERSION}/downloads/cartu-${VERSION}-${TARGET}.tar.gz" \
    | tar -xz -C /tmp
mv /tmp/cartu ~/.local/bin/cartu

Available targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-gnu. macOS users compile from source via cargo install (next section). Verify the archive against the SHA256SUMS file attached to the same release.

For Windows: download cartu-{version}-x86_64-pc-windows-gnu.zip, unzip, place cartu.exe on your PATH.

Via cargo binstall (no compilation)

If you have cargo-binstall:

cargo binstall cartulary --version "0.7.0-alpha.1"

cartulary ships a [package.metadata.binstall] block pointing at the GitLab Release artefacts — binstall picks the right archive for your platform.

Via cargo install (compile from source)

cargo install cartulary --version "0.7.0-alpha.1"

Compiles from the published crate on crates.io. Requires Rust 1.88+ via rustup.rs.

Build from source (contributors)

git clone https://gitlab.com/crazy-crafters/cartulary
cd cartulary
cargo install --path .

Requires Rust 1.88+. Beyond rustc/cargo, the dev workflow expects just (recipe runner) and cargo-llvm-cov (coverage). Nix users get them automatically via the flake (nix develop); other contributors should install them manually:

cargo install --locked just cargo-llvm-cov
rustup component add llvm-tools-preview

Audit tools

Dead-code and visibility audits use cargo-hawk, a workspace-aware pub-item linter. The flake devShell ships the rustc-dev component hawk needs. Install once, then run from the workspace root:

RUSTC_BOOTSTRAP=1 cargo install --locked cargo-hawk
cargo hawk check --manifest-path Cargo.toml

Findings split into three lints: hawk::dead_public (unused exports), hawk::unnecessary_public (over-broad visibility), hawk::unnecessary_restricted_visibility (over-narrow). --fix applies the safe visibility narrowings automatically.

Supply-chain gate

just supply-chain runs three tools, each covering a different angle. It is part of just ci, so every pipeline blocks on it. The flake devShell ships all three; otherwise cargo install --locked cargo-audit cargo-deny cargo-vet.

Recipe	Tool	Question it answers	Policy file
just audit	cargo-audit	does any resolved version carry a RUSTSEC advisory?	.cargo/audit.toml
just deny	cargo-deny	are licences, sources and bans respected?	deny.toml
just vet	cargo-vet	is each dep audited by a trusted peer or explicitly exempted?	supply-chain/

A new advisory fires. Preferred order: bump the dep, then pressure upstream if it is transitive, and only then waive. A waiver goes in .cargo/audit.toml with the advisory id, why the fix is out of reach, and the id of the issue that owns its removal. An ignore without a tracking issue is a silent acceptance of risk — refuse it in review.

A new licence appears. deny.toml carries an explicit SPDX allow-list. GPL and LGPL deps are accepted (CECILL-2.1 is GPL-compatible by design, Article 5.3.4); AGPL is not. Add the identifier to licenses.allow after checking compatibility, or scope it to one crate with a [[licenses.exceptions]] entry when the crate publishes a malformed identifier.

A new dep enters the graph. cargo vet fails until it is covered. Import sets from Mozilla, Google, Bytecode Alliance, ISRG, Zcash and Embark provide the audits we trust; refresh them with cargo vet import <peer> <url> then cargo vet prune. Anything they do not cover is exempted in supply-chain/config.toml — the exemption is the honest record that nobody read the code. To lift one, review the diff and record it with cargo vet certify <crate> <version>.

---

⚡ 30-second tour

cartu init                                          # scaffold cartulary.toml + docs/
cartu adr new "Use PostgreSQL as primary database"  # record an architecture decision
cartu issue new --tag flow:feature "Add MFA"        # open an issue
cartu issue list
cartu check                                         # validate frontmatter, links, transitions
cartu man                                           # browse concept docs
cartu site build --out site                         # static HTML site with syntax-highlighted code

Pick the next thread from the documentation section above.

🌐 Documentation site

cartu site build renders every entry a workspace holds — decision records, issues, logbook entries — together with the page trees it mounts, into static HTML under --out. A page is addressed by the id of what it shows: /issues/ISSUE-01M2…/, which no retitling moves.

Previewing it needs nothing from cartu: any static file server will do, and the contributor shell carries one.

cartu site build --out site
darkhttpd site --port 8080 --no-listing

Every page is <dir>/index.html, so a server that does not serve a directory index has to be told — miniserve site --index index.html, python3 -m http.server --directory site. To rebuild as you write, pair it with a watcher: find docs cartulary.toml | entr -r cartu site build.

⬆️ Upgrading

cartu refuses a workspace whose cartulary.toml is behind its schema until cartu migrate has run; the run is idempotent and reports every file it touched. Schema 15 (0.6.0) renames every entry directory to <PREFIX>-<ulid>-<slug> — docs/adr/ADR-01KK…-use-rust/ — so the id is read from where the record sits and a corpus may carry records signed with several prefixes. Links inside the workspace resolve as before, and a published site is unaffected: a page is addressed by the id of what it shows, so renaming its directory does not move its URL.

---

🔎 Similar tools

Tool	Category	Decision records	Issue tracking	Flow metrics	Plain files	Single binary
adr-tools	ADR CLI	✅	❌	❌	✅	❌
log4brains	ADR + web UI	✅	❌	❌	✅	❌
git-bug	Issue tracker	❌	✅	❌	❌	✅
git-issue	Issue tracker	❌	✅	❌	✅	❌
cartulary	ADR + issues	✅	✅	✅	✅	✅

The market is split: ADR tools have no issue tracking, issue trackers have no decision records. cartulary covers both, plus flow metrics, structural validation, and a ULID-based identifier scheme that survives parallel branches. See market-benchmark.md for the full analysis.

---

🤝 Contributing

Contributions welcome — open an issue or submit a merge request.

cartulary enforces Conventional Commits 1.0.0 (rationale in ADR-0019); the house style — types, scopes, body, footer — is SR-01M2RNZ8D6A87JWRDE5K6Q0603. The hook rejects a non-conforming subject; to get the same check locally:

cargo install committed
just install-hooks

CI pipeline

Every pipeline stage that runs a Rust tool executes it through the flake's dev shell, so CI and local development share one pinned toolchain instead of whatever a base image happens to ship. Two shells back the jobs: nix develop (default) and nix develop .#ci, which adds the cross-compilation chain and pandoc for the release and docs jobs.

Local command	CI job	Shell
just ci	test	nix develop
committed <range>	commit-lint	nix develop
cargo zigbuild --release --target <target>	build	nix develop .#ci
cargo publish	cargo-publish	nix develop
./generate-html.sh	pages	nix develop .#ci

Releases are cut by maintainers with cargo release --execute X.Y.Z, which runs git-cliff to update CHANGELOG.md and triggers cargo publish + GitLab Release artefacts on tag push. Maintainers either enter the Nix dev shell (nix develop, which ships cargo-release and git-cliff) or install the two tools manually:

cargo install --locked cargo-release git-cliff

---

📄 License

CeCILL

---

🎨 Credits

Logo: Book cover by Lorc, from game-icons.net, licensed under CC BY 3.0.