# Prepared video publishing dashboard sprint pattern

Session learning from the AutoShorts Dashboard product-core correction.

## Trigger

Use this when building or polishing a creator/publishing dashboard that manages prepared video assets, topic planning, metadata review, scheduling, and controlled private/draft upload approval.

## Product rule

The dashboard is the **control center**, not the machinery room. The visible product should feel like a professional creator/publishing workspace. Hide internal production names and automation details from UI, README, and product-facing docs.

Allowed platform/legal wording:
- Synthetic media
- AIGC disclosure
- Commercial content disclosure

Avoid in visible/product-facing copy unless the product is explicitly an operator console:
- Jarvis / Hermes / AutoShortsBot
- bot / AI pipeline / AI-generated pipeline
- Human gate
- autoposter framing

## Recommended sprint order

1. **Token/repo hygiene first** if GitHub is part of the sprint: reload the token from disk, bypass credential caches, verify `ls-remote`, inspect permissions behaviorally, and push CI/workflow files before feature work.
2. **Language neutralization:** scan UI, README, and product docs for internal automation terms; replace with prepared packages, content inbox, topic pipeline, creator approval, private upload, platform draft, audit trail.
3. **Operations cockpit:** dashboard home should show Ready for approval, Needs metadata, Scheduled private uploads, Uploaded private/draft, Failed actions, Recent prepared packages, Next topic, Ideas waiting, Current content pipeline, and Quick actions.
4. **Real media before polish:** replace grey placeholders with real thumbnails/video previews. Add a backend media endpoint such as `GET /api/videos/{video_id}/thumbnail` that loads `thumbnail_path`, generates a frame from `video.file_path` if missing, stores under local ignored storage, sets cache headers, and never leaks absolute paths. Use one frontend `VideoThumb` component everywhere.
5. **Prepared package workflow:** support `storage/incoming/package_xxx/` with `video.mp4`, `manifest.json`, optional thumbnail/transcript; dedupe by `package_id` and checksum; show import logs and errors. For workflow realism, import the latest real local rendered packages into ignored storage and never commit media binaries.
6. **Review page:** make this the primary page: video preview, thumbnail, working title, topic/series, TikTok/YouTube metadata visible together, account selector, privacy/private setting, schedule time, disclosure, save metadata, approve private upload, reject/needs changes, status timeline, metadata version history, audit log.
7. **Topics/Ideas database before provider glamour:** build `/topics` for ideas, links, keywords, short explanations, notes, pillar, series, priority, status, and actions like Use next, Hold, Needs research, Archive, Add source link, Add idea.
8. **Seed/demo or real import data:** include a deterministic seed command for UI review and/or an import script for latest local real packages. Make clear demo data is not fake functionality and real media stays in ignored storage.
9. **Provider uploads last:** only after package/review/topics/cockpit are stable, add YouTube private upload then TikTok draft/sandbox flows.
10. **Creator learning loop before provider glamour:** if analytics exists, simplify it around Results, Improvements, and Import data. Build `CreativeChange` + `ActivityEvent`, show views and linked/unlinked status by default, and connect metadata edits to before/after analytics snapshots before adding new platform APIs.
11. **Handoff required for larger sprints:** create/update `docs/HANDOFF.md` and a short UX review note when the sprint changes architecture/workflow. Include current branch, preview URL/ports, run commands, implemented vs skeleton features, data model notes, tests, and next priorities.

## Neutral manifest shape

```json
{
  "package_id": "package_2026_06_06_001",
  "source": "prepared_package",
  "working_title": "Example title",
  "language": "de",
  "topic_id": null,
  "series": null,
  "suggested_tiktok_caption": "Editable TikTok caption",
  "suggested_youtube_title": "Editable YouTube title",
  "suggested_youtube_description": "Editable YouTube description",
  "suggested_hashtags": ["#example"],
  "disclosure": {
    "synthetic_media": true,
    "commercial_content": false
  },
  "status": "ready_for_review"
}
```

## Verification

- Run backend tests and frontend build.
- Run endpoint/API smokes for media, imports, save metadata, schedule, approve, and analytics pages; do not assume button presence means workflow success.
- Run a visible-copy scan for forbidden internal terms in `frontend/src`, `README.md`, and product-facing docs.
- Run a Git media/binary scan before commit: no `.mp4`, `.mov`, `.webm`, generated thumbnails, or processed/incoming package folders except `.gitkeep` should be tracked.
- Browser-QA `/dashboard`, `/videos`, `/videos/:id/review`, `/calendar`, `/analytics`; capture snapshots or screenshots for the final report.
- Use visual QA after layout changes. If a card looks polished but text is cramped or clipped, fix hierarchy/column spans before reporting.
- Report which features truly work versus skeleton/placeholder.
- Include commit SHAs, push status, preview URL/ports, imported package IDs/titles, metadata source, changed file groups, and Handoff path.

## Pitfalls

- Do not continue into YouTube/TikTok API work when the user says the product core feels provisional. Stabilize the workflow and language first.
- A green build with empty pages is not acceptable for stakeholder review; seed or import enough real/dev data for the dashboard to show next actions.
- Grey thumbnail boxes make the dashboard feel fake even if the backend is solid. Build a reusable thumbnail component plus backend thumbnail endpoint early, then use it across dashboard, inbox, review, and calendar.
- Review pages become too technical if TikTok and YouTube metadata are hidden behind tabs only. Show side-by-side preview cards and keep edit fields large enough to verify captions/descriptions.
- Schedule endpoints often receive ISO strings from the frontend; parse to real `datetime` objects before storing in SQLite/SQLModel and add a regression test.
- CSV previews must handle quoted commas and emoji. Use a real parser such as PapaParse on the frontend even if the backend remains source of truth.
- `docs/HANDOFF.md` should be updated every major sprint, but a commit cannot reliably contain its own final SHA after amend. Put branch/preview/ports/runbook in the file and report the final exact SHA in the sprint summary.
- “Human gate” still implies bot/autoposter machinery. Use “Creator approval” or “Approval required”.
- Keep internal developer references separate from product-facing docs; backend module names may be temporarily internal, but routes/menu labels/README/product docs must be neutral.