From 03faea59c8f24485e066567119dec0c772a21a46 Mon Sep 17 00:00:00 2001
From: homfunc <4338462+homfunc@users.noreply.github.com>
Date: Fri, 1 May 2026 12:53:37 +1200
Subject: [PATCH] Update local integration documentation

Co-Authored-By: Oz <oz-agent@warp.dev>
---
 README.md       |  9 +++++++++
 instructions.md | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 instructions.md

diff --git a/README.md b/README.md
index b828abb68..fb8e3dfe5 100644
--- a/README.md
+++ b/README.md
@@ -87,6 +87,15 @@ version with PyTorch and TensorFlow). We aim to depreciate the TF part in 2027.
 
 We recommend using our conda file, see [here](https://github.com/DeepLabCut/DeepLabCut/blob/main/conda-environments/README.md) or the [`deeplabcut-docker` package](https://github.com/DeepLabCut/DeepLabCut/tree/main/docker). 
 
+## Local sibling-repo integration
+This repository can also be used as a sibling checkout together with:
+- `../XROMM_DLCTools`
+- `../xmalab`
+
+In that local layout, `XROMM_DLCTools` uses the optional `dlc` dependency group to import this checkout directly, and its baseline harness runs both a DeepLabCut smoke scenario and a broader end-to-end local workflow integration scenario.
+
+See `instructions.md` in this repo for the local integration notes and exact commands.
+
 # [Documentation: The DeepLabCut Process](https://deeplabcut.github.io/DeepLabCut/README.html)
 
 Our docs walk you through using DeepLabCut, and key API points. For an overview of the toolbox and workflow for project management, see our step-by-step at [Nature Protocols paper](https://doi.org/10.1038/s41596-019-0176-0).
diff --git a/instructions.md b/instructions.md
new file mode 100644
index 000000000..cc9bf4cbf
--- /dev/null
+++ b/instructions.md
@@ -0,0 +1,39 @@
+# DeepLabCut Local Integration Instructions
+These notes describe how this repository is used in the local 3-repo XROMM workflow together with `../XROMM_DLCTools` and `../xmalab`.
+## 1) Expected local layout
+Recommended sibling checkout layout:
+- `XROMM_DLCTools/`
+- `DeepLabCut/`
+- `xmalab/`
+`XROMM_DLCTools/pyproject.toml` maps its optional `dlc` dependency group to this repository through `tool.uv.sources`.
+## 2) DeepLabCut’s role in the workflow
+Within the integrated workflow, DeepLabCut provides:
+- project creation / dataset generation support
+- video analysis / prediction entrypoints
+- the local import target used by `XROMM_DLCTools`
+- synthetic smoke coverage through the baseline harness
+The current local integration suite also uses this repo to verify that the newer workflow service in `XROMM_DLCTools` still interoperates with a sibling DeepLabCut checkout.
+## 3) Local setup for this repo
+Standard developer setup:
+```bash
+uv sync --group dev
+```
+When working from `../XROMM_DLCTools`, enable the sibling import path there with:
+```bash
+uv sync --group dlc
+```
+## 4) Integration validation from XROMM_DLCTools
+Run these commands from `../XROMM_DLCTools`:
+```bash
+uv run python scripts/baseline_harness.py --scenario deeplabcut_repo_smoke --output-dir baseline_artifacts/deeplabcut_smoke --deeplabcut-repo ../DeepLabCut
+```
+Full multi-repo suite:
+```bash
+uv run python scripts/baseline_harness.py --scenario all --output-dir baseline_artifacts/integration_all --deeplabcut-repo ../DeepLabCut --xmalab-repo ../xmalab
+```
+True end-to-end local workflow scenario:
+```bash
+uv run python scripts/baseline_harness.py --scenario phase3_local_workflow_e2e --output-dir baseline_artifacts/e2e_local_workflow --deeplabcut-repo ../DeepLabCut --xmalab-repo ../xmalab
+```
+## 5) Compatibility notes
+The local workflow integration path expects this repo to remain importable in “lite mode” when GUI dependencies are unavailable, and relies on the public `deeplabcut` import surface plus the synthetic project helpers under `examples/utils.py`.