ledgerwerk

Usage

Initialize a workspace

Run initialization from the repository root:

docledger init

By default this creates the canonical .ledger/ layout: .ledger/ledger.toml, the Documentledger tool configuration, and its project data mount. Use --project-name to set the project name. Legacy storage-path and hidden-config options are migration-only.

Check workspace status

docledger --json status

Status reports the workspace state:

  • uninitialized: no documentledger.toml was found.

  • bootstrap_required: there is no baseline scan yet, or there is a baseline but no usable doc links.

  • incremental_clean: the latest scan has no affected linked sections.

  • incremental_affected: the latest scan has affected linked sections that should be reviewed.

  • mapping_incomplete: changed source files are not yet fully linked to documentation.

The result also reports recommended_command, recommended_reason, compact latest-scan counts, and any root-layout diagnostics that should be fixed before trusting a baseline.

Scan source and documentation files

docledger --json scan

A scan collects files from the configured source and documentation roots, hashes them, indexes Python source units, and compares the current state to the previous scan. The first scan establishes a baseline and does not report changed, deleted, stale, or unlinked sources.

Later scans report:

  • unchanged, true when the source and documentation hashes match the previous scan exactly. No scan state is rewritten, no source files are re-indexed, and the previous scan version is reused; the human output prints No tracked file changes since scan version <version> instead of Recorded scan version <version>.

  • changed_sources, source files whose hash changed or that are new since the previous scan.

  • changed_units, source units whose tracked semantic hashes changed. For Python this is usually the changed function, method, class, or module contract rather than the whole file.

  • deleted_sources, source files that were present in the previous scan and are now gone.

  • affected_sections, the documentation sections currently impacted by changed or deleted linked source units.

  • stale_docs, a compatibility projection of the docs that still contain affected sections.

  • unlinked_changed_sources, changed source files that do not have documentation links.

Find and update stale documentation

docledger --json docs affected
docledger docs build-context --affected --out /tmp/docledger-context.md

docs affected reports the live affected sections for the latest scan. After a section is updated and marked fresh, it disappears from docs affected immediately; a follow-up scan is optional confirmation, not the only way to clear affectedness.

The rendered context contains only the affected doc sections, their linked changed source units, the current relevant source snippets, unlinked changed sources, and configured validation commands. Inspect the affected sections and linked changed source units first. Expand to whole files only when the changed unit cannot be understood in isolation.

Bootstrapping a new repository

A fresh repository has no links yet, so the first scan reports no stale docs. To drive an initial documentation pass, use the explicit bootstrap flow:

docledger init
docledger scan
docledger docs build-context --bootstrap --out /tmp/docledger-bootstrap.md
docledger links propose --all-docs --out-dir /tmp/docledger-maps
docledger --json links import-map --directory /tmp/docledger-maps --check-and-apply

The bootstrap context and proposal flow give agents a deterministic first-pass link graph without applying anything until the full batch validates. See Bootstrap for the full setup sequence.

Mark documentation fresh

After updating and validating an affected section, mark it fresh:

docledger mark-fresh --doc docs/usage.md --section usage-validate-ledger-state --reason "Docs updated after scan version 2."

mark-fresh records the latest scan version, the current document hash, the current section hash, and the tracked source-unit hashes for the selected links. It requires a non-empty reason. Use --all to mark every currently affected section from the latest scan, or --doc without --section to update all affected sections in one doc explicitly.

Unlinked docs are rejected by default:

docledger mark-fresh --doc docs/index.md --reason "Navigation page."        # rejected: unlinked_doc
docledger mark-fresh --doc docs/index.md --allow-unlinked --reason "Navigation page."

This prevents silently tracking a doc that can never become stale from source changes. Pass --allow-unlinked only for intentionally unlinked docs; the record stores the reason with an (intentionally unlinked) marker.

Validate ledger state

docledger doctor

Doctor checks storage schema metadata, document record paths, suspicious root configuration, missing documentation files, missing source files, duplicate edges, missing source-unit ids, and missing section ids.

JSON and human output

Pass --json before the command to emit a stable JSON envelope:

{ "ok": true, "command": "status", "result": {}, "events": [] }

Errors also use a JSON envelope when --json is set, and the envelope preserves the real command name:

{
  "ok": false,
  "command": "scan",
  "error": {
    "code": "workspace_not_found",
    "message": "...",
    "remediation": []
  },
  "events": []
}

Without --json, commands print human-readable output and errors print concise Error: messages with remediation hints.

Ledger state and commit policy

Documentledger stores its durable state under .ledger/documentledger/data/; rendered and proposal artifacts use the resolved cache mount. The recommended commit policy for a documentation freshness ledger is:

  • Commit .ledger/ledger.toml, .ledger/documentledger/config.toml, .ledger/documentledger/data/storage.yaml, .ledger/documentledger/data/scan.yaml, and .ledger/documentledger/data/docs/*.yaml. These are the source of truth for project identity, the current scan baseline, section-level links, tracked hash state, and freshness markers.

  • Ignore the resolved cache artifacts directory. Rendered context is regenerated on demand by docs build-context.

Do not edit .ledger/ files directly; use the docledger commands so the records stay consistent. Existing .documentledger/ layouts are compatibility input for explicit migration only.

Storage commands

Use docledger storage where to inspect the active layout. Migrate a legacy workspace with a reviewed dry-run plan, then verify before any cleanup:

docledger storage migrate --dry-run --plan-file migration.json
docledger storage migrate --plan-file migration.json --adopt-project-uuid
docledger storage verify --strict
docledger storage cleanup-legacy --dry-run

Routine commands never migrate automatically and read-only commands do not initialize cache directories or repair bindings.