Command line
============

``claimdag [--dir DIR] VERB``

=================================================================================================== =================================================================================================================================================================================
Verb                                                                                                Does
=================================================================================================== =================================================================================================================================================================================
``upsert [--id ID] [--kind K] [--status S] [--role R] [--parent ID] [--summary TEXT] [--actor ID]`` create (mint when ``--id`` is absent) or update a node
``get ID``                                                                                          one node with its dependencies
``list [--terminal] [--archived] [--all] [--json]``                                                 nodes, newest first; live work by default
``claim ID --assignee ID [--gen N]``                                                                compare-and-swap claim; prints the new generation
``renew ID [--actor ID]``                                                                           move the lease, keep the generation
``release ID (--actor ID | --force)``                                                               hand one claim back before it is terminal: ready, no assignee, generation moved. ``--actor`` must be the holder; ``--force`` acts for nobody and appends a line to ``forced.log``
``reopen ID [--actor ID]``                                                                          bring a terminal node back to ready, generation moved. No record of the earlier completion is kept on disk
``complete ID [--status done|failed|cancelled] [--summary TEXT] (--actor ID | --force) [--gen N]``  terminal; refused when ``--gen`` is stale, and ``done`` is refused while a dependency is unfinished. ``--force`` acts for nobody and appends a line to ``forced.log``
``reclaim [--lease SECS]``                                                                          hand back every claim quiet longer than the lease
``link PARENT CHILD`` / ``unlink PARENT CHILD``                                                     a hard dependency
``archive ID`` / ``unarchive ID``                                                                   hide or show a terminal node
``ready [--role R] [--assignee ID] [--slack N] [--balanced] [--json]``                              ready nodes ordered by list scheduling or balanced P2C dispersion
``claim-next --assignee ID [--role R] [--slack N]``                                                 atomically select and claim the best ready node with role affinity and P2C dispersion
=================================================================================================== =================================================================================================================================================================================

Ids are 32 lowercase hex characters (xxHash3-128). The zero id means unset.

Statuses
========

``todo``, ``ready``, ``claimed``, ``done``, ``failed``, ``cancelled``. ``ready`` is
derived: a ``todo`` node whose every dependency is terminal. A claim requires
``ready``. One live claim per assignee.

Kinds and roles
===============

Kinds: ``task`` and the closed set the schema names. Roles: ``unset`` and the
closed set the schema names. Summary is the one open text field.

The snapshot
============

``work.bin`` in the graph directory: an unpacked Cap'n Proto message, mapped
read-only by readers and rewritten whole by the one mutating process. A
directory with no file is an empty graph to a writer and "no graph here" to
a reader.

Environment
===========

================ ==============================================================================================================================================
Variable         Meaning
================ ==============================================================================================================================================
``CLAIMDAG_DIR`` the graph directory; else ``$XDG_RUNTIME_DIR/claimdag``, then ``$XDG_STATE_HOME/claimdag``, ``~/.local/state/claimdag``, ``/tmp/claimdag-UID``
================ ==============================================================================================================================================

Crates
======

================ ===================================================
Crate            Carries
================ ===================================================
``claimdag``     the graph, ids, leases, critical path, the snapshot
``claimdag-cli`` ``claimdag``
``claimdag-tui`` the pane, on icedtea
``claimdag-mcp`` the Model Context Protocol (MCP) surface
================ ===================================================