# 📂 {{FOLDER_NAME}}
 
A navigation‑first index for this section of the TriadicFrameworks canon.  
If you're new to this folder, begin with the **Start Here** track below.
 
---
 
## 🚦 Start Here
A gentle entry point for newcomers.
 
- 📘 **Overview** — High‑level introduction to this folder’s purpose.  
- 🧭 **Key Concepts** — The essential ideas you should know before exploring further.  
- 🧩 **First Example / First Steps** — A simple, concrete starting point.
 
---
 
## 🗂️ Contents
 
- 📄 **{{file1.md}}** — Short description of what this file provides.  
- 📄 **{{file2.md}}** — Short description.  
- 📁 **{{subfolder}}/** — Short description of what’s inside.  
- 📁 **{{subfolder}}/** — Short description.
 
(Add or remove items as needed.)
 
---
 
## 🧭 Notes
 
- This README is **navigation‑first**.  
- Narrative, context, and conceptual framing live in this folder’s `ABOUT.md`.  
- All links point to canonical Markdown files — no duplication, no drift.

# 🧩 About This Folder
 
This section of the TriadicFrameworks canon focuses on **{{folder theme}}** — its structure, purpose, and role within the broader RTT ecosystem.
 
## 🌱 What Lives Here
 
This folder contains:
 
- **Conceptual framing** for {{folder theme}}  
- **Core definitions and invariants**  
- **Examples or simulations** that illustrate the structure  
- **Reference materials** for students and practitioners  
 
Everything here is designed to be **clear, minimal, and reusable**.
 
## 🔍 Why This Matters
 
{{Explain why this domain or component is important.  
How it connects to RTT.  
What it helps readers notice or understand.}}
 
## 🧭 How to Use This Folder
 
- Start with the **README.md** for navigation.  
- Use this `ABOUT.md` when you want context, intuition, or conceptual grounding.  
- Dive into examples or simulations once you’re comfortable with the basics.  
 
## 🪶 Stewardship Note
 
This folder is part of a **completed structural substrate**.  
Future work happens through **instantiation, validation, or extension**, not foundational revision.

<div style="text-align:center; margin-top:4rem;">
 
  <!-- Search Box -->
  <input 
    type="text" 
    id="tf-search" 
    placeholder="Search TriadicFrameworks…" 
    style="width:60%; padding:1rem; font-size:1.2rem; border-radius:8px; border:1px solid #ccc;"
  />
 
  <!-- Search Mode Toggle -->
  <div style="margin-top:0.5rem; font-size:0.9rem; color:#666;">
    <label>
      <input type="checkbox" id="tf-search-toggle" />
      Search Everything (repo + papers + Zenodo)
    </label>
  </div>
 
  <!-- Theme Image -->
  <div style="margin-top:3rem;">
    <img 
      id="tf-theme-image" 
      src="https://raw.githubusercontent.com/umaywant2/TriadicFrameworks/main/docs/corpus/theme/default.png" 
      alt="RTT Theme" 
      style="max-width:60%; border-radius:8px;"
    />
  </div>
 
  <!-- Quiet Links -->
  <div style="margin-top:3rem; font-size:1rem; color:#777;">
    <a href="/docs/ABOUT.md">About</a> •
    <a href="/docs/README.md">Docs</a> •
    <a href="/papers/">Papers</a> •
    <a href="https://github.com/umaywant2/TriadicFrameworks">Repo</a> •
    <a href="https://zenodo.org/communities/triadicframeworks/">Zenodo</a>
  </div>
 
</div>

SEARCH BOX BEHAVIOR SPEC — TRIADICFRAMEWORKS LANDING PAGE
 
1. DEFAULT MODE: REPO SEARCH
   - Searches only the TriadicFrameworks GitHub repository.
   - Matches file names, headings, and content.
   - Returns results grouped by:
       • docs/
       • domains/
       • simulations/
       • examples/
       • tools/
       • papers/ (local copies only)
 
2. TOGGLE: “SEARCH EVERYTHING”
   - When enabled, expands search to:
       • GitHub repo
       • triadicframeworks.org/papers
       • Zenodo community
   - Results are grouped by source.
   - Repo results always appear first.
 
3. RESULT FORMAT
   - Title
   - Short snippet (first matching line)
   - Source (repo, papers, Zenodo)
   - Direct link to canonical Markdown or paper
 
4. NO AI INTERPRETATION
   - Search is literal, not semantic.
   - No rewriting, summarizing, or guessing.
   - This keeps results predictable and stable.
 
5. OPTIONAL BOT‑LIKE COMMANDS (FUTURE)
   - /diagrams
   - /paradox
   - /regimes
   - /sim {{name}}
   - /primer
   (Not required now, but the architecture supports it.)
 
6. PRIVACY & SIMPLICITY
   - No tracking.
   - No personalization.
   - No cookies.
   - No analytics.
   - Pure functional search.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>{{FOLDER_NAME}} | TriadicFrameworks</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      margin: 2rem auto;
      max-width: 900px;
      line-height: 1.6;
      color: #222;
    }
    nav {
      text-align: right;
      margin-bottom: 2rem;
      font-size: 0.9rem;
    }
    nav a {
      color: #666;
      margin-left: 1rem;
      text-decoration: none;
    }
    #content {
      margin-top: 2rem;
    }
  </style>
</head>
 
<body>
 
  <!-- Quiet Navigation -->
  <nav>
    <a href="/index.html">Home</a>
    <a href="/docs/ABOUT.md">About</a>
    <a href="/docs/README.md">Docs</a>
    <a href="/papers/">Papers</a>
  </nav>
 
  <!-- Markdown Content -->
  <div id="content">
    <!-- Your static site generator will inject README.md here -->
  </div>
 
</body>
</html>

<script>
  const images = [
    "theme/rtt-diagram-1.png",
    "theme/rtt-diagram-2.png",
    "theme/rtt-diagram-3.png",
    "theme/rtt-diagram-4.png"
  ];
 
  const img = document.getElementById("tf-theme-image");
 
  function rotateImage() {
    const next = Math.floor(Math.random() * images.length);
    img.src = images[next];
  }
 
  // Rotate every 12 hours (or whatever interval you prefer)
  rotateImage();
  setInterval(rotateImage, 12 * 60 * 60 * 1000);
</script>

<div id="tf-search-results" style="margin-top:2rem;">
 
  <!-- Example result block -->
  <div class="tf-result" style="margin-bottom:1.5rem;">
    <div style="font-size:1.1rem; font-weight:600;">
      {{Result Title}}
    </div>
 
    <div style="font-size:0.9rem; color:#555; margin:0.3rem 0;">
      {{Snippet or first matching line}}
    </div>
 
    <div style="font-size:0.8rem; color:#888;">
      Source: {{repo | papers | zenodo}}
    </div>
 
    <a href="{{canonical link}}" style="font-size:0.9rem; color:#0066cc;">
      Open →
    </a>
  </div>
 
</div>

# 🧭 TriadicFrameworks Navigation Philosophy
 
TriadicFrameworks uses a **three‑layer navigation model** designed for clarity, stability, and zero duplication.
 
---
 
## 1. Landing Page — Search‑First
 
The root website presents a minimal, search‑first interface:
 
- Large search box  
- Optional rotating theme image  
- Quiet corner links  
- No narrative  
- No duplication  
 
This surface is optimized for **returning users** and **fast access**.
 
---
 
## 2. ABOUT.md — Narrative + Curiosity
 
Each major folder includes an `ABOUT.md` file containing:
 
- Conceptual framing  
- Purpose and context  
- Why the material matters  
- How it fits into RTT  
 
This layer is for **newcomers**, educators, and curious readers.
 
---
 
## 3. README.md — Navigation‑First
 
Each folder’s `README.md` is:
 
- structural  
- minimal  
- emoji‑enhanced  
- link‑only  
- non‑narrative  
 
It includes:
 
- a **Start Here** track  
- short descriptions  
- canonical links to Markdown files  
- subfolder navigation  
 
This layer is for **students, practitioners, and researchers**.
 
---
 
## 4. HTML Wrappers — Thin, Stable, Non‑Authoritative
 
Folder‑level `index.html` files:
 
- wrap the README  
- provide quiet navigation  
- never duplicate content  
- never override Markdown  
 
HTML is a **presentation layer**, not a content layer.
 
---
 
## 5. Canonical Source of Truth
 
All authoritative content lives in:
 
- Markdown files  
- the GitHub repository  
- the Zenodo archive (for papers and records)  
 
The website is a **rendered view**, not a separate documentation system.
 
---
 
## 6. Stewardship Principles
 
- Minimal surfaces  
- No drift  
- No duplication  
- Clear separation of narrative and navigation  
- Canonical Markdown as the backbone  
- HTML as a quiet wrapper  
- Search as the primary interface  
 
This philosophy keeps TriadicFrameworks **legible**, **stable**, and **future‑proof**.

:root {
  --tf-bg: #ffffff;
  --tf-fg: #222222;
  --tf-muted: #666666;
  --tf-link: #0066cc;
  --tf-border: #dddddd;
  --tf-max-width: 900px;
  --tf-font: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
}
 
body {
  margin: 2rem auto;
  max-width: var(--tf-max-width);
  font-family: var(--tf-font);
  line-height: 1.6;
  color: var(--tf-fg);
  background: var(--tf-bg);
}
 
a {
  color: var(--tf-link);
  text-decoration: none;
}
 
a:hover {
  text-decoration: underline;
}
 
nav {
  text-align: right;
  margin-bottom: 2rem;
  font-size: 0.9rem;
}
 
nav a {
  color: var(--tf-muted);
  margin-left: 1rem;
}
 
#content {
  margin-top: 2rem;
}
 
code, pre {
  font-family: "SF Mono", Menlo, Monaco, Consolas, "Liberation Mono", monospace;
}

/* Dark theme variables */
body.dark {
  --tf-bg: #111111;
  --tf-fg: #f5f5f5;
  --tf-muted: #aaaaaa;
  --tf-link: #66aaff;
  --tf-border: #333333;
}

