add sources

src/srs-technical-spec-documents/AGENT.md

@@ -0,0 +1,52 @@
+# 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.