# AutoShorts Dashboard real-data/content-library sprint pattern

Use this when implementing or continuing AutoShorts Dashboard sprints that move the product from technical ingestion/review to creator-understandable analytics, mapping, content-family planning, and roadmap handoff.

## Core workflow

1. **Read the handoff before touching code**
   - Start with `docs/HANDOFF.md` and update it again before commit.
   - Maintain `docs/ROADMAP.md` as the sprint spine, not as an afterthought.
   - Report exact commit SHA, push status, preview URL, ports, tests, and what remains skeleton.

2. **Real data beats demo theatrics**
   - If analytics source-of-truth files are missing or incomplete, do not fake a successful import.
   - Add an explicit import guard for expected batch cardinality (e.g. exactly 3 YouTube CSVs for `Youtube 260606`).
   - Demo/fixture analytics must be `is_demo=true` and hidden by default in normal Results.
   - Keep imported CSVs/media out of Git; commit only `.gitkeep` and scripts/docs.

3. **Use creator-facing names first**
   Display-name priority for analytics rows:
   1. linked `VideoAsset.working_title`
   2. linked YouTube `PostDraft.title`
   3. YouTube CSV title
   4. cleaned CSV title
   5. external/YouTube ID only as a small technical subline, never the main row title

   Primary UI terms should be: YouTube video, Imported analytics, Linked package, Content family, Change note, Result, Improvement, Next recommendation. Keep raw provider IDs and metadata in advanced details only.

4. **Make mapping visible and actionable**
   - Show Mapping status at the top of Analytics Results: `N analytics videos`, `linked`, `not linked`, plus `Review mappings`.
   - For each unlinked analytics video show CSV/YouTube title, views, published date, YouTube video ID, and import batch.
   - Candidate packages should show thumbnail/working title/YouTube title/TikTok caption excerpt/package ID/match confidence and actions: Link, Open package review. Add `Link to topic only` and `Ignore` in later hardening sprints.
   - Matching priority: YouTube video ID in metadata/Shorts URL/draft fields → exact YouTube title → title similarity → nearby publish date → manual selection.

5. **Content Library, not lonely Topics**
   - Rename Topics UI to Content Library with subtitle `Families, scripts and next video decisions`.
   - Model or adapt existing tables to show Content Families with Ideas, Scripts, Produced videos, Planned variants, Performance, and Next recommendation.
   - Provide an importer that scans existing `review_package*.json` / manifests and upserts content families/scripts from package metadata, hooks, scripts, captions, descriptions, package IDs, video paths, and status.

6. **Recommendation endpoint**
   - Add `GET /api/content/recommendations/next` returning family, idea/script, reasons, confidence, and recommended_action.
   - MVP rules: reward high family views/retention/subscriber delta, include high-priority unproduced ideas, and rotate away from excessive same-family repetition. If no real analytics exist yet, say confidence is low and explain why.

7. **Be honest on future-platform pages**
   - Accounts, Logs, Verification, Settings should not be fake placeholders.
   - Accounts: show connected accounts/status/scopes/expiry/last API call/last error or a clear “connection not implemented yet; Sprint 8/9”.
   - Logs: aggregate activity/import/publish/API logs with redacted payload details.
   - Verification: use a TikTok readiness/checklist screen until Sandbox flow exists.
   - Settings: persist local workflow paths such as analytics Drive folder, default source dir, import limit, and demo mode.

## Google Drive / CSV import pattern

- First check local mounts: `~`, `~/GoogleDrive`, `~/gdrive`, `~/Drive`, `~/MyDrive`.
- Then check available tooling: `rclone`, `gdrive`, `gws`, `gog`.
- If `gog` is used, set keyring env privately and never print the value. Search may find files when folder listing is flaky; folder names can differ in word order (`260606 Youtube` vs `Youtube 260606`).
- If Drive access is incomplete, document checked paths/tools and require manual drop-in to `storage/imports/youtube/<batch>/` instead of improvising.

## Verification checklist before commit

- Backend: `uv run pytest -q` and `uv run ruff check app tests`.
- Frontend: `npm run build`.
- API smoke key endpoints: analytics simple/results/unlinked, content families, recommendations, settings, logs.
- Browser QA: Analytics and Content Library load; no console errors.
- Copy scan: primary UI does not expose raw terms like `ExternalPost`, `Snapshot`, `metadata_json`.
- Git scan: no CSVs, MP4s, media, DBs, or generated caches tracked.
- Commit and push; if normal HTTPS auth fails, use the approved local token path without echoing it and verify remote with token-authenticated `ls-remote`.

## Pitfalls

- Do not claim the real analytics import succeeded if the source batch is incomplete. A correctly empty Results page is better than mixed fixture data.
- Do not let old demo records leak into normal views after adding real-data support.
- Do not expose provider/database terms in the creator UI; keep them in advanced/debug details only.
- Do not let `docs/HANDOFF.md` contain `pending SHA` after final commit; either update/amend or explicitly report the final SHA in the completion note.
- Do not commit downloaded Google Drive CSVs or runtime import folders; use `.gitignore` plus `storage/imports/.gitkeep`.