Substratum.cloud

Appearance

Docs Directory - AI Agent Instructions ​

Last Updated: 2026-06-09

This directory contains the technical specifications, schemas, and documentation for Substratum v1.0.

📝 Documentation Standards ​

  • Format: Use standard Markdown.
  • Linting: All markdown files must pass markdownlint. Run pnpm run lint:md from the project root before committing changes.
  • Tone: Keep explanations clear and concise. product-overview.md is plain-language for all audiences (no technical jargon). Other docs may be technical.
  • Formatting:
    • Use tables for feature comparisons.
    • Use JSON code blocks with $schema for schema definitions.
    • Do not use HTML tags in markdown unless strictly necessary.

🚀 Publishing (tngl.sh) ​

  • Dev: pnpm run docs:dev
  • Build only: pnpm run docs:build → output in site/
  • Deploy: pnpm run docs:deploy (commits site/) then git push origin main

Tangled Sites serves /site from main (see ADR 06). After adding ADRs or editing .vitepress/config.mts, run docs:deploy.

When adding architecture pages, update architecture/00-index.md, docs/.vitepress/config.mts sidebar, then deploy.

When adding operations runbooks, update operations/00-index.md, docs/.vitepress/config.mts sidebar, then deploy.

🔗 Key References ​

  • glossary.md: Canonical ubiquitous language (product, deployment, storage, mesh, deprecated terms). Update when introducing or renaming public vocabulary.
  • architecture/00-index.md: The codified architectural decisions (Modular Monolith, Ports & Adapters, Network Behavior).
  • product-overview.md: Plain-language product story for families and non-builders.
  • business-model.md: Public pricing philosophy, free vs paid identity paths, and implementation honesty.
  • technical-specification.md: The core architecture, phases, and high-level design.
  • passport-receipt-schema.md: The JSON schema for file metadata, provenance signatures, and ACLs.
  • operations/00-index.md: Production deployment, catalog vs blockstore capacity, and OAuth / PDS origin runbooks (with Mermaid diagrams).
  • .vitepress/config.mts: The VitePress configuration file. You MUST update the sidebar in this file when adding new documents.