---
owner: gmikcon
status: active
last_reviewed: 2026-05-09
review_interval: 90d
confidence: high
source_of_truth: project-policy
---

# Documentation Rules

## Storage

- Markdown is used for human-readable documentation.
- YAML is used for structured inventory.
- JSON Schema is used to validate structured inventory.
- Git is the durable source of truth.

## Secrets

Never store raw secret values in this repository.

Do not store:

- passwords;
- API tokens;
- private keys;
- recovery codes;
- session cookies.

Store references to secret locations instead, such as password manager item names or future vault paths.

The validation API scans Markdown, YAML, JSON, and dotenv-style files for common raw secret assignments.
Use reference values such as `unknown`, `redacted`, `password manager`, `vault`, or `ref:...` when a field must describe where a secret lives.

## Review

Update `last_reviewed` only when the information has actually been checked.

Use `confidence: high` only for information confirmed from a reliable source, direct inspection, or owner confirmation.

Security-sensitive changes should use review mode once the documentation server supports it.

## Agent Changes

Agents should prefer structured inventory operations over raw file edits when possible.

Every important inventory record should link to a documentation page.

Every public traffic route should list its exposure and target services when known.

Inventory item `id` values must be unique within each inventory file.

Use the broadest durable inventory type that matches the fact:

- `hosts.yml` for operating-system environments and machines;
- `services.yml` for applications, daemons, reverse proxies, workers, and infrastructure services;
- `endpoints.yml` for URLs, APIs, management UIs, SSH ports, local ports, and other addressable access points;
- `integrations.yml` for dependencies and cross-entity relationships that do not belong to a single record;
- `projects.yml` for repositories, project documentation, deployment links, and project-to-infrastructure references.

Do not create a narrowly specialized inventory type until the same shape appears repeatedly and cannot be represented cleanly by existing broad types.

Run `GET /validate` before applying or committing documentation changes. A clean report means:

- inventory files pass JSON Schema validation;
- required Markdown frontmatter is present;
- inventory `docs` links point to existing files;
- inventory IDs are not duplicated;
- no obvious raw secrets were detected.

Use `GET /relationships` when an agent needs the current infrastructure graph. This endpoint is intentionally read-only and returns unresolved references separately from validation errors, so partially documented nodes such as future hosts, external VPS names, or route placeholders can be made visible without blocking incremental documentation work.

Use [service-documentation-template.md](service-documentation-template.md) when creating or normalizing service, application, smart-home, or project-service documentation.