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

The store is **PostgreSQL on 55432** (``$SCITEX_STORE_DSN``); unset raises.
Add a card and read back the in-progress list:

.. code-block:: python

    import scitex_cards as cards

    cards.add_task(None, id="design", title="Design", status="done")
    cards.add_task(
        None, id="build", title="Build",
        status="in_progress", depends_on=["design"],
    )
    rows = cards.list_tasks(None, status="in_progress")

Render the store's dependency graph to a PNG from Python:

.. code-block:: python

    import scitex_cards as cards

    rows = cards.list_tasks(None, status="in_progress")
    from scitex_cards._diagram import build_mermaid, render

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

…or from the shell:

.. code-block:: bash

    # store: $SCITEX_STORE_DSN (PostgreSQL on 55432); unset raises
    scitex-cards render-graph -o tasks.png

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

    # list the resolved tasks (machine-readable with --json)
    scitex-cards 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-cards`` ships only the mechanism — no task content. The store is
**PostgreSQL on 55432**, and there is ONE store identity:

1. an explicit ``store`` / ``--store`` argument (wins even if missing)
2. ``$SCITEX_STORE_DSN`` — e.g. ``postgresql://scitex_cards@127.0.0.1:55432/scitex_cards``

Nothing else. Unset **raises**. There is deliberately no second-engine tier, no project
scope (a per-repo store meant one agent saw a different board depending on which
directory it started in), and no bundled ``examples/tasks.yaml`` fallback. Two
backends would be two ways to be wrong about which board you are reading.
