fix(docs): preserve accessible examples and gate index publication

Author: waleedlatif1

.gitattributes

@@ -42,5 +42,5 @@ Dockerfile* text eol=lf
 *.eot binary
 *.pdf binary
 
-apps/docs/migration/*.json linguist-generated=true
+apps/docs/migration/report.json linguist-generated=true
 apps/docs/migration/verification/** linguist-generated=true

.github/workflows/ci.yml

@@ -1158,7 +1158,7 @@ jobs:
               - 'apps/docs/lib/search/**'
               - 'apps/docs/lib/openapi-specs.ts'
               - 'apps/docs/lib/urls.ts'
-              - 'apps/docs/public/openapi*.json'
+              - 'apps/docs/openapi*.json'
               - 'apps/docs/package.json'
               - 'bun.lock'
               - '.github/workflows/docs.yml'

.github/workflows/docs-negotiation.yml

@@ -45,7 +45,7 @@ permissions:
 
 concurrency:
   group: docs-negotiation-${{ github.ref }}-${{ inputs.benchmark && 'benchmark' || 'verification' }}
-  cancel-in-progress: true
+  cancel-in-progress: ${{ !inputs.benchmark }}
 
 jobs:
   benchmark:
@@ -89,7 +89,8 @@ jobs:
           cp .readiness-harness/apps/docs/scripts/benchmark-readiness.ts apps/docs/scripts/benchmark-readiness.ts
           if [ "$MEASURED_TARGET" = production ]; then
             gh api "repos/$GITHUB_REPOSITORY/deployments?environment=Production&per_page=1" >test-results/benchmark/deployment.json
-            REVISION=$(jq -r '.[0].sha' test-results/benchmark/deployment.json)
+            # Candidate deployments do not establish which revision owns the public alias.
+            REVISION=unverified-public-origin
           else
             REVISION=$(git rev-parse HEAD)
           fi

.github/workflows/docs.yml

@@ -7,7 +7,25 @@ on:
         required: false
       OPENAI_API_KEY:
         required: false
-  workflow_dispatch: # Allow manual triggering
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: I verified the matching docs deployment and a restorable index backup
+        type: boolean
+        required: true
+        default: false
+      deployed_revision:
+        description: Full source SHA of the verified serving docs deployment
+        type: string
+        required: true
+      deployment_id:
+        description: Verified serving docs deployment ID
+        type: string
+        required: true
+      backup_reference:
+        description: Restorable docs_embeddings backup identifier (no credentials)
+        type: string
+        required: true
 
 permissions:
   contents: read
@@ -18,16 +36,30 @@ jobs:
     # Network-bound on the embeddings API: ~9% CPU and ~3% peak memory on 8 vCPU.
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 30
-    if: github.ref == 'refs/heads/main'
+    if: github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch' && inputs.publish
     concurrency:
       group: docs-search-index-production
       cancel-in-progress: false
 
     steps:
+      - name: Record verified deployment and backup
+        env:
+          DEPLOYED_REVISION: ${{ inputs.deployed_revision }}
+          DEPLOYMENT_ID: ${{ inputs.deployment_id }}
+          BACKUP_REFERENCE: ${{ inputs.backup_reference }}
+        run: |
+          test "$DEPLOYED_REVISION" = "$GITHUB_SHA"
+          test -n "$DEPLOYMENT_ID"
+          test -n "$BACKUP_REFERENCE"
+          jq -n --arg revision "$DEPLOYED_REVISION" --arg deployment "$DEPLOYMENT_ID" \
+            --arg backup "$BACKUP_REFERENCE" --arg actor "$GITHUB_ACTOR" \
+            '{revision: $revision, deploymentId: $deployment, backupReference: $backup, verifiedBy: $actor}' \
+            > "$RUNNER_TEMP/docs-search-authorization.json"
+
       - name: Checkout code
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
         with:
-          ref: main
+          ref: ${{ github.sha }}
           persist-credentials: false
 
       - name: Setup workspace
@@ -51,4 +83,6 @@ jobs:
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: docs-search-index
-          path: apps/docs/test-results/docs-search-*.json
+          path: |
+            apps/docs/test-results/docs-search-*.json
+            ${{ runner.temp }}/docs-search-authorization.json

apps/docs/MACHINE_ACCESS.md

@@ -60,7 +60,7 @@ bun scripts/index-search.ts
 
 `--plan` is local and read-only. `--check` requires the search database and reports missing, stale or retired documents without writes. It compares stored chunk text, embedding model and input identity, headings, citations and metadata with the canonical catalog. The final command prepares bounded embedding batches, atomically updates one document at a time, and removes retired documents only after all page updates succeed. A failed page leaves its previous index intact. Citation or metadata changes reuse existing vectors when the embedding input is unchanged. The canonical index includes authored content and generated API operations; the agent VFS retains its deliberate `academy` and `api-reference` exclusions.
 
-Add one or more `--path=/introduction` arguments to plan, check or repair specific canonical pages. Scoped publication never retires other pages. Publication and checks acquire an exclusive PostgreSQL advisory lock; a competing invocation fails before changing rows. The main-branch workflow also serializes publisher jobs and checks out current `main`, including when an older queued workflow starts. Do not run an older publisher checkout against the index.
+Add one or more `--path=/introduction` arguments to plan, check or repair specific canonical pages. Scoped publication never retires other pages. Publication and checks acquire an exclusive PostgreSQL advisory lock; a competing invocation fails before changing rows. Automatic index publication is disabled. The main-branch workflow only publishes after a manual dispatch with `publish` confirmed, the serving docs deployment ID, its full source SHA, and a restorable index backup reference. It checks out the dispatch's exact SHA and rejects a different deployment revision before accessing the index. The operator must independently verify the serving deployment and backup before confirming; the workflow records that attestation but does not create or validate a backup. Publisher jobs remain serialized. Do not run an older publisher checkout against the index.
 
 Set `DOCS_SEARCH_REPORT_PATH` to choose the JSON report destination. The default is `test-results/docs-search-index.json`. Reports include embedding request, input and provider token counts. The main-branch docs workflow retains separate publication and freshness reports; no production indexing is part of the docs build.
 

apps/docs/app/[[...slug]]/page.tsx

@@ -6,7 +6,7 @@ import { getMDXComponents } from '@/components/docs/mdx'
 import { DocsPageFrame } from '@/components/docs/page-frame'
 import { StructuredData } from '@/components/structured-data'
 import { getPage, getPages } from '@/lib/content/catalog'
-import { DOCS_BASE_URL } from '@/lib/urls'
+import { DOCS_BASE_URL, getMarkdownPath } from '@/lib/urls'
 import { loadPage } from '@/.content/registry'
 
 interface PageProps {
@@ -30,7 +30,8 @@ export async function generateMetadata({ params }: PageProps): Promise<Metadata>
     alternates: {
       canonical: url,
       types: {
-        'text/markdown': `${url === `${DOCS_BASE_URL}/` ? `${DOCS_BASE_URL}/index` : url}.md`,
+        'text/markdown': `${DOCS_BASE_URL}${getMarkdownPath(page.url)}`,
+        'text/plain': `${DOCS_BASE_URL}/llms.txt`,
       },
     },
     openGraph: {

apps/docs/app/api/docs/pages/route.ts

@@ -1,4 +1,4 @@
-import { listPages, listPagesSchema } from '@/lib/http/pages'
+import { listPages, listPagesSchema, UnknownPageCursorError } from '@/lib/http/pages'
 
 export function GET(request: Request) {
   const params = new URL(request.url).searchParams
@@ -14,7 +14,9 @@ export function GET(request: Request) {
     return Response.json(listPages(parsed.data), {
       headers: { 'Cache-Control': 'public, max-age=60, s-maxage=3600' },
     })
-  } catch {
-    return Response.json({ error: 'Unknown page cursor' }, { status: 400 })
+  } catch (error) {
+    if (error instanceof UnknownPageCursorError)
+      return Response.json({ error: error.message }, { status: 400 })
+    throw error
   }
 }

apps/docs/app/global.css

@@ -3,6 +3,22 @@
 @source '../../../packages/emcn/src';
 @source '../../../packages/workflow-renderer/src';
 @custom-variant dark (&:where(.dark, .dark *));
+@custom-variant hover-hover {
+  @media (hover: hover) and (pointer: fine) {
+    &:hover {
+      @slot;
+    }
+  }
+}
+
+@theme {
+  --text-micro: 10px;
+  --text-xs: 11px;
+  --text-caption: 12px;
+  --text-small: 13px;
+  --text-base: 15px;
+  --text-md: 16px;
+}
 
 @theme inline {
   --font-sans: var(--font-geist-sans);

apps/docs/app/layout.tsx

@@ -46,7 +46,12 @@ export default function RootLayout({ children }: RootLayoutProps) {
               description,
               url: DOCS_BASE_URL,
               inLanguage: 'en',
-              publisher: { '@type': 'Organization', name: 'Sim', url: SIM_SITE_URL },
+              publisher: {
+                '@type': 'Organization',
+                '@id': `${SIM_SITE_URL}#organization`,
+                name: 'Sim',
+                url: SIM_SITE_URL,
+              },
             }),
           }}
         />

apps/docs/components/docs/page-actions.tsx

@@ -6,6 +6,7 @@ import { useCopyToClipboard } from '@sim/emcn'
 import { Check, ChevronDown, Duplicate, SquareArrowUpRight } from '@sim/emcn/icons'
 import { cn } from '@/components/docs/classnames'
 import { docsControlClass, docsMenuClass, docsMenuItemClass } from '@/components/docs/primitives'
+import { getMarkdownPath } from '@/lib/urls'
 
 interface PageActionsProps {
   url: string
@@ -15,12 +16,14 @@ export function PageActions({ url }: PageActionsProps) {
   const { copied, copy } = useCopyToClipboard()
   const [status, setStatus] = useState<'idle' | 'loading' | 'ready' | 'error'>('idle')
   const prepared = useRef<string | null>(null)
-  const markdownUrl = `${url === '/' ? '/index' : url}.md`
+  const markdownUrl = getMarkdownPath(url)
   const showCopied = copied && status === 'idle'
   async function copyPage() {
     setStatus('loading')
     const prepare = async () => {
-      const response = await fetch(markdownUrl, { signal: AbortSignal.timeout(10000) })
+      const signal =
+        typeof AbortSignal.timeout === 'function' ? AbortSignal.timeout(10000) : undefined
+      const response = await fetch(markdownUrl, { signal })
       if (!response.ok) throw new Error('Page could not be loaded')
       const markdown = await response.text()
       if (!markdown.trim()) throw new Error('Page is empty')