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.1.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.1.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.1.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.1.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.

---

⚡ 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.

---

🔎 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). Allowed types: feat, fix, docs, refactor, perf, test, build, ci, chore, style. Subject in imperative mood, lowercase, no trailing period, ≤72 chars. CI rejects non-conforming commits; 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.