Iconik

Build me a single-user local media catalog for my own drives, the honest
personal floor of iconik. It is for exactly one person; facility-scale asset
management is what iconik is for. Requirements:

- A Node CLI plus a local web app: better-sqlite3 for the index, Express serving on
  localhost, plain server-rendered pages.
- `scan <volume>` walks the drive, records path, size, mtime, and volume label, then
  runs ffprobe for duration, codec, resolution, frame rate, and embedded timecode.
  Re-running it is incremental, keyed on path plus mtime plus size.
- Every video gets a 480p H.264 proxy and a contact sheet of 9 frames written to
  ~/MediaCatalog/proxies/<hash>/, so I can identify a clip without mounting the drive
  it lives on.
- Search across filename, path, codec, and my own notes with SQLite FTS5, plus filters
  for duration, resolution, and volume. Results play the proxy inline.
- Offline drives stay in the index and are marked offline when the volume is not
  mounted, with the volume label shown so I know which shelf to go to.
- Free-text notes and tags per clip, and a starred collection I can export as a JSON
  or CSV shot list.
- Everything is local: no accounts, no cloud, no telemetry. The SQLite file plus the
  proxies folder is the entire product and both are backupable.
- Out of scope: multi-user access, permissions, cloud storage gateways, and AI tagging.
  Do not build a login system. If a second person needs this, buy iconik.
- README: installing ffmpeg, expected first-scan time for a 20TB volume, and a warning
  to run the proxy pass overnight.

# AGENTS.md — Build guide for Iconik

## Project scope
For one person on their own drives: walk the volumes, make ffmpeg proxies, extract metadata, and search it locally. A catalog, not a MAM.

Catalogue verdict: no. Iconik is not a search box, it is a storage gateway network. Its job is to make an on-prem NAS in one building, an LTO library in another, and three cloud buckets behave like one library, generate proxies for all of it, and then let a producer in another timezone browse the parts they are allowed to see without ever touching the original storage. Every hard part of that is infrastructure and permissions, and none of it gets easier because an agent writes the code. A solo editor can absolutely build a personal catalog of their own drives, and that is worth doing. It is not a MAM, and the moment a second person or a second site is involved you are staffing a product, not running a script.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- ffmpeg
- a machine that can see every volume you want indexed
- SQLite plus FTS5
- storage for proxies
- a lot of patience for the first index

## Stack and architecture
- A Node CLI plus a local web app: better-sqlite3 for the index, Express serving on localhost, plain server-rendered pages.
- Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Interface for this cloud media asset management workflow: a CLI with a dry-run or preview command and an explicit output path.

## Security and data integrity
- Offline drives stay in the index and are marked offline when the volume is not mounted, with the volume label shown so I know which shelf to go to.
- Validate imported records and file paths; keep user data within the storage location named in the prompt.
- State the practical limit: storage gateways that index on-prem NAS, LTO, and cloud buckets as one library.

## Agent implementation rules
- Project rule, data: Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
- Project rule, behavior: Everything is local: no accounts, no cloud, no telemetry. The SQLite file plus the proxies folder is the entire product and both are backupable.
- Project rule, recovery: Offline drives stay in the index and are marked offline when the volume is not mounted, with the volume label shown so I know which shelf to go to.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this cloud media asset management operation with sample or user-owned data: Everything is local: no accounts, no cloud, no telemetry. The SQLite file plus the proxies folder is the entire product and both are backupable.
- Show a concrete result or export: Free-text notes and tags per clip, and a starred collection I can export as a JSON or CSV shot list.
- State the practical limit: storage gateways that index on-prem NAS, LTO, and cloud buckets as one library.

## Engineering roadmap
1. Phase 1, architecture and data: A Node CLI plus a local web app: better-sqlite3 for the index, Express serving on localhost, plain server-rendered pages. Model source media, edit decisions, processing jobs, and exported assets; keep stable source IDs and timestamps.
2. Phase 2, implement: Everything is local: no accounts, no cloud, no telemetry. The SQLite file plus the proxies folder is the entire product and both are backupable.
3. Phase 3, implement: For one person on their own drives: walk the volumes, make ffmpeg proxies, extract metadata, and search it locally. A catalog, not a MAM.
4. Phase 4, review and output: Backlight's cloud MAM: indexes on-prem, LTO, and cloud storage into one searchable, permissioned media library. Free-text notes and tags per clip, and a starred collection I can export as a JSON or CSV shot list.
5. Phase 5, recovery and acceptance: Offline drives stay in the index and are marked offline when the volume is not mounted, with the volume label shown so I know which shelf to go to. Verify this invariant with a saved fixture: The original hash must remain unchanged; cuts and captions must stay aligned after export despite a variable input frame rate. State the practical limit: storage gateways that index on-prem NAS, LTO, and cloud buckets as one library.

## Paid-product capabilities outside this build
- storage gateways that index on-prem NAS, LTO, and cloud buckets as one library
- per-user and per-collection permissions with an audit trail
- proxy transcoding that keeps up with petabyte ingest
- Adobe and Resolve panels plus the desktop player
- shared collections and review for clients who never see your storage
- archive and restore lifecycle out to deep cloud storage

## Implementation prompt
Build me a single-user local media catalog for my own drives, the honest
personal floor of iconik. It is for exactly one person; facility-scale asset
management is what iconik is for. Requirements:

- A Node CLI plus a local web app: better-sqlite3 for the index, Express serving on
  localhost, plain server-rendered pages.
- `scan <volume>` walks the drive, records path, size, mtime, and volume label, then
  runs ffprobe for duration, codec, resolution, frame rate, and embedded timecode.
  Re-running it is incremental, keyed on path plus mtime plus size.
- Every video gets a 480p H.264 proxy and a contact sheet of 9 frames written to
  ~/MediaCatalog/proxies/<hash>/, so I can identify a clip without mounting the drive
  it lives on.
- Search across filename, path, codec, and my own notes with SQLite FTS5, plus filters
  for duration, resolution, and volume. Results play the proxy inline.
- Offline drives stay in the index and are marked offline when the volume is not
  mounted, with the volume label shown so I know which shelf to go to.
- Free-text notes and tags per clip, and a starred collection I can export as a JSON
  or CSV shot list.
- Everything is local: no accounts, no cloud, no telemetry. The SQLite file plus the
  proxies folder is the entire product and both are backupable.
- Out of scope: multi-user access, permissions, cloud storage gateways, and AI tagging.
  Do not build a login system. If a second person needs this, buy iconik.
- README: installing ffmpeg, expected first-scan time for a 20TB volume, and a warning
  to run the proxy pass overnight.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.