Skip to content

Internal docs naming convention

Date: 2026-08-23
Status: Approved standard for Last 1 Enterprises internal wiki (internal-docs.last1.enterprises).

Purpose

One greppable pattern across aggregated product docs so operators and agents can:

  • Find authoritative specs, plans, and runbooks quickly
  • Distinguish canonical vs historical vs deprecated material
  • Enforce consistent frontmatter in CI on every PR

Precedent: Bitwarden naming convention in lastvet-gates.

Filename patterns by doc type

Doc type Pattern Examples
Specification <ENTITY>_<TOPIC>_SPEC.md MERIDIAN_EVAL_SPEC.md, DUAL_GRANT_SPEC.md
Plan <ENTITY>_<TOPIC>_PLAN.md RLS_BATCH2_PLAN.md, AWS_MIGRATION_ASSESSMENT.md
Runbook <TOPIC>_RUNBOOK.md VA_PRODUCTION_CUTOVER_RUNBOOK.md
Security posture SECURITY_POSTURE_<AREA>.md SECURITY_POSTURE_DATABASE_ACCESS.md
Session state SESSION_STATE_<YYYY-MM-DD>.md SESSION_STATE_2026-07-16.md
E2E run log E2E_RUN_LOG_<YYYY-MM-DD>_<DESCRIPTOR>.md E2E_RUN_LOG_2026-07-15.md
Gate doc GATE_<N>_<PURPOSE>.md GATE_0_KICKOFF.md, GATE_0_5_STATUS.md
Decision record DECISION_<YYYY-MM-DD>_<TOPIC>.md DECISION_2026-08-10_R940_CUTOVER.md
Architecture <ENTITY>_ARCHITECTURE_<VERSION>.md SOVEREIGN_V2_ARCHITECTURE.md
Discovery <ENTITY>_<TOPIC>_DISCOVERY.md SOVEREIGN_V2_SESSION1_DISCOVERY.md
Integration INTEGRATION_<A>_<B>.md or <PRODUCT>_INTEGRATION.md LAST1_ID_INTEGRATION.md

Use SCREAMING_SNAKE_CASE for filenames. Date segments use ISO YYYY-MM-DD (no time in filename).

Directory structure (aggregated wiki)

Synced content preserves source-repo tree under entity prefixes:

content/entities/<entity>/
  gates/          # specifications, plans, gate docs (LastVet gates repo)
  api/            # API-specific docs
  web/            # web/marketing/legal sync
  ios/            # iOS sync
  provider/       # provider portal sync
  security/       # posture docs, audits (logical; may live under gates/docs/security/)
  deployment/     # runbooks, topology
  architecture/   # architecture docs
  decisions/      # decision records
  sessions/       # session state (historical)

Hand-crafted wiki pages (landing pages, governance) live outside sync prefixes.

Deprecated docs move to content/archive/<entity>/ preserving relative path.

Frontmatter schema (mandatory)

Every markdown file under content/ must start with:

---
title: Human-readable title
entity: lastvet | meridian | sovereign | angel | onset | last1-id | last1org | horizon | realoutcomes | radiocheck | last1-app | shared
status: canonical | historical | deprecated | draft
owner: ryan | robert | matt | claude-cursor | claude-anthropic | shared
last_updated: YYYY-MM-DD
audience: internal | external | both
tags: [list, of, tags]
supersedes: null
superseded_by: null
external_slug: null
---

Optional fields may be a single path string or a list of paths for supersedes.

Status definitions

Status Meaning
canonical Currently authoritative; kept up to date
historical Factually accurate record of past state; audit trail
deprecated Superseded; kept for link continuity only
draft In progress; not yet authoritative

Audience

Value Meaning
internal Staff and approved partners only (default)
external Intended for public export (docs.last.vet, Phase 4)
both Canonical internal copy may be exported

If audience is external or both, external_slug is required (URL slug on public docs).

Go-forward rules

  1. Every new doc gets full frontmatter at creation time (no exceptions).
  2. Filename follows the patterns above.
  3. Place files in the correct entity directory.
  4. Cross-wiki links use paths from the wiki root: /entities/<entity>/... (preferred) or valid relative paths within the same entity tree.
  5. When superseding a doc: set old doc status: deprecated, superseded_by: <path>, and new doc supersedes: <path>.

CI runs scripts/validate-frontmatter.py on every PR and deploy.

Anti-patterns (reject in review)

  • Docs without frontmatter
  • Docs in the wrong entity folder
  • Ambiguous filenames (NOTES.md, TEMP.md, README-old.md without context)
  • Deleting deprecated docs without archival move to content/archive/
  • Session or run logs without YYYY-MM-DD in the filename
  • Using audience: engineering (legacy; use internal)

grep cheatsheet

# Canonical security posture docs
rg -l '^status: canonical' content/entities/lastvet | rg SECURITY_POSTURE

# Historical gate run logs
rg --files content/entities/lastvet | rg 'E2E_RUN_LOG_'

# Deprecated AWS lane (should be under archive/)
rg -l '^status: deprecated' content/archive/lastvet