Documentation Metadata Standard

This document defines the standard YAML frontmatter schema for all VoiceAssist documentation. Following this standard ensures consistent metadata across docs and enables machine-readable indexing for AI agents and search systems.

Schema Definition

Every markdown document should include a YAML frontmatter block at the top:

---
title: "Document Title"
slug: "category/document-name"
summary: "One-line description of what this document covers."
status: "stable"
stability: "production"
owner: "backend"
lastUpdated: "2025-12-04"
audience: ["human", "ai-agents", "backend"]
tags: ["tag1", "tag2"]
category: "reference"
relatedServices: ["api-gateway", "web-app"]
version: "1.0.0"
ai_summary: >-
  A 2-3 sentence summary optimized for AI context loading. Include key facts,
  purpose, and cross-references to related docs when useful.
---

Field Definitions

Required Fields

Recommended Fields

Optional Fields

AI-Specific Fields

These fields optimize documentation for AI agent consumption:

ai_summary Guidelines:

• Length: 2-3 sentences, technical and concise
• Content: Focus on what the doc covers, key facts, and when to use it
• Style: Direct statements, no marketing language
• Cross-references: Mention related docs when useful
• Requirement: Strongly recommended when audience includes ai-agents

Example ai_summary:

ai_summary: >-
  Defines the WebSocket protocol for voice streaming including message types,
  connection lifecycle, and error handling. Key endpoints: /ws/voice for STT/TTS,
  /ws/thinker-talker for real-time AI responses. See VOICE_MODE_PIPELINE.md for
  full voice architecture.

component Guidelines:

The component field identifies the logical system or component that a document primarily describes. This enables AI agents to pivot between documentation and code.

• Format: <layer>/<name> (e.g., backend/api-gateway, frontend/web-app)
• Purpose: Links docs to code for cross-referencing via /agent/doc-code-map.json
• Requirement: Strongly recommended for architecture, voice, admin, api, and security/infra docs

Common component values:

relatedPaths Guidelines:

The relatedPaths field lists repo-relative paths to code files directly related to the document. This creates a bidirectional mapping between docs and code.

• Format: Array of POSIX-style paths relative to monorepo root
• Purpose: Enables AI agents to find implementation files from docs, and docs from code
• Requirement: Strongly recommended when audience includes ai-agents and category is one of: architecture, voice, admin, api, security, infra

Example with code linkage:

---
title: Voice Mode Pipeline Architecture
slug: voice/pipeline-architecture
status: stable
owner: backend
lastUpdated: "2025-12-04"
audience: ["human", "ai-agents", "backend"]
category: voice
component: "backend/api-gateway"
relatedPaths:
  - "services/api-gateway/app/api/voice.py"
  - "services/api-gateway/app/services/voice_pipeline.py"
  - "apps/web-app/src/components/voice/VoiceModePanel.tsx"
ai_summary: >-
  Describes the end-to-end voice pipeline from audio capture to TTS response.
  Key files: voice.py (API routes), voice_pipeline.py (orchestration).
---

Validation notes:

• Paths should match entries in /agent/repo-index.json or /agent/repo/manifest.json
• Missing or invalid paths will be flagged in /agent/doc-code-map.json under meta.missing_paths

Allowed Values

status

stability

owner

audience

Note: Use ai-agents (not agent) as the canonical value for AI readers. Legacy values agent and ai-agent are accepted for backwards compatibility but should be updated to ai-agents in new docs.

category

Examples

Architecture Document

---
title: Unified Architecture Documentation
slug: architecture/unified
summary: Complete system architecture covering all components, data flows, and integration points.
status: stable
stability: production
owner: mixed
lastUpdated: "2025-11-27"
audience: ["human", "ai-agents", "backend", "frontend", "devops"]
tags: ["architecture", "system-design", "overview"]
category: architecture
relatedServices: ["api-gateway", "web-app", "admin-panel"]
component: "backend/api-gateway"
relatedPaths:
  - "services/api-gateway/app/main.py"
  - "services/api-gateway/app/config.py"
  - "apps/web-app/src/app/layout.tsx"
version: "2.0.0"
ai_summary: >-
  System-wide architecture overview covering API Gateway, web apps, and data flows.
  Key entry points: main.py (backend), layout.tsx (frontend).
---

API Reference Document

---
title: REST API Reference
slug: api-reference/rest-api
summary: Complete REST API documentation with request/response examples.
status: stable
stability: production
owner: backend
lastUpdated: "2025-11-27"
audience: ["human", "agent", "backend", "frontend"]
tags: ["api", "rest", "reference", "endpoints"]
relatedServices: ["api-gateway"]
version: "2.0.0"
---

Operational Runbook

---
title: Incident Response Runbook
slug: operations/runbooks/incident-response
summary: Step-by-step procedures for handling production incidents.
status: stable
stability: production
owner: sre
lastUpdated: "2025-11-27"
audience: ["human", "devops", "admin"]
tags: ["operations", "runbook", "incident", "on-call"]
relatedServices: ["api-gateway", "monitoring"]
version: "1.0.0"
---

Deprecated Document

---
title: Legacy Server Documentation
slug: server/legacy
summary: Documentation for the deprecated server/ directory.
status: deprecated
stability: legacy
owner: backend
lastUpdated: "2025-11-27"
audience: ["human", "agent"]
tags: ["legacy", "deprecated"]
relatedServices: []
version: "1.0.0"
deprecated: true
replacedBy: "architecture/backend"
---

Migration Guide

When updating existing documents:

1. Rename fields:

   • last_updated → lastUpdated
   • description → summary

2. Map old status values:

   • production → status: stable, stability: production
   • in-development → status: draft, stability: beta
   • deprecated → status: deprecated, stability: legacy

3. Add missing required fields:

   • Always add slug (derive from file path)
   • Always add status and lastUpdated

4. Add recommended fields:

   • Add owner based on content area
   • Add audience (most docs should include ["human", "agent"])
   • Add relevant tags

Validation

The docs-site validates frontmatter at build time. Invalid or missing required fields will generate warnings. Use the validation scripts:

cd apps/docs-site

# Validate frontmatter metadata
pnpm validate:metadata

# Run all validation checks
pnpm validate:all

What validate:metadata checks:

• Presence of required fields (title, slug, status, lastUpdated)
• Valid enum values for status, stability, owner, category
• Valid values in audience array (including ai-agents)
• ISO date format for lastUpdated
• Array types for audience, tags, relatedServices

AI-specific validation:

• Documents with audience: ["ai-agents"] should have an ai_summary field
• Missing ai_summary on AI-targeted docs generates a warning

Version History