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 jettoptx-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 MOA_NODES in lib/moa-registry.ts:

{
  id: "your-page-id",
  label: "Short Name",
  group: "section-key",
  agt: "COG",
  radius: 15,
  href: "/docs/section/page",
  description: "One sentence describing this page",
  subLabels: ["Tag 1", "Tag 2", "Tag 3"],
  emo: 20, env: 25, cog: 55
}

PATH_TO_NODE, PAGE_AGT, and mobile SUB_PAGES are derived automatically from MOA_NODES.

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

Add edges to MOA_EDGES in lib/moa-registry.ts:

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

Every new page needs at least 2 edges: one to its section parent and one cross-section link.

5. Mobile Sidebar

MOBILE_SUB_PAGES is derived from MOA_NODES by group. When adding a new top-level section, update NAV_SECTIONS in components/mobile-sidebar.tsx.

6. PATH_TO_NODE

No manual step — augment-space-btn.tsx and mdx-link.tsx import PATH_TO_NODE from lib/moa-registry.ts.

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 jettoptx-docs as a Template

jettoptx-docs is designed to be forked and customized:

1. Fork — git clone https://github.com/jettoptx/jettoptx-docs.git my-docs
2. Replace — Swap MDX files in content/docs/ with your own
3. Customize graph — Edit MOA_NODES and MOA_EDGES in lib/moa-registry.ts
4. Update nav — Modify content/docs/meta.json and lib/source.ts
5. Deploy — Push to GitHub, connect to Vercel, done

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 MOA_NODES in lib/moa-registry.ts
• Added edges to MOA_EDGES in lib/moa-registry.ts (min 2)
• (If new section) Updated content/docs/meta.json and NAV_SECTIONS in mobile-sidebar.tsx
• Updated both changelog surfaces (footer block in components/footer.tsx + long-form content/docs/reference/changelog.mdx) and bumped Last updated: <date> — v<version>