From 72b75cdeaf860e6326be401e15bc6a17b66da9ad Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Wed, 9 Sep 2026 18:07:43 -0400
Subject: [PATCH] docs(ariadne): update CLI skeleton README

---
 src/ariadne/README.md | 53 +++++++++++++++++++++++++++++++++----------
 1 file changed, 41 insertions(+), 12 deletions(-)

diff --git a/src/ariadne/README.md b/src/ariadne/README.md
index b0474dc..6d43b77 100644
--- a/src/ariadne/README.md
+++ b/src/ariadne/README.md
@@ -1,23 +1,52 @@
 # Ariadne
 
-Ariadne analyzes Clew output for a local Ren'Py game install.
-
-Keep project-owned source under `src/ariadne/`.
-Keep game-derived files local and ignored under `src/ariadne/output/`.
+Ariadne analyzes Clew-produced data for local Ren'Py projects.
 
 Clew owns extraction, preparation, and Ren'Py AST export.
-Ariadne consumes Clew's `clew-renpy-ast-v1` JSON from `output/ast/`.
-Ariadne maps that data into internal analysis state.
+Ariadne consumes Clew output and builds analysis artifacts from it.
+Keep project-owned source under `src/ariadne/`; keep generated or game-derived files out of Git.
 
-## CLI skeleton
+## CLI
 
-Run all declared stages with:
+Run the default target, `all`:
 
 ```sh
-bazel run //src/ariadne:ariadne -- --output-dir output/
+bazel run //src/ariadne:ariadne
 ```
 
-The skeleton currently declares one `parse` stage.
-It writes a placeholder artifact under `output/graph/parse/`.
+Write output under a specific directory:
 
-Use `--force` to remove stage output before rerunning the stage.
+```sh
+bazel run //src/ariadne:ariadne -- --output-dir output
+```
+
+Run through a specific target stage and its prerequisites:
+
+```sh
+bazel run //src/ariadne:ariadne -- parse
+bazel run //src/ariadne:ariadne -- add-jump-edges
+```
+
+Available target stages:
+
+- `all`
+- `parse`
+- `add-implicit-edges`
+- `add-init-edges`
+- `add-jump-edges`
+
+Relative `--output-dir` paths resolve from the workspace root when Ariadne runs through `bazel run`.
+
+## Pipeline skeleton
+
+Ariadne currently has pipeline scaffolding only.
+Each executable stage prepares an output directory at:
+
+```text
+<output-dir>/graph/<stage>/
+```
+
+If a stage output directory already exists and is not empty, Ariadne fails unless `--force` is set.
+With `--force`, Ariadne removes the existing stage output directory before recreating it.
+
+Stage implementations are placeholders and do not write graph artifacts yet.