Mnemoverse Docs

Appearance

Architecture Documentation Standards ​

These standards keep our docs agent-friendly, link-stable, and easy to maintain.

1) Language and tone ​

  • English only
  • Short, specific sentences; avoid marketing language
  • Prefer active voice; use consistent terminology across sections

2) File, path, and slug rules ​

  • One topic per file; filename is the canonical slug
  • Use kebab-case for filenames and directories (e.g., experience-layer, context-assembler)
  • Section landing pages live at index.md or README.md inside a directory
  • Link using clean URLs (no .md, no /index): /architecture/orchestration/

3) Frontmatter (keep flat and predictable) ​

Recommended keys:

  • title: Short, human-facing title
  • description: One-line summary under 140 chars
  • lastmod: ISO date string (YYYY-MM-DD)
  • status: draft | alpha | beta | stable | deprecated
  • audience: humans,agents | developers | researchers
  • tags: comma-separated keywords
  • priority: 0.3–1.0 (for sitemap weighting, optional)

Example:

yaml
---
title: "ACS (Adaptive Context Scaling) Architecture Specification"
description: "Technical spec for ACS orchestrator."
lastmod: 2025-09-05
status: alpha
audience: humans,agents
tags: orchestration,acs
priority: 0.9
---

4) Links and references ​

  • Internal: absolute from /docs root, clean URLs (e.g., /architecture/evaluation/)
  • Avoid relative ../.. chains; they rot easily when moving files
  • Do not link to /README or /index; always target directory root
  • External links should include the canonical URL; avoid trackers or redirects

5) Code fences and media ​

  • Prefer txt for metrics and query snippets to avoid extra highlighters
  • Use mermaid sparingly; keep diagrams small and purposeful
  • All images live next to the doc or in a local image/ folder in the same section

6) Structure and ordering ​

  • Use order: in frontmatter to control sibling ordering when needed
  • Add small table of contents only for long (> ~100 lines) specs
  • Each section directory should have a landing page describing:
    • Scope and responsibilities
    • Interfaces and dependencies
    • Key data models or contracts
    • Links to deep dives and implementation guides

7) Drafts and change control ​

  • Mark early work with status: draft or alpha
  • For breaking changes in contracts, add an ADR or change note and update the Contracts section
  • Keep a brief changelog for orchestration and other fast-moving areas

8) Accessibility and privacy ​

  • No raw secrets or sensitive personal data in examples
  • Redact or synthesize data samples
  • Favor text over heavy images; include alt text if images are necessary

9) Quality gates before merge ​

  • npm run links:check-internal → zero broken internal links
  • npm run docs:build → passes without dead-link failures
  • Optional: npm run seo for sitemap refresh

10) Common pitfalls to avoid ​

  • Linking to /.../index or /.../README (use /.../)
  • Mixing relative and absolute link styles
  • Large, nested lists without context; prefer short sections with clear headings

If a change impacts navigation or slugs, add temporary redirects in .vitepress/config.mjs (rewrites) and remove them once links are updated across the site.