fix(guides): keep catalog out of the plugin skills tree

.agents/skills/ce-skill-work/references/new-skill.md

@@ -29,7 +29,7 @@ Contrast pair (the only description example):
 
 ## Repo inventory (all in the same change)
 
-A user-facing skill needs: `skills/guides/<name>.md` (purpose, novel mechanics, when to use, chain position), a catalog row in `skills/guides/README.md`, a root `README.md` inventory row, and the skill-count bump in `tests/release-metadata.test.ts`. Run `bun run release:validate` and `bun run test`.
+A user-facing skill needs: `docs/guides/<name>.md` (purpose, novel mechanics, when to use, chain position), a catalog row in `docs/guides/README.md`, a root `README.md` inventory row, and the skill-count bump in `tests/release-metadata.test.ts`. Run `bun run release:validate` and `bun run test`.
 
 ## Validate
 

AGENTS.md

@@ -63,7 +63,7 @@ bun run codex:dev -- remove   # remove both supported CE installation surfaces
 ```
 src/              CLI entry point, parsers, converters, target writers
 skills/           Compound Engineering plugin skills
-skills/guides/    User-facing skill catalog
+docs/guides/      User-facing plugin guides (catalog and configuration)
 .claude-plugin/   Claude plugin manifest and marketplace catalog metadata
 .codex-plugin/    Codex plugin manifest
 .cursor-plugin/   Cursor plugin manifest and marketplace catalog metadata
@@ -89,8 +89,8 @@ Do not assume a repo change is "just CLI" or "just plugin" without checking whic
 When changing plugin content:
 
 - Update substantive docs like `README.md` when the plugin behavior, inventory, or usage changes.
-- When adding a user-facing skill, document it: create a `skills/guides/<skill-name>.md` page (purpose, novel mechanics, when to use, chain position — follow the shape of the existing pages), add a catalog row under the right category in `skills/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. `skills/guides/README.md` is the **only** place a skill's prose description is maintained. The root `README.md` carries a grouped overview that lists skill *names* under a category, so a new skill also needs its name added to the right group row and the three stated skill counts bumped (badge, intro, section lead). `tests/release-metadata.test.ts` enforces that every skill name appears in that overview exactly once, that no unknown name appears, and that the three counts match the skill directories under `skills/` (each with a `SKILL.md`) — so the suite catches a missing name, a stale count, or a name left behind during a move. Choosing the *right* group is yours; a test that knew the correct category per skill would be the second inventory this arrangement exists to avoid — the previous three-way sync of full descriptions was unenforced and had already drifted, which is why descriptions now live in exactly one place. Every current user-facing skill has a page, including `lfg` and `ce-dogfood`.
-- When adding, removing, renaming, or changing the meaning/default/consumer of a `.compound-engineering/config.yaml` option, update `skills/ce-setup/references/config-template.yaml`, its byte-identical `.compound-engineering/config.example.yaml` copy, the centralized `skills/guides/configuration.md` reference, and the affected consumer skill docs in the same change. Ordinary keys may also live in optional checkout-local `config.local.yaml` (overrides the repo file). `docs_root` belongs only in `config.yaml`. Durable team instructions still belong in the project's normal agent-instructions mechanism.
+- When adding a user-facing skill, document it: create a `docs/guides/<skill-name>.md` page (purpose, novel mechanics, when to use, chain position — follow the shape of the existing pages), add a catalog row under the right category in `docs/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`. `docs/guides/README.md` is the **only** place a skill's prose description is maintained. The root `README.md` carries a grouped overview that lists skill *names* under a category, so a new skill also needs its name added to the right group row and the three stated skill counts bumped (badge, intro, section lead). `tests/release-metadata.test.ts` enforces that every skill name appears in that overview exactly once, that no unknown name appears, and that the three counts match the skill directories under `skills/` (each with a `SKILL.md`) — so the suite catches a missing name, a stale count, or a name left behind during a move. Choosing the *right* group is yours; a test that knew the correct category per skill would be the second inventory this arrangement exists to avoid — the previous three-way sync of full descriptions was unenforced and had already drifted, which is why descriptions now live in exactly one place. Every current user-facing skill has a page, including `lfg` and `ce-dogfood`.
+- When adding, removing, renaming, or changing the meaning/default/consumer of a `.compound-engineering/config.yaml` option, update `skills/ce-setup/references/config-template.yaml`, its byte-identical `.compound-engineering/config.example.yaml` copy, the centralized `docs/guides/configuration.md` reference, and the affected consumer skill docs in the same change. Ordinary keys may also live in optional checkout-local `config.local.yaml` (overrides the repo file). `docs_root` belongs only in `config.yaml`. Durable team instructions still belong in the project's normal agent-instructions mechanism.
 - Do not hand-bump release-owned versions in plugin or marketplace manifests.
 - Do not hand-add release entries to `CHANGELOG.md` or treat it as the canonical source for new releases.
 - Run `bun run release:validate` if agents, commands, skills, MCP servers, or release-owned descriptions/counts may have changed.
