willtools-demo/docs/snapshot-tool.md

Snapshot tool — how it works, and how to run it

The snapshot tool makes a timestamped, detached copy of the model, opens a Revit onto that copy on its own (nobody in front of it), runs a batch inside it, and closes — so the engineer's own model and session are never tied up.

It is two halves:

1. SnapshotClose pushbutton (Tools panel, runs inside the live Revit). Its one irreplaceable job is Phase A: hand over the model's IDENTITY. Only the open document can cheaply report a cloud model's region + GUIDs, and without those nothing else can find the model again. Phase A also indexes the model as it stands (this is where the reinforce feature registry is refreshed) and journals what it did. It then writes a request file (the cached identity) and spawns the detached host cycle — it does not make the copy itself.
2. tools/snapshot_cycle.py (plain host CPython, detached — Claude can start it, no Revit needs to be open in front of anyone). Five steps: DETACH → close-sandbox → open-sandbox → run batch → CLOSE, each journalled.

Why a copy is made by SaveAs, not "Detach from Central"

A cloud model cannot be opened detached: any DetachFromCentralOption on a cloud ModelPath raises "Detach option is not valid for cloud model," Autodesk says SaveAs is the way, and the UI greys the checkbox out. So the cycle's "detach" is a SaveAs to a timestamped copy under snapshot.detached_dir.

The one rule that makes it usable: identity is captured once, from a live press

A cloud model is only identifiable from a session that has it open — the region and GUIDs live in the open document. So:

• You must press SnapshotClose once from a live session that has the model open. That press captures the cloud GUIDs and caches them (the request file).
• After that, the cycle can run with NO live session — it reopens the model from the cached GUIDs. This is the path to auto-running snapshots with nobody in front of Revit: identity cached once → every later cycle is headless.

If the identity was never cached (e.g. the press was interrupted), the cycle cannot start and says so — a cloud model with only a display path and no GUIDs can't be located. Fix: open the model and press SnapshotClose once more.

Running the cycle by hand (after the identity is cached)

python tools/snapshot_cycle.py \
  --fresh-detach \                 # write a new timestamped copy first
  --job "<job folder under WILLTOOLS_JOBS>" \
  --request <the request file the button cached> \   # OR --source <path>, OR
                                                     # snapshot.source_cloud in job knowledge
  --revit 2024 \                   # PIN the year — the machine has several Revits;
                                   # omitting this is what silently no-fired before
  --revit-exe "C:/Program Files/Autodesk/Revit 2024/Revit.exe" \
  --pyrevit  "C:/Users/<you>/AppData/Roaming/pyRevit-Master/bin/pyrevit.exe" \
  --dry-run                        # print the whole plan and do NOTHING — always dry-run first

Drop --dry-run to actually run. Useful flags: --run "<host cmd>" (the batch, default snapshot.batch), --keep-open, --wait-minutes, --use <file> (skip the detach and cycle onto an existing copy).

Job-knowledge keys the cycle reads (WILLTOOLS_JOBS/<job>/knowledge.yaml)

snapshot:
  detached_dir: <where timestamped copies are written>   # REQUIRED, or --detached-dir
  source_cloud: {region: ..., project_guid: ..., model_guid: ...}  # optional: lets the
                                    # cycle run with no live press ever, once you have the GUIDs

Journal — every run is recorded, silence is never success

<job>/snapshots.jsonl gets a line on every exit path (this was a real bug once: a day the cycle never fired looked exactly like a day it worked, so a missing run is now reported in capitals at the top of the report). Phase A also journals phase-a-snapshot (piece count, timing, provenance) and phase-a-update-stats (the reinforce feature-ID diff).

Known failure modes

• snapshot.detached_dir is not set → set it in job knowledge, or --detached-dir.
• "a fresh detach needs to know WHICH model to copy" → identity not cached; press SnapshotClose once from the live model (see the identity rule above).
• Silent no-fire in ~16 s → historically a missing --revit=<year> with several Revit versions installed; always pin --revit. The cycle now resolves the year from the exe and journals on every exit, so this is loud now.

Toward fully automatic

Once snapshot.source_cloud (the GUIDs) is stored in the job knowledge — captured once from a live press — the cycle needs no Revit open in front of anyone and no request file, so it can be scheduled/auto-run headlessly. That is the intended end state.