# Requirements — Wedding Newspaper Generator

## Intent Analysis

The user is building a wedding-newspaper generator: a tool to take authored
content — the stories, schedules, messages, and inside jokes of a wedding — and
render them as a genuine-feeling newspaper. The deep goal is not just "generate
HTML" but to produce a keepsake that reads, on real paper, like a newspaper
published the day of the wedding: classic broadsheet look, a proper masthead,
crosswords and comics, and a front-page cartoon that ties the occasion together.

The product must be fully local: the generator runs on the couple's laptop,
content is private, and nothing is published beyond the machine. The output is
a self-contained HTML page opened directly (`file://`) and printed to A4 from
the browser's own print dialog. Because a printed multi-page newspaper is the
central deliverable, layout fidelity on paper — clean automatic page breaks,
content flowing across sheets — is a first-class, non-negotiable requirement.

## Functional Requirements

### FR1 — Multi-page newspaper output (MUST)

The generator SHALL produce a newspaper that flows across multiple A4 sheets
with automatic page breaks when content exceeds one page; it MUST NOT be
limited to a single page.

- FR1.1 — When the total content exceeds one A4 sheet, the output MUST
  continue onto subsequent sheets with a clean break between pages.
- FR1.2 — Page breaks MUST occur at section or article boundaries where
  possible (never splitting a single article's body awkwardly mid-paragraph
  unless unavoidable).
- FR1.3 — Each printed page MUST be self-consistent: page numbers, running
  headers/footers, and masthead continuation render correctly across sheets.

### FR2 — Classic newspaper masthead (MUST)

- FR2.1 — The front page SHALL render a title (masthead) banner.
- FR2.2 — The masthead SHALL include a date line, an issue number, and a
  "Volume X" line.
- FR2.3 — The masthead SHALL be styled in the classic broadsheet manner
  (large serif title, rule lines above and below).

### FR3 — Article types (MUST)

The layout SHALL support all of the following content types, mapped from
markdown into newspaper sections:

- FR3.1 — Lead / front-page story (a large featured article on page one).
- FR3.2 — Interior news articles with headings and bylines.
- FR3.3 — Pull quotes, sidebars, and fact boxes (standalone callout styling,
  not just body paragraphs).
- FR3.4 — A "schedule" or "events" block (e.g. ceremony / reception
  timetable), rendered as a clearly formatted table.
- FR3.5 — A lighter section (messages / letters / well-wishes / memory
  corner) distinct in visual weight from hard news.

### FR4 — Crosswords and comics ("the funnies") (MUST)

- FR4.1 — The generator SHALL build crossword puzzles **from content the user
  provides** (grid + across/down clues derived from user-supplied words/theme
  words and clues), not from a fixed built-in set.
- FR4.2 — The generator SHALL support comic-strip blocks (one or more panels
  with art + dialogue), including beyond a single cartoon.
- FR4.3 — Crossword and comic blocks MUST remain printable and legible on A4.
- FR4.4 — The "fun" section is first-class: it may include other word puzzles
  (e.g. word search / "find-a-word") and other comics (e.g. Dilbert, Garfield,
  or a tasteful equivalent) so long as they are funny and print cleanly.

### FR5 — Front-page cartoon tied to the occasion (MUST)

- FR5.1 — The front page SHALL render an xkcd-style or genuine single-panel
  cartoon that relates to the wedding / the couple / the day.
- FR5.2 — The cartoon SHALL be generated with awareness of context: the
  couple, the occasion and the day's details inform its subject, so it feels
  like it belongs rather than a generic cartoon.
- FR5.3 — The cartoon SHALL be rendered entirely on-machine (see NFR3
  Local-only and NFR4 Zero-network); the final printed page never depends on a
  remote resource.
- FR5.4 — A genuine xkcd cartoon MAY be sourced from the real xkcd site
  (searched for one related to the occasion) as a generation-time input; if
  one is fetched, it SHALL be embedded locally so the delivered page remains
  self-contained and print-capable offline.

### FR6 — Photos and images (MUST)

- FR6.1 — Articles SHALL support embedded photos/images placed per article.
- FR6.2 — The layout SHALL auto-balance images into the column structure so
  they flow naturally with text.
- FR6.3 — Images SHALL support optional captions and byline/credit lines.

### FR7 — Content ingestion (MUST)

- FR7.1 — Content is authored as Markdown (and/or plain text) files and
  read by the generator.
- FR7.2 — The generator SHALL produce a single self-contained `newspaper.html` —
  the printed artifact — from the ingested content.
- FR7.3 — The generated page SHALL provide a live-load path (native file
  picker / drag-and-drop) so alternate content can be swapped in and rendered
  without regenerating (matches affirmed practice: user-granted reads only).
- FR7.4 — Photos are optional inputs: when photos are supplied, the layout
  SHALL embed them (per FR6); when none are supplied, the layout SHALL generate
  cleanly without photographs (never fabricate placeholder images).
