docs: add package and agent workflow guides

.claude/skills/gnn4colliders-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gnn4colliders-workflow
-description: Run, validate, and modify GNN4Colliders with public Hugging Face data, semantic configs, ROOT-GNN parity, and the repository architecture.
+description: Run, validate, and modify the canonical GNN4Colliders package using semantic configs, public Hugging Face ROOT data, ROOT-GNN checks, and the shared package architecture.
 ---
 
 # GNN4Colliders workflow
@@ -8,16 +8,20 @@ description: Run, validate, and modify GNN4Colliders with public Hugging Face da
 Use this skill for package execution, validation, training, data preparation,
 or implementation work in GNN4Colliders.
 
-Read [the shared workflow runbook](../../../docs/agent-workflows/gnn4colliders-workflow.md)
-before acting. It is the canonical source for commands and scientific
-invariants.
+Read [the shared workflow runbook](../../../docs/agent-workflows/gnn4colliders-workflow.md),
+[`docs/architecture.md`](../../../docs/architecture.md), and
+[`docs/configuration.md`](../../../docs/configuration.md) before non-trivial
+work. They are the canonical source for commands and scientific invariants.
 
 Start with `config_hf_smoke` for small public-data checks; use
-`config_hf_delphes` only for requested full 12-process work. Run
-`python -m validation.run_public_validation` for scientific validation and
-`GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity` for strict
+`config_hf_delphes` only for requested full 12-process work. For a temporary
+end-to-end check, run `uv run python scripts/dev/smoke_end_to_end.py`. Run
+`uv run python -m validation.run_public_validation` for scientific validation
+and `GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity` for strict
 ROOT-GNN parity. Before non-trivial changes, inspect
-`docs/architecture.md` and `docs/migration.md`. Do not modify `legacy/`.
+`docs/architecture.md` and `docs/migration.md`. Historical runtime code is
+not part of main; use frozen parity fixtures and explicit compatibility
+adapters for old checkpoints or output formats.
 
 Report exact commands, test counts, meaningful skips, parity status, and
 unresolved questions at handoff.

.codex/skills/gnn4colliders-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gnn4colliders-workflow
-description: Run, validate, and modify the GNN4Colliders package using its public Hugging Face data, semantic configs, ROOT-GNN parity gates, and repository architecture.
+description: Run, validate, and modify the canonical GNN4Colliders package using semantic configs, public Hugging Face ROOT data, ROOT-GNN checks, and the shared package architecture.
 ---
 
 # GNN4Colliders workflow
@@ -8,20 +8,28 @@ description: Run, validate, and modify the GNN4Colliders package using its publi
 Use this skill for package execution, validation, training, data preparation,
 or implementation work in GNN4Colliders.
 
-Read [the shared workflow runbook](../../../docs/agent-workflows/gnn4colliders-workflow.md)
-before acting. It contains the canonical commands and project-specific
-scientific invariants.
+Read [the shared workflow runbook](../../../docs/agent-workflows/gnn4colliders-workflow.md),
+[`docs/architecture.md`](../../../docs/architecture.md), and
+[`docs/configuration.md`](../../../docs/configuration.md) before non-trivial
+work. They contain the canonical commands and project-specific scientific
+invariants.
 
 Key routing:
 
 - Start with `config_hf_smoke` for a small public-data execution check.
 - Use `config_hf_delphes` only when the full 12-process dataset is requested.
+- Use `uv run python scripts/dev/smoke_end_to_end.py` for a fast temporary ROOT
+  prepare/train/evaluate/predict workflow.
 - Run `validation.run_public_validation` for the portable scientific check.
 - Use `GNN4COLLIDERS_REQUIRE_ROOT_GNN=1` for mandatory ROOT-GNN parity.
 - Inspect `docs/architecture.md` and `docs/migration.md` before non-trivial
   changes.
