feat: initialize Nocal terminal calendar

AGENTS.md

@@ -0,0 +1,82 @@
+# Nocal agent instructions
+
+These instructions apply to the entire repository.
+
+## Operating model
+
+Use a frontier-capability model as the lead agent. The lead owns product and
+technical judgment: it inspects the repository, defines the architecture,
+creates the implementation plan, decomposes work, assigns non-overlapping file
+ownership, reviews every delivered change, integrates the result, and performs
+the final verification.
+
+Delegate bounded coding tasks to cheaper/lower-cost agents whenever the
+orchestration environment supports model selection. Coding agents should
+implement clearly specified slices; they should not independently redefine the
+architecture or expand product scope. Reserve the frontier model's context for
+planning, difficult cross-cutting decisions, code review, debugging integration
+failures, security/data-loss analysis, and final validation.
+
+Delegation never transfers accountability. The lead must inspect the actual
+diffs and rerun relevant checks; an agent's claim that code compiles or tests
+pass is not sufficient evidence. Small, tightly coupled fixes may be completed
+directly by the lead when delegation would create more coordination cost than
+implementation value.
+
+## Delegation protocol
+
+Before dispatching implementation work, the lead must:
+
+1. Read this file and inspect the current workspace, including uncommitted work.
+2. State the intended behavior, interfaces, invariants, and failure semantics.
+3. Give each agent exclusive ownership of an explicit file or directory set.
+4. Identify shared API contracts up front and prevent concurrent edits to the
+   same files.
+5. Keep build files, integration, roadmap decisions, and final review under the
+   lead unless explicitly delegated.
+
+Each coding agent must:
+
+- stay inside its assigned scope and preserve unrelated user changes;
+- use C++20 and avoid new runtime dependencies unless the lead approves them;
+- use `apply_patch` for source edits;
+- add or update deterministic tests for its behavior;
+- compile with strict warnings and report the exact checks run;
+- document limitations, unhandled edge cases, and any shared-contract mismatch;
+- never mark a task complete based only on visual inspection.
+
+## Product and architecture constraints
+
+- Nocal is a local-first, keyboard-driven terminal calendar for Linux and
+  Hyprland.
+- The month grid remains the primary view and appointments remain navigable
+  inside day cells.
+- Styling must use the terminal's default background and semantic ANSI palette.
+  Do not introduce hard-coded RGB themes. `NO_COLOR` must remain usable.
+- Keep domain, storage, synchronization, and TUI concerns separated. Provider
+  APIs and iCalendar details must not leak into rendering code.
+- Treat calendar writes as data-loss-sensitive. Mutations need validation,
+  atomic persistence, rollback on failure, and tests for failure paths.
+- Keep terminal lifecycle code exception-safe: raw mode, cursor visibility, and
+  the alternate screen must always be restored.
+- Remote synchronization is out of scope until the local mutation and durable
+  cache boundaries are reliable.
+
+## Verification requirements
+
+The lead's final review for a change should be proportional to its risk and
+normally include:
+
+```sh
+nix-shell --run 'meson compile -C build'
+nix-shell --run 'meson test -C build --print-errorlogs'
+```
+
+Also run strict warning-as-error compilation for changed translation units.
+For storage, parsing, terminal lifecycle, or mutation work, run the Address and
+Undefined Behavior sanitizer build and exercise relevant failure paths. TUI
+changes require a live PTY smoke test covering interaction and terminal-state
+restoration.
+
+Do not report completion while required tests fail, while delegated changes are
+unreviewed, or while user data can be lost on an ordinary error path.