chore(docs): add shell-docs symlink

.claude/docs/documentation.md

@@ -72,10 +72,11 @@ file with frontmatter into the right subdirectory; it appears in nav on its own.
 legacy `reference/v1/` tree uses `meta.json`. For the full new-hook checklist see
 [Hook Development](hooks.md).
 
-**The top-level `docs/` folder is retired and removed from `main`. Never recreate it.**
-The old `docs/content/docs/` tree and `docs/` Next app no longer publish anything.
-Historical content remains recoverable from the archive refs:
-`archive/docs-save-do-not-prune` and `archive/docs-retired-2026-06-17`.
+**The top-level `docs/` path is only a symlink to `showcase/shell-docs/`.**
+It exists for `cd docs` muscle memory, not as a separate docs app. The old
+`docs/content/docs/` tree and retired Next app no longer publish anything. Historical
+content remains recoverable from the archive refs: `archive/docs-save-do-not-prune` and
+`archive/docs-retired-2026-06-17`.
 
 ## 2. AG-UI protocol docs → upstream `ag-ui-protocol/ag-ui`
 

.claude/docs/hooks.md

@@ -8,4 +8,5 @@ When creating a new hook, always complete **all** of the following:
 4. **API reference**: Add a reference page at `showcase/shell-docs/src/content/reference/hooks/<hookName>.mdx` with `title` and `description` frontmatter. The v2 reference navigation is generated automatically by walking the `reference/` tree and reading frontmatter (see `showcase/shell-docs/src/lib/reference-items.ts`) — there is **no `meta.json`** to edit for v2 reference; the file and its frontmatter are the metadata. (Only the legacy `reference/v1/` tree uses `meta.json`.)
 5. **Conceptual docs (if needed)**: If the hook needs usage/how-to documentation beyond the API reference, add a guide page under `showcase/shell-docs/src/content/docs/` and update that section's `meta.json` so it appears in navigation.
 
-Never recreate the retired top-level `docs/` folder. See [Documentation](documentation.md).
+Never recreate the retired `docs/content/docs/` tree. The top-level `docs/` path is only
+a symlink to shell-docs. See [Documentation](documentation.md).

AGENTS.md

@@ -25,7 +25,7 @@ AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → *
 - **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
 - **Commit as you go** — every meaningful unit of work gets its own commit, pushed immediately. Don't let untracked files accumulate across a session. Tests belong in the commit that introduces the code being tested. Full rules in [Git & PRs](.claude/docs/git.md#commit-early-and-often-in-logical-chunks).
 - **Draft PR up front** — the moment a new branch has one commit, push it and open a **draft PR**. Don't wait until "ready" — unmerged-and-unpushed work is invisible. Flip the PR from draft to ready (`gh pr ready <pr#>`) only when the developer says so. See [Git & PRs](.claude/docs/git.md#open-a-draft-pr-up-front).
-- **Documentation lives in shell-docs** — author CopilotKit docs in `showcase/shell-docs/src/content/`. The retired top-level `docs/` app has been removed from `main`; never recreate it for live documentation. AG-UI protocol docs are authored upstream in `ag-ui-protocol/ag-ui`, not directly in this repo. See [Documentation](.claude/docs/documentation.md).
+- **Documentation lives in shell-docs** — author CopilotKit docs in `showcase/shell-docs/src/content/`. The top-level `docs/` path is only a symlink to `showcase/shell-docs/`; never recreate the old `docs/content/docs/` tree for live documentation. AG-UI protocol docs are authored upstream in `ag-ui-protocol/ag-ui`, not directly in this repo. See [Documentation](.claude/docs/documentation.md).
 
 ## Private Agent Instructions
 
@@ -44,7 +44,7 @@ If you need a skill and don't have the plugin installed, clone the repo and read
 
 ## Documentation Editing
 
-Before editing anything that looks like product docs, read [Documentation](.claude/docs/documentation.md) and the local README for the docs area you are touching. The live docs source is **not** the removed top-level `docs/` app.
+Before editing anything that looks like product docs, read [Documentation](.claude/docs/documentation.md) and the local README for the docs area you are touching. The live docs source is **`showcase/shell-docs/`**; top-level `docs/` is only a symlink there.
 
 - **CopilotKit product docs** live under `showcase/shell-docs/src/content/`:
   - Guides, how-tos, and concepts: `showcase/shell-docs/src/content/docs/`