@@ -343,6 +343,7 @@ So: a skill's *core* behavior **can** live in a bundled script across hosts —
 
 ## Repository Docs Convention
 
+- **Guides** live in `docs/guides/` — the user-facing skill catalog and configuration reference. Keep them here, not under `skills/`, so they do not ship inside the plugin package.
 - **Plans** live in `docs/plans/` — unified plan artifacts. New `ce-brainstorm` outputs are requirements-only unified plans (`artifact_readiness: requirements-only`); `ce-plan` enriches them to implementation-ready plans (`artifact_readiness: implementation-ready`). Historical `docs/brainstorms/*-requirements.*` files remain readable legacy inputs and should not be migrated just because a new plan is created.
 - **Brainstorm evidence / legacy requirements** may live in `docs/brainstorms/` — historical requirements docs and specialized analysis artifacts such as `docs/brainstorms/riffrec-feedback/`. Do not treat this as the canonical output path for new `ce-brainstorm` artifacts.
 - **Solutions** live in `docs/solutions/` — documented solutions to past problems (bugs, best practices, workflow patterns), organized by category with YAML frontmatter (`module`, `tags`, `problem_type`). Relevant when implementing or debugging in documented areas.

CONTRIBUTING.md

@@ -35,7 +35,7 @@ Do not hand-bump versions in plugin or marketplace manifests, and do not hand-wr
 
 Skills live in `skills/<name>/SKILL.md` and are authored once, then distributed to every supported host. That makes them different from ordinary code: a skill is a set of goals, not a state machine, and it has to work on harnesses with different capabilities. Read `AGENTS.md` before changing anything under `skills/`.
 
-When you add a user-facing skill, document it: add a `skills/guides/<skill-name>.md` page and a catalog row in `skills/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`.
+When you add a user-facing skill, document it: add a `docs/guides/<skill-name>.md` page and a catalog row in `docs/guides/README.md`, and bump the skill count in `tests/release-metadata.test.ts`.
 
 ## Reporting security issues
 

README.md

@@ -8,7 +8,7 @@
 
 [![Build Status](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/EveryInc/compound-engineering-plugin/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-black.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-33-black.svg)](skills/guides/README.md)
