Vernigo

Build me a personal YouTube outlier research tool inspired by Vernigo. Requirements:

- Django + PostgreSQL, one self-hosted web app; Google login is out of scope,
  use a single admin password from .env.
- Let me add YouTube channel IDs manually or import them from a CSV seed list.
- Pull each channel's recent videos through the official YouTube Data API and
  store title, thumbnail, views, duration, publish date, and channel stats.
- Calculate an outlier multiplier as video views divided by the average views
  of that channel's previous five videos available in the database.
- A searchable video grid with filters for multiplier, views, subscribers,
  duration, publish date, category, and channel age; sortable by multiplier,
  views, or newest.
- Bookmark folders: create, rename, and delete folders, and save or remove
  videos without duplicating them.
- A niche page that groups imported channels by a manually assigned niche and
  ranks niches using median views per video divided by videos published.
- Run refresh jobs with Celery + Redis once per day, respect API quota errors,
  and show the last successful refresh time for every channel.
- Store all secrets in .env; include Docker Compose for Django, PostgreSQL,
  Redis, Celery worker, and scheduler.
- Out of scope: crawling all of YouTube, a 10M-video corpus, community ranking
  signals, automatic niche classification, and claims that this finds the
  best opportunities market-wide. It only analyzes the channels I seed.
- README: YouTube API setup, quota limits, CSV format, calculation details,
  backup steps, and the limits of a small personal dataset.

# AGENTS.md — Build guide for Vernigo

## Project scope
Track a curated list of YouTube channels, compare each video's views with that channel's recent average, and browse the resulting outliers with filters and bookmark folders.

Catalogue verdict: no. You can build filters, bookmarks, and an outlier score over a small set of YouTube channels, but Vernigo's product is the continuously refreshed corpus: millions of videos, channel baselines, niche-level supply and demand signals, and ranking data improved by how thousands of users interact with the library. A one-shot app can reproduce the interface and formula, not the dataset that makes the results useful.
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
- YouTube Data API key
- curated channel seed list
- scheduled data collection
- database
- always-on box for refresh jobs

## Stack and architecture
- Django + PostgreSQL, one self-hosted web app; Google login is out of scope, use a single admin password from .env.
- Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Interface for this YouTube outlier and niche research workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- Run refresh jobs with Celery + Redis once per day, respect API quota errors, and show the last successful refresh time for every channel.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: the 10M-video historical and continuously updating database.

## Agent implementation rules
- Project rule, data: Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
- Project rule, behavior: Bookmark folders: create, rename, and delete folders, and save or remove videos without duplicating them.
- Project rule, recovery: Run refresh jobs with Celery + Redis once per day, respect API quota errors, and show the last successful refresh time for every channel.

## 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 YouTube outlier and niche research operation with sample or user-owned data: Bookmark folders: create, rename, and delete folders, and save or remove videos without duplicating them.
- Show a concrete result or export: Store all secrets in .env; include Docker Compose for Django, PostgreSQL, Redis, Celery worker, and scheduler.
- State the practical limit: the 10M-video historical and continuously updating database.

## Engineering roadmap
1. Phase 1, architecture and data: Django + PostgreSQL, one self-hosted web app; Google login is out of scope, use a single admin password from .env. Model data sources, dated observations, derived metrics, and report snapshots; keep stable source IDs and timestamps.
2. Phase 2, implement: Bookmark folders: create, rename, and delete folders, and save or remove videos without duplicating them.
3. Phase 3, implement: Run refresh jobs with Celery + Redis once per day, respect API quota errors, and show the last successful refresh time for every channel.
4. Phase 4, review and output: Store all secrets in .env; include Docker Compose for Django, PostgreSQL, Redis, Celery worker, and scheduler.
5. Phase 5, recovery and acceptance: Run refresh jobs with Celery + Redis once per day, respect API quota errors, and show the last successful refresh time for every channel. Verify this invariant with a saved fixture: A replayed batch cannot double-count events; missing or late data must be labelled in the report. State the practical limit: the 10M-video historical and continuously updating database.

## Paid-product capabilities outside this build
- the 10M-video historical and continuously updating database
- broad discovery beyond channels you already know
- unsaturated niche rankings across the wider YouTube market
- community interaction signals from more than 2,000 users
- ranking quality improved by accumulated usage data
- coverage and freshness without managing YouTube API quotas

## Implementation prompt
Build me a personal YouTube outlier research tool inspired by Vernigo. Requirements:

- Django + PostgreSQL, one self-hosted web app; Google login is out of scope,
  use a single admin password from .env.
- Let me add YouTube channel IDs manually or import them from a CSV seed list.
- Pull each channel's recent videos through the official YouTube Data API and
  store title, thumbnail, views, duration, publish date, and channel stats.
- Calculate an outlier multiplier as video views divided by the average views
  of that channel's previous five videos available in the database.
- A searchable video grid with filters for multiplier, views, subscribers,
  duration, publish date, category, and channel age; sortable by multiplier,
  views, or newest.
- Bookmark folders: create, rename, and delete folders, and save or remove
  videos without duplicating them.
- A niche page that groups imported channels by a manually assigned niche and
  ranks niches using median views per video divided by videos published.
- Run refresh jobs with Celery + Redis once per day, respect API quota errors,
  and show the last successful refresh time for every channel.
- Store all secrets in .env; include Docker Compose for Django, PostgreSQL,
  Redis, Celery worker, and scheduler.
- Out of scope: crawling all of YouTube, a 10M-video corpus, community ranking
  signals, automatic niche classification, and claims that this finds the
  best opportunities market-wide. It only analyzes the channels I seed.
- README: YouTube API setup, quota limits, CSV format, calculation details,
  backup steps, and the limits of a small personal dataset.

## 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.