Document fresh-machine setup and status

TODO.md

@@ -29,6 +29,7 @@
 - Artgrid metadata fidelity is improved, but stable public hover-video preview extraction is still not solved.
 - Frontend now logs more useful API and debug information than earlier versions.
 - A local self-test workflow now exists and should be run before container builds or pushes.
+- A fresh-machine bootstrap was revalidated in a user-local toolchain setup on `2026-03-17`; `go test ./...` and `bash scripts/selftest.sh` now pass in that setup.
 
 ## Current Architecture
 - `backend/main.go`
@@ -402,6 +403,19 @@
 - `SEARXNG_WEB_ENGINE`
 - `GEMINI_API_KEY`
 
+## Local Development Environment Notes
+- This machine started without `go`, `pip`, `ffmpeg`, `yt-dlp`, or `node`.
+- To unblock local development without root:
+  - installed Go `1.24.0` under `~/.local/tooling/go`
+  - installed `pip` in user site with `get-pip.py --user --break-system-packages`
+  - installed `imageio-ffmpeg` in user site and linked its bundled `ffmpeg` into `~/.local/bin/ffmpeg`
+  - installed `yt-dlp` standalone binary into `~/.local/bin/yt-dlp`
+  - linked `go` and `gofmt` into `~/.local/bin`
+  - appended `~/.local/bin` and `~/.local/tooling/go/bin` to `PATH` in `~/.bashrc`
+- `node` is still not installed on this machine.
+- This is acceptable for the current repo because there is still no Node-based frontend build or lint workflow in-tree.
+- If future frontend work adds a Node toolchain, document the exact version and setup steps here before pushing.
+
 ## Local Self-Test Workflow
 - Primary command:
   - `bash scripts/selftest.sh`
@@ -419,6 +433,9 @@
   - this is a smoke test, not a browser-level verification suite
 
 ## Verified Locally In This Environment
+- [x] user-local Go toolchain available on `PATH`
+- [x] user-local `ffmpeg` available on `PATH`
+- [x] user-local `yt-dlp` available on `PATH`
 - [x] `go build -o /tmp/ai-media-hub ./backend`
 - [x] `go test ./...`
 - [x] Python syntax check for worker + self-test helper
@@ -426,6 +443,7 @@
 - [x] local `/api/search` against mock SearXNG through `scripts/selftest.sh`
 - [x] local `/api/upload` through `scripts/selftest.sh`
 - [ ] full browser-level validation was not fully reproducible in this environment
+- [ ] Node-based frontend lint/build step is still unavailable in this environment
 
 ## Recent Change Log
 - Date: `2026-03-16`
@@ -520,11 +538,13 @@
 - Current state:
   - latest work in this environment has been pushed successfully multiple times after the earlier remote unpacker issue
   - the older push failure note is historical context only and should not be treated as the current repo state
+  - before the `2026-03-17` documentation-only update, push/auth from this specific machine had not yet been revalidated
 - Operational note:
   - because the frontend is static and aggressively cached, browser hard refreshes are often required after UI / modal / preview changes
 
 ## Highest-Value Next Steps
 - [ ] Reduce `/api/search` latency further without collapsing result count
+- [ ] Build a repeatable repo-local bootstrap script or documented setup command set for non-root machines so fresh PC setup does not depend on shell history
 - [ ] Improve Envato / Artgrid preview acquisition reliability so Gemini Vision sees real frames more often
 - [ ] Revisit Google Video UX:
   - current YouTube embed was abandoned due error `153`
@@ -591,6 +611,23 @@
 - If behavior in the browser does not match the latest backend/frontend code, the first assumption should be stale frontend assets until proven otherwise
 
 ## Recent Change Log
+- Date: `2026-03-17`
+- What changed:
+  - Re-audited the repository structure and `TODO.md` handover state on a fresh machine.
+  - Bootstrapped a user-local development toolchain because the machine initially lacked `go`, `pip`, `ffmpeg`, and `yt-dlp`.
+  - Revalidated the documented self-test flow and updated this handover document with environment notes, current verification status, and next-step priorities.
+- Why it changed:
+  - Ongoing work will happen from different PCs, so the project needed an explicit record of what this repo requires to become runnable when root-level package installation is unavailable.
+- How it was verified:
+  - `go version`
+  - `ffmpeg -version`
+  - `yt-dlp --version`
+  - `go test ./...`
+  - `bash scripts/selftest.sh`
+- What is still risky or incomplete:
+  - This machine still has no `node`, so any future frontend build/lint workflow will need an explicit setup step before it can become part of local verification.
+  - The environment bootstrap done here is user-local rather than repo-automated, so reproducing it on another PC is still partly manual until a bootstrap script or setup doc lands.
+
 - Date: `2026-03-16`
 - What changed:
   - When Gemini batch evaluation is only partially successful, the API now explicitly backfills the final list with preview-capable ranked candidates instead of leaving the visible result set too thin.