<!-- Toggle button (e.g., in nav) -->
<button id="tf-dark-toggle" style="font-size:0.8rem; margin-left:1rem;">
  🌙 Dark
</button>
 
<script>
  const toggle = document.getElementById("tf-dark-toggle");
  const body = document.body;
 
  // Load preference
  if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) {
    body.classList.add("dark");
  }
 
  toggle.addEventListener("click", () => {
    body.classList.toggle("dark");
  });
</script>

<script>
  // Example: embed or fetch this JSON per folder
  const tfSitemap = [
    { type: "file", name: "README.md", desc: "Navigation index" },
    { type: "file", name: "ABOUT.md", desc: "Context and narrative" },
    { type: "file", name: "primer.md", desc: "Introductory material" },
    { type: "folder", name: "examples", desc: "Worked examples" }
  ];
 
  function renderSitemap(containerId) {
    const container = document.getElementById(containerId);
    if (!container) return;
 
    const ul = document.createElement("ul");
 
    tfSitemap.forEach(item => {
      const li = document.createElement("li");
      const link = document.createElement("a");
      link.textContent = item.name;
      link.href = item.type === "folder" ? `./${item.name}/` : `./${item.name}`;
      li.appendChild(link);
 
      if (item.desc) {
        const span = document.createElement("span");
        span.style.marginLeft = "0.5rem";
        span.style.color = "#666";
        span.textContent = `— ${item.desc}`;
        li.appendChild(span);
      }
 
      ul.appendChild(li);
    });
 
    container.appendChild(ul);
  }
 
  // Call this where needed
  // renderSitemap("tf-sitemap");
