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