-- Keep implementation architecture-neutral where possible and do not modify
-  `legacy/`.
+- Keep shared data, features, tasks, training, and inference architecture-
+  neutral; put graph topology in `graphs/` and model-specific behavior in
+  `models/root_gnn/`.
+- Historical runtime code is not part of main. Use committed frozen parity
+  fixtures and explicit compatibility adapters for old checkpoints or output
+  formats.
 
 When handing off work, include exact commands, test counts, meaningful skips,
 parity status, and unresolved ambiguity.

README.md

@@ -11,6 +11,12 @@ datasets:
 - HWresearch/Delphes
 ---
 
+## Using the package
+
+This file is the research paper and model card. For installation and practical
+CLI instructions, start with the [package quickstart](docs/quickstart.md).
+The deeper developer guide is [README_PROJECT.md](README_PROJECT.md).
+
 # Pretrained Event Classification Model for High Energy Physics Analysis
 
 Joshua Ho, Ryan Roberts, Shuo Han, and Haichen Wang

docs/agent-workflows/gnn4colliders-workflow.md

@@ -30,6 +30,16 @@ uv sync --dev --extra root-gnn
 Use the `root-gnn` extra for DGL-backed tests and ROOT-GNN workflows. ONNX
 checks additionally need the `onnx` extra.
 
+For the shortest end-to-end check, use the repository's temporary ROOT
+fixture:
+
+```bash
+uv run python scripts/dev/smoke_end_to_end.py
+```
+
+This creates a temporary ROOT file, prepares a graph cache, trains one CPU
+epoch, evaluates, predicts, and removes its temporary files.
+
 ## Public data and configurations
 
 The supported public source is the pinned `HWresearch/Delphes` dataset. The
@@ -53,6 +63,21 @@ The full configuration can download a large dataset. Do not use it for an
 ordinary smoke check. See [configuration.md](../configuration.md) for source
 fields, cache behavior, labels, and split semantics.
 
+The CLI has five subcommands:
+
+```bash
+uv run gnn4colliders prepare ...
+uv run gnn4colliders train ...
+uv run gnn4colliders evaluate ...
+uv run gnn4colliders predict ...
+uv run gnn4colliders export ...
+```
+
+Use semantic Hydra overrides such as `model=root_gnn/edge_network` and
+`task=binary_classification`; keep implementation module paths out of user
+configuration. A run writes its resolved configuration and checkpoints below
+`environment.output_root`.
+
 ## Validation and testing
 
 Run the portable scientific regression before claiming a data or physics
@@ -87,6 +112,10 @@ on CPU hosts and must be reported.
   modules.
 - Avoid private filesystem paths, hidden global state, and untracked generated
   validation output.
+- Do not import or recreate a historical runtime backend. The old behavior is
+  represented by frozen reference fixtures and the `root-gnn-parity-baseline`
+  tag; compatibility code is limited to explicit checkpoint/metadata/output
+  boundaries.
 - For a parity difference, characterize it with a deterministic test and state
   whether it is intentional.
 

docs/quickstart.md

