Follow-up to PR #4771 surgical sync. The upstream reference/v2/* files
mirror shell-docs's canonical reference/ tree under a parallel
docs/-prefixed path that doesn't exist in shell-docs's routing. Syncing
them in creates duplicate parallel files. Block them from future sync
runs.
Per-file follow-up captured separately: mirror any legitimate content
updates from upstream's reference/v2 into the canonical reference/ tree
as needed (notably useCopilotKit.mdx, where the upstream version had 66
more lines than the current canonical).
The docs-sync workflow propagates upstream docs/content/docs/** changes
into showcase/shell-docs/src/content/docs/**. When shell-docs has
deliberately deleted/restructured pages, the existing PATH_EXCLUSIONS
mechanism prevents re-introduction.
PR #4771 surgical review surfaced 5 deliberate-deletion paths missing
from the exclusion list:
- (root)/index.mdx + (root)/quickstart.mdx — collapsed into a single
shell-docs '/' route in commit 8adbebd30 ('merge docs landing +
/quickstart picker').
- (root)/prebuilt-components.mdx — top-level single-file version is
duplicative of the prebuilt-components/ directory + index.
- integrations/{langgraph,microsoft-agent-framework}/index.mdx —
framework landing files collapsed into the canonical /<fw>/ route in
commit d1cd9f06a ('collapse framework landing into shell').
Adding these to PATH_EXCLUSIONS so future docs-sync runs don't re-flag
them as upstream-wins conflicts.
## Summary
Cleans up shell-docs after PR #4521 reintroduced content earlier PRs
intentionally retired, adds a Deploy section with an inlined AWS
AgentCore guide using a custom command-tabs component, and hardens the
sync script against future regressions of the same shape.
## Changes
### Deploy section + AgentCore page (custom UX)
- New `<AgentCoreCommandTabs />` component — framework-aware command
tabs with hljs highlighting and copy buttons, built on shell-docs's own
`<Tabs>`/`<Tab>` primitives. Upstream's version depends on fumadocs-ui,
which shell-docs doesn't install.
- Replaces main's `<Content />` stub at `/deploy/agentcore` with the
full inlined guide.
- Wires the Deploy section into the root sidebar via `deploy/meta.json`
+ a `---Deploy---` group in `meta.json`.
- Registers the component in `mdx-registry.tsx`.
### Remove duplicates reintroduced by the upstream sync
- Delete
`learn/{index,intelligence-platform,threads,tutorials/multi-conversation-chat}.mdx`.
Canonical homes are at `/premium/intelligence-platform`,
`/premium/threads-explained`, and `/tutorials/multi-conversation-chat`.
`next.config.ts` already redirects `/learn/*` to those destinations.
- Delete root `ag-ui-middleware.mdx`. Canonical home is
`/agentic-protocols/ag-ui-middleware`. `next.config.ts` already
redirects `/ag-ui-middleware`.
### Harden sync script
Add `PATH_EXCLUSIONS` regexes so next sync runs don't bring these paths
back:
- `docs/content/docs/learn/`
- `docs/content/docs/(root)/ag-ui-middleware.mdx`
- Orphan shared-state files:
`langgraph/shared-state/workflow-execution`,
`adk/shared-state/{workflow-execution,state-inputs-outputs}`,
`llamaindex/shared-state/state-inputs-outputs`
- AgentCore upstream sources (root shell, per-framework
`deploy-agentcore.mdx`, shared snippet) — shell-docs owns the canonical
inlined version
### Optional schema migrations Step
Adds an opt-in `(Optional) Enable schema migrations` Step to
`premium/self-hosting.mdx` covering `migrations.enabled: true` in the
Helm values + the verification behavior.
## Test plan
- [ ] `/deploy/agentcore` renders the inlined guide; both
`<AgentCoreCommandTabs />` blocks show framework tabs with highlighted
bash and a working copy button
- [ ] Deploy appears as a sidebar group between Premium and What's New
- [ ] `/learn/threads`, `/learn/intelligence-platform`,
`/learn/tutorials/multi-conversation-chat`, and `/learn` all redirect to
their canonical destinations (no longer 200 with duplicate content)
- [ ] `/ag-ui-middleware` redirects to
`/agentic-protocols/ag-ui-middleware`
- [ ] The optional schema migrations Step renders in
`/premium/self-hosting` between the secrets Step and the
install-the-chart Step
- [ ] Next dry-run of `sync-docs-from-main.ts` does not flag the
newly-excluded paths
PATH_EXCLUSIONS is the durable mechanism for keeping retired upstream
paths out of shell-docs, but it requires the person retiring a page to
also add the regex — and that step has been missed (#4521 brought back
/learn/* and root /ag-ui-middleware.mdx after earlier PRs intentionally
removed them).
Add a safety net: before writing each upstream file, check if its target
shell-docs path exists in git's deletion history and isn't currently on
disk. If so, surface it in the auto-PR's review-items.txt under a new
'Files re-introduced from shell-docs deletion history' section and
include reintroduced.length in hasReviewItems so the PR is flagged
needs-review (exit 3) instead of auto-merged.
Doesn't block the write — content is still synced, the detector is
informational. The fix loop is: human reviews, decides intent. If
unwanted, add a PATH_EXCLUSIONS regex and delete the file; next sync
the detector picks it up again until the regex is in place.
Verified locally — current dry-run flags 3 real findings (root/index,
langgraph/index, microsoft-agent-framework/index) that were deleted in
favor of meta.json folder pages.
The previous sync brought back /learn/*, root /ag-ui-middleware.mdx, the
upstream AgentCore 3-shell + shared snippet, and several orphan
shared-state files that shell-docs deliberately doesn't carry. Add
matching PATH_EXCLUSIONS so future syncs don't reintroduce them.
Not bumping .docs-sync-sha — the previous sync's sha is still accurate
and the new exclusions take effect on the next run.
24 files in two byte-identical families across 12 integration trees:
- 12 `integrations/<fw>/threads.mdx` — 7 lines each, all md5 0371508d…,
body is just `<Threads />`.
- 12 `integrations/<fw>/premium/self-hosting.mdx` — 8 lines each, all
md5 06d17f98…, body is just `<SelfHosting />`.
Both render shared snippets the root-level pages already render. The
`buildFrameworkOverridesNav` filter dropped them from the merged
sidebar (root wins), and the framework-scoped router falls back to
root MDX when no per-framework override exists, so deletion is
invisible to users — `/built-in-agent/threads`,
`/langgraph-python/premium/self-hosting`, etc. continue to render
identically. Verified: each URL still returns 200 with full body
(340–465 KB) by curling the dev server before commit.
Add path-exclusion patterns to sync-docs-from-main.ts so future
upstream syncs don't resurrect them. Same shape as the BIA branch's
`(other)/` exclusion. Sample-tested the regexes against expected-
exclude and expected-keep paths — all classify correctly.
Audit covered every `integrations/<fw>/*.mdx` with body ≤ 2 non-blank
lines; no false-negative stubs of other shapes.
Every framework under integrations/<fw>/ shipped its own copy of
contributing/ + telemetry/ content that was byte-identical (or
trivially divergent — a stray "cd" path, a legacy CLI name) to the
canonical copy at root (other)/. The duplicates were stale sync
artifacts with no framework-specific content: "how to contribute to
CopilotKit" and "how to configure telemetry" don't vary by agent
framework.
Beyond disk clutter (~2.5k lines across 8 frameworks), the duplicates
surfaced as a "Other" group nested under the framework-scoped
sidebar section whenever the merged nav built from meta.json — a
second copy of root's own "Other" section at the bottom of the
sidebar. Deleting the trees makes that UI bug disappear without any
filter patching.
Scope:
- Remove integrations/<fw>/(other)/ trees for ag2, agno, aws-strands,
crewai-flows, langgraph, llamaindex, mastra, microsoft-agent-framework.
- Drop ---Other--- + ...(other) entries from each framework's meta.json.
- Add a path-exclusion filter in sync-docs-from-main.ts so the next
sync run doesn't resurrect the subtrees when upstream edits touch
them. Upstream keeps its copies (removing them there means touching
all 13 parallel framework trees, out of scope for this branch).
MDX docs moved from shell to shell-docs, but several generated artifacts
are still consumed by both shells:
- registry.json: shell uses it (home grid, integrations, matrix,
middleware, layout); shell-docs uses it (docs renderer framework lookup)
- demo-content.json: shell uses it (integrations/[slug]/[demo]); shell-docs
uses it (<Snippet> in docs renderer)
- search-index.json: shell-docs consumes it for the docs search modal;
shell also keeps a copy so its header search still works — links 301
across to docs.showcase.copilotkit.ai.
Updated scripts:
- generate-registry.ts: dual-emits registry.json to both shells
(constraints.json stays shell-only — integration-explorer is shell)
- bundle-demo-content.ts: dual-emits demo-content.json
- generate-search-index.ts: scans from shell-docs/src/content (where MDX
now lives), writes to both shells' data dirs
- probe-docs.ts: scans shell-docs/src/content/docs (content source moved),
still writes docs-status.json under shell/ for the dashboard
- sync-docs-from-main.ts: target path updated to shell-docs/src/content
Tests in __tests__/ reference shell/src/data paths; dual-emit keeps
those stable so existing afterEach-restore hooks continue to work.
Sam Julien