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.

Discovery scans should first be recorded under 90-maintenance/discovery-observations/ unless the entity is already confirmed as infrastructure-relevant. Household, mobile, TV, and other dynamic devices should normally remain observations instead of canonical inventory records.

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 when creating or normalizing service, application, smart-home, or project-service documentation.