</script>
 
<div id="tf-sitemap"></div>

TriadicFrameworks/
├─ README.md                 # Root repo overview
├─ ABOUT.md                  # Root narrative (optional)
├─ docs/
│  ├─ README.md              # Site docs landing (navigation‑first)
│  ├─ ABOUT.md               # Docs narrative
│  ├─ _template/
│  │  ├─ README.md           # Folder‑level README template
│  │  └─ ABOUT.md            # Folder‑level ABOUT template
│  ├─ domains/
│  │  ├─ index.html
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  └─ ... domain files ...
│  ├─ simulations/
│  │  ├─ index.html
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  └─ ... simulation files ...
│  ├─ tools/
│  │  ├─ index.html
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  └─ ... analyzers, utilities ...
│  ├─ examples/
│  │  ├─ index.html
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  └─ ... worked examples ...
│  └─ _meta/
│     └─ navigation-philosophy.md
├─ papers/
│  └─ ... paper metadata / links ...
└─ theme/
   ├─ rtt-diagram-1.png
   ├─ rtt-diagram-2.png
   └─ ...

const fs = require("fs");
const path = require("path");
 
const ROOT = path.join(__dirname, ".."); // repo root
 
function generateSitemapForFolder(folderPath) {
  const entries = fs.readdirSync(folderPath, { withFileTypes: true });
 
  const sitemap = entries
    .filter(e => !e.name.startsWith(".")) // ignore hidden
    .filter(e => e.name !== "sitemap.json") // avoid recursion
    .map(e => {
      const full = path.join(folderPath, e.name);
      const isDir = e.isDirectory();
 
      return {
        type: isDir ? "folder" : "file",
        name: e.name,
        path: full.replace(ROOT, ""),
        desc: "" // optional: can be filled manually later
      };
    });
 
  fs.writeFileSync(
    path.join(folderPath, "sitemap.json"),
    JSON.stringify(sitemap, null, 2)
  );
}
 
