Plan

# Implementation Plan: AI Joke Generator MVP

**Branch**: `002-ai-joke-generator` | **Date**: 2026-10-03

## Summary

Next.js app with marketing home, `/generate` joke surface, authenticated `/dashboard` (client mock), and `/learn` step routes that render repository markdown artifacts. Joke “AI” is `src/lib/joke-engine.ts` (curated + templates). Persistence via `src/lib/joke-store.ts` and `localStorage`.

## Technical context

| Area | Choice |
| --- | --- |
| Framework | Next.js 16 App Router, TypeScript |
| UI | Tailwind 4, shadcn/ui |
| State | React context + localStorage |
| Port | 4317 (dev/start scripts) |
| Spec workflow | `.specify/`, `.cursor/skills`, `specs/002-ai-joke-generator/` |

## Project structure

```text
src/app/                    # /, /generate, /dashboard, /learn, /learn/[step]
src/components/             # Header, footer, learn/*, providers, ui/*
src/lib/                    # joke-engine, joke-store, spec-artifacts
.specify/memory/            # constitution.md
specs/002-ai-joke-generator/  # spec.md, plan.md, tasks.md
specs/_archive/             # Retired QueueBeacon feature
```

## Constitution check

- Demo-safe auth/billing/AI: satisfied via mocks and local engine
- Specification-first: this plan implements `spec.md`
- Teach by example: `/learn/[step]` reads files via `readSpecArtifact()`
- No database in MVP: satisfied

## Validation

- `npm run build` succeeds
- Manual: generate joke → sign in → see history → open each `/learn/*` step
- Artifacts in UI match on-disk markdown