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.