# AGENT

## Scope & Purpose
- This AGENT file governs the `src/srs-technical-spec-documents/` tree, which houses the engineering master documents, requirements, and integration blueprints for AtlasOS – Calypso.
- Treat this directory as reference material for every backend/frontend change—its contents describe non-negotiable design rules, safety guardrails, phases, and architecture decisions.
- Updates to these files should reflect reality; if the implementation drifts, update the docs first and then the code (and vice versa) so each stays a faithful record.

## Source of Truth
- `CURSOR.md` is the single source of truth for AtlasOS – Calypso (see its header and `## 12. Final Authority` section). If two documents disagree, the guidance in `CURSOR.md` wins unless leadership explicitly overrides it.
- Always cross-reference `CURSOR.md` when adding or modifying requirements (`SRS-00…05`), component lists, or implementation phases. Cite the specific `CURSOR` section when you rely on it so reviewers understand the provenance.
- When creating new spec fragments, link back to the nearest `SRS-0X` doc and update the master `CURSOR` summary so the hierarchy stays aligned.

## Document Contributions
- Keep all files in Markdown (`.md`); avoid switching formats because pipelines expect Markdown rendering (PDF/HTML builds will be added later).
- Maintain the existing structure: title, short description, then numbered sections/headers with bolded directives or lists. Preserve Indonesian terminology when it carries intention that English translations might dilute (e.g., `infra`, `KPI` definitions). Provide English commentary where helpful but don’t remove localized emphasis without confirming intent.
- Maintain consistent naming: use `SRS-XX-Topic.md`, `component-list...`, `mhvtl-...` etc. Follow kebab-case with hyphen separators, lower‑case words, and no spaces.
- When spelling out commands or configuration paths, wrap them in backticks and use lowercase (e.g., `` `systemctl daemon-reload` ``) to keep them machine-readable.

## Writing Style Guidelines
- Use sentence case for section/titles (`## 1. Non-Negotiable Design Rules`). Avoid all-caps headings except for acronyms that are part of existing terminology (e.g., `MHVTL`).
- Keep paragraphs short (max 3 sentences) and bullet lists concise. A long paragraph should be split into numbered/bulleted statements so the rules are easy to scan.
- Favor active voice ("Calypso exports …"), imperative tone for rules ("Do X"), and consistent terminology for features (`Calypso`, ``Calypso API``, `SCST`, `MHVTL`).
- Annotate non-English terms inline (e.g., `audit (audit trail)`). Keep translations brief and in parentheses to avoid dilution.
- Preserve ASCII-only syntax for diagrams (use the existing ASCII boxes or Mermaid in future). Avoid using diagrams that require external tooling unless they are stored in Markdown code fences.

## References & Links
- When you mention a backend CLI or frontend script, point to the actual repo file (e.g., `backend/Makefile`, `frontend/package.json`). Anchor them with Markdown links for quick navigation: `backend/Makefile#L1-L46`.
- If you reference policy from other directories (e.g., `AGENTS.md`), link to the absolute path (e.g., `` `../../AGENTS.md` ``) so future agents know where to look.
- For environment/setup instructions, reuse the text from the root `AGENTS.md` and cite it rather than copying it verbatim. Adds context: "See `../AGENTS.md` for Go/React toolchain requirements.".

## Contributions & Review
- Every change passes through the root repo review process; mention in your pull request description which spec file you touched and why (`CURSOR change due to API update`, `SRS-02 clarifies tape mapping`).
- Keep `CURSOR.md` synchronized with the lower-level SRS docs. For example, when adding a new endpoint to `backend`, ensure Section 6 in `CURSOR` is updated alongside the detailed doc that mentions the endpoint.
- When editing for clarity, preserve any numbered lists or `(1)`, `(2)` markers; they often correspond to release gating checklists or DoD items.
- Don't reorder sections unless you add a new one; this avoids merge conflicts across branches that rely on a stable structure.

## Review Expectations
- Run a spellcheck in your head: these docs are read by executives and engineers alike. Avoid typos in commands and names.
- Mention any assumptions or pending decisions at the bottom of the document in a clearly marked `## Notes / Questions` section so reviewers can call them out.
- If you introduce new tooling or process, add a short note to `component-list-atlasos-calypso.md` describing how it impacts the appliance architecture.

## Safety & Guardrails
- Whenever you write about safety rules (Multi-initiator, destructive actions, audit), cross-check `CURSOR.md` Section 9 plus any `SRS-XX` section that overlaps. Do not weaken hard requirements unless there is explicit direction from the product owner.
- Mark any change that might conflict with deployment automation (`systemd`, `mhvtl`) with an obvious `> **Warning:**` block so maintainers know to check automation scripts.

## Automation & Tests
- There are no automated build/lint/test commands for these documents. Verification is manual proofreading and ensuring `git diff` shows clean Markdown changes.
- If you add diagrams or code snippets, keep them in fenced code blocks and annotate the language (e.g., `` ```bash ``) even if they live in Markdown files.

## Summary
- This directory documents foundational decisions. Keep `CURSOR.md` current, reference it whenever possible, and maintain the style/structure of the SRS documents.
- All new content should be purposeful, cite the relevant architecture rule, and follow the Markdown conventions described above.
