AGENTS.md

@@ -32,7 +32,7 @@ CI=true SOURCE_FRAMES=30 dora run dataflow.yml --uv   # the same, headless
 - **`dora_image_view/bbox.py`** — Parses the `bbox` struct into xyxy corners. `xywh` is centre-based (x, y are the box centre). `_flat()` unwraps the single-element list that `pa.array([{...}])` produces around each field, and reads a field stored flat as-is.
 - **`examples/source.py`** — The synthetic source node: an animated frame, a depth map of the same scene (a flat wall with the square in front of it), the box around the square, and a caption. It exists so the example dataflow exercises all three inputs without a camera or a detector, and so CI can run the dataflow rather than only validate it. `SOURCE_FRAMES` bounds the run, which is what lets CI wait for a clean exit instead of killing it on a timeout.
 - **`dora-node.yml`** — Node manifest (`apiVersion: 1`). `dora validate` injects these types into any dataflow that reaches the node by `path:`; a `git:`-sourced node does **not** pick it up, which is why the example builds from the checkout. `image` and `text` carry type URNs naming the element type because each payload is a raw buffer described by its metadata, not an Arrow struct. `bbox` is deliberately **untyped**: senders disagree on whether its numeric fields are 32- or 64-bit, and the node reads either.
-- **`examples/dora-node.yml`** — Manifest for the source node, and not optional. `dora validate` matches a manifest to a `path:` node by entrypoint; with no manifest beside `examples/source.py`, the root `dora-node.yml` is tried against it, does not match its entrypoint, and warns — which `strict_types: true` turns into a failure. Declaring the source's types here rather than as `output_types:` in `dataflow.yml` is also what makes them *checked*: an inline annotation shadows the manifest, so the manifest would be injected but never compared.
+- **`examples/dora-node.yml`** — Manifest for the source node, and not optional. A manifest describes exactly one node (the schema is `NodeManifest`, singular), so the second node in this repository gets a second manifest; a `dora-node.yml` next to a plain `path:` node is [the documented way](https://dora-rs.ai/dora/hub/node-manifest) to type a node without publishing it. `dora validate` matches a manifest to a `path:` node by entrypoint; with no manifest beside `examples/source.py`, the root `dora-node.yml` is tried against it, does not match its entrypoint, and warns — which `strict_types: true` turns into a failure. Declaring the source's types here rather than as `output_types:` in `dataflow.yml` is also what makes them *checked*: an inline annotation shadows the manifest, so the manifest would be injected but never compared.
 - **`dataflow.yml`** — The example and the CI gate, with `strict_types: true`. Both nodes are `path:` nodes with a manifest, so both contracts are injected and compared against each other; `bbox` is annotated on neither side, matching the manifests.
 - **`.gitea/workflows/validate.yml`** — CI: lints, runs the unit tests, validates the dataflow and runs it headless. Needs no camera and no display. One job on purpose — the gates themselves take about a second, and are dwarfed by preparing the runner.
 

examples/dora-node.yml

@@ -1,10 +1,14 @@
 # Manifest for the example source node.
 #
-# Its reason to exist is as much mechanical as documentary: `dora validate`
+# A manifest describes exactly one node, so a second node in this repository
-# matches a node manifest to a `path:` node by entrypoint, and without a
+# gets a second manifest. This is the documented way to type a node you have
-# manifest here the repository-root dora-node.yml -- whose entrypoint is
+# not published: "a dora-node.yml sitting next to a plain `path:` node is
-# `dora-image-view` -- gets tried against `examples/source.py`, does not match,
+# picked up automatically" -- https://dora-rs.ai/dora/hub/node-manifest
-# and warns. Under `strict_types: true` that warning fails the run.
+#
+# It is not optional here. `dora validate` matches a manifest to a `path:` node
+# by entrypoint; with no manifest beside examples/source.py the repository-root
+# one is tried against it, does not match its `dora-image-view` entrypoint, and
+# warns -- which `strict_types: true` turns into a failure.
 #
 # Declaring the types here rather than as `output_types:` in dataflow.yml is
 # what makes them checked: an inline annotation shadows the manifest, so the
@@ -50,7 +54,6 @@ outputs:
       Depth of the same scene in millimetres, [height, width]: a flat wall with
       the square standing in front of it.
 
-
 env:
   SOURCE_WIDTH:
     type: int