diff --git a/AGENTS.md b/AGENTS.md
index 0c3f1e5..1a81bfc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -113,8 +113,8 @@ pnpm typecheck         # Type-check all packages
 pnpm lint              # Lint all packages (ESLint boundaries enforced)
 pnpm turbo boundaries  # Validate workspace dependency graph (Turbo boundaries)
 pnpm turbo gen feature       # Scaffold a new feature package (see docs/guides/scaffolding-a-feature.md)
-pnpm turbo gen core-package  # Scaffold an optional core package back (realtime, events, trpc, ui — see docs/scaffolding/core-package-generator.md)
-pnpm turbo gen core-ui-component  # Scaffold a core-ui atomic-design component (atom/molecule/organism — see docs/scaffolding/core-ui-component-generator.md)
+pnpm turbo gen core-package  # Scaffold an optional core package back (realtime, events, trpc, ui — see docs/guides/scaffolding-core-package.md)
+pnpm turbo gen core-ui-component  # Scaffold a core-ui atomic-design component (atom/molecule/organism — see docs/guides/scaffolding-core-ui-component.md)
 pnpm test              # Run all unit + integration tests (Vitest)
 pnpm test:e2e          # Run e2e tests (Playwright across both apps)
 pnpm build             # Build all packages (Turborepo)
diff --git a/docs/scaffolding/core-package-generator.md b/docs/guides/scaffolding-core-package.md
similarity index 100%
rename from docs/scaffolding/core-package-generator.md
rename to docs/guides/scaffolding-core-package.md
diff --git a/docs/scaffolding/core-ui-component-generator.md b/docs/guides/scaffolding-core-ui-component.md
similarity index 77%
rename from docs/scaffolding/core-ui-component-generator.md
rename to docs/guides/scaffolding-core-ui-component.md
index 74e209a..e4c0c8a 100644
--- a/docs/scaffolding/core-ui-component-generator.md
+++ b/docs/guides/scaffolding-core-ui-component.md
@@ -18,12 +18,12 @@ pnpm turbo gen core-ui-component
 
 The generator emits 4 files into `packages/core-ui/src/<tier>s/<kebab-name>/`:
 
-| File | Purpose |
-|---|---|
-| `<kebab-name>.tsx` | Component implementation (forwardRef + cn + className passthrough) |
-| `<kebab-name>.stories.tsx` | Storybook stories (Meta + StoryObj + one Default story; tier-prefixed title) |
-| `<kebab-name>.test.tsx` | Vitest + Testing Library smoke tests (renders, className passthrough, ref forwarding) |
-| `index.ts` | Barrel that re-exports the component + Props type |
+| File                       | Purpose                                                                               |
+| -------------------------- | ------------------------------------------------------------------------------------- |
+| `<kebab-name>.tsx`         | Component implementation (forwardRef + cn + className passthrough)                    |
+| `<kebab-name>.stories.tsx` | Storybook stories (Meta + StoryObj + one Default story; tier-prefixed title)          |
+| `<kebab-name>.test.tsx`    | Vitest + Testing Library smoke tests (renders, className passthrough, ref forwarding) |
+| `index.ts`                 | Barrel that re-exports the component + Props type                                     |
 
 The new export is also spliced into `packages/core-ui/src/<tier>s/index.ts` immediately after the `// <gen:<tier>s>` anchor, so the component is reachable from the tier barrel (and transitively from the root `@repo/core-ui` export) without any manual wiring.