content upgrades

Author: DeveloperAlly

docs-guide/contributing/contributing.mdx

@@ -30,4 +30,4 @@ Use visual-explainer when you need high-signal review artifacts for structural c
 
 For full details and corrected repo path references, see:
 
-- [`v2/x-experimental/visual-explainer-livepeer-guide.md`](../../v2/x-experimental/visual-explainer-livepeer-guide.md)
+- [`docs-guide/feature-guides/visual-explainer-workflows.mdx`](../feature-guides/visual-explainer-workflows.mdx)

…ental/visual-explainer-livepeer-guide.md …re-guides/visual-explainer-workflows.mdxv2/x-experimental/visual-explainer-livepeer-guide.md renamed to docs-guide/feature-guides/visual-explainer-workflows.mdx v2/x-experimental/visual-explainer-livepeer-guide.md renamed to docs-guide/feature-guides/visual-explainer-workflows.mdx

@@ -1,3 +1,21 @@
+---
+title: 'Visual Explainer Workflows'
+sidebarTitle: 'Visual Explainer'
+description: 'Pilot workflow guidance for using visual-explainer in docs maintenance, review, and reporting.'
+keywords:
+  [
+    'livepeer',
+    'visual explainer',
+    'docs guide',
+    'feature guide',
+    'pilot workflow',
+    'diff review',
+    'plan review',
+    'fact check',
+    'project recap',
+  ]
+---
+
 # Visual Explainer — Livepeer docs-v2 Implementation Guide
 
 > **What this is:** A practical guide to implementing [nicobailon/visual-explainer](https://github.com/nicobailon/visual-explainer) as a developer/maintainer tooling layer for the `livepeer/docs` `docs-v2` branch. This is not a content authoring tool — it operates alongside the docs, not inside Mintlify.
@@ -277,6 +295,19 @@ If these conditions are not met, keep this workflow internal to maintainers.
 
 ---
 
+## Operator Runbook (Planning Only)
+
+Use this checklist after the relocation is complete. Do not execute these commands as part of this migration change.
+
+1. `/diff-review`: run for structural PRs (`docs.json`, `snippets/components/**`, `.github/workflows/**`) and capture one artifact per review.
+2. `/plan-review`: run once against the AI-first plan document and save a single gap-analysis artifact.
+3. `/fact-check`: run on delivery/retrospective docs before stakeholder circulation.
+4. `/project-recap`: run once per onboarding/handoff cycle to generate orientation context.
+
+Outputs should remain out-of-repo and follow the naming convention in this guide.
+
+---
+
 ## Quick Reference: Commands
 
 | Command | Best Use in This Repo |

docs-guide/indexes/ai-tools.mdx

@@ -50,3 +50,21 @@ Produced assets:
 2. Pick the target pack from `ai-tools/agent-packs/<agent>/`.
 3. Add the pack file to the agent's local rules/skills location.
 4. Run `node tools/scripts/repo-audit-orchestrator.js --mode static --scope full` as the first verification run.
+
+## Codex Skill Portability
+
+- Canonical source: `ai-tools/ai-skills/templates/*.template.md`
+- Local install target: `$CODEX_HOME/skills` (fallback: `~/.codex/skills`)
+- Sync behavior: safe upsert only (creates/updates managed skills; no deletion)
+
+Runbook:
+
+```bash
+node tools/scripts/sync-codex-skills.js --check
+node tools/scripts/sync-codex-skills.js
+node tools/scripts/sync-codex-skills.js --skills lpd-bootstrap-and-doctor,staged-test-suite-runner --dry-run
+```
+
+Generated metadata:
+
+- `agents/openai.yaml` is generated deterministically for each synced skill.

docs-guide/indexes/pages-index.mdx

@@ -168,6 +168,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.File name="community-guides.mdx" />
           <Tree.File name="community-projects.mdx" />
         </Tree.Folder>
+        <Tree.Folder name="quickstart">
+          <Tree.File name="AI-prompt.mdx" />
+          <Tree.File name="gateway-setup.mdx" />
+        </Tree.Folder>
         <Tree.Folder name="references">
           <Tree.Folder name="api-reference">
             <Tree.Folder name="AI-API">
@@ -228,10 +232,6 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.Folder name="monitor">
             <Tree.File name="monitor-and-optimise.mdx" />
           </Tree.Folder>
-          <Tree.Folder name="quickstart">
-            <Tree.File name="get-AI-to-setup-the-gateway.mdx" />
-            <Tree.File name="quickstart-a-gateway.mdx" />
-          </Tree.Folder>
           <Tree.Folder name="requirements">
             <Tree.File name="setup.mdx" />
           </Tree.Folder>
@@ -388,12 +388,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
               <Tree.File name="start-egress.mdx" />
               <Tree.File name="stop-egress.mdx" />
               <Tree.File name="update-user.mdx" />
-              <Tree.File name="update.mdx" />
             </Tree.Folder>
             <Tree.Folder name="sessions">
               <Tree.File name="get-all.mdx" />
               <Tree.File name="get-clip.mdx" />
-              <Tree.File name="get-recording.mdx" />
               <Tree.File name="get.mdx" />
               <Tree.File name="overview.mdx" />
             </Tree.Folder>
@@ -707,6 +705,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.File name="community-projects.mdx" />
           <Tree.File name="faq.mdx" />
         </Tree.Folder>
+        <Tree.Folder name="quickstart">
+          <Tree.File name="AI-prompt.mdx" />
+          <Tree.File name="gateway-setup.mdx" />
+        </Tree.Folder>
         <Tree.Folder name="references">
           <Tree.Folder name="api-reference">
             <Tree.Folder name="AI-API">
@@ -767,10 +769,6 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.Folder name="monitor">
             <Tree.File name="monitor-and-optimise.mdx" />
           </Tree.Folder>
-          <Tree.Folder name="quickstart">
-            <Tree.File name="get-AI-to-setup-the-gateway.mdx" />
-            <Tree.File name="quickstart-a-gateway.mdx" />
-          </Tree.Folder>
           <Tree.Folder name="requirements">
             <Tree.File name="setup.mdx" />
           </Tree.Folder>
@@ -928,12 +926,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
               <Tree.File name="start-egress.mdx" />
               <Tree.File name="stop-egress.mdx" />
               <Tree.File name="update-user.mdx" />
-              <Tree.File name="update.mdx" />
             </Tree.Folder>
             <Tree.Folder name="sessions">
               <Tree.File name="get-all.mdx" />
               <Tree.File name="get-clip.mdx" />
-              <Tree.File name="get-recording.mdx" />
               <Tree.File name="get.mdx" />
               <Tree.File name="overview.mdx" />
             </Tree.Folder>
@@ -1176,6 +1172,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.File name="community-projects.mdx" />
           <Tree.File name="faq.mdx" />
         </Tree.Folder>
+        <Tree.Folder name="quickstart">
+          <Tree.File name="AI-prompt.mdx" />
+          <Tree.File name="gateway-setup.mdx" />
+        </Tree.Folder>
         <Tree.Folder name="references">
           <Tree.Folder name="api-reference">
             <Tree.Folder name="AI-API">
@@ -1236,10 +1236,6 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
           <Tree.Folder name="monitor">
             <Tree.File name="monitor-and-optimise.mdx" />
           </Tree.Folder>
-          <Tree.Folder name="quickstart">
-            <Tree.File name="get-AI-to-setup-the-gateway.mdx" />
-            <Tree.File name="quickstart-a-gateway.mdx" />
-          </Tree.Folder>
           <Tree.Folder name="requirements">
             <Tree.File name="setup.mdx" />
           </Tree.Folder>
@@ -1397,12 +1393,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
               <Tree.File name="start-egress.mdx" />
               <Tree.File name="stop-egress.mdx" />
               <Tree.File name="update-user.mdx" />
-              <Tree.File name="update.mdx" />
             </Tree.Folder>
             <Tree.Folder name="sessions">
               <Tree.File name="get-all.mdx" />
               <Tree.File name="get-clip.mdx" />
-              <Tree.File name="get-recording.mdx" />
               <Tree.File name="get.mdx" />
               <Tree.File name="overview.mdx" />
             </Tree.Folder>
@@ -1610,10 +1604,14 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
         <Tree.Folder name="monitor">
           <Tree.File name="monitor-and-optimise.mdx" />
         </Tree.Folder>
+        <Tree.Folder name="payments">
+          <Tree.File name="payment-clearinghouse.mdx" />
+        </Tree.Folder>
         <Tree.Folder name="requirements">
           <Tree.File name="setup.mdx" />
         </Tree.Folder>
         <Tree.File name="run-a-gateway.mdx" />
+        <Tree.File name="transcoding.mdx" />
         <Tree.File name="why-run-a-gateway.mdx" />
       </Tree.Folder>
       <Tree.Folder name="using-gateways">
@@ -1717,6 +1715,7 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
       <Tree.Folder name="about-orchestrators">
         <Tree.File name="architecture.mdx" />
         <Tree.File name="economics.mdx" />
+        <Tree.File name="job-types.mdx" />
         <Tree.File name="orchestrator-functions.mdx" />
         <Tree.File name="overview.mdx" />
       </Tree.Folder>
@@ -1736,9 +1735,11 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
         <Tree.File name="orchestrator-tools.mdx" />
       </Tree.Folder>
       <Tree.Folder name="quickstart">
+        <Tree.File name="batch-ai-quickstart.mdx" />
         <Tree.File name="join-a-pool.mdx" />
         <Tree.File name="orchestrator-setup.mdx" />
         <Tree.File name="overview.mdx" />
+        <Tree.File name="realtime-ai-quickstart.mdx" />
       </Tree.Folder>
       <Tree.Folder name="references">
         <Tree.File name="cli-flags.mdx" />
@@ -1806,12 +1807,10 @@ Run command: node tools/scripts/generate-docs-guide-pages-index.js --write
             <Tree.File name="start-egress.mdx" />
             <Tree.File name="stop-egress.mdx" />
             <Tree.File name="update-user.mdx" />
-            <Tree.File name="update.mdx" />
           </Tree.Folder>
           <Tree.Folder name="sessions">
             <Tree.File name="get-all.mdx" />
             <Tree.File name="get-clip.mdx" />
-            <Tree.File name="get-recording.mdx" />
             <Tree.File name="get.mdx" />
             <Tree.File name="overview.mdx" />
           </Tree.Folder>

docs-guide/indexes/scripts-index.mdx

@@ -56,6 +56,7 @@ Run command: node tests/unit/script-docs.test.js --write --rebuild-indexes
 | `tests/integration/v2-wcag-audit.selftest.js` | Script-level self-tests for the v2 WCAG audit (local HTTP + Puppeteer axe run, and temp-file fix/stage behavior without Mintlify). | `node tests/integration/v2-wcag-audit.selftest.js` | docs |
 | `tests/run-all.js` | Utility script for tests/run-all.js. | `node tests/run-all.js` | docs |
 | `tests/run-pr-checks.js` | Run changed-file scoped validation checks for pull request CI. | `node tests/run-pr-checks.js --base-ref main` | docs |
+| `tests/unit/codex-skill-sync.test.js` | Validate template-driven Codex skill sync behavior including check drift, safe upsert, subset sync, and openai.yaml generation. | `node tests/unit/codex-skill-sync.test.js` | docs |
 | `tests/unit/docs-guide-sot.test.js` | Validate docs-guide source-of-truth coverage, README pointers, and generated index freshness. | `node tests/unit/docs-guide-sot.test.js` | docs |
 | `tests/unit/docs-navigation.test.js` | Validate docs.json page-entry syntax in check-only mode by default, with optional report writing and approved remaps. | `./lpd tests unit docs-navigation.test` | docs |
 | `tests/unit/docs-usefulness-accuracy-verifier.test.js` | Validate source-weighted 2026 accuracy verification rules (GitHub vs DeepWiki precedence, freshness, fallback, and cache reuse). | `node tests/unit/docs-usefulness-accuracy-verifier.test.js` | docs |
@@ -156,6 +157,7 @@ Run command: node tests/unit/script-docs.test.js --write --rebuild-indexes
 | `tools/scripts/snippets/test-scripts.sh` | Utility script for tools/scripts/snippets/test-scripts.sh. | `bash tools/scripts/snippets/test-scripts.sh` | docs |
 | `tools/scripts/snippets/update-component-library.sh` | Utility script for tools/scripts/snippets/update-component-library.sh. | `bash tools/scripts/snippets/update-component-library.sh` | docs |
 | `tools/scripts/style-and-language-homogenizer-en-gb.js` | Enforce EN-GB style and terminology profile for English v2 docs in phase 1. | `node tools/scripts/style-and-language-homogenizer-en-gb.js --scope full` | docs |
+| `tools/scripts/sync-codex-skills.js` | Sync canonical skill templates into local Codex skills using safe upsert and deterministic openai.yaml generation. | `node tools/scripts/sync-codex-skills.js` | docs |
 | `tools/scripts/test-all-pages-browser.js` | Utility script for tools/scripts/test-all-pages-browser.js. | `node tools/scripts/test-all-pages-browser.js` | docs |
 | `tools/scripts/test-all-pages-comprehensive.js` | Utility script for tools/scripts/test-all-pages-comprehensive.js. | `node tools/scripts/test-all-pages-comprehensive.js` | docs |
 | `tools/scripts/test-v2-pages.js` | Utility script for tools/scripts/test-v2-pages.js. | `node tools/scripts/test-v2-pages.js` | docs |

docs-guide/source-of-truth-policy.mdx

@@ -28,6 +28,7 @@ This document defines canonical ownership boundaries to prevent drift across REA
 | Script/runtime behavior         | Code + tests                                          | Behavioral truth always lives in executable code and validation tests. |
 | Script metadata and inventory   | Script headers + generated indexes                    | Script headers feed script index generation.                           |
 | Repo feature navigation map     | `docs-guide/*.mdx` (manual canonical files)           | Internal maintainer source of truth.                                   |
+| Codex skill portability         | `ai-tools/ai-skills/templates/*.template.md`          | Local installs are synced from templates via `sync-codex-skills.js`.  |
 | Public user-facing docs content | `v2/pages/**`                                         | Mintlify docs in `docs.json` navigation.                               |
 | CI/test execution behavior      | Workflow files + test runner scripts                  | Narrative summaries must link to these files.                          |
 | Issue/PR intake behavior        | `.github/ISSUE_TEMPLATE/*` + PR templates + workflows | Generated templates index summarizes usage.                            |
@@ -110,3 +111,4 @@ It should not duplicate deep procedures that already exist in:
 1. Any meaningful process change must update the relevant docs-guide canonical file in the same PR.
 2. Any script/workflow/template change must regenerate indexes in the same PR.
 3. If README and docs-guide disagree, docs-guide canonical files are considered authoritative for operational navigation.
+4. Codex skill installs must be generated from templates using `node tools/scripts/sync-codex-skills.js` (manual edits in local skill folders are non-canonical).