- FR7.5 — Newspaper metadata (masthead title, couple names, date, issue
  number, volume) is dynamic and SHALL be supplied at generation time rather
  than hard-coded, so a new issue can be produced without editing the code.

### FR8 — Optional AI draft support (SHOULD)

- FR8.1 — The generator MAY call a local AI to draft newspaper copy (lead
  story, filler articles, pull quotes) before the final render.
- FR8.2 — AI-drafted copy MUST be authored into content exactly as if
  hand-written, then flow through the same layout pipeline.
- FR8.3 — The AI route MUST be local Ollama only; the granted model is
  `deepseek-v4-flash:cloud`. No content SHALL be sent to an external/cloud
  service.
- FR8.4 — AI generation SHALL run the whole first-pass newspaper, then STOP
  for per-article human review: the user SHALL be able to approve, request
  edits, or replace any single article's copy before the final render. This
  review is per-article; approved articles stay unchanged while others are
  revised and re-rendered.

## Non-Functional Requirements

- NFR1 (Printability) — The page MUST print cleanly to A4 from the browser's
  own print dialog, with no clipping and correct margins. (MUST)
- NFR2 (Layout integrity) — Print CSS MUST keep every section, article,
  image, and puzzle inside the sheet with no overflow, orphaned columns, or
  broken page breaks. (MUST)
- NFR3 (Local-only) — Everything must run purely from the local filesystem;
  the page MUST never be served or deployed beyond localhost. (MUST)
- NFR4 (Zero network) — The page SHALL make zero network requests (no CDN
  fonts, no remote `<script>`/`<style>`/assets), so it is fully functional
  offline from `file://`. Fonts, images, and any asset ship with the page.
  (MUST)
- NFR5 (Content read policy) — Content SHALL be read only through
  user-granted means (native file picker / drag-and-drop); the page SHALL NOT
  rely on `fetch()` of sibling local files (opaque-origin CORS blocks it in
  stock browsers). (MUST)
- NFR6 (Pure, dependency-free render) — The output SHALL be pure HTML5 + CSS
  + vanilla JS with no build step and no external dependencies. (MUST)
- NFR7 (Fidelity to markdown) — The markdown→HTML transform SHALL preserve
  content exactly (no mangled quotes, em-dashes, escaping, or dropped
  sections). (MUST)
- NFR8 (Classic aesthetic) — The visual theme SHALL be classic broadsheet:
  black ink on white/cream, serif headlines and body, and column rules.
  (SHOULD, from Q5=a)
- NFR9 (AI isolation) — Any AI generation SHALL be an optional, opt-in step
  that never runs when not requested, and SHALL keep all content local
  (Ollama). (MUST)

## Constraints

- C1 — The project runs on the wedding couple's local machine, never published.
- C2 — Node.js is available but the Python (3.14) + `uv` runtime is the
  affirmed primary path; the generator is a Python static generator.
- C3 — Output must be a self-contained static HTML file; no server process is
  required or desired at print time.
- C4 — Only local Ollama is permitted for AI; no external/cloud LLM API.
- C5 — A4 is the fixed print format.

## Assumptions

- A1 — The couple prefers print realism (classic broadsheet) over modern web
  styling for the printed keepsake.
- A2 — "Fluid" pagination (flow onto as many A4 pages as needed) is preferred
  over forcing a fixed page count (Q7=a).
- A3 — Photos will be supplied as local image files referenced from content;
  the generator embeds them (self-contained output).
- A4 — The xkcd-style cartoon is generated by the local AI with contextual
  awareness of the couple and day, then rendered as an SVG/embedded image.
- A5 — Crosswords are authored as structured puzzle data (grid + clues)
  provided in content, then laid out by the generator.
- A6 — A default visual identity (title, accent) can be supplied by the user
  but is not required for the generator to produce a valid first output.

## Out of Scope

- OS1 — Deploying or hosting the newspaper anywhere (web, static host,
  printer service).
- OS2 — Sending any content or generation to an external/cloud AI service.
- OS3 — Dynamic server-side rendering or a persistent runtime service.
- OS4 — A full WYSIWYG editor UI (content stays in markdown/text files).
- OS5 — Non-A4 print formats (US Letter, tabloid) in this iteration.

## Open Questions

- OQ1 (RESOLVED) — Crosswords and other "fun" puzzles are **built from user-provided
  content**; the fun section may include other comics that are funny, and the
  xkcd-style cartoon should be a genuine xkcd searched on the real site when
  possible.
- OQ2 (RESOLVED) — Photos are handled when supplied; if none are supplied,
  no photos are generated or fabricated.
- OQ3 (RESOLVED) — Newspaper masthead metadata (title, names, date, issue,
  volume) is dynamic and brought in at generation time.
- OQ4 (RESOLVED) — AI generation runs the whole first-pass newspaper, then
  provides a per-article human review mechanism (approve / request edits /
  replace any single article) before the final render.