@@ -0,0 +1,149 @@
+# GNN4Colliders quickstart
+
+GNN4Colliders turns collider ROOT events into shared event samples, applies
+physics features, builds a representation for a selected model family, and
+runs training or inference through one CLI. The current production model
+family is `root_gnn`; the shared data and task layers are intended to support
+future representations as well.
+
+```text
+ROOT -> EventSample -> features -> GraphSampleCache -> ROOT-GNN -> logits
+```
+
+## Install
+
+The supported environment is Python 3.12. From the repository root:
+
+```bash
+uv sync --dev --extra root-gnn
+```
+
+The `root-gnn` extra is required for DGL-backed graph workflows and ROOT-GNN
+parity tests. Add `--extra onnx` when using export validation.
+
+## Run a local end-to-end smoke test
+
+This is the fastest way to verify the package without downloading production
+data:
+
+```bash
+uv run python scripts/dev/smoke_end_to_end.py
+```
+
+The script creates a tiny temporary ROOT file, prepares a cache, trains one
+CPU epoch, evaluates, predicts, and cleans up. It is the recommended first
+command after installation or a code change.
+
+## Run the public Hugging Face smoke configuration
+
+The small pinned fixture is selected by `config_hf_smoke`:
+
+```bash
+uv run gnn4colliders prepare --config-name config_hf_smoke
+uv run gnn4colliders train --config-name config_hf_smoke
+```
+
+The first command resolves and caches the public ROOT fixture. The default
+debug trainer runs one epoch. Outputs are written below `outputs/hf_smoke/`;
+the resolved configuration and checkpoint path are recorded there.
+
+For the full 12-process pretraining source, use this only when the larger
+download is intentional:
+
+```bash
+uv run gnn4colliders prepare --config-name config_hf_delphes
+```
+
+The data source, revision, checksum, tree, feature branches, and split rules
+are documented in [configuration.md](configuration.md).
+
+## Use your own ROOT file
+
+Preparation accepts Hydra overrides. Supply the ROOT file, tree, cache path,
+feature branch specification, object types, and scales:
+
+```bash
+uv run gnn4colliders prepare \
+  data.files=[data/events.root] \
+  data.tree_name=Events \
+  data.cache.path=cache/events.pt \
+  'data.feature_branches=[[jet_pt],[jet_eta],[jet_phi],CALC_E,[1.0],[0.0],NODE_TYPE]' \
+  data.object_types=[vector] \
+  data.scales=[1,1,1,1,1,1,1]
+```
+
+Then train, evaluate, or predict using the same cache:
+
+```bash
+uv run gnn4colliders train data.cache.path=cache/events.pt trainer.max_epochs=1
+uv run gnn4colliders evaluate \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/default/checkpoints/epoch_0000.pt
+uv run gnn4colliders predict \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/default/checkpoints/epoch_0000.pt \
+  inference.output=outputs/predictions.npz
+```
+
+The feature override above is illustrative: replace it with branches that
+exist in the input tree. See [configuration.md](configuration.md) for the
+full schema.
+
+## Models, tasks, and checkpoints
+
+Select behavior with semantic config groups rather than Python module paths:
+
+```bash
+uv run gnn4colliders train \
+  model=root_gnn/edge_network \
+  task=pretraining_multiclass \
+  data.cache.path=cache/events.pt \
+  trainer.max_epochs=20
+```
+
+To fine-tune a pretrained ROOT-GNN checkpoint, use the fine-tuning model and
+provide `checkpoint.pretrained`:
+
+```bash
+uv run gnn4colliders train \
+  model=root_gnn/fine_tuned_edge_network \
+  task=binary_classification \
+  data.cache.path=cache/target.pt \
+  checkpoint.pretrained=/path/to/pretrained.pt \
+  model.freeze_backbone=true
+```
+
+`checkpoint.resume` continues an existing run, restoring its training state;
+`checkpoint.pretrained` starts a new task from model weights and creates a new
+head and optimizer. Evaluation uses the held-out test split by default.
+
+## Validate changes
+
+Run focused tests first, then the full suite and style checks:
+
+```bash
+uv run pytest tests/unit -q
+GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity -q
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+```
+
+For the portable public-data regression:
+
+```bash
+uv run python -m validation.run_public_validation --no-download
+```
+
+The parity gate requires DGL and compares the new implementation against
+committed frozen reference fixtures. Historical runtime code is not imported
+from main; compatibility adapters are reserved for old checkpoint, metadata,
+and output boundaries.
+
+## Where to look next
+
+- [Architecture](architecture.md) — package boundaries and data flow.
+- [Configuration](configuration.md) — Hydra groups and data sources.
+- [Migration](migration.md) — rewrite status and compatibility policy.
+- [Developer guide](../README_PROJECT.md) — transfer learning, distributed
+  training, ONNX export, and output contracts.