From 4c311ac3fb6798b1cbbc7c9149bfabffd14ec4a4 Mon Sep 17 00:00:00 2001 From: Sam Julien Date: Thu, 18 Jun 2026 14:54:25 -0700 Subject: [PATCH] chore(docs): add shell-docs symlink --- .claude/docs/documentation.md | 9 +++++---- .claude/docs/hooks.md | 3 ++- AGENTS.md | 6 +++--- CLAUDE.md | 2 +- CONTRIBUTING.md | 2 +- docs | 1 + showcase/shell-docs/README.md | 7 ++++--- 7 files changed, 17 insertions(+), 13 deletions(-) create mode 120000 docs diff --git a/.claude/docs/documentation.md b/.claude/docs/documentation.md index fabfa25e5c..33ed2cd222 100644 --- a/.claude/docs/documentation.md +++ b/.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` diff --git a/.claude/docs/hooks.md b/.claude/docs/hooks.md index 21400cde8f..6862d5ba0c 100644 --- a/.claude/docs/hooks.md +++ b/.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/.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). diff --git a/AGENTS.md b/AGENTS.md index f51fa1d405..343f18179d 100644 --- a/AGENTS.md +++ b/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 `) 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//` 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) diff --git a/CLAUDE.md b/CLAUDE.md index 7eec14ff78..516f61df5b 100644 --- a/CLAUDE.md +++ b/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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 15015e7882..67c4cd6326 100644 --- a/CONTRIBUTING.md +++ b/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? diff --git a/docs b/docs new file mode 120000 index 0000000000..4ca4e79bd4 --- /dev/null +++ b/docs @@ -0,0 +1 @@ +showcase/shell-docs \ No newline at end of file diff --git a/showcase/shell-docs/README.md b/showcase/shell-docs/README.md index a82b294835..00cbc25aac 100644 --- a/showcase/shell-docs/README.md +++ b/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/`.