Skip to content

Documentation standards

Every technical or domain page should include, where applicable:

  1. Purpose — one paragraph.
  2. Boundaries — in scope / out of scope.
  3. Key components — paths in the monorepo.
  4. Data / API contracts — tables, endpoints, ingest kinds.
  5. Flow — mermaid diagram.
  6. Failure modes / debug — what to check when it breaks.
  7. Related links — cross-references within Internal Docs.

Language

Section titled “Language”
  • Internal Docs: English.
  • Host Agent build spec: Polish in hostzu/spec.md (implementation blueprint).

Security

Section titled “Security”
  • OK: service URLs, Azure subscription/RG names in runbooks.
  • Never: secrets, tokens, connection strings — reference Key Vault instead.
Section titled “Sidebar”

Add new pages in Internal-Documentation/astro.config.mjs under the appropriate section.

Canon

Section titled “Canon”

Internal Docs are the only canonical knowledge base. Do not duplicate system truth in docs/ or Edge/docs/.

When you find gaps, add follow-ups to root TODO.md.