Specify

# Feature Specification: AI Joke Generator MVP

**Feature Branch**: `002-ai-joke-generator`

**Created**: 2026-10-03

**Status**: Implemented (demo)

**Input**: Fun micro SaaS: landing, local “AI” joke generator (no API keys), mock auth dashboard with history/limits, and in-app Spec Kit learning path using this repo’s artifacts.

## User Scenarios & Testing

### User Story 1 - Visitor generates jokes (Priority: P1)

A visitor picks a topic and gets a fresh joke instantly, labeled as demo AI with no external API.

**Why this priority**: Core product value.

**Independent Test**: Open `/generate`, choose topic, click generate, see joke and copy button.

**Acceptance Scenarios**:

1. **Given** the generate page, **When** user clicks Generate, **Then** a joke appears within 500ms with topic-appropriate flavor.
2. **Given** the same topic and seed, **When** user generates repeatedly, **Then** jokes rotate through curated variety (deterministic engine).

---

### User Story 2 - Signed-in user tracks jokes (Priority: P1)

A signed-in user sees recent jokes on the dashboard and hits a daily limit on the free plan.

**Acceptance Scenarios**:

1. **Given** mock sign-in, **When** user generates jokes, **Then** they appear in dashboard history (newest first).
2. **Given** free plan and 15 jokes today, **When** user generates again, **Then** upgrade guidance is shown (mock Pro unlocks higher limit).

---

### User Story 3 - Learn Spec Kit from this repo (Priority: P1)

A developer walks a step-wise path (constitution → specify → plan → tasks → implement) and reads **actual markdown** from this repository.

**Acceptance Scenarios**:

1. **Given** `/learn`, **When** user opens each step, **Then** content matches files under `.specify/memory/` and `specs/002-ai-joke-generator/`.
2. **Given** implement step, **When** user follows links, **Then** they reach `/generate` and `/dashboard` described in `plan.md`.

## Requirements

- Mock GitHub sign-in (no OAuth)
- Mock Pro upgrade (no Stripe)
- Port **4317** for dev/start
- Responsive layout with shadcn/ui
- Archive superseded QueueBeacon specs under `specs/_archive/`