---
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.

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.