# Audio Vault MVP Requirements

Build to these requirements; do not mistake them for finished features. This file states **product scope** traced to [Chat 1](chat1.md). It does not duplicate chosen defaults.

## Document Hierarchy

| Document | Role |
|---|---|
| **[DECISIONS.md](DECISIONS.md)** | Authoritative chosen defaults (D-01–D-156). **Wins over** stale wording here or in research docs. |
| **[CONFIG.md](CONFIG.md)** | Runtime env keys and default values (from decisions). |
| **[WEB.md](WEB.md)** | Browser Baseline, PWA, security, performance, and accessibility recommendations (September 2026). |
| **[TODO.md](TODO.md)** | Implementation and verification evidence; checkboxes track proof, not decisions. |
| **[PLAN.md](PLAN.md)** | Phased execution order. |
| **This file (AV-R*)** | Stable requirement IDs and transcript sources. When a requirement is decided, it **points to DECISIONS** instead of restating values. |

Later explicit user decisions control. IDs and transcript sources stay stable. **Derived** means an engineering interpretation. Numeric defaults live in [DECISIONS.md](DECISIONS.md); implementation evidence in [TODO.md](TODO.md).

---

## Identity and Delivery

- **AV-R01.** Project: Audio Vault. Repository: https://github.com/droxey/audiovault. *Source: [070](chat1.md#070--user), [072](chat1.md#072--user).*
- **AV-R02.** Canonical domain: https://audiovau.lt; replaces audiovault.musexmachine.com. Purchased September 7, 2026 through Hostinger; DNS managed by Cloudflare. DNS import timing: [D-18](DECISIONS.md#infrastructure-and-operations). *Source: [068](chat1.md#068--user), [106](chat1.md#106--user).*
- **AV-R03.** Seller: Muse & Machine LLC. Business partner is in Norway. *Source: [047](chat1.md#047--user), [087](chat1.md#087--user).*
- **AV-R04.** Code freeze and end-of-September milestone scope. **Decided:** [D-01](DECISIONS.md#schedule-acceptance-and-capacity) (Sep 10, 2026, 11:59 PM US Eastern — same day as launch), [D-02](DECISIONS.md#schedule-acceptance-and-capacity) (milestone contents), [D-03](DECISIONS.md#schedule-acceptance-and-capacity) (public launch Sep 10, 2026, US Eastern), [D-04](DECISIONS.md#schedule-acceptance-and-capacity) (acceptance owner), [D-05](DECISIONS.md#schedule-acceptance-and-capacity) (capacity). Env: `PUBLIC_LAUNCH_DATE`, `CODE_FREEZE_DATE`. *Source: [055](chat1.md#055--user), [081](chat1.md#081--user).*
- **AV-R05.** Web MVP first: Linux/cloud Go service, desktop browsers, and installable iOS/Android PWA. Hosting split: [D-10](DECISIONS.md#infrastructure-and-operations)–[D-17](DECISIONS.md#infrastructure-and-operations). Accessibility target: [D-102](DECISIONS.md#legal-policies-and-accessibility). *Source: [013](chat1.md#013--user), [016](chat1.md#016--user), [018](chat1.md#018--user), [019](chat1.md#019--user).*
- **AV-R06.** September MVP permits clearly labeled **simulated** streamer playback; real uploads, browser playback, signup/login, and Stripe **test** checkout remain required for the milestone. **Decided:** [D-02](DECISIONS.md#schedule-acceptance-and-capacity), [D-110](DECISIONS.md#streamer-and-version-2). *Source: [033](chat1.md#033--user), [043](chat1.md#043--user), [065](chat1.md#065--user), [118](chat1.md#118--user).*
- **AV-R07.** Current repository baseline includes a static storage calculator in `docs/` plus research/planning; the Go music application is not yet built. Calculator refresh timing: [D-90](DECISIONS.md#calculator-and-economics)–[D-92](DECISIONS.md#calculator-and-economics). *Source: [110](chat1.md#110--user), [118](chat1.md#118--user).*

## Listener Experience

- **AV-R08.** Help audiophiles move large, precious NAS music collections into managed cloud storage with minimal effort, cost, and supervision. *Source: [008](chat1.md#008--user), [044](chat1.md#044--user), [096](chat1.md#096--user), [100](chat1.md#100--user).*
- **AV-R09.** Use the fewest practical pages, with a simple upload queue, library, and player. Keep upload state while navigating. *Derived from: [049](chat1.md#049--user).*
- **AV-R10.** Support Chrome, Safari, Firefox, and Edge. **Decided:** minimum versions [D-117](DECISIONS.md#web-platform-and-browsers) (Baseline Widely available on 2026-09-07 defaults), **configurable via `.env`** [D-130](DECISIONS.md#web-platform-and-browsers); real-browser matrix sign-off [D-129](DECISIONS.md#web-platform-and-browsers); engineering detail in [WEB.md](WEB.md). Matrix evidence: [AV-T12](TODO.md). *Source: [050](chat1.md#050--user).*
- **AV-R11.** Preserve every original audio byte and folder path. No transcoding, downsampling, playback copies, or embedded-tag rewriting. Path limits: [D-59](DECISIONS.md#uploads-files-and-integrity). *Source: [025](chat1.md#025--user), [035](chat1.md#035--user), [039](chat1.md#039--user), [100](chat1.md#100--user).*
- **AV-R12.** Support FLAC, WAV, AIFF, ALAC, MP3, AAC, and DSD (DSF/DFF). **Music files only** at upload scan ([D-123](DECISIONS.md#uploads-files-and-integrity)); sidecars and rejection rules: [D-57](DECISIONS.md#uploads-files-and-integrity)–[D-58](DECISIONS.md#uploads-files-and-integrity). Validation implementation: [AV-T16](TODO.md). *Source: [008](chat1.md#008--user), [023](chat1.md#023--user).*
- **AV-R13.** Provide both folders/filenames and artist/album/track browsing from metadata. *Source: [037](chat1.md#037--user).*
- **AV-R14.** Manual catalog metadata edits without modifying originals; external identification with confident auto-apply and review for uncertain matches. **Decided:** [D-70](DECISIONS.md#metadata-and-privacy)–[D-74](DECISIONS.md#metadata-and-privacy). Slip cut: [D-06](DECISIONS.md#schedule-acceptance-and-capacity). *Source: [039](chat1.md#039--user), [041](chat1.md#041--user).*

## Uploads and Storage

- **AV-R15.** Company-managed S3-compatible storage (default Cloudflare R2, US jurisdiction). BYO customer storage is **out of scope** ([AV-T39](TODO.md)). **Decided:** [D-12](DECISIONS.md#infrastructure-and-operations), [D-10](DECISIONS.md#infrastructure-and-operations)–[D-11](DECISIONS.md#infrastructure-and-operations). *Source: [008](chat1.md#008--user), [020](chat1.md#020--user), [062](chat1.md#062--user).*
- **AV-R16.** Select/drag files and folders; configurable concurrent uploads. **Decided:** [D-51](DECISIONS.md#uploads-files-and-integrity). *Source: [035](chat1.md#035--user), [048](chat1.md#048--user).*
- **AV-R17.** Upload integrity and recovery are the primary release gate. Account for every selected file; report rejected, unreadable, changed, and failed entries. *Derived from: [044](chat1.md#044--user), [049](chat1.md#049--user), [100](chat1.md#100--user). Evidence: [AV-T11](TODO.md)–[AV-T12](TODO.md).*
- **AV-R18.** Persist upload manifests and multipart progress; safe pause on browser close; resume after reopen/reselect when required. **Decided:** [D-52](DECISIONS.md#uploads-files-and-integrity), [D-26](DECISIONS.md#authentication-and-sessions) (logout behavior). *Derived from: [052](chat1.md#052--user).*
- **AV-R19.** Do not repeat verified completed uploads; idempotent finalize and quota accounting. **Decided:** [D-54](DECISIONS.md#uploads-files-and-integrity) (identity), collision/overwrite: [D-55](DECISIONS.md#uploads-files-and-integrity)–[D-56](DECISIONS.md#uploads-files-and-integrity). *Derived from: [052](chat1.md#052--user), [100](chat1.md#100--user).*
- **AV-R20.** Verify integrity before library publication; detect changed sources; never mix versions. **Decided:** [D-54](DECISIONS.md#uploads-files-and-integrity), [D-58](DECISIONS.md#uploads-files-and-integrity). *Derived from: [044](chat1.md#044--user), [100](chat1.md#100--user).*
- **AV-R21.** Keep NAS originals intact; verified cloud import does not auto-delete source. No NAS-retention UI messaging: [D-61](DECISIONS.md#uploads-files-and-integrity). *Derived from: [100](chat1.md#100--user).*
- **AV-R22.** Large-library design must address the Luke 10 TB story and feasibility above 20 TB. **Decided:** plan cap [D-31](DECISIONS.md#subscription-stripe-and-launch-geography) (2 TB), engineering ceiling [D-32](DECISIONS.md#subscription-stripe-and-launch-geography) (20 TB), story interpretation [D-33](DECISIONS.md#subscription-stripe-and-launch-geography), file cap and depth [D-127](DECISIONS.md#account-limits-and-settings), soak target [D-125](DECISIONS.md#account-limits-and-settings), uplink assumption [D-126](DECISIONS.md#account-limits-and-settings), per-account limit overrides [D-128](DECISIONS.md#account-limits-and-settings). *Source: [091](chat1.md#091--user), [100](chat1.md#100--user).*
- **AV-R23.** Recovery retention, cleanup, backups, and restoration evidence. **Decided:** backups [D-14](DECISIONS.md#infrastructure-and-operations), orphan cleanup [D-53](DECISIONS.md#uploads-files-and-integrity), trash [D-80](DECISIONS.md#retention-and-account-lifecycle)–[D-81](DECISIONS.md#retention-and-account-lifecycle), account deletion [D-82](DECISIONS.md#retention-and-account-lifecycle). “No loss ever” remains intent, not an unlimited guarantee. Evidence: [AV-T13](TODO.md). *Derived from: [049](chat1.md#049--user), [052](chat1.md#052--user).*

## Playback and Devices

- **AV-R24.** Play compatible originals in the browser, including phone/tablet access. *Source: [010](chat1.md#010--user), [011](chat1.md#011--user), [025](chat1.md#025--user), [033](chat1.md#033--user).*
- **AV-R25.** When unsupported in the browser, offer streamer path; v1 streamer is **simulated** with clear labeling. **Decided:** [D-110](DECISIONS.md#streamer-and-version-2). *Source: [027](chat1.md#027--user), [118](chat1.md#118--user).*
- **AV-R26.** Next integration priority: quiet connect to one compatible local streamer; prompt when several exist. **Decided:** [D-112](DECISIONS.md#streamer-and-version-2) (Phase 7; deferred for MVP/freeze). *Source: [031](chat1.md#031--user), [118](chat1.md#118--user).*
- **AV-R27.** Intended integration: manufacturer API/SDK; streamer retrieves authorized originals from object storage. Phase 7; do not fake as v1. *Source: [031](chat1.md#031--user), [100](chat1.md#100--user).*
- **AV-R28.** Intended real integration: home/remote streamer control. Phase 7+. *Source: [029](chat1.md#029--user), [100](chat1.md#100--user).*
- **AV-R29.** DLC manufacturer, models, SDK, discovery, and browser feasibility require verification before physical claims. **Decided:** defer details [D-111](DECISIONS.md#streamer-and-version-2). Evidence: [AV-T25](TODO.md)–[AV-T29](TODO.md). *Derived from: [013](chat1.md#013--user), [031](chat1.md#031--user).*

## Accounts and Commercial Scope

- **AV-R30.** Public signup/login and paid subscriptions wherever legally supported. **Decided:** geography [D-40](DECISIONS.md#subscription-stripe-and-launch-geography); auth methods [D-20](DECISIONS.md#authentication-and-sessions)–[D-26](DECISIONS.md#authentication-and-sessions), freeze mix [D-152](DECISIONS.md#authentication-and-sessions); auth email [D-131](DECISIONS.md#infrastructure-and-operations) (Resend outbound from `@audiovau.lt`). *Source: [043](chat1.md#043--user), [083](chat1.md#083--user), [085](chat1.md#085--user).*
- **AV-R31.** Stripe; one fixed-price plan with storage cap. **Decided:** [D-30](DECISIONS.md#subscription-stripe-and-launch-geography)–[D-31](DECISIONS.md#subscription-stripe-and-launch-geography) ($49/mo USD, 2 TB). *Source: [045](chat1.md#045--user), [063](chat1.md#063--user), [065](chat1.md#065--user), [089](chat1.md#089--user).*
- **AV-R32.** Billing lifecycle defaults (currency, intervals, trial, grace, cancel, refunds, test/live mode). **Decided:** [D-30](DECISIONS.md#subscription-stripe-and-launch-geography)–[D-41](DECISIONS.md#subscription-stripe-and-launch-geography); env detail in [CONFIG.md](CONFIG.md). Stripe Price IDs: evidence [AV-T20](TODO.md). *Sources: [045](chat1.md#045--user), [089](chat1.md#089--user), [091](chat1.md#091--user).*
- **AV-R33.** Respect applicable US, EU, and Norway/EEA obligations; eligible countries and counsel review before go-live. **Decided:** launch geography [D-40](DECISIONS.md#subscription-stripe-and-launch-geography); policy drafts and counsel [D-100](DECISIONS.md#legal-policies-and-accessibility)–[D-101](DECISIONS.md#legal-policies-and-accessibility). This document does not certify compliance. Evidence: [AV-T22](TODO.md), [AV-T40](TODO.md)–[AV-T42](TODO.md). *Derived from: [046](chat1.md#046--user), [047](chat1.md#047--user), [085](chat1.md#085--user).*

## Calculator

- **AV-R34.** Static calculator under `docs/`; product static/PWA on **Cloudflare Pages** at apex ([D-16](DECISIONS.md#infrastructure-and-operations)); default provider preset Cloudflare R2. Retire GitHub Pages / `docs/CNAME` plan for product hosting ([AV-T36](TODO.md)). *Source: [062](chat1.md#062--user), [110](chat1.md#110--user), [118](chat1.md#118--user).*
- **AV-R35.** Compare provider/region presets relevant to US and Norway-facing listening. European regions do not imply Norway residency. *Source: [102](chat1.md#102--user).*
- **AV-R36.** Partner can enter rates, add providers, save quotes, and export/import scenarios. *Source: [091](chat1.md#091--user), [104](chat1.md#104--user).*
- **AV-R37.** Model storage, requests, egress, retention, allowances, and operating assumptions. *Derived from: [096](chat1.md#096--user).*
- **AV-R38.** Mirroring remains a future **cost scenario**, not MVP music scope. **Decided:** [D-115](DECISIONS.md#streamer-and-version-2). *Source: [096](chat1.md#096--user), [118](chat1.md#118--user).*
- **AV-R39.** Refresh default prices from current vendor sources; preserve custom quotes on failure; show sources and dates. **Decided:** defer until after music MVP [D-90](DECISIONS.md#calculator-and-economics); daily feed when built [D-91](DECISIONS.md#calculator-and-economics). *Source: [104](chat1.md#104--user), [118](chat1.md#118--user).*
- **AV-R40.** Baseline loads a published snapshot; live refresh is not yet implemented. **Decided:** not blocking freeze [D-92](DECISIONS.md#calculator-and-economics). Evidence: [AV-T04](TODO.md). *Baseline; [118](chat1.md#118--user); [VALIDATION.md](VALIDATION.md).*

## Version 2 and Later

- **AV-R41.** Go companion: background upload + OS drive; both version 2. *Source: [054](chat1.md#054--user), [060](chat1.md#060--user), [081](chat1.md#081--user).*
- **AV-R42.** NAS and native Windows/macOS/Linux installation after web MVP. **Decided:** OS priority [D-113](DECISIONS.md#streamer-and-version-2); OS drive read-write [D-114](DECISIONS.md#streamer-and-version-2). *Source: [016](chat1.md#016--user), [081](chat1.md#081--user).*
- **AV-R43.** Mirroring deferred; NAS source deletion must not silently delete cloud copies. **Decided:** [D-115](DECISIONS.md#streamer-and-version-2). *Source: [118](chat1.md#118--user).*

## Project Deliverables

- **AV-R44.** Preserve [docs/USER_STORIES.md](../USER_STORIES.md) with the supplied Luke story. *Source: [100](chat1.md#100--user).*
- **AV-R45.** Planning/research docs and PNG architecture diagram. *Source: [058](chat1.md#058--user), [111](chat1.md#111--user).*
- **AV-R46.** README: diagram first, title, badges, purpose, setup, use, configuration, sources last. *Source: [114](chat1.md#114--user).*
- **AV-R47.** Document configurable values via [CONFIG.md](CONFIG.md) and [.env.example](../../.env.example); secrets and undecided values stay blank; runtime secrets outside `docs/`. *Source: [114](chat1.md#114--user), [118](chat1.md#118--user).*
- **AV-R48.** Maintain [`config/dns/records.txt`](../../config/dns/records.txt) as the product DNS import source; apply only explicit product decision updates (e.g. [D-155](DECISIONS.md#infrastructure-and-operations) retires `*.dev.audiovau.lt`). Title/count mismatch noted — review at [AV-T35](TODO.md) before [AV-T34](TODO.md). Import/change DNS only per [D-18](DECISIONS.md#infrastructure-and-operations). *Source: [114](chat1.md#114--user), [118](chat1.md#118--user).*
- **AV-R49.** Record registrar nameserver-change task; original four-hour deadline not reconstructible. **Decided:** before public launch only [D-18](DECISIONS.md#infrastructure-and-operations). Task: [AV-T34](TODO.md). *Source: [109](chat1.md#109--user).*

---

## Remaining Work

Product defaults are recorded in [DECISIONS.md](DECISIONS.md) (D-01–D-156). Remaining gaps are **implementation evidence** and **human-only ops** in [TODO.md](TODO.md) — for example AV-T21 (production infra), AV-T34 (apex DNS), AV-T40–T42 counsel publication, AV-T43 (mailboxes), and AV-T22 (counsel sign-off).

When a task is `blocked-human` and no DECISIONS row exists yet, agents ask **one question per message**, with lettered multiple-choice options and the **recommended option listed first** ([AGENTS.md](../../AGENTS.md#ask-human-decision-questions)).

---

## Requirement-to-Decision Index

| Requirements | Decision IDs |
|---|---|
| AV-R04, AV-R06 | D-01–D-06, D-110, D-132 |
| AV-R05, AV-R15 | D-10–D-17, D-102, D-117, D-121, D-130, D-135–D-156 |
| AV-R14 | D-06, D-70–D-74 |
| AV-R16–R21, AV-R23 | D-50–D-61, D-80–D-82, D-14, D-53, D-134, D-123 |
| AV-R22 | D-31–D-33, D-125–D-128 |
| AV-R25–R29 | D-110–D-112, D-111, D-140 |
| AV-R30–R33 | D-20–D-26, D-30–D-41, D-40, D-100–D-101, D-131, D-138, D-144–D-145, D-152, D-156 |
| AV-R34, AV-R39–R40 | D-90–D-92, D-16, D-146 |
| AV-R38, AV-R42–R43 | D-113–D-115 |
| AV-R48–R49 | D-18, D-147, D-155 |

When [DECISIONS.md](DECISIONS.md) changes, update the **Decided** links in this file and the index above; do not copy decision text here.