function walk(folderPath) {
  generateSitemapForFolder(folderPath);
 
  const entries = fs.readdirSync(folderPath, { withFileTypes: true });
  for (const e of entries) {
    if (e.isDirectory() && !e.name.startsWith(".")) {
      walk(path.join(folderPath, e.name));
    }
  }
}
 
walk(path.join(ROOT, "docs"));
console.log("Sitemaps generated.");

[
  {
    "type": "file",
    "name": "README.md",
    "path": "/docs/domains/README.md",
    "desc": ""
  },
  {
    "type": "file",
    "name": "ABOUT.md",
    "path": "/docs/domains/ABOUT.md",
    "desc": ""
  },
  {
    "type": "folder",
    "name": "physics",
    "path": "/docs/domains/physics",
    "desc": ""
  }
]

<div id="tf-sitemap"></div>
 
<script>
  async function loadSitemap() {
    const res = await fetch("./sitemap.json");
    const data = await res.json();
 
    const container = document.getElementById("tf-sitemap");
    const ul = document.createElement("ul");
 
    data.forEach(item => {
      const li = document.createElement("li");
      const link = document.createElement("a");
 
      link.textContent = item.name;
      link.href = item.type === "folder" ? `./${item.name}/` : `./${item.name}`;
      li.appendChild(link);
 
      if (item.desc) {
        const span = document.createElement("span");
        span.style.marginLeft = "0.5rem";
        span.style.color = "#666";
        span.textContent = `— ${item.desc}`;
        li.appendChild(span);
      }
 
      ul.appendChild(li);
    });
 
    container.appendChild(ul);
  }
 
  loadSitemap();
</script>

name: Generate Sitemaps
 
on:
  push:
    branches: [ main ]
 
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
 
      - name: Generate sitemaps
        run: node scripts/generate-sitemaps.js
 
      - name: Commit sitemap updates
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add .
          git commit -m "Update sitemaps" || echo "No changes"
          git push

"kind": "primer" | "example" | "simulation" | "reference" | "note"

const fs = require("fs");
const path = require("path");
 
const ROOT = path.join(__dirname, "..", "docs");
 
function collectSitemaps(folder) {
  const entries = fs.readdirSync(folder, { withFileTypes: true });
  let results = [];
 
  for (const e of entries) {
    const full = path.join(folder, e.name);
 
    if (e.isDirectory()) {
      results = results.concat(collectSitemaps(full));
    }
 
    if (e.name === "sitemap.json") {
      const rel = full.replace(path.join(__dirname, ".."), "");
      results.push(rel);
    }
  }
 
  return results;
}
 
