Project overview

This file is the canonical guardrails + pointers for Codex work in this repo.

Project overview

• docs/overview.md
• README.md (end-user docs for release v2.0; may lag behind dev)

Current status

• docs/status.md

Ongoing tasks

• docs/todo.md
• TODO

Setup

• docs/setup.md

Architecture

• docs/architecture.md

Design contracts (immutable)

• docs/design/filtering-contract.md
• docs/design/config-flow-contract.md
• docs/design/calendar-contract.md
• docs/design/sensor-contract.md

Context for Codex

• docs/context.md
• docs/decisions.md
• test/fixtures/usecases.json (UC catalog)

Legacy references

• docs/resume_prompt.txt (legacy backup)
• docs/design/filtering-design-checkpoint.md (legacy backup)
• docs/design/filtering-config-flow-design.md (legacy backup)
• docs/vibe/context.md (legacy, empty)

Project file structure (in-file)

• custom_components/skolmat/: Home Assistant integration code.
• custom_components/skolmat/processors/: optional per-source normalizers.
• skolmat-card/: Lovelace card submodule.
• docs/: working docs and design contracts.
• test/: fixtures and tests (including UC catalog).

Devcontainer model (in-file)

• .devcontainer/devcontainer.json uses image hass_dev_image_2025.12.2.
• Post-create runs container setup-project -> .devcontainer/setup-project.
• Mounts skolmat-card/ into HA config www/.
• Bootstraps HA .storage from .devcontainer/ha_config_bootstrap/.storage.
• Ports: 8123 (HA) and 5678 (debugpy).

Generic guardrails (in-file)

• Do not modify design contracts unless explicitly requested.
• Treat test/fixtures/usecases.json as ground truth. All implemented logic should be represented in this file. Suggest updates when neccesary.
• Don’t refactor entire architecture without approval.
• Never refactor code outside of the currently discussed scope.
• Only run code generation related to current file / feature.
• Prefer small, reviewable changes; avoid sweeping reformatting.
• Update or add tests when behavior changes; call out gaps explicitly if not possible. Suggest additions/updates to test/fixtures/usecases.json as needed.
• When requirements are unclear, pause and ask one question at a time before coding.
• Keep dev docs in docs/ aligned with actual behavior; do not update end-user docs (README.md) unless requested.
• Avoid editing legacy backups unless explicitly asked.
• Use UTF-8 when Swedish terms or data require it; do not force ASCII where it harms clarity.
• Log important decisions in docs/decisions.md without waiting for confirmation.