Quick Start
===========

A minimal ``tasks.yaml``:

.. code-block:: yaml

    tasks:
      - {id: design, title: Design, status: done}
      - {id: build, title: Build, status: in_progress, depends_on: [design]}
      - {id: ship, title: Ship, status: goal, depends_on: [build]}

Render it to a dependency-graph PNG from Python:

.. code-block:: python

    import scitex_todo as todo

    tasks = todo.load_tasks("tasks.yaml")
    mermaid_src = todo.build_mermaid(tasks)
    engine = todo.render(mermaid_src, "tasks.png")   # 'mmdc' or 'kroki'

…or from the shell:

.. code-block:: bash

    # default store: project -> user -> bundled example (or $SCITEX_TODO_TASKS)
    scitex-todo render-graph -o tasks.png

    # inspect the generated mermaid without rendering
    scitex-todo render-graph --print-mermaid

    # list the resolved tasks (machine-readable with --json)
    scitex-todo list-tasks --json

Task schema
-----------

Each task in the ``tasks:`` list:

.. list-table::
   :header-rows: 1
   :widths: 18 12 70

   * - Field
     - Required
     - Meaning
   * - ``id``
     - yes
     - unique id, referenced by ``depends_on`` / ``blocks``
   * - ``title``
     - yes
     - short label
   * - ``status``
     - yes
     - ``goal`` | ``pending`` | ``in_progress`` | ``blocked`` | ``done`` | ``deferred`` | ``failed``
   * - ``repo``
     - no
     - owning repo / area
   * - ``depends_on``
     - no
     - ids this task depends on (arrow ``dep --> task``)
   * - ``blocks``
     - no
     - ids this task inhibits (``blocker -- blocks --x task``)
   * - ``note``
     - no
     - free-text annotation
   * - ``priority``
     - no
     - integer rank (lower = higher); document order if absent
   * - ``parent``
     - no
     - id of the task this nests under (drill-down view)

Where your task data lives
--------------------------

``scitex-todo`` ships only the mechanism — no task content. The store resolves
in this order (first existing wins):

1. an explicit ``--tasks`` path
2. ``$SCITEX_TODO_TASKS``
3. project scope: ``<git-root>/.scitex/todo/tasks.yaml``
4. user scope: ``~/.scitex/todo/tasks.yaml`` (relocatable via ``$SCITEX_DIR``)
5. the bundled generic example
