From a64e68e6ad5d86c9fca65d2f4f653cf5725b0c3a Mon Sep 17 00:00:00 2001 From: Toddy Mladenov Date: Thu, 13 Aug 2026 20:43:03 -0700 Subject: [PATCH 1/2] docs(observability): explain the supply-chain-graph-data branch The querying guide only showed indexing the in-repo folder/examples and never said the real, workflow-generated events live on the append-only supply-chain-graph-data branch. Add a 'Where the data lives' section with the fetch + worktree + index steps, the schema note (#203), and the graph-service git-sync path. Fixes #204 --- .../querying-the-supply-chain-graph.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/guides/observability/querying-the-supply-chain-graph.md b/docs/guides/observability/querying-the-supply-chain-graph.md index 657aa2b..e676349 100644 --- a/docs/guides/observability/querying-the-supply-chain-graph.md +++ b/docs/guides/observability/querying-the-supply-chain-graph.md @@ -50,6 +50,33 @@ run every command verbatim. --- +## Where the data lives + +The `supply-chain-graph/` folder on `main` ships the **schema**, the +**`examples/` fixtures** used in this guide, and any hand-authored records. The +**real, workflow-generated events are not on `main`** — each producer stages one +immutable event file per run and the `record-graph-events` collector commits them +(append-only) to a dedicated **`supply-chain-graph-data`** branch. + +To query your pipeline's actual events, fetch that branch and index it: + +```bash +git fetch origin supply-chain-graph-data +git worktree add --detach /tmp/scg-data origin/supply-chain-graph-data +cssc-graph index /tmp/scg-data/supply-chain-graph -d /tmp/scg.db --rebuild +``` + +The branch carries its own `schema/`, kept current by the collector +([#203](https://github.com/toddysm/cssc-framework/issues/203)), so no +`--schema-dir` override is needed. In the cluster, `graph-service` gets the same +data through its optional git-sync init container, which syncs +`supply-chain-graph-data` into `DATA_ROOT`. + +The `examples/` walkthrough below uses the in-repo fixtures instead, so every +command runs verbatim on a fresh clone. + +--- + ## Experience 1 — the `cssc-graph` CLI ### Install From 10937ad93dccb97b9a5cebdc41575f888221822c Mon Sep 17 00:00:00 2001 From: Toddy Mladenov Date: Fri, 14 Aug 2026 19:18:56 -0700 Subject: [PATCH 2/2] docs: clarify multiple events per run and schema-dir caveat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Copilot review: (1) the collector records one or more event files per run, not exactly one; (2) the 'no --schema-dir needed' claim depends on #203 — reword to note it holds from #203 onward and give the --schema-dir fallback for an older branch snapshot. --- .../querying-the-supply-chain-graph.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/guides/observability/querying-the-supply-chain-graph.md b/docs/guides/observability/querying-the-supply-chain-graph.md index e676349..b4acaa8 100644 --- a/docs/guides/observability/querying-the-supply-chain-graph.md +++ b/docs/guides/observability/querying-the-supply-chain-graph.md @@ -54,9 +54,9 @@ run every command verbatim. The `supply-chain-graph/` folder on `main` ships the **schema**, the **`examples/` fixtures** used in this guide, and any hand-authored records. The -**real, workflow-generated events are not on `main`** — each producer stages one -immutable event file per run and the `record-graph-events` collector commits them -(append-only) to a dedicated **`supply-chain-graph-data`** branch. +**real, workflow-generated events are not on `main`** — each producer stages one or +more immutable event files per run and the `record-graph-events` collector commits +them (append-only) to a dedicated **`supply-chain-graph-data`** branch. To query your pipeline's actual events, fetch that branch and index it: @@ -66,11 +66,13 @@ git worktree add --detach /tmp/scg-data origin/supply-chain-graph-data cssc-graph index /tmp/scg-data/supply-chain-graph -d /tmp/scg.db --rebuild ``` -The branch carries its own `schema/`, kept current by the collector -([#203](https://github.com/toddysm/cssc-framework/issues/203)), so no -`--schema-dir` override is needed. In the cluster, `graph-service` gets the same -data through its optional git-sync init container, which syncs -`supply-chain-graph-data` into `DATA_ROOT`. +The branch ships its own `schema/`; from +[#203](https://github.com/toddysm/cssc-framework/issues/203) onward the collector +keeps it in step with the code, so the command above needs no `--schema-dir`. (If +you hit an `unknown kind` error against an older branch snapshot, pass +`--schema-dir` pointing at a current `supply-chain-graph/schema`.) In the cluster, +`graph-service` gets the same data through its optional git-sync init container, +which syncs `supply-chain-graph-data` into `DATA_ROOT`. The `examples/` walkthrough below uses the in-repo fixtures instead, so every command runs verbatim on a fresh clone.