# Repository Guidelines

## Project Structure and Module Organization
- python version is `python3.13`
- `generator.py` is the main CLI that builds a single `.ics` calendar file from a story JSON.
- `config.toml` holds schedule rules (start date/time, blocked weeks/dates, organizer info).
- `stories/` contains story inputs; each file includes a `meta` object and an `events` list.
- `stories/template.json` is a starter template for new stories.
- `fredagsbar_output/` stores generated `.ics` and preview `.html` files (local artifacts ignored via `.gitignore`).
- `requirements.txt` pins Python dependencies.

## Build, Test, and Development Commands
- `python -m venv .venv` and `source .venv/bin/activate` to create a local virtualenv.
- `pip install -r requirements.txt` installs dependencies.
- `python generator.py stories/object_87-B.json` generates a calendar file in `fredagsbar_output/`.
- `python generator.py stories/object_87-B.json --preview-html` also writes an HTML preview to `fredagsbar_output/`.
- Optional flags: `--config`, `--output-dir`, `--timezone`, `--duration-minutes`, `--no-color`.
- `python generator.py stories/<your_story>.json` runs the generator with another story file.

## Coding Style and Naming Conventions
- Use standard Python style: 4-space indentation, snake_case for functions and variables.
- Keep JSON keys consistent with existing stories (`meta.name`, `meta.theme_color`, `events[].title`, `events[].story`).
- For stable calendar updates, set `meta.id` and `events[].id` (or `events[].uid` to force a specific UID). Optionally set `config.toml` `uid_namespace` to change the deterministic UID namespace.
- The generator writes back `events[].uid` after a successful run and validates existing UID values for mismatches or duplicates.
- If a prior `fredagsbar_output/FULL_SERIES_<slug>.ics` exists, its UIDs are reused and injected into the story JSON.
- Name story files with descriptive, lowercase filenames using underscores or hyphens (for example: `stories/new_story.json`).
- Output filenames are derived from `meta.name` and written as `fredagsbar_output/FULL_SERIES_<slug>.ics`.

## Testing Guidelines
- Automated tests live in `tests/`. Run `python -m unittest discover`.
- Coverage includes date skipping, UID mapping, HTML injection, and preview rendering.
- When altering scheduling logic, confirm blocked weeks/dates and holiday skipping behavior from `config.toml`.

## Commit and Pull Request Guidelines
- Use short, imperative commit subjects consistent with history (for example: "update repo path").
- Do not commit generated `.ics` files; `fredagsbar_output/` is treated as a local artifact directory.
- In PRs, describe the story or scheduling changes, and mention the output filename you generated for verification.
- If you modify `config.toml`, call out changes to dates, blocked weeks, or organizer settings in the PR description.

## Configuration and Content Tips
- Stories can include HTML in `events[].story`; the generator converts HTML to plain text for descriptions and renders the HTML in previews.
- Keep `repo_url` in `config.toml` accurate, as it is embedded in the event description.
- `blocked_dates` supports both `YYYY-MM-DD` and `MM-DD` entries.
- Optional `repo_url`, `organizer_email`, and `uid_namespace` must be strings when set.
- HTML previews include a skipped-dates section when blocked dates/weeks are encountered.