docs: migrate missing pages + re-sync drifted pages (issue #26)

[Steve-Dusty]

Summary

Addresses issue #26 (Docs audit: migrate/sync remaining pages from upstream swarms mkdocs nav).

Three things in this PR:

1. Migrate 13 missing pages from upstream that weren't yet in this repo
2. Re-sync 21 existing pages with upstream where upstream gained new content but local hadn't been editorially restructured
3. Fix 2 pre-existing broken links in prediction-markets pages (surfaced by mint broken-links)

Plus 2 upstream pages were verified-as-removed in upstream code and intentionally excluded.

What's in each commit

1. docs: migrate 13 missing pages from upstream (issue #26)

Group	New pages
API Reference	agent-mcp, custom-swarm, agent-registry, multi-agent-helpers, subagent-registry
Agent Development	agent-loader, agents-yaml, fallback-models, diy-memory
Third-Party Agents (new nav group)	new-agent, external-party-agents
Core Concepts	benefits, choosing-architecture

Each page migrated from upstream .md to Mintlify .mdx (frontmatter, admonitions → callouts, content tabs → <Tabs>, code-fence languages, link rewrites, MDX safety).

2. docs: fix 2 broken Card links to financial-analysis page

Both examples/finance/prediction-markets-{kalshi,polymarket}.mdx had a Card linking to /examples/finance/financial-analysis (which doesn't exist). The real page is at /examples/use-cases/financial-analysis. From merged PR #13. Surfaced by mint broken-links.

3. docs: re-sync 21 pages with upstream swarms (issue #26)

For files in issue #26's "should be re-synced" list where:

• Upstream has gained substantial new content (≥3 new H2 headings AND ≥30 new lines, or ≥1 new H2 AND ≥50 new lines)
• Local has no post-migration content edits (only the gpt-4o → claude-sonnet-4-6 swap from commit 548ae37)

Re-migrated from current upstream master. Local frontmatter (title, icon) preserved; description regenerated from new intro; gpt-4o → claude-sonnet-4-6 swap re-applied.

Group	Files
API Reference (14)	graph-workflow · social-algorithms · heavy-swarm · debate-with-judge · majority-voting · mixture-of-agents · spreadsheet-swarm · llm-council · auto-swarm-builder · multi-agent-execution-utilities · multi-agent-router · agent-router · swarm-router · hierarchical-swarm
Reasoning Agents (7)	reflexion-agent · gkp-agent · reasoning-duo · self-consistency-agent · agent-judge · reasoning-agents-overview · reasoning-agent-router

Excluded pages (intentionally not migrated)

Issue #26 entry	Reason
swarms/structs/maker.md → api/maker.mdx	Upstream mkdocs.yml references it but the file does not exist in the repo (404). Upstream commit 7d2bd1e7 removed the MAKER struct + source + docs together.
swarms/agents/openai_assistant.md → agents/openai-assistant.mdx	Same commit 7d2bd1e7 removed swarms/agents/openai_assistant.py, swarms/models/openai_assistant.py, and examples/single_agent/external_agents/openai_assistant_wrapper.py — but left docs/swarms/agents/openai_assistant.md orphaned. The class no longer exists in the library, so the doc isn't useful. Confirmed via grep -rn 'class OpenAIAssistant' swarms/ returning zero matches.

Deferred work (still on the #26 backlog after this PR)

These have drift but auto-re-syncing would be wrong — saved for human judgment:

3 AHEAD_LOCAL_EDIT — your post-migration content edits would be destroyed:

• api/sequential-workflow.mdx — your f3baeca sequential workflow streaming commit added streaming docs upstream doesn't have
• agents/agent-memory.mdx — your 5f7978f update memory docs rewrote it
• architectures/overview.mdx — your 3fbc58a clean up multi agent docs intentionally shortened it

5 LOCAL_BIGGER — local has more sections/structure than upstream (heavily editorialized by PRs #21/#23):
api/structs-overview, api/orchestration-methods, api/concurrent-workflow, api/model-router, api/skill-orchestra

17 REVIEW — mixed signals; both upstream and local have unique sections. Auto-overwriting either way loses content:
api/planner-worker-swarm, api/advisor-swarm, api/planner-generator-evaluator, api/round-robin-swarm, api/self-moa-seq, api/forest-swarm, api/council-as-judge, api/hierarchical-communication-framework, api/hhcs, api/swarm-matcher, api/swarm-rearrange, api/agent-rearrange, api/group-chat, api/batched-grid-workflow, agents/iterative-agent, agents/agent-skills, agents/structured-outputs

Verification

Cross-checked against upstream kyegomez/swarms at master head 64ccdc9e (2026-05-14):

• ✅ mint broken-links — no broken links across the entire docs site
• ✅ docs.json — valid JSON; every nav entry resolves to a file
• ✅ JSX tag balance — all 34 touched files have balanced <Tabs>/<Tab>/<Note>/<Tip>/<Warning>/<Info>/<Check>/<CardGroup>/<Card>
• ✅ No leftover mkdocs syntax (!!!, === ", :material-, :octicons-, <div class>)
• ✅ All documented classes exist in actual swarms source — verified via grep -rn 'class X' for AgentJudge, AgentLoader, AgentRegistry, AgentRouter, AutoSwarmBuilder, DebateWithJudge, GKPAgent, GraphWorkflow, HeavySwarm, HierarchicalSwarm, IterativeReflectiveExpansion, LLMCouncil, MajorityVoting, MixtureOfAgents, MultiAgentRouter, ReasoningAgentRouter, ReasoningDuo, ReflexionAgent, SelfConsistencyAgent, SocialAlgorithms, SpreadSheetSwarm, SubagentRegistry, SwarmRouter
• ✅ Constructor signatures spot-checked — actual __init__ args match documented param tables for HeavySwarm (17/17), LLMCouncil (7/7), SwarmRouter, MajorityVoting, DebateWithJudge, GraphWorkflow, HierarchicalSwarm, AgentRegistry, SubagentRegistry, AgentLoader
• ✅ Agent.__init__ confirmed to expose mcp_url, mcp_urls, mcp_config (for api/agent-mcp.mdx) and fallback_model_name, fallback_models (for agents/fallback-models.mdx)
• ✅ create_agents_from_yaml() referenced by agents-yaml.mdx exists at swarms/agents/create_agents_from_yaml.py:168
• ✅ All 4 multi-agent helper methods (talk_to, talk_to_multiple_agents, receive_message, send_agent_message) exist on the Agent class
• ✅ All re-synced files: zero remaining gpt-4o references (all swapped to claude-sonnet-4-6)

Stats

• 34 files changed (13 new + 21 re-synced + 2 broken-link fixes + docs.json)
• 3 logical commits for review clarity

Closes part of #26.

[Steve-Dusty]

This has been open since May and is conflicting again. Before spending a rebase on it, a note on shape, because I don't think it should land as one PR.

It's still needed. I checked the 13 added pages against main — agents/agent-loader.mdx, agents-yaml.mdx, diy-memory.mdx, external-party-agents.mdx, fallback-models.mdx, new-agent.mdx and the rest are all still missing, so the migration gap #26 describes is real and open.

But it's unreviewable as one change. +15,223 / −3,079 across 37 files mixes two different jobs:

1. 13 new pages migrated from the upstream mkdocs nav — additive, low risk, reviewable on their own.
2. 24 modified pages re-synced against drifted sources — each one a judgement call about what the current truth is, and the part that actually needs eyes.

Bundled together, the second job hides inside the first, and the diff conflicts with almost any docs change that lands meanwhile — which is why it has gone stale twice.

Proposal: close this in favour of a series — one PR adding the missing pages plus their docs.json entries, then one per drift cluster for the re-syncs. Same precedent as splitting #315 into #321–#324. Each piece stays reviewable and stops blocking the others.

Happy to do that split, or to rebase this as-is if you'd rather take it in one go — just say which.

[Steve-Dusty]

Re-verified this against main today rather than rebasing it blind. Three things changed since my August note, and one of them means this should not be merged in its current shape even if someone wanted to.

1. The gap is still real — all 13 pages

I checked every path this PR adds, by path, against main:

MISSING  agents/agent-loader.mdx        MISSING  api/agent-mcp.mdx
MISSING  agents/agents-yaml.mdx         MISSING  api/agent-registry.mdx
MISSING  agents/diy-memory.mdx          MISSING  api/custom-swarm.mdx
MISSING  agents/external-party-agents.mdx  MISSING  api/multi-agent-helpers.mdx
MISSING  agents/fallback-models.mdx     MISSING  api/subagent-registry.mdx
MISSING  agents/new-agent.mdx           MISSING  concepts/benefits.mdx
                                        MISSING  concepts/choosing-architecture.mdx

13 of 13. Nothing has been migrated in the meantime.

2. agent-loader would land twice — this is the blocker

main already has api/agent-loader.mdx (5,483 B). This PR adds agents/agent-loader.mdx (+788 lines). Merging as-is ships two agent-loader pages at two paths.

I missed this in August because I checked the destination paths and correctly found them missing, without checking whether the same page already existed somewhere else. It does.

It is worse than a plain duplicate: api/agent-loader.mdx is not in docs.json at all, so it is currently an unlinked page — which is exactly why it survived my check and every audit before it. Filed as #62 along with three more api/ pages in the same state (async-subagent, ma-blocks, swarming-architectures). That one needs deciding before this PR can add a second copy.

3. Issue #26 is closed, so this PR has no live target

#26 was closed as completed by @kyegomez on 2026-06-19, while the 13 pages it describes are still missing — see the list above. So either the audit was resolved some other way and this PR should be closed, or the issue was closed early and should be reopened. I have asked on #26 rather than guessing.

Where that leaves the PR

Unchanged from August, now with more reason: +15,223 / −3,079 across 37 files is two jobs in one diff — 13 additive new pages, and 24 re-synced pages that are each a judgement call about current truth. It has gone stale three times because it conflicts with almost any docs change that lands meanwhile, and it is conflicting again now.

I am not going to spend another rebase on it in this shape. What I would like to do instead, once #26's status is settled:

1. one PR: the 13 new pages plus their docs.json entries, with the agent-loader collision resolved per [Bug][nav][Four api/ pages exist on main but are absent from docs.json, so nothing links to them] #62;
2. one PR per drift cluster for the re-syncs.

Same precedent as splitting #315 into #321–#324. Happy to start on (1) the moment #26 is reopened or a replacement issue is confirmed — I would rather not open a PR against a closed issue.