[G9a] Docs site: sync wave-1 pages, navigation, pending-translation check, comparison section

[LinuxDevil]

Goal

Bring the docs site (repository LinuxDevil/agent-sdk-docs, live at lousho.com) in line with the SDK documentation after G1 to G8: register the new pages, regenerate the English pages, add navigation entries for both languages, keep the site's CI green while the Arabic pages are translated in follow-up tickets (G9b, G9c, G9d), and add the "Lousho vs eve vs AI SDK agents" section with an honest matrix to the landing page. Plan row G9 (this is its first part; the plan's single line is split into four tickets because 12 new pages and about 25 restructured pages cannot be translated in one pull request).

Current state

Checked in E:\agent-sdk-docs at 40cb386 (the SDK side at cc5ddb8). This is a separate repository; the SDK repository's BRIEF-2 rules about worktrees apply the same way (work in your own worktree of E:\agent-sdk-docs, branch lou-g9a-<slug>, pull request to LinuxDevil/agent-sdk-docs main). A merge to main deploys the site (README.md: "A merge to main is a deploy").

• scripts/sync-sdk-docs.mjs: PAGES (line 26) maps SDK files to slugs (37 entries, listed there); SIDEBAR_TITLES (line 69); HAND_WRITTEN = ['introduction', 'coding-agents', 'examples'] (line 79). The script writes <slug>.mdx for every PAGES entry, rewrites links and anchors, and exits 1 and reports "SDK docs with no page (add them to PAGES)" or "pages missing from docs.json navigation".
• docs.json navigation.languages has en and ar; each has three tabs (Documentation, Examples, Reference) with groups. English Documentation groups today: Get started (introduction, quickstart, installation, coding-agents), Build an agent (tools, approvals, sessions, memory, structured-output, streaming, reasoning, providers), Compose agents (sub-agents, skills, agent-directories, flows), Run it reliably (durable-execution, compaction, guardrails, workspace-tools), Put it in front of people (react, vue, svelte, ai-sdk-ui, nextjs, channels, schedules, acp), Test and observe (testing, evals, observability), Ship (cli, deployment, registry, agent-forge); Reference tab: api-overview, configuration, errors, utilities, changelog. The Arabic navigation mirrors it with ar/<slug> entries and Arabic group names. No redirects key exists in docs.json.
• scripts/check-translations.mjs (run in CI by .github/workflows/check.yml together with npx mint validate and npx mint broken-links) requires an ar/<slug>.mdx for every English page except changelog (UNTRANSLATED), the same number of fenced code blocks (identical byte for byte, Mermaid excepted), the same number of ##-#### headings, no internal link outside /ar/, valid anchors, and a manifest ar/translations.json hash per page; a page whose English hash differs from the recorded one is "stale" and fails the run. So after the sync every changed page is stale and every new page is missing, and CI is red until all are translated.
• scripts/TRANSLATING.md has the translator rules and glossary. Hand-written pages: introduction.mdx (has ar/introduction.mdx), coding-agents.mdx ("Lousho with coding agents": how a coding agent reads these docs; it is not the same as G3's walkthrough), examples.mdx.
• New SDK pages to register (each SDK ticket lists its page in its acceptance criteria; confirm with ls docs/ of the SDK at merge time): G1 docs/executor-api.md, G3 docs/build-a-coding-agent.md, G4a docs/mcp.md, G4b docs/hooks.md, G4c docs/triggers.md, G5a docs/migrating-to-create-agent.md, G5b docs/troubleshooting.md, G6 docs/cloudflare-workers.md, G7 docs/runs.md, docs/models-and-cost.md, docs/stream-events.md, docs/queue-and-steer.md.
• Restructured SDK pages whose Arabic pages go stale: quickstart, durable-execution, workspace-tools, approvals, sessions, streaming, sub-agents, compaction, skills, structured-output, tools, providers, observability, guardrails, testing, api-overview, configuration, flows, deployment, agent-forge, installation, errors, channels, schedules, cli, introduction (this ticket edits it), plus any other page whose text changed; the sync output and check-translations.mjs give the exact list.
• Audit evidence for the matrix: .agent-loop/audit2/our-report.md section 1 (our column, strict rule), eve-report.md sections 3 and 4 (eve 0.70.0 at dd50d12, 2026-10-02), open-harness-and-field-report.md part B4 (Vercel AI SDK ToolLoopAgent, read from docs, nothing run), and AUDIT-2.md sections 3, 6, 7 (in E:\agent-sdk\.claude\worktrees\loop-orch\.agent-loop\).

Scope

In:

1. Run the SDK doc sync: add every new page to PAGES with the slugs executor-api, build-a-coding-agent, mcp, hooks, triggers, migrating-to-create-agent, troubleshooting, cloudflare-workers, runs, models-and-cost, stream-events, queue-and-steer (add SIDEBAR_TITLES where the SDK title is long: migrating-to-create-agent: "Migrating to createAgent()", build-a-coding-agent: "Build a coding agent", stream-events: "Stream events", queue-and-steer: "Queued input and steering"); run npm run sync -- E:\agent-sdk against an up-to-date SDK checkout of main (after G1 to G8 have merged); commit the regenerated .mdx files.
2. Navigation in docs.json, English (decided placement): Get started: add troubleshooting after installation. Build an agent: add hooks after approvals, runs after sessions, stream-events and queue-and-steer after streaming, models-and-cost and then build-a-coding-agent after providers. Compose agents: add mcp after skills. Put it in front of people: add triggers after schedules. Ship: add cloudflare-workers after deployment. Reference: add executor-api and migrating-to-create-agent after api-overview. Arabic navigation: add the ar/<slug> entries only for pages whose Arabic file exists in the same pull request (none of the new ones, for this ticket); G9d adds them.
3. Pending-translation mechanism, so CI stays green: change scripts/check-translations.mjs to read ar/pending.json (a JSON array of slugs). For a slug in the array the script skips every check for that slug (missing file, stale, headings, code blocks, links) and prints pending <slug>; it still fails for a slug that is neither pending nor consistent. Add --list-pending that prints the array. Initialize ar/pending.json with every new slug and every slug the new sync made stale (run the check first, collect its "stale" and "no ar page" lines). Document the mechanism in README.md (the Arabic section) and in scripts/TRANSLATING.md: a translator removes a slug from ar/pending.json when the Arabic page matches, runs --record, and CI enforces it from then on.
4. The landing page section in introduction.mdx and ar/introduction.mdx: ## How it compares placed after "Where an agent can live" and before "Next steps". Content (decided): two sentences of context (what is compared and on what date: eve 0.70.0, Vercel AI SDK ToolLoopAgent on ai 7, Lousho 1.0.0-alpha; checked 2026-10-02; Lousho is alpha, so rows change), then one table with columns Capability, Lousho, eve, AI SDK agents, and the rows below. Every cell is one of "yes", "partly" (with three or fewer words saying what is missing), "no", or "not checked". Take each cell from the cited report row; do not upgrade a cell the report marks inferred. Rows and values, from the audit:
   • Runs as a library, no server: Lousho yes (an import, Node 22); eve no (needs Node 24 and a Nitro server; eve-report.md section 1); AI SDK not checked.
   • Code-first createAgent() API: Lousho yes; eve no (AUDIT-2.md section 3, "What eve does not have"); AI SDK yes (ToolLoopAgent, open-harness-and-field-report.md B4).
   • Durable runs and resume: Lousho yes (tools run at least once); eve yes (Workflow worlds; confirm in eve-report.md section 3, else "not checked"); AI SDK partly (WorkflowAgent in a separate package, B4 item 7).
   • Session fork: Lousho yes (executor and agent.fork()); eve no; AI SDK not checked.
   • Input and output guardrails: Lousho yes; eve no; AI SDK not checked.
   • Model fallback chain: Lousho yes; eve partly (3-attempt retry, no chain); AI SDK not checked.
   • Record and replay tests: Lousho yes; eve no (mockModel only); AI SDK not checked.
   • MCP over stdio: Lousho yes; eve no; AI SDK not checked.
   • Edge runtime (Workers): Lousho partly (spec files only, three providers, two tools); eve no; AI SDK not checked.
   • Any AI SDK model as the provider: Lousho no (four named providers; changes with a wave-2 ticket); eve yes; AI SDK yes.
   • File input (PDF): Lousho partly (images only); eve yes; AI SDK not checked.
   • Tool search / deferred tools: Lousho no; eve yes; AI SDK yes (toolSearch(), B4 item 2).
   • Code mode: Lousho no; eve yes; AI SDK yes (B4 item 3).
   • Third-party OAuth for tools: Lousho no; eve yes; AI SDK not checked.
   • Route auth and principals: Lousho partly (a bearer token); eve yes; AI SDK not checked.
   • Chat channels: Lousho partly (Slack, Discord, webhook, HTTP); eve yes (nine more); AI SDK not checked.
   • Local trace viewer: Lousho no (OpenTelemetry spans, no viewer); eve yes; AI SDK yes (DevTools, B4 item 1).
   • Visual studio: Lousho yes (Agent Forge); eve partly (TUI traces and a hosted tab); AI SDK not checked.
     Under the table, a short list "Where we still win" (the four points of AUDIT-2.md section 7) and one sentence: "This table is a snapshot. The competitors ship often; check their docs, and tell us about a cell that is wrong." with a link to the SDK repository's issues. Translate the section into Arabic in ar/introduction.mdx following scripts/TRANSLATING.md (keep the table structure; product names stay in English), and re-record introduction in ar/translations.json.
5. coding-agents.mdx (and ar/coding-agents.mdx): add one sentence in "Your Lousho agent as a coding agent" linking to /build-a-coding-agent; keep the structure (heading count unchanged) and re-record.
   Out: translating the regenerated pages (G9b, G9c, G9d); changing SDK docs; redirects (see Notes); the sync automation workflow (R5, wave 0).

Acceptance criteria

• npm run sync -- <sdk checkout> reports no unmapped SDK docs, no pages missing from navigation and no unresolved heading links; the regenerated .mdx files are committed.
• docs.json English navigation lists all twelve new slugs in the placement above and parses as JSON; the Arabic navigation has no entry for a missing file.
• node scripts/check-translations.mjs exits 0 with ar/pending.json listing exactly the new and stale slugs; npx mint validate and npx mint broken-links pass locally (or the pull request shows the CI run).
• The comparison table has no cell that is not backed by a cited report row; the pull request description lists each cell with its source (report file and section).
• introduction and coding-agents English and Arabic pages updated, recorded in ar/translations.json, heading counts equal between languages.
• README.md and scripts/TRANSLATING.md describe the pending mechanism.

Live test

None: this ticket spends nothing.

Dependencies

G1, G2a, G2b, G2c, G3, G4a, G4b, G4c, G5a, G5b, G6, G7, G8 must have merged (the sync reads the SDK's main). R5 (wave 0, sync automation in this repository) may add a workflow that also edits PAGES and docs.json; if it has merged, use its commands. Owner decision before merging (a merge deploys lousho.com): "The landing page gets a public comparison with eve and the Vercel AI SDK, as listed. Approve the rows and the wording, or tell me which rows to drop." The implementer opens the pull request and stops; the owner approves the matrix.

Notes for the implementer

• Mintlify heading ids differ from GitHub's; sync-sdk-docs.mjs already rewrites anchors (scripts/anchors.mjs). Do not hand-edit generated pages.
• redirects: the SDK moved sections between pages (G4a, G4b, G4c, G6, G7), so some deep links into old anchors on the site will land on the page top. Mintlify redirects work on paths, not on fragments, and no whole page was removed, so add no redirects. Say this in the pull request.
• Keep the table honest by default: "not checked" is an acceptable cell; a claim about a competitor that the audit marked inferred is not.
• No ticket ids (LOU-...) in the text you write.

---

Round 2 ticket G9a. Before starting, read the agent brief (worktree rules, verification list, live-test budget) and the plan. One ticket is one pull request; put Closes #<this issue> in it.

[LinuxDevil]

Starting G9a (model: Sonnet 5.5, 2026-10-02). Scope per orchestrator: comparison section deferred; G6 page not yet on SDK main; sync + navigation + pending-translation mechanism for every page on SDK main today.

[LinuxDevil]

G9a merged: LinuxDevil/agent-sdk-docs#6 (docs site synced to SDK main c3de073).

Done: 12 new pages and all restructured pages synced, English and Arabic navigation, ar/pending.json mechanism (--list-pending, --mark-pending; documented in README and scripts/TRANSLATING.md), coding-agents link to build-a-coding-agent. Pending Arabic pages show an Arabic notice linking the English page (stub if never translated).

Remaining (issue stays open):

• Comparison section in introduction/ar/introduction: deferred, needs the owner's approval of its rows.
• cloudflare-workers (G6) page: not on SDK main yet; add per the README "Adding a page later" steps.
• Arabic pending, 35 pages. New (12): build-a-coding-agent, executor-api, hooks, mcp, migrating-to-create-agent, models-and-cost, openapi-tools, queue-and-steer, runs, stream-events, triggers, troubleshooting. Stale (23): agent-forge, api-overview, approvals, channels, cli, compaction, configuration, durable-execution, errors, flows, guardrails, installation, observability, providers, quickstart, sessions, skills, streaming, structured-output, sub-agents, testing, tools, workspace-tools. Split between G9b/G9c/G9d as planned (node scripts/check-translations.mjs --list-pending).
• Two dead anchors in SDK docs: Docs: two links point to headings that do not exist (executor-api.md, troubleshooting.md) #288.

[LinuxDevil]

All scope items done: docs site synced to post-wave-4 SDK main (59 EN pages), navigation complete EN+AR, pending-translation mechanism in check-translations.mjs (61 pages, 0 pending/0 problems/0 stale), comparison section merged (agent-sdk-docs#11) with Arabic mirror in ar/introduction.mdx.