+[![Skills](https://img.shields.io/badge/skills-33-black.svg)](docs/guides/README.md)
 
 </div>
 
@@ -125,12 +125,12 @@ The core loop is six steps: **brainstorm** the requirements, **plan** the implem
 
 | Skill | Purpose |
 |-------|---------|
-| [`/ce-brainstorm`](skills/guides/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning |
-| [`/ce-plan`](skills/guides/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans |
-| [`/ce-work`](skills/guides/ce-work.md) | Execute implementation-ready plans natively or through a qualified cross-model author while retaining host verification, commits, and shipping |
-| [`/ce-simplify-code`](skills/guides/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review |
-| [`/ce-code-review`](skills/guides/ce-code-review.md) | Report-only multi-agent review against the plan before merging; local apply is explicit |
-| [`/ce-compound`](skills/guides/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter |
+| [`/ce-brainstorm`](docs/guides/ce-brainstorm.md) | Interactive Q&A to think through a feature or problem and write a requirements-only unified plan before planning |
+| [`/ce-plan`](docs/guides/ce-plan.md) | Enrich feature ideas or requirements-only plans into implementation-ready plans |
+| [`/ce-work`](docs/guides/ce-work.md) | Execute implementation-ready plans natively or through a qualified cross-model author while retaining host verification, commits, and shipping |
+| [`/ce-simplify-code`](docs/guides/ce-simplify-code.md) | Refine the freshly written code for clarity and reuse before review |
+| [`/ce-code-review`](docs/guides/ce-code-review.md) | Report-only multi-agent review against the plan before merging; local apply is explicit |
+| [`/ce-compound`](docs/guides/ce-compound.md) | Capture the learning into `docs/solutions/` so the next loop starts smarter |
 
 Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainstorm` and `/ce-plan` read as grounding -- brainstorms sharpen plans, plans inform future plans, reviews catch more issues, patterns get documented. That return arrow is the whole point.
 
@@ -140,7 +140,7 @@ Each cycle compounds: `/ce-compound` writes learnings that the next `/ce-brainst
 
 <sub>Replayed from a real pair of sessions 18 days apart, with names and paths anonymized and the six-minute run compressed to about 30 seconds. Nothing shown is behavior the skills don't have — see <a href="assets/demo/README.md">assets/demo</a> for the source and the substitutions.</sub>
 
-> Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](skills/guides/configuration.md#artifact-root).
+> Artifact folders like `docs/solutions/` and `docs/plans/` are the **defaults**. A project whose `docs/` is tracked content can relocate every CE artifact folder under one repo-relative root via the `docs_root` setting -- see [configuration](docs/guides/configuration.md#artifact-root).
 
 ## Try it
 
@@ -166,26 +166,26 @@ After installing, run `/ce-setup` in any project. It reports optional tool capab
 
 `/lfg` runs the loop hands-off: it plans, works through the plan, simplifies, runs code review and applies the fixes, runs browser tests, then commits. When a git remote exists it pushes, opens a PR, and watches CI with a bounded repair loop (it does not merge, and it can finish with leftovers if the repair budget is hit). With no remote it stops at local commits. Start it after `/ce-brainstorm` so it plans against real requirements rather than a one-line prompt.
 
-Starting from a bug instead of a feature? Use [`/ce-debug`](skills/guides/ce-debug.md). Not sure what to build yet? Start with [`/ce-ideate`](skills/guides/ce-ideate.md).
+Starting from a bug instead of a feature? Use [`/ce-debug`](docs/guides/ce-debug.md). Not sure what to build yet? Start with [`/ce-ideate`](docs/guides/ce-ideate.md).
 
 ## Skills at a glance
 
-33 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[skills/guides](skills/guides/README.md)**.
+33 skills, grouped by what they are for. The full catalog, with a page per skill and how each one chains into the others, is in **[docs/guides](docs/guides/README.md)**.
 
 | Group | Skills | What it covers |
 |-------|--------|----------------|
-| [Core loop](skills/guides/README.md#the-core-loop) | `ce-brainstorm` `ce-plan` `ce-work` `ce-simplify-code` `ce-code-review` `ce-compound` | The six steps of every iteration |
-| [Around the loop](skills/guides/README.md#around-the-loop) | `ce-strategy` `ce-product-pulse` `ce-sweep` `ce-compound-refresh` | Anchors and feeds that keep the loop grounded |
-| [On demand](skills/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` | Reached for when a specific need arises |
-| [Git workflow](skills/guides/README.md#git-workflow) | `ce-commit` `ce-commit-push-pr` `ce-babysit-pr` `ce-resolve-pr-feedback` `ce-worktree` | Committing, shipping, and shepherding PRs |
-| [Autonomous](skills/guides/README.md#autonomous-pipeline) | `lfg` | The whole pipeline, hands-off |
-| [Testing & design](skills/guides/README.md#frontend-design) | `ce-test-browser` `ce-test-xcode` `ce-polish` `ce-dogfood` | Verifying and polishing what you built |
-| [Collaboration](skills/guides/README.md#collaboration) | `ce-proof` `ce-handoff` `ce-promote` | Sharing work and handing it off |
-| [Utilities](skills/guides/README.md#workflow-utilities) | `ce-setup` `ce-retune` `ce-riffrec-feedback-analysis` | Setup and maintenance |
+| [Core loop](docs/guides/README.md#the-core-loop) | `ce-brainstorm` `ce-plan` `ce-work` `ce-simplify-code` `ce-code-review` `ce-compound` | The six steps of every iteration |
+| [Around the loop](docs/guides/README.md#around-the-loop) | `ce-strategy` `ce-product-pulse` `ce-sweep` `ce-compound-refresh` | Anchors and feeds that keep the loop grounded |
+| [On demand](docs/guides/README.md#on-demand) | `ce-ideate` `ce-pov` `ce-debug` `ce-explain` `ce-doc-review` `ce-optimize` `ce-prototype` | Reached for when a specific need arises |
+| [Git workflow](docs/guides/README.md#git-workflow) | `ce-commit` `ce-commit-push-pr` `ce-babysit-pr` `ce-resolve-pr-feedback` `ce-worktree` | Committing, shipping, and shepherding PRs |
+| [Autonomous](docs/guides/README.md#autonomous-pipeline) | `lfg` | The whole pipeline, hands-off |
+| [Testing & design](docs/guides/README.md#frontend-design) | `ce-test-browser` `ce-test-xcode` `ce-polish` `ce-dogfood` | Verifying and polishing what you built |
+| [Collaboration](docs/guides/README.md#collaboration) | `ce-proof` `ce-handoff` `ce-promote` | Sharing work and handing it off |
+| [Utilities](docs/guides/README.md#workflow-utilities) | `ce-setup` `ce-retune` `ce-riffrec-feedback-analysis` | Setup and maintenance |
 
 **Learn more**
 
-- [Skill documentation catalog](skills/guides/README.md)
+- [Skill documentation catalog](docs/guides/README.md)
 - [Compound engineering: how Every codes with agents](https://every.to/chain-of-thought/compound-engineering-how-every-codes-with-agents)
 - [The story behind compounding engineering](https://every.to/source-code/my-ai-had-already-fixed-the-code-before-i-saw-it)
 
@@ -418,7 +418,7 @@ No. Bun is only needed for repo development tasks and converter maintenance.
 
 ### Where do I see all available skills?
 
-The grouped overview is [above](#skills-at-a-glance); the full catalog with a page per skill is [`skills/guides/README.md`](skills/guides/README.md). Each skill's authoritative runtime spec lives in `skills/<skill>/SKILL.md`.
+The grouped overview is [above](#skills-at-a-glance); the full catalog with a page per skill is [`docs/guides/README.md`](docs/guides/README.md). Each skill's authoritative runtime spec lives in `skills/<skill>/SKILL.md`.
 
 ### Where is release history?
 
@@ -432,8 +432,8 @@ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for setup, and [`docs/development.md`](
 
 | | |
 |---|---|
-| [Skill catalog](skills/guides/README.md) | A page per skill, and how they chain together |
-| [Configuration](skills/guides/configuration.md) | `.compound-engineering/config.yaml` options |
+| [Skill catalog](docs/guides/README.md) | A page per skill, and how they chain together |
+| [Configuration](docs/guides/configuration.md) | `.compound-engineering/config.yaml` options |
 | [Installing](#install) · [Upgrading](docs/install/upgrading.md) | Per-host install and refresh |
 | [Contributing](CONTRIBUTING.md) · [Development](docs/development.md) | Working on the plugin itself |
 | [Security](SECURITY.md) · [Privacy](PRIVACY.md) | Reporting and data handling |

docs/solutions/skill-design/authoring-auto-invoke-standing-instructions.md

@@ -70,7 +70,7 @@ Apply when adding a "Make It Automatic" section to any CE skill's docs page, or
 
 The self-guard is verifiable: a cross-host routing eval (5 resolved-scope scenarios × Claude + Codex, fresh subagents reading the on-disk `SKILL.md`) scored 10/10 — docs-only and lockfile/generated scopes short-circuited, a mixed diff narrowed to its code file, and both a ~5-line explicit-scope case and a normal code diff ran, confirming the guard keys on change kind, not size.
 
-Standing-instruction shape (auto-run variant; the dedicated "Make It Automatic" heading was later folded into a short standing-instruction paragraph on `skills/guides/ce-simplify-code.md`):
+Standing-instruction shape (auto-run variant; the dedicated "Make It Automatic" heading was later folded into a short standing-instruction paragraph on `docs/guides/ce-simplify-code.md`):
 
 > When you finish a coherent unit of work — a feature is complete, or you're wrapping up to open a PR — and before you review, commit, or hand it off, automatically invoke the `ce-simplify-code` skill on the changed code. Do this at that completion checkpoint only, not after every individual edit or intermediate fix while you're still building. Run it only when the accumulated diff has at least 10 substantive code lines and the skill hasn't already run since the last code edit. Never run it for documentation- or Markdown-only changes; formatting-, lint-, or dependency/lockfile-only changes; generated or vendored files; other purely mechanical changes; or code you've said to keep as written.
 
@@ -81,4 +81,4 @@ Skill-side preflight (from `skills/ce-simplify-code/SKILL.md` Step 1): if the re
 - [`portable-agent-skill-authoring.md`](./portable-agent-skill-authoring.md) — the canonical cross-model/cross-harness authoring guide these phrasing rules instantiate
 - [`discoverability-check-for-documented-solutions.md`](./discoverability-check-for-documented-solutions.md) — the sibling pattern of a skill making a small, principled edit to an instruction file
 - [`post-menu-routing-belongs-inline.md`](./post-menu-routing-belongs-inline.md) — related SKILL.md authoring-placement discipline
-- `ce-compound`'s "Make Capture Automatic" section (`skills/guides/ce-compound.md`, PR #1110) — the pattern this generalizes
+- `ce-compound`'s "Make Capture Automatic" section (`docs/guides/ce-compound.md`, PR #1110) — the pattern this generalizes

tests/ce-test-browser-driver-policy.test.ts

@@ -108,8 +108,8 @@ describe("ce-test-browser browser-driver policy", () => {
   })
 
   test("user documentation describes the same hierarchy", async () => {
-    const docs = await readRepoFile("skills/guides/ce-test-browser.md")
-    const catalog = await readRepoFile("skills/guides/README.md")
+    const docs = await readRepoFile("docs/guides/ce-test-browser.md")
+    const catalog = await readRepoFile("docs/guides/README.md")
 
     expect(docs).toMatch(/host-native.+integrated browser/is)
     expect(docs).toMatch(/embedded in or directly owned by the active harness/i)