@@ -58,7 +58,7 @@ Before editing anything that looks like product docs, read [Documentation](.clau
 - For authored frameworks (`docs_mode: authored`), edit `showcase/shell-docs/src/content/docs/integrations/<docsFolder>/` and its `meta.json`.
 - For snippets, edit `showcase/shell-docs/src/content/snippets/`; snippets can feed root docs, authored framework pages, and showcase-driven framework pages.
 - **AG-UI protocol docs** are canonical upstream in `ag-ui-protocol/ag-ui`. The `showcase/shell-docs/src/content/ag-ui/` tree is a downstream mirror; change AG-UI upstream first, then sync the mirror back.
-- **Do not recreate top-level `docs/`**. The retired Next app no longer publishes to `docs.copilotkit.ai`. Historical content is available from the archive branch/tag, not from `main`.
+- **Do not recreate `docs/content/docs/`**. Top-level `docs/` is only a symlink to shell-docs. The retired Next app no longer publishes to `docs.copilotkit.ai`. Historical content is available from the archive branch/tag, not from `main`.
 - To run shell-docs locally, follow `showcase/shell-docs/README.md` and use the shell-docs npm commands.
 
 ## Reference (read when relevant to your task)

CLAUDE.md

@@ -23,7 +23,7 @@ AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → *
 - **Flat package structure** — all packages live directly under `packages/` (no `v1/` or `v2/` subdirectories). Every package uses the `@copilotkit/` scope.
 - **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
 - **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
-- **Documentation lives in shell-docs** — author all CopilotKit docs in `showcase/shell-docs/src/content/`. The retired top-level `docs/` app has been removed from `main`; never recreate it. AG-UI protocol docs are authored upstream in `ag-ui-protocol/ag-ui`, not here. See [Documentation](.claude/docs/documentation.md).
+- **Documentation lives in shell-docs** — author all CopilotKit docs in `showcase/shell-docs/src/content/`. The top-level `docs/` path is only a symlink to `showcase/shell-docs/`; never recreate the old `docs/content/docs/` tree. AG-UI protocol docs are authored upstream in `ag-ui-protocol/ag-ui`, not here. See [Documentation](.claude/docs/documentation.md).
 
 ## Reference (read when relevant to your task)
 

CONTRIBUTING.md

@@ -31,7 +31,7 @@ If you don't feel ready to make a code contribution yet, no problem! You can als
 
 There are two documentation domains — make sure your change goes to the right place, or it won't reach the live site:
 
-- **CopilotKit docs** (docs.copilotkit.ai) are authored in **`showcase/shell-docs/src/content/`** (`docs/`, `reference/`, `snippets/`, `framework-overviews/`). When adding a page, update the relevant `meta.json` so it appears in navigation. The retired top-level `docs/` app has been removed from `main`; do not recreate it.
+- **CopilotKit docs** (docs.copilotkit.ai) are authored in **`showcase/shell-docs/src/content/`** (`docs/`, `reference/`, `snippets/`, `framework-overviews/`). When adding a page, update the relevant `meta.json` so it appears in navigation. Top-level `docs/` is only a symlink to `showcase/shell-docs/`; do not recreate the old `docs/content/docs/` tree.
 - **AG-UI protocol docs** (docs.ag-ui.com) are authored upstream in [`ag-ui-protocol/ag-ui`](https://github.com/ag-ui-protocol/ag-ui), not in this repo. The `showcase/shell-docs/src/content/ag-ui/` copy is a downstream mirror.
 
 # How do I make a code contribution?

docs

@@ -0,0 +1 @@
+showcase/shell-docs

showcase/shell-docs/README.md

@@ -92,7 +92,8 @@ AG-UI protocol docs are authored upstream in `ag-ui-protocol/ag-ui`. The
 `src/content/ag-ui/` tree is a downstream mirror rendered on the CopilotKit docs host.
 Change AG-UI docs upstream first, then sync the mirror back into shell-docs.
 
-## Removed Top-Level Docs
+## Top-Level Docs Symlink
 
-The repository's retired top-level `docs/` app and `docs/content/docs/` tree have been
-removed from `main`. Do not recreate them. Use `showcase/shell-docs/src/content/` instead.
+The repository's top-level `docs/` path is a symlink to `showcase/shell-docs/` for
+contributor muscle memory. It is not a separate docs app. Do not recreate the old
+`docs/content/docs/` tree; author CopilotKit docs in `showcase/shell-docs/src/content/`.