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.

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.

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.

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.

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.

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.