DOCS Rules

DOCS Rules

This page teaches agents and developers how to correctly add, edit, and classify pages in the OPTX documentation system. Follow these rules to keep the MOA knowledge graph, AGT tensor classification, and navigation consistent.

If you're using joe-docs as a template for your own project, this is your walkthrough for understanding the system and customizing it.

For Agents & LLMs

When you add or edit a documentation page, you must complete every step below. Skipping any step breaks the knowledge graph or navigation.

1. MDX Page Structure

Every doc page is an .mdx file in content/docs/<section>/. Each file must have frontmatter:

---
title: Your Page Title
description: One-line summary of what this page covers
icon: Rocket  # Lucide icon name for sidebar
---

Fumadocs auto-discovers pages from the file tree — no manual route config needed for sub-pages.

2. AGT Tensor Classification

Every page must be classified with a primary AGT (Agentive Gaze Tensor):

Assign emo, env, and cog scores that sum to 100. The highest score determines the primary tensor.

3. Add MOA Graph Node

Add a node to NODES_DATA in components/moa-visual.tsx:

{
  id: "your-page-id",        // kebab-case, unique
  label: "Short Name",       // display label on graph
  group: "section-key",      // matches GROUP_LABELS keys
  agt: "COG",                // primary tensor
  radius: 15,                // 11-22, larger = more important
  href: "/docs/section/page",
  description: "One sentence describing this page",
  subLabels: ["Tag 1", "Tag 2", "Tag 3"],
  emo: 20, env: 25, cog: 55  // must sum to 100
}

4. Add MOA Graph Edges (MOC — Map of Context)

Add edges to EDGES in components/moa-visual.tsx for every meaningful cross-reference:

{ source: "your-page-id", target: "related-page-id" },
{ source: "parent-section-id", target: "your-page-id" },

Every new page needs at least 2 edges: one to its section parent and one cross-section link. This is the MOC (Map of Context) — it defines how knowledge connects across the documentation.

5. Register in Mobile Sidebar

Add an entry to SUB_PAGES in components/mobile-sidebar.tsx under the parent section key:

{ label: "Your Page Title", href: "/docs/section/page", agt: "COG" },

6. Add PATH_TO_NODE Mapping

Add a mapping in PATH_TO_NODE in components/augment-space-btn.tsx:

"/docs/section/page": "your-page-id",

7. Navigation Ordering

Sub-pages are auto-discovered by Fumadocs. If adding a new top-level section, add its folder name to content/docs/meta.json:

{
  "pages": ["dojo", "getting-started", ..., "your-section"]
}

8. Style & Naming

• Fonts: Orbitron (--font-orbitron) for headings/labels, Geist Mono (--font-geist-mono) for body/code
• Colors: var(--color-orange-500) for OPTX-orange accents — never hardcode rgb(255, 105, 0). The var resolves to neon #FF6900 in dark mode and burnt brick rgb(220, 78, 31) in light mode. AGT tensor colors are still hardcoded by design.
• Icons: Use Lucide icon names in frontmatter
• Descriptions: One sentence per concept, keep it concise

9. Changelog Currency (NON-NEGOTIABLE)

Every shipped change MUST be reflected in BOTH changelog surfaces in the same session. Applies to LLMs, VLMs, and human contributors equally — no exceptions.

The two surfaces:

1. Footer changelog block — the <details><summary>Changelog</summary> <li> entries in components/footer.tsx. Also bump the "Last updated: <date> — v<version>" line one level up.
2. Long-form page — content/docs/reference/changelog.mdx, organized into ### Added, ### Changed, ### Security, ### Process subsections.

Either land the changelog update in the same commit as the work, or as an immediate follow-up commit before the session ends. Don't leave the visible changelog stale relative to the deployed app.

Versioning:

• Within the same calendar day, extend the most recent version entry with new bullets.
• Bump (e.g. v2.0.2 → v2.0.3) when crossing into a new day OR shipping a clearly distinct release.

For Human Developers

Adding a Page

1. Create an .mdx file in content/docs/<section>/
2. Add frontmatter: title, description, icon
3. Write your content in Markdown (JSX components supported)

Classify Your Page

Pick the dominant cognitive dimension:

• COG — Technical, analytical, requires reasoning
• EMO — About identity, social interaction, agent personality
• ENV — Infrastructure, networks, spatial topology

Register the Page

Update 3 files after creating content:

Always Update the Changelog (Same Session)

Every shipped change lands in both changelog surfaces — same commit or immediate follow-up. The two places:

1. components/footer.tsx — the footer changelog block + the Last updated: <date> — v<version> line
2. content/docs/reference/changelog.mdx — the long-form page

Within a calendar day, extend the most recent version entry. Bump the version when crossing days or shipping a distinct release. No orphaned releases.

Using joe-docs as a Template

joe-docs is designed to be forked and customized:

1. Fork — git clone https://github.com/jettoptx/joe-docs.git my-docs
2. Replace — Swap MDX files in content/docs/ with your own
3. Customize graph — Edit MOA node data in components/moa-visual.tsx
4. Update nav — Modify lib/source.ts for your structure
5. Deploy — Push to GitHub, connect to Vercel, done

The AGT tensor system, MOA knowledge graph, mobile sidebar, and augment space all adapt to your content automatically.

Checklist

When adding a new page, use this checklist:

• Created .mdx file with frontmatter (title, description, icon)
• Chose primary AGT tensor (COG/EMO/ENV)
• Added node to NODES_DATA in moa-visual.tsx
• Added edges to EDGES in moa-visual.tsx (min 2)
• Added entry to SUB_PAGES in mobile-sidebar.tsx
• Added path mapping to PATH_TO_NODE in augment-space-btn.tsx
• (If new section) Updated content/docs/meta.json
• Updated both changelog surfaces (footer block in components/footer.tsx + long-form content/docs/reference/changelog.mdx) and bumped Last updated: <date> — v<version>