From b1882b8af2d92657d09ae61686eec442ddf7e27e Mon Sep 17 00:00:00 2001
From: Glen Beane <356266+gbeane@users.noreply.github.com>
Date: Tue, 28 Jul 2026 15:38:11 -0400
Subject: [PATCH 1/5] Add JABS Hub-backed projects client integration plan

---
 .../plans/jabs-hub-backed-projects-plan.md    | 608 ++++++++++++++++++
 1 file changed, 608 insertions(+)
 create mode 100644 docs/development/plans/jabs-hub-backed-projects-plan.md

diff --git a/docs/development/plans/jabs-hub-backed-projects-plan.md b/docs/development/plans/jabs-hub-backed-projects-plan.md
new file mode 100644
index 00000000..6e117b00
--- /dev/null
+++ b/docs/development/plans/jabs-hub-backed-projects-plan.md
@@ -0,0 +1,608 @@
+# Plan: Hub-Backed JABS Projects — Client Integration (jabs-behavior-classifier)
+
+**Status:** Draft / planning 
+**Author:** Glen Beane (with Claude Code)  
+**Repository:** `jabs-behavior-classifier` (this repo — the PySide6 desktop GUI / Python client).  
+**Companion doc:** the Hub-side (Go) design lives in the `jabs-hub` repo at
+`docs/specs/0006-jabs-project-backend-design.md`. The REST API, the PostgreSQL data model, and
+the annotation-document schema (Appendix A.1) are the **shared contract** — keep them in sync. 
+**Scope:** The client half of Hub-backed JABS projects under a **cloud-native** model: the desktop
+GUI becomes a caching client that pulls videos, pose files, annotations, and project metadata from
+JABS Hub / Google Cloud Storage into a local cache, works against the cache (frame-accurate
+labeling, feature extraction, training, offline), and pushes changes back.
+
+---
+
+## 1. Overview — JABS Hub-backed projects
+
+A **Hub-backed JABS project is a cloud project**: its videos, pose files, behavior annotations,
+and project metadata all live in **JABS Hub** (PostgreSQL + Google Cloud Storage, at
+`github.com/TheJacksonLaboratory/jabs-hub`). The desktop GUI is a **caching client** — it pulls
+what it needs from Hub / GCS into a local **cache directory**, works against the cache, and pushes
+changes back. There is **no hybrid**: a Hub-backed project never has authoritative local-only
+media. Local-only (non-Hub) projects are unchanged.
+
+- **Videos live in a shared library.** Videos — external/uploaded files *or* JABS-2.0 device
+  recordings — are uploaded into a Hub **video library**, decoupled from any recording session. A
+  project references library videos **many-to-many**: one stored copy can back multiple projects.
+- **Source of truth = cloud; local = cache.** One uniform pull → cache → push model for every
+  *source* artifact (video, pose, annotations, metadata). **Derived** artifacts (features,
+  predictions, classifiers) are recomputed locally from the cached pose and stay local (§4.9).
+- **Offline-first.** The cache makes a project fully usable offline; edits queue and sync on
+  reconnect.
+- **Primary driver.** Replace the "zip up `jabs/annotations/` and email it" label-sharing workflow
+  with automatic, versioned sync (§2.3). Because the exact pose file also comes from Hub, the
+  identity-alignment footgun (labels are keyed by identity, which the pose file defines) is
+  **eliminated**, not merely flagged.
+
+**This is a two-part plan**, split across the two repositories it touches:
+
+- **Client integration** — *this document* (`jabs-behavior-classifier`): OIDC auth, the Hub
+  client, the caching layer (media resolver + annotation cache), sync engine, opt-in/open flows,
+  and playback of Hub-hosted media.
+- **Hub backend** — `jabs-hub` repo, `docs/specs/0006-jabs-project-backend-design.md`: the video
+  library + decoupled upload, the `projects` / `project_videos` (many-to-many) / `annotations`
+  data model, the REST API, membership/authorization, and media object storage.
+
+### Phasing (cloud-native, library-first build order)
+
+| Phase | Title | Delivers |
+|------|-------|----------|
+| **0** | Foundations | OIDC auth in the client + `HubClient`; the client cache/abstraction seams (annotation store + media resolver) landed as a pure refactor with local-only behavior unchanged. (Hub: auth on new routes, base scaffolding.) |
+| **1** | Video library + media | Client: a Hub-aware media resolver + local media cache + lazy hydration + playback prefetch — download/cache to **open and play** a Hub project's videos. (Uploading into the library is a web-UI / `jabs-cli` concern.) (Hub: `videos` table, decoupled upload, list/search, content-addressed storage, signed download.) Deliverable: the GUI opens a Hub project and plays its videos. |
+| **2** | Hub-backed projects | Client: **open** a cloud project (created in the web UI) referencing library videos; the local project dir is a cache; project-settings sync. (Hub: `projects` + `project_members` + `project_videos` join + metadata.) |
+| **3** | Annotations (label sharing) | Client: annotation cache + sync engine + offline outbox + conflict handling; pose consistency guaranteed. (Hub: `annotations` + history + optimistic-concurrency contract + behavior index.) Delivers the label-sharing payoff. |
+| **Post-MVP** | Collaboration + ML | Web preview playback + prediction-track overlay (library browse itself is part of the initial web UI), classifier registry/model cards, real-time collaboration, normalized fine-grained labels. |
+
+Phase 0 lands the seams first so they are independently reviewable and de-risk the rest (mirrors
+the 0001 Parquet feature-cache implementation plan, which extracted the I/O boundary
+before changing behavior).
+
+**Relationship to prior work:** this supersedes the older *"JABS Hub"* Word design doc (the
+device/recording/processing platform already exists) **and** an earlier iteration of this plan that
+migrated annotations first and left media local. The cloud-native model was chosen deliberately
+over that piecemeal approach: the video library needs cloud media anyway, and full cloud storage
+makes the label-sharing use case correct (shared pose ⇒ aligned identities) rather than merely
+warned.
+
+---
+
+## 2. Goals, Non-Goals, and Motivating Use Cases
+
+### 2.1 Goals
+
+1. **Cloud-native Hub-backed projects.** A Hub-backed project stores its video, pose, annotations,
+   and metadata in Hub; the GUI caches locally and stays fully usable offline. Local-only projects
+   are unaffected.
+2. **Video library as the media home.** The GUI pulls library videos (and pose) down for
+   playback/labeling/training. Uploading into the library is a web-UI / `jabs-cli` task, not a
+   desktop-GUI flow.
+3. **Automatic annotation sync** with version history, attribution, and conflict handling —
+   replacing the manual zip hand-off.
+4. **Uniform caching model.** One pull/cache/push mechanism for every source artifact; derived
+   artifacts recomputed locally from the cached pose.
+5. **Single source of authority.** Hub is authoritative online; the client reconciles the cache
+   against it, resolving the "which copy is current" ambiguity.
+
+### 2.2 Non-Goals
+
+- Replacing the desktop GUI with a web labeling client. The GUI stays the frame-accurate labeling
+  surface; the JABS Hub web UI (to be developed) creates/manages projects and the video library but
+  does not do frame-accurate labeling.
+- **Creating or managing Hub projects in the desktop GUI** (create a project, add library videos,
+  share) — that happens in the JABS Hub web UI. The desktop GUI **opens** an existing Hub project by
+  its identifier (§4.7).
+- Storing **derived** artifacts (features/predictions/classifiers) in Hub for the MVP — they are
+  recomputed locally from the cached pose (§4.9). An **optional cloud cache for features** (the
+  expensive one) and a classifier registry for predictions/classifiers are post-MVP (§10).
+- Real-time collaborative cursors / live presence (post-MVP).
+- True frame streaming of remote video (playback is download-to-cache + prefetch; §4.6).
+
+### 2.3 Motivating use cases
+
+1. **Asymmetric label sharing (primary driver; needs Phase 3 annotation sync *and* project sharing, D19).** A behavior expert labels
+   videos; a colleague trains/evaluates classifiers from those labels. Today the expert zips
+   `<project>/jabs/annotations/` and sends it — manual, overwrites local work, no history, and no
+   guarantee both sides use the *same* pose file. In a cloud project both users open the same Hub
+   project; labels sync automatically with history and attribution, and because the **pose file is
+   pulled from Hub too**, the collaborator's labels always align to the correct identities. No zip,
+   no overwrite, no pose-mismatch footgun.
+2. **Create a project in the web UI, open it in the GUI.** In the JABS Hub web UI a user creates a
+   project and adds videos to it from the library (JABS recordings or uploaded external files), then
+   opens it in the desktop GUI (§4.7) — the media hydrates on demand.
+3. **Work from any machine / HPC** with no manual file copying — the cache hydrates from Hub.
+
+### 2.4 Unobtrusiveness for non-Hub users (hard requirement)
+
+Many JABS users do not have access to (or do not use) JABS Hub. Hub integration MUST be invisible
+to them:
+
+- **No startup cost.** The app launches and every local-project workflow behaves exactly as today —
+  no network calls, no auth prompts, no "sign in to Hub" nags, no added latency. Hub code paths are
+  **lazy-imported** and never execute until the user invokes a Hub action.
+- **One unobtrusive entry point.** A single **File → "Open Project from JABS Hub"** menu item
+  (§4.7); no toolbars, banners, or modal prompts intrude on local use. Local project open/create
+  never touches Hub.
+- **Opt-in auth.** OIDC login is triggered only by a Hub action, never at startup; credentials live
+  in the OS keyring, never in project files.
+- **Graceful absence.** If the Hub client dependency or connectivity is unavailable, only Hub
+  actions are affected — local projects are untouched, with a clear message rather than a crash.
+
+A regression test asserts that launching the app and opening a local project make **zero** Hub
+imports or network calls (§7).
+
+---
+
+## 3. Current State — client seams we build on
+
+### 3.1 Video/pose resolution seams (now core, not Phase 2)
+
+- Video↔pose pairing is name-derived: `NAME.mp4` ↔ `NAME_pose_est_v{N}.h5` (`_POSE_SUFFIX_RE`,
+  `packages/jabs-core/.../utilities.py:69`; `get_pose_path`,
+  `src/jabs/pose_estimation/__init__.py:40`).
+- **Single video path resolver:** `VideoManager.video_path(video_file)` →
+  `Path(video_dir, video_file)` (`src/jabs/project/video_manager.py:251`). **This is the seam a
+  Hub-aware resolver overrides** to download-on-demand into the cache.
+- **Single video open point:** `VideoReader.__init__` → `cv2.VideoCapture(str(path))`
+  (`src/jabs/video_reader/video_reader.py:19`). Path-only; needs random-access seeking → the
+  client must **download the full file to the cache before opening** (no true streaming).
+- **`video_dir` / `pose_dir` are already decoupled** from the project directory (`ProjectPaths`,
+  `src/jabs/project/project_paths.py:18`; `Project.__init__` accepts them, `project.py:189`). This
+  is exactly the plumbing to point at a cache root.
+- **Pose loading needs the full local file** (hashed end-to-end via `hash_file`,
+  `utilities.py:39`; h5py random access). No lazy/partial read → download-to-cache.
+- **Feature/prediction caches key on name + validate on pose hash** (blake2b), not on path
+  (`src/jabs/feature_extraction/features.py:178`; `packages/jabs-io/.../feature_cache/base.py:71`;
+  `src/jabs/project/prediction_manager.py:167`). **Consequence:** a byte-identical pose pulled from
+  Hub keeps derived caches valid — the basis for keeping derived artifacts local (§4.9).
+- **Project open touches every video/pose file** (`_validate_pose_files`, `video_manager.py:238`;
+  scan workers, `parallel_workers.py:175`) — must become **manifest-driven + lazy** so opening a
+  cloud project does not download everything up front (§4.6).
+
+### 3.2 Annotation seams
+
+- **Writes funnel through one method:** `Project.save_annotations(annotations, pose)`
+  (`src/jabs/project/project.py:618`) — atomic temp-file `replace()` into
+  `jabs/annotations/<video>.json`, stamps `labeler` (`getpass.getuser()`). Single write seam.
+- **Reads are scattered across four sites**, all direct `open()` + `json`:
+  `VideoManager.load_video_labels` (`video_manager.py:109`), `VideoManager.load_annotations`
+  (`:262`), `Project.load_counts` (`project.py:1461`), and — in a **child process** —
+  `parallel_workers._load_video_labels` (`parallel_workers.py:207`, path from `project.py:978`).
+- **Serialization is clean:** `VideoLabels.as_dict` / `.load` (`video_labels.py:178` / `:278`),
+  plain JSON, `SERIALIZED_VERSION = 1` (`video_labels.py:16`). Schema in Appendix A.1.
+- **No storage abstraction** today; all concrete `pathlib` + `json`. GUI saves eagerly and
+  synchronously on every edit (`central_widget.py:880`, …). `VideoLabels.merge` with a
+  `MergeStrategy` exists (`video_labels.py:301`) for conflict resolution.
+
+### 3.3 Project + settings seams
+
+- **`Project`** (`project.py:137`) composes `ProjectPaths`, `SettingsManager`, `VideoManager`,
+  `FeatureManager`, `PredictionManager`, `SessionTracker`. **`SettingsManager`**
+  (`settings_manager.py`) owns `project.json` (behaviors, window sizes, settings, metadata,
+  video_files, selected_behavior).
+- Videos are enumerated by a **local directory glob** (`VideoManager.get_videos`,
+  `video_manager.py:153`) → for a cloud project this becomes the Hub **manifest**
+  (`GET /projects/{id}/videos`).
+
+---
+
+## 4. Client Architecture
+
+### 4.1 High-level
+
+```mermaid
+flowchart LR
+    subgraph Desktop["JABS desktop GUI (jabs-behavior-classifier)"]
+        UI[GUI / Project]
+        RES[Media resolver]
+        AS[Annotation cache/store]
+        CACHE[(Local cache dir\nvideo + pose + jabs/)]
+        DERIVED[(Derived: features/predictions\nrecomputed locally)]
+        HC[HubClient + OIDC]
+        UI --> RES
+        UI --> AS
+        RES --> CACHE
+        AS --> CACHE
+        CACHE --> DERIVED
+        UI --> HC
+        RES --> HC
+    end
+
+    subgraph Hub["JABS Hub (Go / net-http / api/v0)"]
+        API[HTTP API + JWT auth]
+        DB[(PostgreSQL\nvideos, projects, annotations)]
+        GCS[(GCS object storage\nvideo + pose, content-addressed)]
+        API --> DB
+        API --> GCS
+    end
+
+    HC -- "REST /api/v0 (Bearer JWT)" --> API
+    HC -- "signed URLs (media up/download)" --> GCS
+    Auth[(Auth0 / OIDC)]
+    HC -- "Auth Code + PKCE" --> Auth
+    API -- "verify JWT" --> Auth
+```
+
+### 4.2 Cloud project = local cache
+
+- **Hub is authoritative** for all source artifacts (video, pose, annotations, metadata). The
+  local project directory is a **cache/working copy** populated from Hub:
+  `ProjectPaths.video_dir`/`pose_dir` point at a media cache root; `jabs/annotations/` is an
+  annotation cache; `project.json` is cached from `projects.settings`.
+- **Uniform lifecycle:** on open, fetch the project manifest, then **lazily** hydrate media as
+  videos are selected, pull annotations, and cache settings. On edit, write the cache immediately
+  and push to Hub in the background. Offline: work against the cache; queue pushes.
+- **Why a cache (not a pure thin client):** the OpenCV reader is path-only and needs seeking, pose
+  needs the full file for h5py + hashing, and the multiprocess training path reads files by
+  `Path`. A local cache satisfies all three with no change to those subsystems, and delivers
+  offline use for free.
+
+### 4.3 Video identity and the library (as the client relies on it)
+
+Owned by the Hub data model (see the Hub doc — Data Model); the client depends on it:
+
+- **A video is a first-class library entity** with a `video_id` UUID — never identified by
+  filename. Projects reference library videos through a **`project_videos` join**
+  (`project_video_id`), many-to-many. One library video can back several projects.
+- **Per project, a video has a `name_in_project`** (the local filename the GUI uses), unique
+  within the project (`UNIQUE(project_id, name_in_project)`). The client maps
+  `name_in_project → project_video_id` from the project manifest, so the cache paths
+  (`<cache>/<name_in_project>`, `jabs/annotations/<name>.json`) never collide within a project.
+- **Annotations are per project+video** (keyed by `project_video_id`): labeling a shared library
+  video in project A never affects project B.
+
+### 4.4 Client caching seams (Phase 0 refactor)
+
+Two seams are introduced as pure refactors (local-only behavior identical to today), then given
+Hub-backed implementations:
+
+**(a) Media resolver** — front the single video/pose path resolvers (§3.1) with a resolver that,
+for a cloud project, downloads-on-demand into the cache and returns the cached path (verifying the
+blake2b hash against the manifest). For a local project it returns the existing path (no-op).
+
+**(b) `AnnotationStore`** — a protocol over the serialized document dict + version:
+
+```python
+class AnnotationStore(Protocol):
+    def load_document(self, video_name: str) -> tuple[dict, int] | None: ...
+    def save_document(self, video_name: str, document: dict, base_version: int | None) -> int: ...
+    def list_labeled_videos(self) -> list[str]: ...
+    def ensure_local(self, video_name: str) -> Path:
+        """Guarantee a cached file exists (for worker processes); return its path."""
+```
+
+- `LocalAnnotationStore` wraps today's behavior; `HubAnnotationStore` caches + syncs (§4.8).
+- Route all five annotation sites (§3.2) through `Project.annotation_store`. The child-process
+  training path keeps reading by `Path`; the job builder (`project.py:978`) calls
+  `store.ensure_local(name)` first so workers stay network-free.
+
+### 4.5 New package: `jabs-hub-client` (import `jabs.hub`)
+
+A new workspace package `packages/jabs-hub-client` (namespace `jabs.hub`):
+
+- **`HubClient`** — typed wrapper over the Hub REST API (library videos, projects, project-videos,
+  annotations, media URLs). Maps the `{code,message}` envelope to typed exceptions.
+- **OIDC auth** — Authorization-Code + PKCE against Auth0, token cache + refresh, OS-keyring
+  storage. Net-new client capability (the app has no networking today).
+- **Cache manager** — the local cache root, LRU eviction + size cap + "pin for offline," and the
+  sync-state file.
+- **Lazy-loaded core dependency.** `jabs.hub` ships as a **core dependency** (always present, so the
+  menu action always works) but is **lazy-imported** — it and its networking/auth/keyring
+  dependencies load only when a Hub action runs, so non-Hub users pay no import or startup cost
+  (§2.4, D18). Not an optional extra (which would force the menu to handle "not installed").
+
+Depends on `jabs-core` only. Separate from `jabs-io` (which is local format adapters); the
+directory name disambiguates from the Go `jabs-hub` repo while the import stays `jabs.hub` (D8).
+
+### 4.6 Media resolver + cache + playback (Phase 1)
+
+- The Hub-aware `VideoManager`/resolver: (1) sources the video list from the project manifest
+  (`GET /projects/{id}/videos`) instead of the local glob; (2) `video_path()` and
+  `get_cached_pose_path()` **download-on-demand** into the cache and return the cached path — for
+  pose it fetches the project's **pinned** pose file (by its `poseHash`, §4.3/D20), not the
+  library's latest, and verifies the blake2b hash; (3) **defers per-video probing** so open is
+  metadata-driven (manifest `numFrames`/`poseVersion`) and hydrates lazily — never a full-project
+  download at open.
+- **Pose upgrades are explicit.** A library video may accrue multiple pose runs; the project keeps
+  its pinned pose until a user upgrades it. An upgrade re-pins to a newer pose file and **migrates
+  labels** by bbox-IoU (the algorithm exists in `jabs-cli update-pose`,
+  `src/jabs/scripts/cli/update_pose.py`). **Where that migration runs is undecided** — likely a
+  server-side batch job on Hub rather than the GUI client (Hub doc §5.7); the client may just
+  request the upgrade and receive the new annotation version. Not committed to the client.
+- **Clips are materialized server-side; the client just downloads them.** A project reference may be
+  a frame range `[clip_start, clip_end]` of the source video + pinned pose (most projects are built
+  from several short clips, not whole hour-long sessions). Rather than the client offsetting into a
+  full source download — which would mean caching a whole 1-hour video to use a 10-min clip — **Hub
+  materializes the clip** (a concrete clip video + a concrete clip pose = exact slice of the pinned
+  pose) as a regenerable cache (Hub doc §10), and the client downloads those like any other media. So
+  the client fetches **only the clip's bytes**, and the GUI/features see a normal 0-based `clip_len`
+  video + matching pose with **no offset logic and no client-side pose slicing**. The clip pose's
+  blake2b hash (a deterministic slice) keys the clip's feature/prediction caches. Annotations are
+  clip-relative. *(Client-side offset into a full-source download is the fallback for an
+  un-materialized clip.)*
+- **Library upload is a web-UI / `jabs-cli` task, not a desktop-GUI flow** (§4.7). The upload
+  mechanics (compute blake2b, request an upload URL, PUT to GCS, `upload-complete`; pose optional)
+  live in `HubClient` and are exercised by a `jabs-cli` helper (to seed/bulk-load the library) and
+  by the web UI — the desktop GUI itself only *downloads*.
+- **Playback:** because `VideoReader` is path-only + seeks, the selected video is downloaded to the
+  cache before opening; a background **prefetch** warms the selected + adjacent videos.
+- **Derived caches survive:** features/predictions validate on pose hash, and the pulled pose is
+  byte-identical, so existing feature/prediction caches remain valid (§3.1). **Hub must store exact
+  pose bytes (no re-encode)** — a hard requirement on the Hub side.
+
+### 4.7 Opening a Hub project + settings sync (Phase 2)
+
+**Projects are created in the JABS Hub web UI**, not the desktop GUI: a user creates a project, adds
+videos to it from the library, and it appears under their personal projects (shareable with other
+Hub users later). The web UI is being built ahead of this work — recording devices/sessions
+monitoring and the video library first, with **project creation layered on after** — so the
+create-project surface is in place by the time the desktop GUI opens Hub projects. The desktop GUI's
+role is to **open** an existing Hub project.
+
+A Hub-backed project is marked locally by `jabs/hub.json` (`{ "baseUrl", "projectId" }`);
+`Project.__init__` reads it and constructs the Hub-backed resolver + annotation store (else the
+local implementations, unchanged).
+
+**v1 GUI entry point — File → "Open Project from JABS Hub":** the action opens a dialog into which
+the user pastes a **JABS Hub project identifier** — the project's shareable link
+`https://<hub-host>/projects/<projectId>` (the client derives `baseUrl`, the `/api/v0` API base, and
+`projectId`), or a bare `projectId` when a default Hub base URL is configured. The client
+authenticates if needed (§2.4), creates/refreshes a **managed local cache directory** (default under
+an app cache root, e.g. `~/.cache/jabs/hub/<projectId>`; configurable), writes `hub.json`, and opens
+it. No pre-existing local directory is required. Pasting an identifier is how a colleague opens a
+project shared with them (§2.3, D17), and it lets us support Hub projects **before** the desktop GUI
+has a project browser.
+
+- **Reopen:** recent-projects remembers opened Hub projects; reopening skips the paste step and
+  re-hydrates the cache.
+- **Later — JABS Hub project browser:** once authenticated, an in-GUI picker lists the user's Hub
+  projects, replacing the paste step for interactive discovery. The paste-identifier action persists
+  for opening shared projects (D17).
+
+**Project-settings sync:** split `project.json` into **shared** (synced to `projects.settings`:
+`behavior`, `window_sizes`, `defaults`, `metadata`, `video_files` metadata, `classifier_mode`,
+`cv_grouping`) vs **local/GUI** (stays local: `selected_behavior`, `cache_format`, app `version`).
+See D4.
+
+### 4.8 Annotation sync engine + conflict (Phase 3)
+
+- A background **`HubSyncWorker`** (QThread) owns all Hub network I/O; the GUI thread never blocks.
+- On save: write the **annotation cache synchronously** (fast; preserves crash-safety + the
+  training path) → enqueue a **debounced/coalesced** Hub `PUT` with the last-synced `baseVersion`.
+- **Sync-state file** `jabs/hub-sync.json`: per-video `{version, dirty, lastPushedAt}` + an
+  **outbox** for offline replay.
+- On open (online): pull changed annotation docs into the cache (version manifest via
+  `GET /projects/{id}/annotations?includeDocuments=false`). Offline: use the cache.
+- **Conflict:** optimistic version + last-write-wins (matching today's `tmp.replace` semantics) +
+  the cache so nothing is lost; `VideoLabels.merge` available for a later 3-way merge. Hub enforces
+  the check-and-set atomically and returns `409` with the current version (Hub doc —
+  Optimistic-Concurrency Contract).
+- **Pose consistency is guaranteed** (not just warned): the client pulls the project's **pinned**
+  pose file (§4.6), so the labels' identities always align, and the pose changes only via an
+  explicit upgrade. The client asserts its cached pose matches the pinned pose file's `poseHash` as a cheap
+  integrity/tamper check.
+
+```mermaid
+sequenceDiagram
+    participant GUI
+    participant Store as HubAnnotationStore
+    participant Cache as Annotation cache
+    participant Sync as HubSyncWorker
+    participant Hub
+    GUI->>Store: save_document(name, doc, baseVersion)
+    Store->>Cache: atomic write (immediate)
+    Store->>Sync: enqueue PUT (debounced)
+    Sync->>Hub: PUT annotations (If-Match: baseVersion)
+    alt version matches
+        Hub-->>Sync: 200 {version: N+1}
+        Sync->>Cache: update sync-state
+    else conflict
+        Hub-->>Sync: 409 {currentVersion: M}
+        Sync->>Hub: GET annotations (M)
+        Sync->>Sync: resolve (LWW; merge optional)
+        Sync->>Hub: PUT (If-Match: M)
+    end
+```
+
+### 4.9 Derived artifacts stay local
+
+Features, predictions, and trained classifiers are **not** stored in Hub for the MVP. They are
+recomputed locally from the cached pose file, and because the pose is byte-identical to what the
+labels were made against, existing feature/prediction caches stay valid across machines (§3.1).
+This keeps the cloud store to *source* artifacts and avoids syncing large, regenerable data.
+
+**Planned future exception — an optional cloud feature cache (§10).** Feature extraction is
+expensive, and the feature cache is keyed by pose hash + `FEATURE_VERSION` + distance scale (§3.1),
+so a computation done once is valid for the same (byte-identical) Hub pose on **any** machine.
+Optionally storing pre-computed features in Hub and downloading them — instead of every client
+recomputing — is therefore a worthwhile later performance tier, layered on top of the MVP
+"recompute locally" default (lookup order: local cache → Hub feature cache → compute). Predictions
+and classifiers could similarly be shared via a classifier registry.
+
+---
+
+## 5. What the client needs from Hub (the contract)
+
+The full API/DTOs/data model are in the Hub doc. The client depends on:
+
+- **Library + media:** `GET /videos` (list/search), `POST /videos` + `.../video-upload-url` /
+  `.../pose-upload-url` / `.../upload-complete` (upload), `GET /videos/{id}/video-url` /
+  `.../pose-url` (signed download). Media is content-addressed; **exact pose bytes preserved**.
+- **Projects & the join manifest:** `GET/POST /projects`, `GET /projects/{id}`; `GET
+  /projects/{id}/videos` returns the manifest — per association: `projectVideoId`, `videoId`,
+  `nameInProject`, `contentHash`, `poseFileId`, `poseHash`, `poseVersion`, `numFrames` (= clip
+  length), `clipStart`/`clipEnd`, `videoState`/`poseState`, `annotationVersion`. Per-association
+  **signed media URLs** (in the manifest or via `.../videos/{projectVideoId}/media-urls`) resolve the
+  **pinned** pose and the source-or-materialized-clip video — never the library "latest". (Linking
+  videos, `register-recording`, and per-video `pose-files` are web-UI / `jabs-cli` operations, not
+  desktop-client calls.)
+- **Annotations:** `GET/PUT /projects/{id}/videos/{projectVideoId}/annotations` with the
+  `If-Match`/`version`/`409` optimistic-concurrency contract; `GET /projects/{id}/annotations`
+  bulk. On write the client also sends a compact **behavior summary** (per behavior/identity:
+  labeled-frame + bout counts, which it already computes) that Hub folds into its
+  `project_video_behaviors` search index — keeping the annotation document itself opaque (D9).
+- **Auth:** OIDC access token (Auth Code + PKCE) sent as `Bearer` JWT.
+- **Opaque annotation document:** the client owns the schema (Appendix A.1) and evolves it via
+  `SERIALIZED_VERSION` without Hub redeploys.
+
+---
+
+## 6. Testing (client)
+
+- **Unit** (pytest + `monkeypatch`/`unittest.mock`, no network; `pytest-mock` is not available):
+  media-resolver download/cache/hash-verify with a faked `HubClient`; `AnnotationStore` contract
+  tests for both implementations; `VideoLabels.as_dict → store → load` round-trip; sync engine
+  debounce/outbox/409-retry; `ensure_local` hydration keeps the training path local.
+- **Integration (opt-in):** against a locally-run Hub in `AUTH_DEV_MODE`.
+- **Backward-compat guard:** a project with no `hub.json` behaves byte-for-byte as today.
+
+---
+
+## 7. Risks and Mitigations (client)
+
+| Risk | Mitigation |
+|---|---|
+| First open of a large cloud project = many big downloads | Manifest-driven, lazy per-video hydration + prefetch + LRU cache; never download a whole project at open. |
+| `VideoReader` is path-only + needs seeking (no streaming) | Download-to-cache before opening; prefetch adjacent videos; pin-for-offline. |
+| Multiprocess workers can't use a network client | `ensure_local` (media + annotations) hydrates the cache before job dispatch; workers read `Path`s. |
+| Scattered annotation reads (4 sites) drift from the store | Land the Phase-0 seam refactor first, local-only, with contract tests; flag direct `open()` of `annotations/`. |
+| Chatty per-edit network writes / GUI stalls | Cache is the synchronous path; Hub PUTs debounced on a background thread. |
+| Pose re-encode on upload invalidates derived caches | Require Hub to store exact pose bytes; verify blake2b on download. |
+| Offline edits lost / double-applied | Outbox with idempotent, versioned replay; sync-state file is the source of truth. |
+| Hub integration degrades the experience for non-Hub users | §2.4: lazy-imported Hub client, no startup network/auth, local paths never touch Hub; a regression test asserts app startup + local-project open make zero Hub imports/calls. |
+
+---
+
+## 8. Decisions (client-relevant; shared with the Hub doc where noted)
+
+| # | Decision | Status |
+|---|---|---|
+| D1 | Hub-backed projects are **cloud-native**: video, pose, annotations, metadata in Hub; the local dir is a cache. No hybrid. *(shared)* | **Confirmed** |
+| D2 | MVP conflict policy = **optimistic version + last-write-wins**, with `VideoLabels.merge` for a later 3-way merge and per-video leases as a stronger later option. | **Recommended (pending confirm)** |
+| D3 | MVP annotation storage = **whole document per project-video** (least churn); normalized per-`(identity,behavior)` is post-MVP. *(shared; Hub owns storage.)* | **Recommended (pending confirm)** |
+| D4 | Split `project.json` into **shared** (synced) vs **local/GUI** keys (§4.7). | **Recommended (pending confirm)** |
+| D8 | New client package **`packages/jabs-hub-client`** (import `jabs.hub`), depending on `jabs-core`. | **Recommended (pending confirm)** |
+| D11 | **Video identity = `video_id` (library) / `project_video_id` (association) surrogates**; `name_in_project` is a within-project natural key only. *(shared)* | **Confirmed** |
+| D12 | **Video↔project is many-to-many via the library from v1** (one library video may back many projects). Supersedes the earlier many-to-one framing. *(shared)* | **Confirmed** |
+| D13 | **Annotations are per project+video**, never shared across projects that reference the same video. *(shared)* | **Confirmed** |
+| D14 | **Derived artifacts stay local for the MVP** (features/predictions/classifiers recomputed from the cached pose); only source artifacts live in Hub. *Planned future work:* an **optional cloud feature cache** — features are expensive to compute and are safely shareable via pose-hash + `FEATURE_VERSION` keying (§4.9/§10). *(shared)* | **Confirmed (MVP); cloud feature cache planned** |
+| D15 | **Build order is library/media → projects → annotations** (cloud-native throughout; no annotations-first hybrid). | **Confirmed** |
+| D17 | GUI entry is **File → "Open Project from JABS Hub"** (paste a **project identifier** — the project URL, or a bare project ID when a default Hub base is configured) first; an in-GUI **project browser** is a later addition once auth + listing exist. The paste action persists for opening shared projects. | **Confirmed** |
+| D19 | **Hub projects are created and managed in the JABS Hub web UI** (create project, add library videos, share); the desktop GUI **opens** existing Hub projects only. The web UI is built ahead of this work (devices/sessions + library first, project creation layered on). Projects are **personal** (owner) initially; sharing — and thus the multi-user label-sharing use case (§2.3) — lands later, so the first cut is single-user cloud projects. | **Confirmed** |
+| D20 | **A project pins a specific pose file per video** (`project_videos.pose_file_id`); a library video may have **multiple** `pose_files` (one per pose run). The project keeps its pinned pose even when newer runs are added; changing it is an **explicit pose upgrade** that re-pins and migrates labels by bbox-IoU. Pinning is what guarantees label/identity alignment. **Where the migration runs (server-side batch job vs GUI client) is undecided** — not committed to the client. *(shared)* | **Confirmed (migration location open)** |
+| D21 | **A project reference is a clip** — an optional `[clip_start, clip_end]` frame range on `project_videos` (null = whole video); one source video may appear as **multiple clips** in a project. Clips are **materialized server-side** as concrete clip video + clip pose objects in a **regenerable, content-addressed cache** keyed by (video, pinned pose, range) (Hub §10), so the client downloads only the clip (not the whole source) and needs no offset/pose-slicing; the canonical library stays single-copy. Annotations are **clip-relative** (0-based within the clip). *(shared)* | **Confirmed** |
+| D18 | Hub integration is **unobtrusive for non-Hub users** (§2.4): no startup network/auth, lazy-imported Hub client, local workflows untouched. `jabs-hub-client` ships as a **core dependency, lazy-imported** (not an optional extra) — always present so the menu action works, never imported until a Hub action runs. | **Confirmed** |
+
+Hub-owned decisions (D5 authz, D6 name uniqueness, D7 pagination, D9 opaque document, D16 decoupled
+library upload) are in the Hub doc.
+
+---
+
+## 9. Rough Effort Estimate (client)
+
+Order-of-magnitude, 1 developer, Hub work landing in parallel. Not a commitment.
+
+| Phase | Client (Python) |
+|---|---|
+| **0** Foundations + seams | 3-4 wk — OIDC + `HubClient` + media-resolver & annotation-store refactor. |
+| **1** Library + media | 4-6 wk — Hub-aware resolver, cache manager, lazy hydration, upload, playback prefetch. |
+| **2** Projects | 2-3 wk — create/open cloud projects, manifest-driven video list, settings sync. |
+| **3** Annotations | 4-5 wk — annotation cache + sync engine + offline outbox + conflict; GUI wiring. |
+
+Roughly **3.5-4.5 developer-months** of client work. (Hub estimates in the Hub doc.)
+
+---
+
+## 10. Post-MVP (client-facing)
+
+- **Normalized fine-grained labels + interval-level change tracking** — see §10.1.
+- **Web preview playback → possibly a full web labeler.** Browsing a library video + its label track
+  in the browser is Hub-side (read-only preview). A **full web-based labeling tool** is a larger
+  future initiative (Hub §15): now feasible via **WebCodecs** for frame-accurate decode, it would be
+  another client emitting the same `label_events` operations (§10.1) — so the operation API is a
+  multi-client labeling contract, not desktop-only. The desktop GUI remains the reference
+  frame-accurate surface; this explicitly revisits the MVP "no web labeling client" non-goal (§2.2).
+- **Classifier registry / model cards** — would let the client publish/pull trained classifiers +
+  predictions (the derived artifacts kept local in the MVP, D14).
+- **Cloud feature cache (optional performance tier)** — feature extraction is time-consuming; a
+  future opt-in tier stores pre-computed features in Hub and downloads them instead of recomputing.
+  Safe to share because the cache is keyed by pose hash + `FEATURE_VERSION` + distance scale
+  (§3.1/§4.9), so another machine's features are valid for a byte-identical Hub pose. Client lookup
+  order: local cache → Hub feature cache → compute (optionally upload). Does not change the MVP
+  "recompute locally" default.
+- **Behavior/video-level locking**, **real-time collaboration**.
+
+### 10.1 Fine-grained label storage (future)
+
+The MVP stores the whole annotation document per project-video (Appendix A.1). To track changes down
+to the individual behavior `start:end` interval (and shrink the write path), Hub can evolve to an
+event-sourced label store with a normalized/multirange current-state representation — the full
+design is in the Hub doc (**§15.1 Fine-grained label storage**). Client-facing implications:
+
+- **Client sends per-edit operations, buffered offline (chosen).** The client emits each paint
+  action as an operation event (with a client-generated `op_id` for idempotency), applies it to its
+  in-memory labels immediately, and appends it to a **persisted operation outbox**. Online,
+  operations stream to Hub; **offline they buffer and flush as one ordered batch on reconnect**,
+  after which the client pulls anything it missed. This supersedes the MVP whole-doc outbox (§4.8) in
+  the fine-grained model and gives true per-action provenance. (A server-side diff of whole-doc
+  `PUT`s is kept only as a fallback for clients that cannot send operations.)
+- **The edit model maps directly to events.** A GUI edit is one of three actions — label behavior,
+  label not-behavior, or clear — applied to a selected interval, overwriting the per-frame state
+  across it (splitting/merging overlapping intervals as needed). `TrackLabels` already performs
+  exactly this overwrite/split/merge in memory (dense array ↔ RLE blocks, `track_labels.py`), and the
+  GUI already saves per edit — so emitting each action as an event is a 1:1 port of existing logic
+  and a cheaper write than today's whole-file rewrite (see Hub §15.1).
+- **Better collaboration.** Interval/behavior-level merge (via `VideoLabels.merge`,
+  `video_labels.py:301`) replaces whole-doc last-write-wins for disjoint edits.
+
+---
+
+## Appendix A
+
+### A.1 Annotation document schema (client-owned; the shared contract; opaque to Hub)
+
+The exact payload `VideoLabels.as_dict` produces / `VideoLabels.load` consumes
+(`src/jabs/project/video_labels.py:178` / `:278`). `labels` are masked by `pose.identity_mask`;
+`unfragmented_labels` are raw; load prefers `unfragmented_labels`. Blocks are inclusive
+`{start, end, present}` (`present=true` → behavior). Hub stores this as an opaque JSONB `document`.
+
+```json
+{
+  "version": 1,
+  "file": "video1.mp4",
+  "num_frames": 10000,
+  "labels":              { "0": { "grooming": [ {"start": 25, "end": 50, "present": true} ] } },
+  "unfragmented_labels": { "0": { "grooming": [ {"start": 25, "end": 50, "present": true} ] } },
+  "metadata": { "project": {}, "video": {} },
+  "external_identities": { "0": 1234 },
+  "annotations": [
+    {"start": 10, "end": 20, "tag": "myTag", "color": "#FF0000", "description": "…", "identity": 0}
+  ],
+  "labeler": "gbeane"
+}
+```
+
+### A.2 Local cache ⇄ Hub mapping
+
+| Local (cache) artifact | Hub resource | Authority |
+|---|---|---|
+| `<cache>/<name_in_project>` (video) | GCS content-addressed object via `videos` row (signed URL) | Hub |
+| `<cache>/<name>_pose_est_v*.h5` (pose) | GCS content-addressed object via `videos` row | Hub |
+| `jabs/annotations/<name>.json` | `annotations` row (JSONB `document`) keyed by `project_video_id` | Hub |
+| `jabs/project.json` (shared keys) | `projects.settings` (JSONB) | Hub |
+| `jabs/project.json` (local/GUI keys) | — | local only |
+| `jabs/features/`, `jabs/predictions/`, `jabs/classifiers/` | — | **local, derived** (recomputed from cached pose; D14) |
+| `jabs/hub.json` (`{baseUrl, projectId}`) | client-only link marker | local |
+
+### A.3 Client source references
+
+- Video/pose resolution seams: `video_manager.py:251` (`video_path`), `:181`
+  (`get_cached_pose_path`), `src/jabs/pose_estimation/__init__.py:40` (`get_pose_path`); open point
+  `src/jabs/video_reader/video_reader.py:19`; `ProjectPaths` decoupling `project_paths.py:18`.
+- Annotation seams: write `project.py:618`; reads `video_manager.py:109`/`:262`, `project.py:1461`,
+  `parallel_workers.py:207` (job base `project.py:978`); serialization `video_labels.py:178`/`:278`,
+  merge `:301`; `SERIALIZED_VERSION` `video_labels.py:16`.
+- Cache keying (why derived caches survive a Hub pull): `features.py:178`,
+  `packages/jabs-io/.../feature_cache/base.py:71`, `prediction_manager.py:167`.
+- Settings/manifest: `settings_manager.py`; video enumeration `video_manager.py:153`.
+```

From a6b6bb0a254b9b11a8a24b267bb7f95c5c79d0c3 Mon Sep 17 00:00:00 2001
From: Glen Beane <356266+gbeane@users.noreply.github.com>
Date: Mon, 3 Aug 2026 23:33:21 -0400
Subject: [PATCH 2/5] address review feedback on Hub-backed projects plan

---
 .../plans/jabs-hub-backed-projects-plan.md    | 141 +++++++++++++++---
 1 file changed, 120 insertions(+), 21 deletions(-)

diff --git a/docs/development/plans/jabs-hub-backed-projects-plan.md b/docs/development/plans/jabs-hub-backed-projects-plan.md
index 6e117b00..afdc5798 100644
--- a/docs/development/plans/jabs-hub-backed-projects-plan.md
+++ b/docs/development/plans/jabs-hub-backed-projects-plan.md
@@ -1,15 +1,15 @@
 # Plan: Hub-Backed JABS Projects — Client Integration (jabs-behavior-classifier)
 
-**Status:** Draft / planning 
-**Author:** Glen Beane (with Claude Code)  
-**Repository:** `jabs-behavior-classifier` (this repo — the PySide6 desktop GUI / Python client).  
-**Companion doc:** the Hub-side (Go) design lives in the `jabs-hub` repo at
-`docs/specs/0006-jabs-project-backend-design.md`. The REST API, the PostgreSQL data model, and
-the annotation-document schema (Appendix A.1) are the **shared contract** — keep them in sync. 
-**Scope:** The client half of Hub-backed JABS projects under a **cloud-native** model: the desktop
-GUI becomes a caching client that pulls videos, pose files, annotations, and project metadata from
-JABS Hub / Google Cloud Storage into a local cache, works against the cache (frame-accurate
-labeling, feature extraction, training, offline), and pushes changes back.
+- **Status:** Draft / planning
+- **Author:** Glen Beane (with Claude Code)
+- **Repository:** `jabs-behavior-classifier` (this repo — the PySide6 desktop GUI / Python client).
+- **Companion doc:** the Hub-side (Go) design lives in the `jabs-hub` repo at
+  `docs/specs/0006-jabs-project-backend-design.md`. The REST API, the PostgreSQL data model, and the
+  annotation-document schema (Appendix A.1) are the **shared contract** — keep them in sync.
+- **Scope:** the client half of Hub-backed JABS projects under a **cloud-native** model: the desktop
+  GUI becomes a caching client that pulls videos, pose files, annotations, and project metadata from
+  JABS Hub / Google Cloud Storage into a local cache, works against the cache (frame-accurate
+  labeling, feature extraction, training, offline), and pushes changes back.
 
 ---
 
@@ -97,6 +97,9 @@ warned.
   expensive one) and a classifier registry for predictions/classifiers are post-MVP (§10).
 - Real-time collaborative cursors / live presence (post-MVP).
 - True frame streaming of remote video (playback is download-to-cache + prefetch; §4.6).
+- **Fine-grained permissions** (roles, per-video/per-behavior rights, group- or lab-level access).
+  The MVP is authenticated access + per-project membership, enforced by Hub — see §2.5 for the full
+  in-scope / out-of-scope breakdown, and D24.
 
 ### 2.3 Motivating use cases
 
@@ -111,6 +114,10 @@ warned.
    project and adds videos to it from the library (JABS recordings or uploaded external files), then
    opens it in the desktop GUI (§4.7) — the media hydrates on demand.
 3. **Work from any machine / HPC** with no manual file copying — the cache hydrates from Hub.
+4. **Going offline, or onto low bandwidth.** Before a flight, a field trip, or a move to a slow or
+   metered link, a user hydrates the **whole** project in one deliberate action — every video, pinned
+   pose file, and annotation document — instead of relying on lazy per-video downloads that would
+   fail once the connection is gone, and pins it so cache eviction leaves it alone (§4.6, D22).
 
 ### 2.4 Unobtrusiveness for non-Hub users (hard requirement)
 
@@ -131,6 +138,50 @@ to them:
 A regression test asserts that launching the app and opening a local project make **zero** Hub
 imports or network calls (§7).
 
+### 2.5 Permissions and authorization — what is in and out of scope
+
+Authorization is **enforced by Hub**, not by the client (Hub doc, D5), but the *goals* it has to meet
+belong in scope here so they are not left implicit. Users are **not** assumed to be uniformly
+trustworthy with write access to everything.
+
+**In scope (MVP)**
+
+- **Authenticated access only.** Every Hub request carries an OIDC access token (§4.5); there is no
+  anonymous, shared-secret, or unauthenticated read path. Without a token the client sees no projects.
+- **Per-project membership, enforced server-side on every request.** A project has an owner and a
+  membership set (`project_members`); Hub authorizes each call against the caller's membership. Per
+  D19 projects are **personal (owner-only)** in the first cut, so the MVP membership set is normally
+  one user — but the check is a membership check from day one, so sharing is an added row, not a
+  redesign.
+- **The client is not a trust boundary.** The GUI only *reflects* permissions (e.g. greying out
+  labeling for a project it may not write); it never grants them. A patched client, a hand-edited
+  `hub.json`, or a guessed project ID gains nothing — every read and write is re-authorized by Hub.
+- **Possessing a project identifier is not access.** Pasting a project link (§4.7) only names the
+  project; the caller must still be a member. Links are shareable *because* they confer no rights.
+- **Short-lived, per-request media credentials.** Signed GCS URLs are minted per authorized request
+  and expire; a cached URL is not a durable capability, and copying a cache directory to another
+  machine does not carry Hub access with it.
+- **Attribution comes from the token.** Annotation history records the identity Hub derives from the
+  access token, not the client-supplied `labeler` field (Appendix A.1), which stays a display value.
+
+**Out of scope (MVP) — named so they are deliberate omissions, not oversights**
+
+- **Roles and fine-grained permissions.** No viewer/labeler/owner distinction, no per-behavior or
+  per-video permissions: a project member reads and writes everything in that project. A role model
+  is post-MVP (§10); when it lands, the client's only job is to honor a `permissions` field on the
+  project manifest and disable the corresponding UI.
+- **Lab-, group-, or organization-level access control**, including any mapping from JAX directory
+  groups. Membership is per project and explicit.
+- **Locking as a permission concept.** Concurrent writers are handled by optimistic concurrency
+  (D2/§4.8), not by access control; behavior/video-level locking is post-MVP (§10).
+- **Protecting the local cache.** Cached video, pose, and annotation files are ordinary files under
+  normal filesystem permissions — no client-side encryption at rest, and no attempt to stop a local
+  user from reading a cache they have filesystem access to. Consequence to document for users: do not
+  place a Hub project cache on shared storage whose readers are not all project members. Tokens are
+  the exception — OS keyring, never in project files (§2.4).
+- **Audit and compliance reporting.** Annotation version history provides attribution and rollback,
+  not a tamper-evident audit log.
+
 ---
 
 ## 3. Current State — client seams we build on
@@ -196,8 +247,8 @@ flowchart LR
         UI[GUI / Project]
         RES[Media resolver]
         AS[Annotation cache/store]
-        CACHE[(Local cache dir\nvideo + pose + jabs/)]
-        DERIVED[(Derived: features/predictions\nrecomputed locally)]
+        CACHE[(Local cache dir<br/>video + pose + jabs/)]
+        DERIVED[(Derived: features/predictions<br/>recomputed locally)]
         HC[HubClient + OIDC]
         UI --> RES
         UI --> AS
@@ -210,8 +261,8 @@ flowchart LR
 
     subgraph Hub["JABS Hub (Go / net-http / api/v0)"]
         API[HTTP API + JWT auth]
-        DB[(PostgreSQL\nvideos, projects, annotations)]
-        GCS[(GCS object storage\nvideo + pose, content-addressed)]
+        DB[(PostgreSQL<br/>videos, projects, annotations)]
+        GCS[(GCS object storage<br/>video + pose, content-addressed)]
         API --> DB
         API --> GCS
     end
@@ -284,8 +335,8 @@ A new workspace package `packages/jabs-hub-client` (namespace `jabs.hub`):
   annotations, media URLs). Maps the `{code,message}` envelope to typed exceptions.
 - **OIDC auth** — Authorization-Code + PKCE against Auth0, token cache + refresh, OS-keyring
   storage. Net-new client capability (the app has no networking today).
-- **Cache manager** — the local cache root, LRU eviction + size cap + "pin for offline," and the
-  sync-state file.
+- **Cache manager** — the local cache root, LRU eviction + size cap + "pin for offline" (D22,
+  including whole-project hydration), and the sync-state file.
 - **Lazy-loaded core dependency.** `jabs.hub` ships as a **core dependency** (always present, so the
   menu action always works) but is **lazy-imported** — it and its networking/auth/keyring
   dependencies load only when a Hub action runs, so non-Hub users pay no import or startup cost
@@ -320,6 +371,21 @@ directory name disambiguates from the Go `jabs-hub` repo while the import stays
   blake2b hash (a deterministic slice) keys the clip's feature/prediction caches. Annotations are
   clip-relative. *(Client-side offset into a full-source download is the fallback for an
   un-materialized clip.)*
+- **Explicit full hydration — "make available offline" (D22).** Lazy per-video hydration is the
+  default, but the user can also pull an entire project up front for the offline / low-bandwidth case
+  (§2.3 use case 4). **File → "Download Project for Offline Use"** fetches every video, pinned pose,
+  and annotation document in the manifest with progress + cancel, and **pins** the project so the
+  cache LRU (§4.5) will not evict it until it is unpinned. Properties that make this safe to invoke
+  casually:
+  - **Resumable and idempotent** — already-cached, hash-verified files are skipped, so re-running
+    after a cancel, a crash, or a dropped connection fetches only what is missing.
+  - **Budget-aware** — the manifest carries per-video sizes, so the client can state the total up
+    front and warn (with the required vs configured cache cap) before a hydration that would exceed
+    the cache budget, rather than thrashing the LRU mid-download.
+  - **Granular** — the same action exists per video (pin/hydrate a subset) for projects larger than
+    the local cache budget.
+  - **Headless equivalent** — a `jabs-cli` command performs the same hydration for HPC/batch use, so
+    a compute node can pre-warm a cache without launching the GUI.
 - **Library upload is a web-UI / `jabs-cli` task, not a desktop-GUI flow** (§4.7). The upload
   mechanics (compute blake2b, request an upload URL, PUT to GCS, `upload-complete`; pose optional)
   live in `HubClient` and are exercised by a `jabs-cli` helper (to seed/bulk-load the library) and
@@ -377,6 +443,26 @@ See D4.
   the cache so nothing is lost; `VideoLabels.merge` available for a later 3-way merge. Hub enforces
   the check-and-set atomically and returns `409` with the current version (Hub doc —
   Optimistic-Concurrency Contract).
+- **Conflict UX (D23).** Conflicts are rare in the first cut — personal, single-user projects (D19) —
+  but the user-visible behavior is specified now, because "last-write-wins" silently losing a labeling
+  session would be worse than today's manual zip hand-off:
+  - **Never block, never lose.** Labeling never waits on the network; a `409` is resolved on the sync
+    thread. Before applying the resolution the client writes the losing document to
+    `jabs/hub-conflicts/<video>-<version>-<timestamp>.json` in the cache, so a discarded edit is
+    always recoverable from disk (and re-importable via `VideoLabels.load`).
+  - **Notify, don't interrupt.** Resolution surfaces as a non-modal status-bar / sync-indicator
+    message — "Labels for `<video>` were also changed by `<user>`; your version was kept, theirs saved
+    to …" — with a link that reveals the conflict file. No modal dialog appears mid-labeling.
+  - **Sync state is always legible.** A per-project indicator shows `synced` / `syncing` /
+    `offline (N queued)` / `conflict`, with per-video detail on hover, so "did my labels reach Hub?"
+    is answerable at a glance instead of inferred.
+  - **Remote changes don't yank the current video.** For a video the user does not have open, a newer
+    pulled document just updates the cache. For the **currently open** video the client keeps showing
+    the user's labels and offers an explicit **"Reload labels from Hub"** — safe to accept, since the
+    local version is already in the cache and the conflict file.
+  - **Post-MVP:** with `VideoLabels.merge`, disjoint edits (different identity, behavior, or frame
+    range) merge silently and only genuine overlaps surface — the point at which a review dialog
+    showing the conflicting intervals becomes worth building. Deliberately not in the MVP.
 - **Pose consistency is guaranteed** (not just warned): the client pulls the project's **pinned**
   pose file (§4.6), so the labels' identities always align, and the pose changes only via an
   explicit upgrade. The client asserts its cached pose matches the pinned pose file's `poseHash` as a cheap
@@ -399,7 +485,7 @@ sequenceDiagram
     else conflict
         Hub-->>Sync: 409 {currentVersion: M}
         Sync->>Hub: GET annotations (M)
-        Sync->>Sync: resolve (LWW; merge optional)
+        Sync->>Sync: resolve (LWW, merge optional)
         Sync->>Hub: PUT (If-Match: M)
     end
 ```
@@ -452,7 +538,10 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
 - **Unit** (pytest + `monkeypatch`/`unittest.mock`, no network; `pytest-mock` is not available):
   media-resolver download/cache/hash-verify with a faked `HubClient`; `AnnotationStore` contract
   tests for both implementations; `VideoLabels.as_dict → store → load` round-trip; sync engine
-  debounce/outbox/409-retry; `ensure_local` hydration keeps the training path local.
+  debounce/outbox/409-retry; `ensure_local` hydration keeps the training path local; full-project
+  hydration is resumable and idempotent — re-running after a simulated cancel re-fetches only the
+  missing files and skips hash-verified ones (D22); a 409 resolution always leaves a loadable document
+  in `jabs/hub-conflicts/` (D23).
 - **Integration (opt-in):** against a locally-run Hub in `AUTH_DEV_MODE`.
 - **Backward-compat guard:** a project with no `hub.json` behaves byte-for-byte as today.
 
@@ -462,7 +551,8 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
 
 | Risk | Mitigation |
 |---|---|
-| First open of a large cloud project = many big downloads | Manifest-driven, lazy per-video hydration + prefetch + LRU cache; never download a whole project at open. |
+| First open of a large cloud project = many big downloads | Manifest-driven, lazy per-video hydration + prefetch + LRU cache; never download a whole project at open. Whole-project hydration exists only as an explicit, resumable user action (D22). |
+| Lazy hydration is useless once the user is offline or on a slow link | Explicit "Download Project for Offline Use" + pin (D22), resumable and budget-aware, plus a `jabs-cli` equivalent for headless pre-warming. |
 | `VideoReader` is path-only + needs seeking (no streaming) | Download-to-cache before opening; prefetch adjacent videos; pin-for-offline. |
 | Multiprocess workers can't use a network client | `ensure_local` (media + annotations) hydrates the cache before job dispatch; workers read `Path`s. |
 | Scattered annotation reads (4 sites) drift from the store | Land the Phase-0 seam refactor first, local-only, with contract tests; flag direct `open()` of `annotations/`. |
@@ -488,10 +578,13 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
 | D14 | **Derived artifacts stay local for the MVP** (features/predictions/classifiers recomputed from the cached pose); only source artifacts live in Hub. *Planned future work:* an **optional cloud feature cache** — features are expensive to compute and are safely shareable via pose-hash + `FEATURE_VERSION` keying (§4.9/§10). *(shared)* | **Confirmed (MVP); cloud feature cache planned** |
 | D15 | **Build order is library/media → projects → annotations** (cloud-native throughout; no annotations-first hybrid). | **Confirmed** |
 | D17 | GUI entry is **File → "Open Project from JABS Hub"** (paste a **project identifier** — the project URL, or a bare project ID when a default Hub base is configured) first; an in-GUI **project browser** is a later addition once auth + listing exist. The paste action persists for opening shared projects. | **Confirmed** |
+| D18 | Hub integration is **unobtrusive for non-Hub users** (§2.4): no startup network/auth, lazy-imported Hub client, local workflows untouched. `jabs-hub-client` ships as a **core dependency, lazy-imported** (not an optional extra) — always present so the menu action works, never imported until a Hub action runs. | **Confirmed** |
 | D19 | **Hub projects are created and managed in the JABS Hub web UI** (create project, add library videos, share); the desktop GUI **opens** existing Hub projects only. The web UI is built ahead of this work (devices/sessions + library first, project creation layered on). Projects are **personal** (owner) initially; sharing — and thus the multi-user label-sharing use case (§2.3) — lands later, so the first cut is single-user cloud projects. | **Confirmed** |
 | D20 | **A project pins a specific pose file per video** (`project_videos.pose_file_id`); a library video may have **multiple** `pose_files` (one per pose run). The project keeps its pinned pose even when newer runs are added; changing it is an **explicit pose upgrade** that re-pins and migrates labels by bbox-IoU. Pinning is what guarantees label/identity alignment. **Where the migration runs (server-side batch job vs GUI client) is undecided** — not committed to the client. *(shared)* | **Confirmed (migration location open)** |
 | D21 | **A project reference is a clip** — an optional `[clip_start, clip_end]` frame range on `project_videos` (null = whole video); one source video may appear as **multiple clips** in a project. Clips are **materialized server-side** as concrete clip video + clip pose objects in a **regenerable, content-addressed cache** keyed by (video, pinned pose, range) (Hub §10), so the client downloads only the clip (not the whole source) and needs no offset/pose-slicing; the canonical library stays single-copy. Annotations are **clip-relative** (0-based within the clip). *(shared)* | **Confirmed** |
-| D18 | Hub integration is **unobtrusive for non-Hub users** (§2.4): no startup network/auth, lazy-imported Hub client, local workflows untouched. `jabs-hub-client` ships as a **core dependency, lazy-imported** (not an optional extra) — always present so the menu action works, never imported until a Hub action runs. | **Confirmed** |
+| D22 | **Hydration is lazy by default, plus an explicit full-project "make available offline" action** (GUI + a `jabs-cli` equivalent) that downloads every video/pose/annotation, pins the project against LRU eviction, and is resumable, idempotent, and budget-aware; per-video pin/hydrate is also available (§2.3 use case 4, §4.6). | **Recommended (pending confirm)** |
+| D23 | **Conflict resolution is user-visible, not silent** (§4.8): the losing document is always written to `jabs/hub-conflicts/`, resolution is reported non-modally with a persistent sync-state indicator, and the currently open video is never reloaded without an explicit user action. A merge-review dialog waits for 3-way merge (post-MVP). | **Recommended (pending confirm)** |
+| D24 | **Permission scope is explicit** (§2.5): authenticated-only access with per-project membership enforced server-side on every request, one access level per project for the MVP, client is not a trust boundary, project links confer nothing. Roles, group/org-level access, locking-as-permission, cache encryption at rest, and audit logging are **out of scope**. Authorization itself is Hub-owned (Hub doc D5). | **Recommended (pending confirm)** |
 
 Hub-owned decisions (D5 authz, D6 name uniqueness, D7 pagination, D9 opaque document, D16 decoupled
 library upload) are in the Hub doc.
@@ -505,7 +598,7 @@ Order-of-magnitude, 1 developer, Hub work landing in parallel. Not a commitment.
 | Phase | Client (Python) |
 |---|---|
 | **0** Foundations + seams | 3-4 wk — OIDC + `HubClient` + media-resolver & annotation-store refactor. |
-| **1** Library + media | 4-6 wk — Hub-aware resolver, cache manager, lazy hydration, upload, playback prefetch. |
+| **1** Library + media | 4-6 wk — Hub-aware resolver, cache manager, lazy hydration, full-project hydration/pin (D22), upload, playback prefetch. |
 | **2** Projects | 2-3 wk — create/open cloud projects, manifest-driven video list, settings sync. |
 | **3** Annotations | 4-5 wk — annotation cache + sync engine + offline outbox + conflict; GUI wiring. |
 
@@ -530,6 +623,10 @@ Roughly **3.5-4.5 developer-months** of client work. (Hub estimates in the Hub d
   (§3.1/§4.9), so another machine's features are valid for a byte-identical Hub pose. Client lookup
   order: local cache → Hub feature cache → compute (optionally upload). Does not change the MVP
   "recompute locally" default.
+- **Project sharing + role-based permissions** — membership beyond the owner (D19), then a role model
+  (viewer / labeler / owner, potentially per-video or per-behavior) that the client honors via a
+  `permissions` field on the project manifest; group- and lab-level access control. Explicitly out of
+  scope for the MVP (§2.5, D24).
 - **Behavior/video-level locking**, **real-time collaboration**.
 
 ### 10.1 Fine-grained label storage (future)
@@ -592,6 +689,8 @@ The exact payload `VideoLabels.as_dict` produces / `VideoLabels.load` consumes
 | `jabs/project.json` (shared keys) | `projects.settings` (JSONB) | Hub |
 | `jabs/project.json` (local/GUI keys) | — | local only |
 | `jabs/features/`, `jabs/predictions/`, `jabs/classifiers/` | — | **local, derived** (recomputed from cached pose; D14) |
+| `jabs/hub-sync.json` (versions, dirty flags, outbox) | — | local only (§4.8) |
+| `jabs/hub-conflicts/<video>-<version>-<timestamp>.json` | superseded `annotations` version | local only, recovery copy (D23) |
 | `jabs/hub.json` (`{baseUrl, projectId}`) | client-only link marker | local |
 
 ### A.3 Client source references

From 630d5e8d6d788078adde062d7519676c7a3500cf Mon Sep 17 00:00:00 2001
From: Glen Beane <356266+gbeane@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:18:13 -0400
Subject: [PATCH 3/5] record lab-wide Hub library posture and optional
 numFrames in the plan

---
 .../plans/jabs-hub-backed-projects-plan.md    | 42 +++++++++++++++----
 1 file changed, 33 insertions(+), 9 deletions(-)

diff --git a/docs/development/plans/jabs-hub-backed-projects-plan.md b/docs/development/plans/jabs-hub-backed-projects-plan.md
index afdc5798..ac8445e7 100644
--- a/docs/development/plans/jabs-hub-backed-projects-plan.md
+++ b/docs/development/plans/jabs-hub-backed-projects-plan.md
@@ -140,9 +140,9 @@ imports or network calls (§7).
 
 ### 2.5 Permissions and authorization — what is in and out of scope
 
-Authorization is **enforced by Hub**, not by the client (Hub doc, D5), but the *goals* it has to meet
-belong in scope here so they are not left implicit. Users are **not** assumed to be uniformly
-trustworthy with write access to everything.
+Authorization is **enforced by Hub**, not by the client (Hub doc D5, recorded in the `jabs-hub`
+repo as **ADR-0014**), but the *goals* it has to meet belong in scope here so they are not left
+implicit. Users are **not** assumed to be uniformly trustworthy with write access to everything.
 
 **In scope (MVP)**
 
@@ -153,6 +153,15 @@ trustworthy with write access to everything.
   D19 projects are **personal (owner-only)** in the first cut, so the MVP membership set is normally
   one user — but the check is a membership check from day one, so sharing is an added row, not a
   redesign.
+- **Membership gates projects, not the video library.** A library video exists before and
+  independently of any project (ADR-0012), so project membership is not a well-defined question for
+  library media: **ADR-0014 Decision 3 makes the library readable *and writable* by any authenticated
+  Hub caller.** For a JABS user that means any colleague with Hub access can list, download, and add
+  to the library — including the videos a project pins — while **projects and annotations**, the
+  scientific work product, are what membership actually protects. This deliberately narrows ADR-0001
+  §4 ("the API checks project membership before generating any URL") to *project* media; per-video
+  library ACLs are deferred (ADR-0014 Open Question 2). Do not present library media in the GUI as
+  though it were private to the project that references it.
 - **The client is not a trust boundary.** The GUI only *reflects* permissions (e.g. greying out
   labeling for a project it may not write); it never grants them. A patched client, a hand-edited
   `hub.json`, or a guessed project ID gains nothing — every read and write is re-authorized by Hub.
@@ -172,6 +181,9 @@ trustworthy with write access to everything.
   project manifest and disable the corresponding UI.
 - **Lab-, group-, or organization-level access control**, including any mapping from JAX directory
   groups. Membership is per project and explicit.
+- **Per-video library ACLs or library ownership.** The catalogue is lab-wide (above). If library
+  videos ever become sensitive — collaborator data, embargoed studies — that is a Hub-side change
+  (ADR-0014 OQ2), and the client would honor it rather than enforce it.
 - **Locking as a permission concept.** Concurrent writers are handled by optimistic concurrency
   (D2/§4.8), not by access control; behavior/video-level locking is post-MVP (§10).
 - **Protecting the local cache.** Cached video, pose, and annotation files are ordinary files under
@@ -353,7 +365,9 @@ directory name disambiguates from the Go `jabs-hub` repo while the import stays
   pose it fetches the project's **pinned** pose file (by its `poseHash`, §4.3/D20), not the
   library's latest, and verifies the blake2b hash; (3) **defers per-video probing** so open is
   metadata-driven (manifest `numFrames`/`poseVersion`) and hydrates lazily — never a full-project
-  download at open.
+  download at open. **`numFrames` is optional** (§5): when the manifest omits it, the client probes
+  that video on first open instead of treating the gap as an error, so metadata-driven open must
+  degrade to probe-on-demand rather than depend on it.
 - **Pose upgrades are explicit.** A library video may accrue multiple pose runs; the project keeps
   its pinned pose until a user upgrades it. An upgrade re-pins to a newer pose file and **migrates
   labels** by bbox-IoU (the algorithm exists in `jabs-cli update-pose`,
@@ -517,11 +531,20 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
 - **Projects & the join manifest:** `GET/POST /projects`, `GET /projects/{id}`; `GET
   /projects/{id}/videos` returns the manifest — per association: `projectVideoId`, `videoId`,
   `nameInProject`, `contentHash`, `poseFileId`, `poseHash`, `poseVersion`, `numFrames` (= clip
-  length), `clipStart`/`clipEnd`, `videoState`/`poseState`, `annotationVersion`. Per-association
-  **signed media URLs** (in the manifest or via `.../videos/{projectVideoId}/media-urls`) resolve the
-  **pinned** pose and the source-or-materialized-clip video — never the library "latest". (Linking
-  videos, `register-recording`, and per-video `pose-files` are web-UI / `jabs-cli` operations, not
+  length, **optional** — see below), `clipStart`/`clipEnd`, `videoState`/`poseState`,
+  `annotationVersion`. Per-association **signed media URLs** (in the manifest or via
+  `.../videos/{projectVideoId}/media-urls`) resolve the **pinned** pose and the
+  source-or-materialized-clip video — never the library "latest". (Linking videos,
+  `register-recording`, and per-video `pose-files` are web-UI / `jabs-cli` operations, not
   desktop-client calls.)
+
+  > `numFrames` is **optional**. It is populated for videos processed by the pipeline (which emits it
+  > in its artifact manifest) and for external uploads whose client supplied it, but is NULL for a
+  > `RECORDING_ONLY` session or any video not yet processed — no Hub table records an exact frame
+  > count. Treat a missing `numFrames` as "probe on first open" rather than an error, and do not
+  > assume the manifest always carries it.
+
+  (Wording from the Hub spec 0006 *Amendments* section, ADR-0012 Decision 3; §4.6 relies on it.)
 - **Annotations:** `GET/PUT /projects/{id}/videos/{projectVideoId}/annotations` with the
   `If-Match`/`version`/`409` optimistic-concurrency contract; `GET /projects/{id}/annotations`
   bulk. On write the client also sends a compact **behavior summary** (per behavior/identity:
@@ -541,7 +564,8 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
   debounce/outbox/409-retry; `ensure_local` hydration keeps the training path local; full-project
   hydration is resumable and idempotent — re-running after a simulated cancel re-fetches only the
   missing files and skips hash-verified ones (D22); a 409 resolution always leaves a loadable document
-  in `jabs/hub-conflicts/` (D23).
+  in `jabs/hub-conflicts/` (D23); a manifest entry with **no** `numFrames` opens via the probe
+  fallback instead of raising (§5).
 - **Integration (opt-in):** against a locally-run Hub in `AUTH_DEV_MODE`.
 - **Backward-compat guard:** a project with no `hub.json` behaves byte-for-byte as today.
 

From 7ac96e777668d442bc1d7407a493566a60c2426f Mon Sep 17 00:00:00 2001
From: Glen Beane <356266+gbeane@users.noreply.github.com>
Date: Tue, 4 Aug 2026 10:36:13 -0400
Subject: [PATCH 4/5] record group-scoped library visibility as a committed
 future requirement

---
 .../plans/jabs-hub-backed-projects-plan.md    | 28 +++++++++++++++----
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/docs/development/plans/jabs-hub-backed-projects-plan.md b/docs/development/plans/jabs-hub-backed-projects-plan.md
index ac8445e7..e981eee8 100644
--- a/docs/development/plans/jabs-hub-backed-projects-plan.md
+++ b/docs/development/plans/jabs-hub-backed-projects-plan.md
@@ -159,9 +159,11 @@ implicit. Users are **not** assumed to be uniformly trustworthy with write acces
   Hub caller.** For a JABS user that means any colleague with Hub access can list, download, and add
   to the library — including the videos a project pins — while **projects and annotations**, the
   scientific work product, are what membership actually protects. This deliberately narrows ADR-0001
-  §4 ("the API checks project membership before generating any URL") to *project* media; per-video
-  library ACLs are deferred (ADR-0014 Open Question 2). Do not present library media in the GUI as
-  though it were private to the project that references it.
+  §4 ("the API checks project membership before generating any URL") to *project* media. Do not
+  present library media in the GUI as though it were private to the project that references it. This
+  is the MVP posture, **not the end state** — group-scoped library visibility is a known future
+  requirement (below), so treat the open catalogue as temporary and keep browse paths behind a
+  filtered query.
 - **The client is not a trust boundary.** The GUI only *reflects* permissions (e.g. greying out
   labeling for a project it may not write); it never grants them. A patched client, a hand-edited
   `hub.json`, or a guessed project ID gains nothing — every read and write is re-authorized by Hub.
@@ -181,9 +183,17 @@ implicit. Users are **not** assumed to be uniformly trustworthy with write acces
   project manifest and disable the corresponding UI.
 - **Lab-, group-, or organization-level access control**, including any mapping from JAX directory
   groups. Membership is per project and explicit.
-- **Per-video library ACLs or library ownership.** The catalogue is lab-wide (above). If library
-  videos ever become sensitive — collaborator data, embargoed studies — that is a Hub-side change
-  (ADR-0014 OQ2), and the client would honor it rather than enforce it.
+- **Group-scoped library visibility — out of scope for the MVP, but a known future requirement, not a
+  hypothetical.** Library videos will eventually need to be readable only to specified groups
+  (collaborator data, embargoed studies), so the lab-wide catalogue above is a starting posture rather
+  than the end state. Enforcement is Hub-side (ADR-0014 Decision 3 today, its OQ2 for the ACL model);
+  the client's job when it lands is to **honor** a visibility/permissions field on the manifest and
+  the library listing, not to enforce one — which is why the client must not build UI that assumes an
+  open catalogue (e.g. "browse everything" affordances with no filtered-query path behind them).
+  **Revocation cannot be retroactive for a cached project:** the cache holds video and pose bytes on
+  disk (§4.2), so withdrawing a group's access later does not reach bytes already pulled. That is
+  inherent to offline-first, and it means group scoping has to be applied at upload/link time rather
+  than relied on as a later withdrawal.
 - **Locking as a permission concept.** Concurrent writers are handled by optimistic concurrency
   (D2/§4.8), not by access control; behavior/video-level locking is post-MVP (§10).
 - **Protecting the local cache.** Cached video, pose, and annotation files are ordinary files under
@@ -651,6 +661,12 @@ Roughly **3.5-4.5 developer-months** of client work. (Hub estimates in the Hub d
   (viewer / labeler / owner, potentially per-video or per-behavior) that the client honors via a
   `permissions` field on the project manifest; group- and lab-level access control. Explicitly out of
   scope for the MVP (§2.5, D24).
+- **Group-scoped library visibility (a committed requirement, not a maybe).** Library videos readable
+  only to specified groups — see §2.5. Client-side work when it lands: honor a visibility field on the
+  library listing and the project manifest, present "no longer accessible" states for cached media
+  whose access was withdrawn, and keep every library browse path behind a filtered query rather than a
+  full scan. Sequenced after Hub decides where group membership lives (ADR-0014 OQ1/OQ2), which is the
+  same decision that gates project sharing.
 - **Behavior/video-level locking**, **real-time collaboration**.
 
 ### 10.1 Fine-grained label storage (future)

From b6ce30902980e3a2c1b46cc30e3603efc5c608b5 Mon Sep 17 00:00:00 2001
From: Glen Beane <356266+gbeane@users.noreply.github.com>
Date: Tue, 4 Aug 2026 11:51:27 -0400
Subject: [PATCH 5/5] fix mermaid label, route list, and drifted source line
 references

---
 .../plans/jabs-hub-backed-projects-plan.md         | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/development/plans/jabs-hub-backed-projects-plan.md b/docs/development/plans/jabs-hub-backed-projects-plan.md
index e981eee8..c30ab3ad 100644
--- a/docs/development/plans/jabs-hub-backed-projects-plan.md
+++ b/docs/development/plans/jabs-hub-backed-projects-plan.md
@@ -241,7 +241,7 @@ implicit. Users are **not** assumed to be uniformly trustworthy with write acces
   `VideoManager.load_video_labels` (`video_manager.py:109`), `VideoManager.load_annotations`
   (`:262`), `Project.load_counts` (`project.py:1461`), and — in a **child process** —
   `parallel_workers._load_video_labels` (`parallel_workers.py:207`, path from `project.py:978`).
-- **Serialization is clean:** `VideoLabels.as_dict` / `.load` (`video_labels.py:178` / `:278`),
+- **Serialization is clean:** `VideoLabels.as_dict` / `.load` (`video_labels.py:178` / `:279`),
   plain JSON, `SERIALIZED_VERSION = 1` (`video_labels.py:16`). Schema in Appendix A.1.
 - **No storage abstraction** today; all concrete `pathlib` + `json`. GUI saves eagerly and
   synchronously on every edit (`central_widget.py:880`, …). `VideoLabels.merge` with a
@@ -254,7 +254,7 @@ implicit. Users are **not** assumed to be uniformly trustworthy with write acces
   (`settings_manager.py`) owns `project.json` (behaviors, window sizes, settings, metadata,
   video_files, selected_behavior).
 - Videos are enumerated by a **local directory glob** (`VideoManager.get_videos`,
-  `video_manager.py:153`) → for a cloud project this becomes the Hub **manifest**
+  `video_manager.py:154`) → for a cloud project this becomes the Hub **manifest**
   (`GET /projects/{id}/videos`).
 
 ---
@@ -281,7 +281,7 @@ flowchart LR
         RES --> HC
     end
 
-    subgraph Hub["JABS Hub (Go / net-http / api/v0)"]
+    subgraph Hub["JABS Hub (Go / net/http / api/v0)"]
         API[HTTP API + JWT auth]
         DB[(PostgreSQL<br/>videos, projects, annotations)]
         GCS[(GCS object storage<br/>video + pose, content-addressed)]
@@ -538,7 +538,7 @@ The full API/DTOs/data model are in the Hub doc. The client depends on:
 - **Library + media:** `GET /videos` (list/search), `POST /videos` + `.../video-upload-url` /
   `.../pose-upload-url` / `.../upload-complete` (upload), `GET /videos/{id}/video-url` /
   `.../pose-url` (signed download). Media is content-addressed; **exact pose bytes preserved**.
-- **Projects & the join manifest:** `GET/POST /projects`, `GET /projects/{id}`; `GET
+- **Projects & the join manifest:** `GET /projects`, `POST /projects`, `GET /projects/{id}`; `GET
   /projects/{id}/videos` returns the manifest — per association: `projectVideoId`, `videoId`,
   `nameInProject`, `contentHash`, `poseFileId`, `poseHash`, `poseVersion`, `numFrames` (= clip
   length, **optional** — see below), `clipStart`/`clipEnd`, `videoState`/`poseState`,
@@ -699,7 +699,7 @@ design is in the Hub doc (**§15.1 Fine-grained label storage**). Client-facing
 ### A.1 Annotation document schema (client-owned; the shared contract; opaque to Hub)
 
 The exact payload `VideoLabels.as_dict` produces / `VideoLabels.load` consumes
-(`src/jabs/project/video_labels.py:178` / `:278`). `labels` are masked by `pose.identity_mask`;
+(`src/jabs/project/video_labels.py:178` / `:279`). `labels` are masked by `pose.identity_mask`;
 `unfragmented_labels` are raw; load prefers `unfragmented_labels`. Blocks are inclusive
 `{start, end, present}` (`present=true` → behavior). Hub stores this as an opaque JSONB `document`.
 
@@ -739,9 +739,9 @@ The exact payload `VideoLabels.as_dict` produces / `VideoLabels.load` consumes
   (`get_cached_pose_path`), `src/jabs/pose_estimation/__init__.py:40` (`get_pose_path`); open point
   `src/jabs/video_reader/video_reader.py:19`; `ProjectPaths` decoupling `project_paths.py:18`.
 - Annotation seams: write `project.py:618`; reads `video_manager.py:109`/`:262`, `project.py:1461`,
-  `parallel_workers.py:207` (job base `project.py:978`); serialization `video_labels.py:178`/`:278`,
+  `parallel_workers.py:207` (job base `project.py:978`); serialization `video_labels.py:178`/`:279`,
   merge `:301`; `SERIALIZED_VERSION` `video_labels.py:16`.
 - Cache keying (why derived caches survive a Hub pull): `features.py:178`,
   `packages/jabs-io/.../feature_cache/base.py:71`, `prediction_manager.py:167`.
-- Settings/manifest: `settings_manager.py`; video enumeration `video_manager.py:153`.
+- Settings/manifest: `settings_manager.py`; video enumeration `video_manager.py:154`.
 ```