From dc0bd5164854d90ace23d86b7e489733d4a446b0 Mon Sep 17 00:00:00 2001
From: ZGaetano <zgaetano@wilddragon.net>
Date: Fri, 22 May 2026 19:16:34 -0400
Subject: [PATCH] docs: growing-files + Premiere panel quickstart

---
 docs/GROWING_FILES_QUICKSTART.md | 87 +++++++++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 1 deletion(-)

diff --git a/docs/GROWING_FILES_QUICKSTART.md b/docs/GROWING_FILES_QUICKSTART.md
index 8289d6e..64bb3a5 100644
--- a/docs/GROWING_FILES_QUICKSTART.md
+++ b/docs/GROWING_FILES_QUICKSTART.md
@@ -1 +1,86 @@
-DOC_PLACEHOLDER
\ No newline at end of file
+# Growing Files + Premiere Panel — Test Plan
+
+A local SMB landing zone for capture so Premiere can edit the master while
+it is still recording. The promotion worker uploads the finalized file to S3
+and the panel relinks Premiere to the hi-res original.
+
+## Cluster state (deployed 2026-05-22)
+
+- TrueNAS dataset: `NVME/MAM-growing` (LZ4, 0777)
+- TrueNAS SMB share: `mam-growing` → `/mnt/NVME/MAM-growing`
+- Host symlink for docker compose: `/mnt/NVME/MAM/wild-dragon-growing` → the dataset
+- mam-api + worker containers mount it at `/growing`
+- Settings (live): `growing_enabled=true`, `growing_smb_url=smb://10.0.0.25/mam-growing`
+
+## Capture flow (when growing_enabled=true)
+
+1. Recorder starts. mam-api spawns a capture sidecar with `GROWING_ENABLED=true`
+   and binds `/mnt/NVME/MAM/wild-dragon-growing:/growing`.
+2. FFmpeg writes the hi-res master directly to
+   `/growing/<projectId>/<clipName>.<ext>` (no S3 stream).
+3. The HLS tee continues to publish `/live/<assetId>/index.m3u8`, so the
+   Recorders + Monitors pages get a real video preview.
+4. On stop — or when the file's mtime is idle for
+   `growing_promote_after_seconds` — the promotion worker:
+   - uploads the local file to S3 at `projects/<projectId>/masters/<clipName>.<ext>`
+   - queues a proxy job
+   - flips the asset to `status=ready`
+   - deletes the local copy.
+
+## Premiere panel install
+
+```
+# macOS
+rsync -a services/premiere-plugin/ ~/Library/Application\ Support/Adobe/CEP/extensions/com.wilddragon.mam.panel/
+
+# Windows
+robocopy services\premiere-plugin %APPDATA%\Adobe\CEP\extensions\com.wilddragon.mam.panel /MIR
+```
+
+Enable CEP debug:
+
+```
+# macOS
+defaults write com.adobe.CSXS.11 PlayerDebugMode 1
+
+# Windows
+reg add "HKCU\Software\Adobe\CSXS.11" /v PlayerDebugMode /t REG_SZ /d 1 /f
+```
+
+Mount the SMB share once at OS level: `smb://10.0.0.25/mam-growing`.
+
+In Premiere: Window → Extensions → Wild Dragon MAM.
+
+## Test the live → finalized swap
+
+1. Start a recorder (Ingest → Recorders → Record).
+2. The Recorder row's preview becomes a real HLS `<video>` element.
+3. In Premiere, with the growing asset selected (status=live), click
+   **Mount Live**. The panel calls `GET /api/v1/assets/:id/live-path`,
+   resolves the SMB UNC path, and `app.project.importFiles()` it. Premiere
+   imports the still-growing MOV.
+4. Stop the recorder. After `growing_promote_after_seconds` of mtime
+   inactivity, the promotion worker uploads to S3 and flips status.
+5. The panel polls every 5 s. When it sees `status=ready` it surfaces
+   **Relink to Hi-Res** — clicking that downloads the finalized hi-res
+   and calls `ProjectItem.changeMediaPath()` to relink in place. Timeline
+   cuts are preserved.
+
+## Knobs (Settings → Growing files (SMB))
+
+- `growing_enabled` — master switch
+- `growing_path` — container mount path (default `/growing`)
+- `growing_smb_url` — what the Premiere panel hands to the editor
+- `growing_promote_after_seconds` — idle threshold for promotion
+
+## What's NOT yet here
+
+- Auth on the SMB share — currently passwordless. Add Samba auth via
+  `midclt call sharing.smb.update` and put creds in the editor's keychain
+  before exposing this beyond the LAN.
+- Concurrent S3 backup of the growing file. Today's MVP writes to SMB only;
+  S3 happens at promotion. If you need belt-and-suspenders, add `-f tee` in
+  capture-manager to fan out to both destinations.
+- Cleanup for stranded files (e.g. recorder crashes mid-capture). The idle
+  threshold will eventually promote them, but a stale-file sweeper would be
+  more graceful.