const all = collectSitemaps(ROOT);
 
fs.writeFileSync(
  path.join(__dirname, "..", "docs", "sitemap_index.json"),
  JSON.stringify({ generated: new Date().toISOString(), sitemaps: all }, null, 2)
);
 
console.log("Global sitemap index generated.");

{
  "generated": "2026-03-08T14:30:00Z",
  "sitemaps": [
    "/docs/sitemap.json",
    "/docs/domains/sitemap.json",
    "/docs/domains/physics/sitemap.json",
    "/docs/simulations/sitemap.json",
    "/docs/examples/sitemap.json"
  ]
}

const fs = require("fs");
const path = require("path");
 
const ROOT = path.join(__dirname, "..", "docs");
 
function walk(folder) {
  const entries = fs.readdirSync(folder, { withFileTypes: true });
  let files = [];
 
  for (const e of entries) {
    const full = path.join(folder, e.name);
 
    if (e.isDirectory()) {
      files = files.concat(walk(full));
    } else if (e.name.endsWith(".md")) {
      files.push(full);
    }
  }
 
  return files;
}
 
const mdFiles = walk(ROOT);
 
const index = mdFiles.map((file, i) => {
  const content = fs.readFileSync(file, "utf8");
  const rel = file.replace(path.join(__dirname, ".."), "");
 
  return {
    id: i,
    path: rel,
    title: path.basename(file),
    text: content.replace(/[#>*`]/g, "") // strip markdown noise
  };
});
 
fs.writeFileSync(
  path.join(__dirname, "..", "docs", "search_index.json"),
  JSON.stringify(index, null, 2)
);
 
console.log("Search index generated.");

[
  {
    "id": 0,
    "path": "/docs/README.md",
    "title": "README.md",
    "text": "TriadicFrameworks Documentation A canonical, navigation-first entry point..."
  },
  {
    "id": 1,
    "path": "/docs/domains/physics/primer.md",
    "title": "primer.md",
    "text": "Physics Primer Resonance-Time Theory applied to physical systems..."
  }
]

# 🗺️ TriadicFrameworks Visual Sitemap
 
```
TriadicFrameworks/
├─ README.md
├─ ABOUT.md
├─ docs/
│  ├─ README.md
│  ├─ ABOUT.md
│  ├─ sitemap_index.json
│  ├─ search_index.json
│  ├─ domains/
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  ├─ sitemap.json
│  │  ├─ physics/
│  │  │  ├─ README.md
│  │  │  ├─ ABOUT.md
│  │  │  ├─ primer.md
│  │  │  ├─ examples/
│  │  │  └─ sitemap.json
│  │  ├─ cognition/
│  │  └─ ...
│  ├─ simulations/
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  ├─ sandbox/
│  │  └─ sitemap.json
│  ├─ tools/
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  ├─ analyzers/
│  │  └─ sitemap.json
│  ├─ examples/
│  │  ├─ README.md
│  │  ├─ ABOUT.md
│  │  └─ sitemap.json
│  └─ _template/
│     ├─ README.md
│     ├─ ABOUT.md
│     └─ index.html
├─ papers/
│  └─ index.html
├─ scripts/
│  ├─ generate-sitemaps.js
│  ├─ generate-global-sitemap.js
│  └─ generate-search-index.js
└─ theme/
   ├─ rtt-diagram-1.png
   ├─ rtt-diagram-2.png
   └─ ...
```

{
  "scripts": {
    "build:nav": "node scripts/generate-sitemaps.js && node scripts/generate-global-sitemap.js",
    "build:search": "node scripts/generate-search-index.js",
    "build": "npm run build:nav && npm run build:search"
  }
}

<input
  type="text"
  id="tf-search"
  placeholder="Search TriadicFrameworks…"
  style="width:60%; padding:1rem; font-size:1.1rem;"
/>
 
<div id="tf-search-results" style="margin-top:2rem;"></div>
 
<script>
  let tfIndex = [];
 
  async function loadIndex() {
    const res = await fetch("/docs/search_index.json");
    tfIndex = await res.json();
  }
 
  function renderResults(results) {
    const container = document.getElementById("tf-search-results");
    container.innerHTML = "";
    results.slice(0, 25).forEach(doc => {
      const div = document.createElement("div");
      div.style.marginBottom = "1.2rem";
 
      const title = document.createElement("div");
      title.style.fontWeight = "600";
      title.textContent = doc.title;
 
      const snippet = document.createElement("div");
      snippet.style.fontSize = "0.9rem";
      snippet.style.color = "#555";
      snippet.textContent = doc.text.slice(0, 160) + "…";
 
      const link = document.createElement("a");
      link.href = doc.path;
      link.textContent = "Open →";
      link.style.fontSize = "0.9rem";
 
      div.appendChild(title);
      div.appendChild(snippet);
      div.appendChild(link);
      container.appendChild(div);
    });
  }
 
  function search(query) {
    const q = query.toLowerCase();
    const results = tfIndex.filter(doc =>
      doc.text.toLowerCase().includes(q) || doc.title.toLowerCase().includes(q)
    );
    renderResults(results);
  }
 
  document.getElementById("tf-search").addEventListener("input", e => {
    const q = e.target.value.trim();
    if (!q) {
      document.getElementById("tf-search-results").innerHTML = "";
      return;
    }
    search(q);
  });
 
  loadIndex();
</script>

<svg xmlns="http://www.w3.org/2000/svg" width="900" height="520" font-family="system-ui, sans-serif" font-size="12">
  <style>
    .box { fill:#f9f9f9; stroke:#cccccc; rx:6; ry:6; }
    .label { fill:#222222; }
    .line { stroke:#cccccc; stroke-width:1; }
  </style>
 
  <!-- Root -->
  <rect class="box" x="380" y="20" width="140" height="40"/>
  <text class="label" x="450" y="45" text-anchor="middle">TriadicFrameworks/</text>
 
  <!-- docs -->
  <line class="line" x1="450" y1="60" x2="250" y2="110"/>
  <rect class="box" x="180" y="110" width="140" height="40"/>
  <text class="label" x="250" y="135" text-anchor="middle">docs/</text>
 
  <!-- papers -->
  <line class="line" x1="450" y1="60" x2="650" y2="110"/>
  <rect class="box" x="580" y="110" width="140" height="40"/>
  <text class="label" x="650" y="135" text-anchor="middle">papers/</text>
 
  <!-- docs children -->
  <line class="line" x1="250" y1="150" x2="120" y2="210"/>
  <rect class="box" x="60" y="210" width="120" height="40"/>
  <text class="label" x="120" y="235" text-anchor="middle">domains/</text>
 
  <line class="line" x1="250" y1="150" x2="250" y2="210"/>
  <rect class="box" x="190" y="210" width="120" height="40"/>
  <text class="label" x="250" y="235" text-anchor="middle">simulations/</text>
 
  <line class="line" x1="250" y1="150" x2="380" y2="210"/>
  <rect class="box" x="320" y="210" width="120" height="40"/>
  <text class="label" x="380" y="235" text-anchor="middle">tools/</text>
 
  <line class="line" x1="250" y1="150" x2="510" y2="210"/>
  <rect class="box" x="450" y="210" width="120" height="40"/>
  <text class="label" x="510" y="235" text-anchor="middle">examples/</text>
 
  <!-- legend -->
  <text class="label" x="40" y="500">High‑level sitemap — canonical structural view of TriadicFrameworks.</text>
</svg>

# 🤝 Contributing to TriadicFrameworks
 
Welcome. This repo is a **canonical research substrate**, not a product.  
Contributions should preserve clarity, structure, and non‑duplication.
 
---
 
## 1. Principles
 
- **Canonical Markdown** — All authoritative content lives in `.md` files.
- **Navigation‑first READMEs** — Structure and links, not essays.
- **Narrative ABOUTs** — Context, story, and conceptual framing.
- **No duplication** — Link to existing artifacts instead of copying.
- **Completed substrate** — Extend via examples, simulations, and notes, not by rewriting foundations.
 
---
 
## 2. Folder pattern
 
Each major folder should contain:
 
- `README.md` — navigation‑first, with a **Start Here** track.
- `ABOUT.md` — narrative and context.
- `sitemap.json` — generated at build time.
- Optional: `index.html` wrapper.
 
Use `docs/_template/` as your reference.
 
---
 
## 3. Adding content
 
1. **Choose the right folder** (domains, simulations, tools, examples).
2. Add your Markdown file with a clear, descriptive name.
3. If needed, add a short line to the folder `README.md` under **Contents**.
4. Run `npm run build` locally to regenerate sitemaps and search index.
5. Open a pull request with:
   - a short description,
   - how it fits the canon,
   - any new terms or invariants introduced.
 
---
 
## 4. Style
 
- Short sections, clear headings.
- Prefer examples and diagrams over long prose.
- Use emoji sparingly in READMEs for navigation cues.
- Avoid speculative claims; mark open questions clearly.
 
---
 
## 5. What not to change
 
- Core RTT definitions and invariants.
- Historical records and archived papers.
- Canonical diagrams without discussion.
 
If you’re unsure, open an issue first.
 
---
 
Thank you for helping keep the substrate clear, legible, and usable for future readers.

---
start_here: true
kind: primer
---
 
# Alignment Primer
...

const fs = require("fs");
const path = require("path");
 
const ROOT = path.join(__dirname, "..", "docs");
 
function walk(folder) {
  const entries = fs.readdirSync(folder, { withFileTypes: true });
  let files = [];
 
  for (const e of entries) {
    const full = path.join(folder, e.name);
    if (e.isDirectory()) {
      files = files.concat(walk(full));
    } else if (e.name.endsWith(".md")) {
      files.push(full);
    }
  }
  return files;
}
 
function parseFrontMatter(content) {
  if (!content.startsWith("---")) return {};
  const end = content.indexOf("---", 3);
  if (end === -1) return {};
  const block = content.slice(3, end).trim();
  const lines = block.split("\n");
  const meta = {};
  lines.forEach(line => {
    const [k, v] = line.split(":").map(s => s.trim());
    if (k && v) meta[k] = v.replace(/^["']|["']$/g, "");
  });
  return meta;
}
 
const files = walk(ROOT);
const startHere = [];
 
files.forEach(file => {
  const content = fs.readFileSync(file, "utf8");
  const meta = parseFrontMatter(content);
  if (meta.start_here === "true") {
    startHere.push({
      path: file.replace(path.join(__dirname, ".."), ""),
      kind: meta.kind || "primer"
    });
  }
});
 
fs.writeFileSync(
  path.join(ROOT, "start_here.json"),
  JSON.stringify(startHere, null, 2)
);
 
console.log("Start Here index generated.");

<div id="tf-start-here"></div>
 
<script>
  async function loadStartHere() {
    try {
      const res = await fetch("/docs/start_here.json");
      const items = await res.json();
 
      const container = document.getElementById("tf-start-here");
      container.innerHTML = "<h2>🚦 Start Here</h2>";
 
      // Group by kind (primer, example, simulation, etc.)
      const groups = {};
      items.forEach(item => {
        const kind = item.kind || "other";
        if (!groups[kind]) groups[kind] = [];
        groups[kind].push(item);
      });
 
      // Render each group
      Object.keys(groups).forEach(kind => {
        const section = document.createElement("div");
        section.style.marginBottom = "1.5rem";
 
        const title = document.createElement("h3");
        title.textContent = kind.charAt(0).toUpperCase() + kind.slice(1);
        section.appendChild(title);
 
        const ul = document.createElement("ul");
 
        groups[kind].forEach(item => {
          const li = document.createElement("li");
          const link = document.createElement("a");
 
          link.href = item.path;
          link.textContent = item.path.split("/").pop().replace(".md", "");
 
          li.appendChild(link);
          ul.appendChild(li);
        });
 
        section.appendChild(ul);
        container.appendChild(section);
      });
 
    } catch (err) {
      console.error("Failed to load Start Here index:", err);
    }
  }
 
  loadStartHere();
</script>

---
start_here: true
kind: primer
---