diff --git a/templates/aurora/.env.example b/archive/templates/aurora/.env.example
similarity index 100%
rename from templates/aurora/.env.example
rename to archive/templates/aurora/.env.example
diff --git a/templates/aurora/.gitignore b/archive/templates/aurora/.gitignore
similarity index 100%
rename from templates/aurora/.gitignore
rename to archive/templates/aurora/.gitignore
diff --git a/templates/aurora/README.md b/archive/templates/aurora/README.md
similarity index 100%
rename from templates/aurora/README.md
rename to archive/templates/aurora/README.md
diff --git a/templates/aurora/app/[[...slug]]/page.tsx b/archive/templates/aurora/app/[[...slug]]/page.tsx
similarity index 100%
rename from templates/aurora/app/[[...slug]]/page.tsx
rename to archive/templates/aurora/app/[[...slug]]/page.tsx
diff --git a/templates/aurora/app/api-reference/[[...slug]]/page.tsx b/archive/templates/aurora/app/api-reference/[[...slug]]/page.tsx
similarity index 100%
rename from templates/aurora/app/api-reference/[[...slug]]/page.tsx
rename to archive/templates/aurora/app/api-reference/[[...slug]]/page.tsx
diff --git a/templates/aurora/app/api/ask/route.ts b/archive/templates/aurora/app/api/ask/route.ts
similarity index 100%
rename from templates/aurora/app/api/ask/route.ts
rename to archive/templates/aurora/app/api/ask/route.ts
diff --git a/templates/aurora/app/blog/[slug]/page.tsx b/archive/templates/aurora/app/blog/[slug]/page.tsx
similarity index 100%
rename from templates/aurora/app/blog/[slug]/page.tsx
rename to archive/templates/aurora/app/blog/[slug]/page.tsx
diff --git a/templates/aurora/app/blog/page.tsx b/archive/templates/aurora/app/blog/page.tsx
similarity index 100%
rename from templates/aurora/app/blog/page.tsx
rename to archive/templates/aurora/app/blog/page.tsx
diff --git a/templates/aurora/app/changelog/page.tsx b/archive/templates/aurora/app/changelog/page.tsx
similarity index 100%
rename from templates/aurora/app/changelog/page.tsx
rename to archive/templates/aurora/app/changelog/page.tsx
diff --git a/templates/aurora/app/layout.tsx b/archive/templates/aurora/app/layout.tsx
similarity index 100%
rename from templates/aurora/app/layout.tsx
rename to archive/templates/aurora/app/layout.tsx
diff --git a/templates/aurora/app/theme.css b/archive/templates/aurora/app/theme.css
similarity index 100%
rename from templates/aurora/app/theme.css
rename to archive/templates/aurora/app/theme.css
diff --git a/templates/aurora/components/top-bar.tsx b/archive/templates/aurora/components/top-bar.tsx
similarity index 100%
rename from templates/aurora/components/top-bar.tsx
rename to archive/templates/aurora/components/top-bar.tsx
diff --git a/templates/aurora/content/docs/development.mdx b/archive/templates/aurora/content/docs/development.mdx
similarity index 100%
rename from templates/aurora/content/docs/development.mdx
rename to archive/templates/aurora/content/docs/development.mdx
diff --git a/templates/aurora/content/docs/docs.json b/archive/templates/aurora/content/docs/docs.json
similarity index 100%
rename from templates/aurora/content/docs/docs.json
rename to archive/templates/aurora/content/docs/docs.json
diff --git a/templates/aurora/content/docs/essentials/code-blocks.mdx b/archive/templates/aurora/content/docs/essentials/code-blocks.mdx
similarity index 100%
rename from templates/aurora/content/docs/essentials/code-blocks.mdx
rename to archive/templates/aurora/content/docs/essentials/code-blocks.mdx
diff --git a/templates/aurora/content/docs/essentials/components.mdx b/archive/templates/aurora/content/docs/essentials/components.mdx
similarity index 100%
rename from templates/aurora/content/docs/essentials/components.mdx
rename to archive/templates/aurora/content/docs/essentials/components.mdx
diff --git a/templates/aurora/content/docs/essentials/images.mdx b/archive/templates/aurora/content/docs/essentials/images.mdx
similarity index 100%
rename from templates/aurora/content/docs/essentials/images.mdx
rename to archive/templates/aurora/content/docs/essentials/images.mdx
diff --git a/templates/aurora/content/docs/essentials/markdown.mdx b/archive/templates/aurora/content/docs/essentials/markdown.mdx
similarity index 100%
rename from templates/aurora/content/docs/essentials/markdown.mdx
rename to archive/templates/aurora/content/docs/essentials/markdown.mdx
diff --git a/templates/aurora/content/docs/essentials/navigation.mdx b/archive/templates/aurora/content/docs/essentials/navigation.mdx
similarity index 100%
rename from templates/aurora/content/docs/essentials/navigation.mdx
rename to archive/templates/aurora/content/docs/essentials/navigation.mdx
diff --git a/templates/aurora/content/docs/index.mdx b/archive/templates/aurora/content/docs/index.mdx
similarity index 100%
rename from templates/aurora/content/docs/index.mdx
rename to archive/templates/aurora/content/docs/index.mdx
diff --git a/templates/aurora/content/docs/openapi.json b/archive/templates/aurora/content/docs/openapi.json
similarity index 100%
rename from templates/aurora/content/docs/openapi.json
rename to archive/templates/aurora/content/docs/openapi.json
diff --git a/templates/aurora/content/docs/quickstart.mdx b/archive/templates/aurora/content/docs/quickstart.mdx
similarity index 100%
rename from templates/aurora/content/docs/quickstart.mdx
rename to archive/templates/aurora/content/docs/quickstart.mdx
diff --git a/templates/aurora/content/docs/slug-history.json b/archive/templates/aurora/content/docs/slug-history.json
similarity index 100%
rename from templates/aurora/content/docs/slug-history.json
rename to archive/templates/aurora/content/docs/slug-history.json
diff --git a/templates/aurora/lib/icons.tsx b/archive/templates/aurora/lib/icons.tsx
similarity index 100%
rename from templates/aurora/lib/icons.tsx
rename to archive/templates/aurora/lib/icons.tsx
diff --git a/templates/aurora/lib/route.tsx b/archive/templates/aurora/lib/route.tsx
similarity index 100%
rename from templates/aurora/lib/route.tsx
rename to archive/templates/aurora/lib/route.tsx
diff --git a/templates/aurora/mdx-components.tsx b/archive/templates/aurora/mdx-components.tsx
similarity index 100%
rename from templates/aurora/mdx-components.tsx
rename to archive/templates/aurora/mdx-components.tsx
diff --git a/templates/aurora/next-env.d.ts b/archive/templates/aurora/next-env.d.ts
similarity index 100%
rename from templates/aurora/next-env.d.ts
rename to archive/templates/aurora/next-env.d.ts
diff --git a/templates/aurora/next.config.ts b/archive/templates/aurora/next.config.ts
similarity index 100%
rename from templates/aurora/next.config.ts
rename to archive/templates/aurora/next.config.ts
diff --git a/templates/aurora/package.json b/archive/templates/aurora/package.json
similarity index 100%
rename from templates/aurora/package.json
rename to archive/templates/aurora/package.json
diff --git a/templates/aurora/proxy.ts b/archive/templates/aurora/proxy.ts
similarity index 100%
rename from templates/aurora/proxy.ts
rename to archive/templates/aurora/proxy.ts
diff --git a/templates/aurora/public/favicon.svg b/archive/templates/aurora/public/favicon.svg
similarity index 100%
rename from templates/aurora/public/favicon.svg
rename to archive/templates/aurora/public/favicon.svg
diff --git a/templates/aurora/public/hero.svg b/archive/templates/aurora/public/hero.svg
similarity index 100%
rename from templates/aurora/public/hero.svg
rename to archive/templates/aurora/public/hero.svg
diff --git a/templates/aurora/public/logo.svg b/archive/templates/aurora/public/logo.svg
similarity index 100%
rename from templates/aurora/public/logo.svg
rename to archive/templates/aurora/public/logo.svg
diff --git a/templates/aurora/tsconfig.json b/archive/templates/aurora/tsconfig.json
similarity index 100%
rename from templates/aurora/tsconfig.json
rename to archive/templates/aurora/tsconfig.json
diff --git a/templates/aurora/widgets/Counter.tsx b/archive/templates/aurora/widgets/Counter.tsx
similarity index 100%
rename from templates/aurora/widgets/Counter.tsx
rename to archive/templates/aurora/widgets/Counter.tsx
diff --git a/templates/aurora/widgets/index.ts b/archive/templates/aurora/widgets/index.ts
similarity index 100%
rename from templates/aurora/widgets/index.ts
rename to archive/templates/aurora/widgets/index.ts
diff --git a/templates/base/.env.example b/archive/templates/base/.env.example
similarity index 100%
rename from templates/base/.env.example
rename to archive/templates/base/.env.example
diff --git a/templates/base/.gitignore b/archive/templates/base/.gitignore
similarity index 100%
rename from templates/base/.gitignore
rename to archive/templates/base/.gitignore
diff --git a/templates/base/README.md b/archive/templates/base/README.md
similarity index 100%
rename from templates/base/README.md
rename to archive/templates/base/README.md
diff --git a/templates/base/app/[[...slug]]/page.tsx b/archive/templates/base/app/[[...slug]]/page.tsx
similarity index 100%
rename from templates/base/app/[[...slug]]/page.tsx
rename to archive/templates/base/app/[[...slug]]/page.tsx
diff --git a/templates/base/app/api-reference/[[...slug]]/page.tsx b/archive/templates/base/app/api-reference/[[...slug]]/page.tsx
similarity index 100%
rename from templates/base/app/api-reference/[[...slug]]/page.tsx
rename to archive/templates/base/app/api-reference/[[...slug]]/page.tsx
diff --git a/templates/base/app/api/ask/route.ts b/archive/templates/base/app/api/ask/route.ts
similarity index 100%
rename from templates/base/app/api/ask/route.ts
rename to archive/templates/base/app/api/ask/route.ts
diff --git a/templates/base/app/blog/[slug]/page.tsx b/archive/templates/base/app/blog/[slug]/page.tsx
similarity index 100%
rename from templates/base/app/blog/[slug]/page.tsx
rename to archive/templates/base/app/blog/[slug]/page.tsx
diff --git a/templates/base/app/blog/page.tsx b/archive/templates/base/app/blog/page.tsx
similarity index 100%
rename from templates/base/app/blog/page.tsx
rename to archive/templates/base/app/blog/page.tsx
diff --git a/templates/base/app/changelog/page.tsx b/archive/templates/base/app/changelog/page.tsx
similarity index 100%
rename from templates/base/app/changelog/page.tsx
rename to archive/templates/base/app/changelog/page.tsx
diff --git a/templates/base/app/layout.tsx b/archive/templates/base/app/layout.tsx
similarity index 100%
rename from templates/base/app/layout.tsx
rename to archive/templates/base/app/layout.tsx
diff --git a/templates/base/app/theme.css b/archive/templates/base/app/theme.css
similarity index 100%
rename from templates/base/app/theme.css
rename to archive/templates/base/app/theme.css
diff --git a/templates/base/components/top-bar.tsx b/archive/templates/base/components/top-bar.tsx
similarity index 100%
rename from templates/base/components/top-bar.tsx
rename to archive/templates/base/components/top-bar.tsx
diff --git a/templates/base/content/docs/development.mdx b/archive/templates/base/content/docs/development.mdx
similarity index 100%
rename from templates/base/content/docs/development.mdx
rename to archive/templates/base/content/docs/development.mdx
diff --git a/templates/base/content/docs/docs.json b/archive/templates/base/content/docs/docs.json
similarity index 100%
rename from templates/base/content/docs/docs.json
rename to archive/templates/base/content/docs/docs.json
diff --git a/templates/base/content/docs/essentials/code-blocks.mdx b/archive/templates/base/content/docs/essentials/code-blocks.mdx
similarity index 100%
rename from templates/base/content/docs/essentials/code-blocks.mdx
rename to archive/templates/base/content/docs/essentials/code-blocks.mdx
diff --git a/templates/base/content/docs/essentials/components.mdx b/archive/templates/base/content/docs/essentials/components.mdx
similarity index 100%
rename from templates/base/content/docs/essentials/components.mdx
rename to archive/templates/base/content/docs/essentials/components.mdx
diff --git a/templates/base/content/docs/essentials/images.mdx b/archive/templates/base/content/docs/essentials/images.mdx
similarity index 100%
rename from templates/base/content/docs/essentials/images.mdx
rename to archive/templates/base/content/docs/essentials/images.mdx
diff --git a/templates/base/content/docs/essentials/markdown.mdx b/archive/templates/base/content/docs/essentials/markdown.mdx
similarity index 100%
rename from templates/base/content/docs/essentials/markdown.mdx
rename to archive/templates/base/content/docs/essentials/markdown.mdx
diff --git a/templates/base/content/docs/essentials/navigation.mdx b/archive/templates/base/content/docs/essentials/navigation.mdx
similarity index 100%
rename from templates/base/content/docs/essentials/navigation.mdx
rename to archive/templates/base/content/docs/essentials/navigation.mdx
diff --git a/templates/base/content/docs/index.mdx b/archive/templates/base/content/docs/index.mdx
similarity index 100%
rename from templates/base/content/docs/index.mdx
rename to archive/templates/base/content/docs/index.mdx
diff --git a/templates/base/content/docs/openapi.json b/archive/templates/base/content/docs/openapi.json
similarity index 100%
rename from templates/base/content/docs/openapi.json
rename to archive/templates/base/content/docs/openapi.json
diff --git a/templates/base/content/docs/quickstart.mdx b/archive/templates/base/content/docs/quickstart.mdx
similarity index 100%
rename from templates/base/content/docs/quickstart.mdx
rename to archive/templates/base/content/docs/quickstart.mdx
diff --git a/templates/base/content/docs/slug-history.json b/archive/templates/base/content/docs/slug-history.json
similarity index 100%
rename from templates/base/content/docs/slug-history.json
rename to archive/templates/base/content/docs/slug-history.json
diff --git a/templates/base/lib/icons.tsx b/archive/templates/base/lib/icons.tsx
similarity index 100%
rename from templates/base/lib/icons.tsx
rename to archive/templates/base/lib/icons.tsx
diff --git a/templates/base/lib/route.tsx b/archive/templates/base/lib/route.tsx
similarity index 100%
rename from templates/base/lib/route.tsx
rename to archive/templates/base/lib/route.tsx
diff --git a/templates/base/mdx-components.tsx b/archive/templates/base/mdx-components.tsx
similarity index 100%
rename from templates/base/mdx-components.tsx
rename to archive/templates/base/mdx-components.tsx
diff --git a/templates/base/next-env.d.ts b/archive/templates/base/next-env.d.ts
similarity index 100%
rename from templates/base/next-env.d.ts
rename to archive/templates/base/next-env.d.ts
diff --git a/templates/base/next.config.ts b/archive/templates/base/next.config.ts
similarity index 100%
rename from templates/base/next.config.ts
rename to archive/templates/base/next.config.ts
diff --git a/templates/base/package.json b/archive/templates/base/package.json
similarity index 100%
rename from templates/base/package.json
rename to archive/templates/base/package.json
diff --git a/templates/base/proxy.ts b/archive/templates/base/proxy.ts
similarity index 100%
rename from templates/base/proxy.ts
rename to archive/templates/base/proxy.ts
diff --git a/templates/base/public/favicon.svg b/archive/templates/base/public/favicon.svg
similarity index 100%
rename from templates/base/public/favicon.svg
rename to archive/templates/base/public/favicon.svg
diff --git a/templates/base/public/hero.svg b/archive/templates/base/public/hero.svg
similarity index 100%
rename from templates/base/public/hero.svg
rename to archive/templates/base/public/hero.svg
diff --git a/templates/base/public/logo.svg b/archive/templates/base/public/logo.svg
similarity index 100%
rename from templates/base/public/logo.svg
rename to archive/templates/base/public/logo.svg
diff --git a/templates/base/tsconfig.json b/archive/templates/base/tsconfig.json
similarity index 100%
rename from templates/base/tsconfig.json
rename to archive/templates/base/tsconfig.json
diff --git a/templates/base/widgets/index.ts b/archive/templates/base/widgets/index.ts
similarity index 100%
rename from templates/base/widgets/index.ts
rename to archive/templates/base/widgets/index.ts
diff --git a/templates/cedar/.env.example b/archive/templates/cedar/.env.example
similarity index 100%
rename from templates/cedar/.env.example
rename to archive/templates/cedar/.env.example
diff --git a/templates/cedar/.gitignore b/archive/templates/cedar/.gitignore
similarity index 100%
rename from templates/cedar/.gitignore
rename to archive/templates/cedar/.gitignore
diff --git a/templates/cedar/README.md b/archive/templates/cedar/README.md
similarity index 100%
rename from templates/cedar/README.md
rename to archive/templates/cedar/README.md
diff --git a/templates/cedar/app/[[...slug]]/page.tsx b/archive/templates/cedar/app/[[...slug]]/page.tsx
similarity index 100%
rename from templates/cedar/app/[[...slug]]/page.tsx
rename to archive/templates/cedar/app/[[...slug]]/page.tsx
diff --git a/templates/cedar/app/api-reference/[[...slug]]/page.tsx b/archive/templates/cedar/app/api-reference/[[...slug]]/page.tsx
similarity index 100%
rename from templates/cedar/app/api-reference/[[...slug]]/page.tsx
rename to archive/templates/cedar/app/api-reference/[[...slug]]/page.tsx
diff --git a/templates/cedar/app/api/ask/route.ts b/archive/templates/cedar/app/api/ask/route.ts
similarity index 100%
rename from templates/cedar/app/api/ask/route.ts
rename to archive/templates/cedar/app/api/ask/route.ts
diff --git a/templates/cedar/app/blog/[slug]/page.tsx b/archive/templates/cedar/app/blog/[slug]/page.tsx
similarity index 100%
rename from templates/cedar/app/blog/[slug]/page.tsx
rename to archive/templates/cedar/app/blog/[slug]/page.tsx
diff --git a/templates/cedar/app/blog/page.tsx b/archive/templates/cedar/app/blog/page.tsx
similarity index 100%
rename from templates/cedar/app/blog/page.tsx
rename to archive/templates/cedar/app/blog/page.tsx
diff --git a/templates/cedar/app/changelog/page.tsx b/archive/templates/cedar/app/changelog/page.tsx
similarity index 100%
rename from templates/cedar/app/changelog/page.tsx
rename to archive/templates/cedar/app/changelog/page.tsx
diff --git a/templates/cedar/app/layout.tsx b/archive/templates/cedar/app/layout.tsx
similarity index 100%
rename from templates/cedar/app/layout.tsx
rename to archive/templates/cedar/app/layout.tsx
diff --git a/templates/cedar/app/theme.css b/archive/templates/cedar/app/theme.css
similarity index 100%
rename from templates/cedar/app/theme.css
rename to archive/templates/cedar/app/theme.css
diff --git a/templates/cedar/components/top-bar.tsx b/archive/templates/cedar/components/top-bar.tsx
similarity index 100%
rename from templates/cedar/components/top-bar.tsx
rename to archive/templates/cedar/components/top-bar.tsx
diff --git a/templates/cedar/content/docs/development.mdx b/archive/templates/cedar/content/docs/development.mdx
similarity index 100%
rename from templates/cedar/content/docs/development.mdx
rename to archive/templates/cedar/content/docs/development.mdx
diff --git a/templates/cedar/content/docs/docs.json b/archive/templates/cedar/content/docs/docs.json
similarity index 100%
rename from templates/cedar/content/docs/docs.json
rename to archive/templates/cedar/content/docs/docs.json
diff --git a/templates/cedar/content/docs/essentials/code-blocks.mdx b/archive/templates/cedar/content/docs/essentials/code-blocks.mdx
similarity index 100%
rename from templates/cedar/content/docs/essentials/code-blocks.mdx
rename to archive/templates/cedar/content/docs/essentials/code-blocks.mdx
diff --git a/templates/cedar/content/docs/essentials/components.mdx b/archive/templates/cedar/content/docs/essentials/components.mdx
similarity index 100%
rename from templates/cedar/content/docs/essentials/components.mdx
rename to archive/templates/cedar/content/docs/essentials/components.mdx
diff --git a/templates/cedar/content/docs/essentials/images.mdx b/archive/templates/cedar/content/docs/essentials/images.mdx
similarity index 100%
rename from templates/cedar/content/docs/essentials/images.mdx
rename to archive/templates/cedar/content/docs/essentials/images.mdx
diff --git a/templates/cedar/content/docs/essentials/markdown.mdx b/archive/templates/cedar/content/docs/essentials/markdown.mdx
similarity index 100%
rename from templates/cedar/content/docs/essentials/markdown.mdx
rename to archive/templates/cedar/content/docs/essentials/markdown.mdx
diff --git a/templates/cedar/content/docs/essentials/navigation.mdx b/archive/templates/cedar/content/docs/essentials/navigation.mdx
similarity index 100%
rename from templates/cedar/content/docs/essentials/navigation.mdx
rename to archive/templates/cedar/content/docs/essentials/navigation.mdx
diff --git a/templates/cedar/content/docs/index.mdx b/archive/templates/cedar/content/docs/index.mdx
similarity index 100%
rename from templates/cedar/content/docs/index.mdx
rename to archive/templates/cedar/content/docs/index.mdx
diff --git a/templates/cedar/content/docs/openapi.json b/archive/templates/cedar/content/docs/openapi.json
similarity index 100%
rename from templates/cedar/content/docs/openapi.json
rename to archive/templates/cedar/content/docs/openapi.json
diff --git a/templates/cedar/content/docs/quickstart.mdx b/archive/templates/cedar/content/docs/quickstart.mdx
similarity index 100%
rename from templates/cedar/content/docs/quickstart.mdx
rename to archive/templates/cedar/content/docs/quickstart.mdx
diff --git a/templates/cedar/content/docs/slug-history.json b/archive/templates/cedar/content/docs/slug-history.json
similarity index 100%
rename from templates/cedar/content/docs/slug-history.json
rename to archive/templates/cedar/content/docs/slug-history.json
diff --git a/templates/cedar/lib/icons.tsx b/archive/templates/cedar/lib/icons.tsx
similarity index 100%
rename from templates/cedar/lib/icons.tsx
rename to archive/templates/cedar/lib/icons.tsx
diff --git a/templates/cedar/lib/route.tsx b/archive/templates/cedar/lib/route.tsx
similarity index 100%
rename from templates/cedar/lib/route.tsx
rename to archive/templates/cedar/lib/route.tsx
diff --git a/templates/cedar/mdx-components.tsx b/archive/templates/cedar/mdx-components.tsx
similarity index 100%
rename from templates/cedar/mdx-components.tsx
rename to archive/templates/cedar/mdx-components.tsx
diff --git a/templates/cedar/next-env.d.ts b/archive/templates/cedar/next-env.d.ts
similarity index 100%
rename from templates/cedar/next-env.d.ts
rename to archive/templates/cedar/next-env.d.ts
diff --git a/templates/cedar/next.config.ts b/archive/templates/cedar/next.config.ts
similarity index 100%
rename from templates/cedar/next.config.ts
rename to archive/templates/cedar/next.config.ts
diff --git a/templates/cedar/package.json b/archive/templates/cedar/package.json
similarity index 100%
rename from templates/cedar/package.json
rename to archive/templates/cedar/package.json
diff --git a/templates/cedar/proxy.ts b/archive/templates/cedar/proxy.ts
similarity index 100%
rename from templates/cedar/proxy.ts
rename to archive/templates/cedar/proxy.ts
diff --git a/templates/cedar/public/favicon.svg b/archive/templates/cedar/public/favicon.svg
similarity index 100%
rename from templates/cedar/public/favicon.svg
rename to archive/templates/cedar/public/favicon.svg
diff --git a/templates/cedar/public/hero.svg b/archive/templates/cedar/public/hero.svg
similarity index 100%
rename from templates/cedar/public/hero.svg
rename to archive/templates/cedar/public/hero.svg
diff --git a/templates/cedar/public/logo.svg b/archive/templates/cedar/public/logo.svg
similarity index 100%
rename from templates/cedar/public/logo.svg
rename to archive/templates/cedar/public/logo.svg
diff --git a/templates/cedar/tsconfig.json b/archive/templates/cedar/tsconfig.json
similarity index 100%
rename from templates/cedar/tsconfig.json
rename to archive/templates/cedar/tsconfig.json
diff --git a/templates/cedar/widgets/index.ts b/archive/templates/cedar/widgets/index.ts
similarity index 100%
rename from templates/cedar/widgets/index.ts
rename to archive/templates/cedar/widgets/index.ts
diff --git a/templates/fern/.env.example b/archive/templates/fern/.env.example
similarity index 100%
rename from templates/fern/.env.example
rename to archive/templates/fern/.env.example
diff --git a/templates/fern/.gitignore b/archive/templates/fern/.gitignore
similarity index 100%
rename from templates/fern/.gitignore
rename to archive/templates/fern/.gitignore
diff --git a/templates/fern/README.md b/archive/templates/fern/README.md
similarity index 100%
rename from templates/fern/README.md
rename to archive/templates/fern/README.md
diff --git a/templates/fern/app/[[...slug]]/page.tsx b/archive/templates/fern/app/[[...slug]]/page.tsx
similarity index 100%
rename from templates/fern/app/[[...slug]]/page.tsx
rename to archive/templates/fern/app/[[...slug]]/page.tsx
diff --git a/templates/fern/app/api-reference/[[...slug]]/page.tsx b/archive/templates/fern/app/api-reference/[[...slug]]/page.tsx
similarity index 100%
rename from templates/fern/app/api-reference/[[...slug]]/page.tsx
rename to archive/templates/fern/app/api-reference/[[...slug]]/page.tsx
diff --git a/templates/fern/app/api/ask/route.ts b/archive/templates/fern/app/api/ask/route.ts
similarity index 100%
rename from templates/fern/app/api/ask/route.ts
rename to archive/templates/fern/app/api/ask/route.ts
diff --git a/templates/fern/app/blog/[slug]/page.tsx b/archive/templates/fern/app/blog/[slug]/page.tsx
similarity index 100%
rename from templates/fern/app/blog/[slug]/page.tsx
rename to archive/templates/fern/app/blog/[slug]/page.tsx
diff --git a/templates/fern/app/blog/page.tsx b/archive/templates/fern/app/blog/page.tsx
similarity index 100%
rename from templates/fern/app/blog/page.tsx
rename to archive/templates/fern/app/blog/page.tsx
diff --git a/templates/fern/app/changelog/page.tsx b/archive/templates/fern/app/changelog/page.tsx
similarity index 100%
rename from templates/fern/app/changelog/page.tsx
rename to archive/templates/fern/app/changelog/page.tsx
diff --git a/templates/fern/app/layout.tsx b/archive/templates/fern/app/layout.tsx
similarity index 100%
rename from templates/fern/app/layout.tsx
rename to archive/templates/fern/app/layout.tsx
diff --git a/templates/fern/app/theme.css b/archive/templates/fern/app/theme.css
similarity index 100%
rename from templates/fern/app/theme.css
rename to archive/templates/fern/app/theme.css
diff --git a/templates/fern/components/top-bar.tsx b/archive/templates/fern/components/top-bar.tsx
similarity index 100%
rename from templates/fern/components/top-bar.tsx
rename to archive/templates/fern/components/top-bar.tsx
diff --git a/templates/fern/content/docs/development.mdx b/archive/templates/fern/content/docs/development.mdx
similarity index 100%
rename from templates/fern/content/docs/development.mdx
rename to archive/templates/fern/content/docs/development.mdx
diff --git a/templates/fern/content/docs/docs.json b/archive/templates/fern/content/docs/docs.json
similarity index 100%
rename from templates/fern/content/docs/docs.json
rename to archive/templates/fern/content/docs/docs.json
diff --git a/templates/fern/content/docs/essentials/code-blocks.mdx b/archive/templates/fern/content/docs/essentials/code-blocks.mdx
similarity index 100%
rename from templates/fern/content/docs/essentials/code-blocks.mdx
rename to archive/templates/fern/content/docs/essentials/code-blocks.mdx
diff --git a/templates/fern/content/docs/essentials/components.mdx b/archive/templates/fern/content/docs/essentials/components.mdx
similarity index 100%
rename from templates/fern/content/docs/essentials/components.mdx
rename to archive/templates/fern/content/docs/essentials/components.mdx
diff --git a/templates/fern/content/docs/essentials/images.mdx b/archive/templates/fern/content/docs/essentials/images.mdx
similarity index 100%
rename from templates/fern/content/docs/essentials/images.mdx
rename to archive/templates/fern/content/docs/essentials/images.mdx
diff --git a/templates/fern/content/docs/essentials/markdown.mdx b/archive/templates/fern/content/docs/essentials/markdown.mdx
similarity index 100%
rename from templates/fern/content/docs/essentials/markdown.mdx
rename to archive/templates/fern/content/docs/essentials/markdown.mdx
diff --git a/templates/fern/content/docs/essentials/navigation.mdx b/archive/templates/fern/content/docs/essentials/navigation.mdx
similarity index 100%
rename from templates/fern/content/docs/essentials/navigation.mdx
rename to archive/templates/fern/content/docs/essentials/navigation.mdx
diff --git a/templates/fern/content/docs/index.mdx b/archive/templates/fern/content/docs/index.mdx
similarity index 100%
rename from templates/fern/content/docs/index.mdx
rename to archive/templates/fern/content/docs/index.mdx
diff --git a/templates/fern/content/docs/openapi.json b/archive/templates/fern/content/docs/openapi.json
similarity index 100%
rename from templates/fern/content/docs/openapi.json
rename to archive/templates/fern/content/docs/openapi.json
diff --git a/templates/fern/content/docs/quickstart.mdx b/archive/templates/fern/content/docs/quickstart.mdx
similarity index 100%
rename from templates/fern/content/docs/quickstart.mdx
rename to archive/templates/fern/content/docs/quickstart.mdx
diff --git a/templates/fern/content/docs/slug-history.json b/archive/templates/fern/content/docs/slug-history.json
similarity index 100%
rename from templates/fern/content/docs/slug-history.json
rename to archive/templates/fern/content/docs/slug-history.json
diff --git a/templates/fern/lib/icons.tsx b/archive/templates/fern/lib/icons.tsx
similarity index 100%
rename from templates/fern/lib/icons.tsx
rename to archive/templates/fern/lib/icons.tsx
diff --git a/templates/fern/lib/route.tsx b/archive/templates/fern/lib/route.tsx
similarity index 100%
rename from templates/fern/lib/route.tsx
rename to archive/templates/fern/lib/route.tsx
diff --git a/templates/fern/mdx-components.tsx b/archive/templates/fern/mdx-components.tsx
similarity index 100%
rename from templates/fern/mdx-components.tsx
rename to archive/templates/fern/mdx-components.tsx
diff --git a/templates/fern/next-env.d.ts b/archive/templates/fern/next-env.d.ts
similarity index 100%
rename from templates/fern/next-env.d.ts
rename to archive/templates/fern/next-env.d.ts
diff --git a/templates/fern/next.config.ts b/archive/templates/fern/next.config.ts
similarity index 100%
rename from templates/fern/next.config.ts
rename to archive/templates/fern/next.config.ts
diff --git a/templates/fern/package.json b/archive/templates/fern/package.json
similarity index 100%
rename from templates/fern/package.json
rename to archive/templates/fern/package.json
diff --git a/templates/fern/proxy.ts b/archive/templates/fern/proxy.ts
similarity index 100%
rename from templates/fern/proxy.ts
rename to archive/templates/fern/proxy.ts
diff --git a/templates/fern/public/favicon.svg b/archive/templates/fern/public/favicon.svg
similarity index 100%
rename from templates/fern/public/favicon.svg
rename to archive/templates/fern/public/favicon.svg
diff --git a/templates/fern/public/hero.svg b/archive/templates/fern/public/hero.svg
similarity index 100%
rename from templates/fern/public/hero.svg
rename to archive/templates/fern/public/hero.svg
diff --git a/templates/fern/public/logo.svg b/archive/templates/fern/public/logo.svg
similarity index 100%
rename from templates/fern/public/logo.svg
rename to archive/templates/fern/public/logo.svg
diff --git a/templates/fern/tsconfig.json b/archive/templates/fern/tsconfig.json
similarity index 100%
rename from templates/fern/tsconfig.json
rename to archive/templates/fern/tsconfig.json
diff --git a/templates/fern/widgets/index.ts b/archive/templates/fern/widgets/index.ts
similarity index 100%
rename from templates/fern/widgets/index.ts
rename to archive/templates/fern/widgets/index.ts
diff --git a/templates/mono/.env.example b/archive/templates/galley/.env.example
similarity index 100%
rename from templates/mono/.env.example
rename to archive/templates/galley/.env.example
diff --git a/templates/mono/.gitignore b/archive/templates/galley/.gitignore
similarity index 100%
rename from templates/mono/.gitignore
rename to archive/templates/galley/.gitignore
diff --git a/archive/templates/galley/README.md b/archive/templates/galley/README.md
new file mode 100644
index 0000000..ba38899
--- /dev/null
+++ b/archive/templates/galley/README.md
@@ -0,0 +1,157 @@
+# Galley — @inkform/theme-galley
+
+Galley is Inkform's own design system, built on `@inkform/framework`. Warm
+opaque paper + ink, one editorial "Proof" red-pencil accent, a serif prose
+voice (Newsreader) beside a mono machine voice (JetBrains Mono) and a sans UI
+voice (General Sans). Depth comes from paper layering and hairlines, never
+heavy shadow or gradient. It supports Guides + API Reference tabs, plus Blog
+and Changelog, out of the box.
+
+---
+
+## Run locally
+
+```bash
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+If this is a fresh clone, copy the env file first:
+
+```bash
+cp .env.example .env.local
+# Edit NEXT_PUBLIC_SITE_URL if needed, then:
+npm run dev
+```
+
+---
+
+## Add content
+
+All content lives in `content/docs/`.
+
+### Navigation — `content/docs/docs.json`
+
+`docs.json` controls the site name, logo, tabs, and page hierarchy:
+
+```jsonc
+{
+  "name": "Your Docs",
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx" },
+            { "title": "Quickstart",   "slug": "quickstart", "file": "quickstart.mdx" }
+          ]
+        }
+      ]
+    },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+- `slug` is the URL path (empty string = the index `/`).
+- `file` is the MDX file path relative to `content/docs/`.
+- The `openapi` field on a tab points to a JSON/YAML spec file in `content/docs/`.
+
+### Writing MDX
+
+Add `.mdx` files under `content/docs/` and register them in `docs.json`.
+Galley supports all built-in blocks: `<Note>`, `<Tip>`, `<Warning>`, `<Card>`,
+`<CardGroup>`, `<Steps>`, `<Step>`, `<Tabs>`, `<Tab>`, `<CodeGroup>`,
+`<Accordion>`, `<ParamField>`, `<Frame>`, and more.
+
+### API Reference
+
+Replace `content/docs/openapi.json` with your own OpenAPI 3.x spec (JSON or
+YAML). The site auto-generates a sidebar and per-operation pages. No extra
+configuration needed — just point the `openapi` tab field at your spec file.
+
+### Blog and Changelog
+
+Both ship wired and ready — `/blog` (list + post pages) and `/changelog`
+(single dated list) render automatically once you add content:
+
+```
+content/
+  blog/
+    my-first-post.mdx    # frontmatter: title, date, author, tags, description
+    series.json          # optional — group posts into a series
+  changelog/
+    2026-01-15-v1.mdx     # frontmatter: title, date, version
+```
+
+Both nav links only appear once at least one entry exists — an empty
+`content/blog`/`content/changelog` (or no folder at all) keeps the top nav
+clean and the pages still render a "no posts yet" state if visited directly.
+
+---
+
+## Maintain
+
+### Slug redirects
+
+When a page's URL changes, record the old → new slug mapping in
+`content/docs/slug-history.json` to issue a 301 redirect:
+
+```json
+{
+  "old-page-slug": "new-page-slug",
+  "essentials/old-name": "essentials/new-name"
+}
+```
+
+### Ask AI widget
+
+The Ask AI button is built in but **disabled by default**. Enable it by setting
+`NEXT_PUBLIC_DOCS_AI_ENABLED=true` in `.env.local`. Wire up a real LLM provider
+in `app/api/ask/route.ts` (see the TODO comment there; currently returns a stub).
+
+---
+
+## Deploy to Vercel
+
+1. Push this directory (or the whole monorepo) to a GitHub repository.
+2. In the Vercel dashboard, click **Add New → Project** and import the repo.
+3. **Framework preset**: Next.js.
+4. **Root directory**: set to the path of this folder if deploying as a
+   standalone (e.g. `oss/templates/galley`), or leave blank if deploying the
+   directory itself.
+5. Add the environment variable `NEXT_PUBLIC_SITE_URL` (your production URL,
+   e.g. `https://docs.example.com`).
+6. Click **Deploy**.
+
+For a custom domain, go to **Settings → Domains** in your Vercel project and add
+your domain. Vercel handles SSL automatically.
+
+---
+
+## Deploy to AWS Amplify
+
+1. Connect the repo in the Amplify console.
+2. Set the **Build settings** manually if auto-detection picks the wrong preset:
+   - **Build command**: `npm ci && npm run build`
+   - **Output directory**: `.next`
+   - **Framework**: Next.js (SSR)
+3. Add the `NEXT_PUBLIC_SITE_URL` environment variable under
+   **Environment variables**.
+4. Deploy. Amplify Hosting supports Next.js SSR/ISR natively since Gen 2.
+
+---
+
+## Ask AI (deferred)
+
+The `<AskAi />` widget in the top bar is built in. To activate it:
+
+1. Set `NEXT_PUBLIC_DOCS_AI_ENABLED=true`.
+2. Implement the LLM call in `app/api/ask/route.ts`.
+3. Add `ANTHROPIC_API_KEY` (or your provider key) as a server-side env var.
+
+The widget renders in both enabled and disabled states — it just shows an
+informational notice when disabled.
diff --git a/templates/mono/app/[[...slug]]/page.tsx b/archive/templates/galley/app/[[...slug]]/page.tsx
similarity index 100%
rename from templates/mono/app/[[...slug]]/page.tsx
rename to archive/templates/galley/app/[[...slug]]/page.tsx
diff --git a/templates/mono/app/api-reference/[[...slug]]/page.tsx b/archive/templates/galley/app/api-reference/[[...slug]]/page.tsx
similarity index 100%
rename from templates/mono/app/api-reference/[[...slug]]/page.tsx
rename to archive/templates/galley/app/api-reference/[[...slug]]/page.tsx
diff --git a/templates/mono/app/api/ask/route.ts b/archive/templates/galley/app/api/ask/route.ts
similarity index 100%
rename from templates/mono/app/api/ask/route.ts
rename to archive/templates/galley/app/api/ask/route.ts
diff --git a/templates/mono/app/blog/[slug]/page.tsx b/archive/templates/galley/app/blog/[slug]/page.tsx
similarity index 100%
rename from templates/mono/app/blog/[slug]/page.tsx
rename to archive/templates/galley/app/blog/[slug]/page.tsx
diff --git a/templates/mono/app/blog/page.tsx b/archive/templates/galley/app/blog/page.tsx
similarity index 100%
rename from templates/mono/app/blog/page.tsx
rename to archive/templates/galley/app/blog/page.tsx
diff --git a/templates/mono/app/changelog/page.tsx b/archive/templates/galley/app/changelog/page.tsx
similarity index 100%
rename from templates/mono/app/changelog/page.tsx
rename to archive/templates/galley/app/changelog/page.tsx
diff --git a/archive/templates/galley/app/layout.tsx b/archive/templates/galley/app/layout.tsx
new file mode 100644
index 0000000..e84db3c
--- /dev/null
+++ b/archive/templates/galley/app/layout.tsx
@@ -0,0 +1,59 @@
+import type { Metadata } from 'next';
+import { Newsreader, JetBrains_Mono } from 'next/font/google';
+import '@inkform/framework/styles.css';
+import './theme.css';
+import { themeInitScript } from '@inkform/framework/theme-toggle';
+import { loadDocsConfig } from '@inkform/framework/content';
+
+// Two-voice typography: Newsreader is the human/prose voice (display +
+// long-form reading), General Sans is the UI voice (loaded via a <link> tag
+// in <head> below — it's a Fontshare font, not on Google Fonts, so it can't
+// go through next/font/google), JetBrains Mono is the machine voice (anything
+// Git touches: paths, hashes, commits, code). Matches the Galley design
+// system's own font stack exactly (see the inkform-design skill).
+const newsreader = Newsreader({
+  subsets: ['latin'],
+  style: ['normal', 'italic'],
+  variable: '--font-heading',
+  display: 'swap',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ['latin'],
+  variable: '--font-mono',
+  display: 'swap',
+});
+
+export async function generateMetadata(): Promise<Metadata> {
+  const config = loadDocsConfig();
+  const name = config?.name ?? 'Galley Docs';
+  return {
+    title: { default: name, template: `%s · ${name}` },
+    description: `Documentation for ${name}`,
+    icons: { icon: config?.favicon ?? '/favicon.svg' },
+  };
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html
+      lang="en"
+      className={`${newsreader.variable} ${jetbrainsMono.variable}`}
+      suppressHydrationWarning
+    >
+      <head>
+        {/* No-flash theme init — must run synchronously before first paint */}
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+        {/* General Sans — Fontshare (not on Google Fonts). See the
+            inkform-design skill's readme.md § Fonts: CDN for now, self-host
+            by dropping binaries in assets/fonts/ and swapping this for a
+            local @font-face rule. */}
+        <link
+          rel="stylesheet"
+          href="https://api.fontshare.com/v2/css?f[]=general-sans@200,300,400,500,600,700&display=swap"
+        />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
diff --git a/archive/templates/galley/app/theme.css b/archive/templates/galley/app/theme.css
new file mode 100644
index 0000000..cdfc6c3
--- /dev/null
+++ b/archive/templates/galley/app/theme.css
@@ -0,0 +1,104 @@
+/*
+ * Galley theme — token overrides for @inkform/framework.
+ * This file is imported AFTER framework/styles.css so its declarations win.
+ * Only --fw-* tokens and small Galley-specific accents are set here.
+ * The framework's structural CSS is untouched.
+ *
+ * Identity: Inkform's own design system — a printer's galley. Warm opaque
+ * paper + ink, one editorial "Proof" red-pencil accent (#C24E3D, unchanged
+ * between light/dark). Depth from paper layering + hairlines, never heavy
+ * shadow or gradient. Values below are lifted directly from the
+ * `inkform-design` skill's tokens/{colors,effects,typography}.css — the
+ * authoritative source; do not hand-tune a value here without checking there
+ * first.
+ */
+
+/* ── Font variables ───────────────────────────────────────────────────────
+   --font-heading and --font-mono are set by next/font in layout.tsx. General
+   Sans has no next/font variable — it's a Fontshare font (loaded via a
+   <link> tag in layout.tsx's <head>), so it's named directly here. */
+:root {
+  --fw-font: 'General Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --fw-font-heading: var(--font-heading, 'Newsreader', Georgia, 'Times New Roman', serif);
+  --fw-mono: var(--font-mono, ui-monospace, 'JetBrains Mono', 'SF Mono', Menlo, monospace);
+}
+
+/* ── Light mode (default) — paper: canvas → raised → well ───────────────── */
+:root {
+  /* Surfaces */
+  --fw-bg: #fcfbf7;
+  --fw-bg-subtle: #f6f4ed;
+  --fw-fg: #191813;
+  --fw-muted: #8b8779;
+  --fw-border: #e4e0d4;
+  --fw-border-strong: #d8d3c5;
+  --fw-card: #f6f4ed;
+  --fw-card-hover: #efebe1;
+  --fw-code-bg: #efebe1;
+  --fw-kbd-bg: #efebe1;
+
+  /* Brand — the proof-red pencil accent */
+  --fw-primary: #c24e3d;
+  --fw-primary-fg: #fcfbf7;
+  --fw-primary-subtle: #f7e9e6;
+
+  /* Shape — Galley's card radius / control radius */
+  --fw-radius: 10px;
+  --fw-radius-sm: 6px;
+
+  /* Shadows — warm-tinted, low elevation, never heavy blur or hard-offset */
+  --fw-shadow: 0 1px 2px rgba(40, 30, 20, 0.05), 0 2px 4px rgba(40, 30, 20, 0.04);
+  --fw-shadow-lg: 0 4px 8px rgba(40, 30, 20, 0.06), 0 14px 34px rgba(40, 30, 20, 0.10);
+  --fw-ring: 0 0 0 3px #f7e9e6;
+
+  /* HTTP method pills — Galley's brand tokens don't define API-method colors
+     (out of brand scope), so these lean on the palette's own git-semantic +
+     warning hues rather than introducing cool blues that would clash with
+     the warm paper surface. */
+  --fw-method-get: #4c9a5c;
+  --fw-method-post: #c24e3d;
+  --fw-method-put: #a9762a;
+  --fw-method-patch: #8a5a78;
+  --fw-method-delete: #97392c;
+  --fw-method-head: #4f7a78;
+  --fw-method-options: #8b8779;
+}
+
+/* ── Dark mode — warm ink, never blue-grey ───────────────────────────────── */
+html.dark {
+  --fw-bg: #131210;
+  --fw-bg-subtle: #1b1a17;
+  --fw-fg: #f2efe6;
+  --fw-muted: #7b776b;
+  --fw-border: #2f2d28;
+  --fw-border-strong: #3b3833;
+  --fw-card: #1b1a17;
+  --fw-card-hover: #242320;
+  --fw-code-bg: #242320;
+  --fw-kbd-bg: #242320;
+
+  /* Brand — Proof holds its value; only the tint deepens */
+  --fw-primary: #c24e3d;
+  --fw-primary-fg: #fcfbf7;
+  --fw-primary-subtle: #33201d;
+
+  /* Shadows on warm near-black */
+  --fw-shadow: 0 1px 2px rgba(0, 0, 0, 0.34), 0 2px 4px rgba(0, 0, 0, 0.28);
+  --fw-shadow-lg: 0 6px 14px rgba(0, 0, 0, 0.46), 0 18px 40px rgba(0, 0, 0, 0.52);
+  --fw-ring: 0 0 0 3px #33201d;
+
+  /* HTTP method pills — lifted for dark stock, same hue family as light */
+  --fw-method-get: #74be84;
+  --fw-method-post: #d6796b;
+  --fw-method-put: #d3a45e;
+  --fw-method-patch: #b586a8;
+  --fw-method-delete: #d98379;
+  --fw-method-head: #7fa8a6;
+  --fw-method-options: #aba79a;
+}
+
+/* Top bar (tabs/anchors/nav links/CTA/brand) is now styled by the shared
+   framework layer (packages/framework/src/styles/layout.css) — it only
+   ever consumed --fw-* tokens here, so there was nothing theme-specific
+   left to override for Galley. See Mono's theme.css for an example of a
+   theme that DOES need a delta on top of the shared base. */
diff --git a/templates/mono/components/top-bar.tsx b/archive/templates/galley/components/top-bar.tsx
similarity index 100%
rename from templates/mono/components/top-bar.tsx
rename to archive/templates/galley/components/top-bar.tsx
diff --git a/templates/mono/content/docs/development.mdx b/archive/templates/galley/content/docs/development.mdx
similarity index 100%
rename from templates/mono/content/docs/development.mdx
rename to archive/templates/galley/content/docs/development.mdx
diff --git a/archive/templates/galley/content/docs/docs.json b/archive/templates/galley/content/docs/docs.json
new file mode 100644
index 0000000..bb4e9e7
--- /dev/null
+++ b/archive/templates/galley/content/docs/docs.json
@@ -0,0 +1,45 @@
+{
+  "name": "Galley",
+  "version": "1.0.0",
+  "logo": "/logo.svg",
+  "favicon": "/favicon.svg",
+  "colors": { "primary": "#c24e3d" },
+  "navbarLinks": [
+    { "name": "Support", "href": "mailto:support@example.com" }
+  ],
+  "anchors": [
+    { "name": "Documentation", "href": "/", "icon": "book" },
+    { "name": "GitHub", "href": "https://github.com/inkform-dev/framework", "icon": "github" }
+  ],
+  "cta": { "label": "Dashboard", "href": "https://example.com/dashboard" },
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx", "icon": "book-open" },
+            { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx", "icon": "rocket" },
+            { "title": "Development", "slug": "development", "file": "development.mdx", "icon": "terminal" }
+          ]
+        },
+        {
+          "group": "Essentials",
+          "pages": [
+            { "title": "Markdown Syntax", "slug": "essentials/markdown", "file": "essentials/markdown.mdx", "icon": "type" },
+            { "title": "Code Blocks", "slug": "essentials/code-blocks", "file": "essentials/code-blocks.mdx", "icon": "code" },
+            { "title": "Images & Embeds", "slug": "essentials/images", "file": "essentials/images.mdx", "icon": "image" },
+            { "title": "Components", "slug": "essentials/components", "file": "essentials/components.mdx", "icon": "blocks" },
+            { "title": "Navigation", "slug": "essentials/navigation", "file": "essentials/navigation.mdx", "icon": "map" }
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "API Reference",
+      "openapi": "openapi.json",
+      "apiReference": { "renderer": "native" }
+    }
+  ]
+}
diff --git a/templates/mono/content/docs/essentials/code-blocks.mdx b/archive/templates/galley/content/docs/essentials/code-blocks.mdx
similarity index 100%
rename from templates/mono/content/docs/essentials/code-blocks.mdx
rename to archive/templates/galley/content/docs/essentials/code-blocks.mdx
diff --git a/templates/mono/content/docs/essentials/components.mdx b/archive/templates/galley/content/docs/essentials/components.mdx
similarity index 100%
rename from templates/mono/content/docs/essentials/components.mdx
rename to archive/templates/galley/content/docs/essentials/components.mdx
diff --git a/templates/mono/content/docs/essentials/images.mdx b/archive/templates/galley/content/docs/essentials/images.mdx
similarity index 100%
rename from templates/mono/content/docs/essentials/images.mdx
rename to archive/templates/galley/content/docs/essentials/images.mdx
diff --git a/templates/mono/content/docs/essentials/markdown.mdx b/archive/templates/galley/content/docs/essentials/markdown.mdx
similarity index 100%
rename from templates/mono/content/docs/essentials/markdown.mdx
rename to archive/templates/galley/content/docs/essentials/markdown.mdx
diff --git a/templates/mono/content/docs/essentials/navigation.mdx b/archive/templates/galley/content/docs/essentials/navigation.mdx
similarity index 100%
rename from templates/mono/content/docs/essentials/navigation.mdx
rename to archive/templates/galley/content/docs/essentials/navigation.mdx
diff --git a/archive/templates/galley/content/docs/index.mdx b/archive/templates/galley/content/docs/index.mdx
new file mode 100644
index 0000000..d851ecc
--- /dev/null
+++ b/archive/templates/galley/content/docs/index.mdx
@@ -0,0 +1,47 @@
+---
+title: Introduction
+description: Welcome to Galley — Inkform's own warm paper-and-ink documentation theme.
+---
+
+# Welcome to Galley
+
+Galley is Inkform's own design system for documentation — warm paper + ink, one
+editorial "Proof" red-pencil accent, a serif prose voice beside a mono machine
+voice. Powered by [`@inkform/framework`](https://github.com/inkform-dev/framework):
+write Markdown, commit it, and ship a fast, searchable, themeable site — no CMS,
+no database, no visual opinions in the way.
+
+<Frame caption="Your docs, your repo, your deploy.">
+  ![Hero](/hero.svg)
+</Frame>
+
+## Set up
+
+The first step to world-class documentation is setting up your editing
+environment and making the site your own.
+
+<CardGroup cols={2}>
+  <Card title="Edit your docs" icon="pencil" href="/quickstart">
+    Get your docs running locally for fast iteration.
+  </Card>
+  <Card title="Preview changes" icon="eye" href="/development">
+    Preview every change before you push so it's always right.
+  </Card>
+  <Card title="Write in MDX" icon="type" href="/essentials/markdown">
+    Markdown with components — callouts, cards, steps, tabs, and more.
+  </Card>
+  <Card title="API Reference" icon="terminal" href="/essentials/navigation">
+    Point `docs.json` at an OpenAPI spec and get a full API reference.
+  </Card>
+</CardGroup>
+
+## Make it yours
+
+Every theme is driven by the same engine and a single `theme.css` token file, so
+you can recolor, re-font, and restyle the whole site without touching layout
+code.
+
+<Note>
+  New here? Start with the [Quickstart](/quickstart) — you'll have a site running
+  in under five minutes.
+</Note>
diff --git a/templates/mono/content/docs/openapi.json b/archive/templates/galley/content/docs/openapi.json
similarity index 100%
rename from templates/mono/content/docs/openapi.json
rename to archive/templates/galley/content/docs/openapi.json
diff --git a/templates/mono/content/docs/quickstart.mdx b/archive/templates/galley/content/docs/quickstart.mdx
similarity index 100%
rename from templates/mono/content/docs/quickstart.mdx
rename to archive/templates/galley/content/docs/quickstart.mdx
diff --git a/templates/mono/content/docs/slug-history.json b/archive/templates/galley/content/docs/slug-history.json
similarity index 100%
rename from templates/mono/content/docs/slug-history.json
rename to archive/templates/galley/content/docs/slug-history.json
diff --git a/templates/mono/lib/icons.tsx b/archive/templates/galley/lib/icons.tsx
similarity index 100%
rename from templates/mono/lib/icons.tsx
rename to archive/templates/galley/lib/icons.tsx
diff --git a/templates/mono/lib/route.tsx b/archive/templates/galley/lib/route.tsx
similarity index 100%
rename from templates/mono/lib/route.tsx
rename to archive/templates/galley/lib/route.tsx
diff --git a/templates/mono/mdx-components.tsx b/archive/templates/galley/mdx-components.tsx
similarity index 100%
rename from templates/mono/mdx-components.tsx
rename to archive/templates/galley/mdx-components.tsx
diff --git a/templates/mono/next-env.d.ts b/archive/templates/galley/next-env.d.ts
similarity index 100%
rename from templates/mono/next-env.d.ts
rename to archive/templates/galley/next-env.d.ts
diff --git a/templates/mono/next.config.ts b/archive/templates/galley/next.config.ts
similarity index 100%
rename from templates/mono/next.config.ts
rename to archive/templates/galley/next.config.ts
diff --git a/archive/templates/galley/package.json b/archive/templates/galley/package.json
new file mode 100644
index 0000000..6e2340f
--- /dev/null
+++ b/archive/templates/galley/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@inkform/theme-galley",
+  "version": "0.2.0",
+  "private": true,
+  "description": "Galley — the warm paper-and-ink editorial theme for @inkform/framework (Inkform's own design system).",
+  "license": "MIT",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inkform/framework": "^0.3.0",
+    "lucide-react": "^0.483.0",
+    "next": "16.2.10",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "pagefind": "^1.5.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "typescript": "^5"
+  }
+}
diff --git a/templates/mono/proxy.ts b/archive/templates/galley/proxy.ts
similarity index 100%
rename from templates/mono/proxy.ts
rename to archive/templates/galley/proxy.ts
diff --git a/archive/templates/galley/public/favicon.svg b/archive/templates/galley/public/favicon.svg
new file mode 100644
index 0000000..43d31e9
--- /dev/null
+++ b/archive/templates/galley/public/favicon.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="Base favicon">
+  <!-- Neutral dark background square -->
+  <rect width="32" height="32" rx="7" fill="#0d0d0d"/>
+  <!-- Stacked squares mark -->
+  <rect x="8"  y="14" width="14" height="10" rx="2" fill="#c24e3d"/>
+  <rect x="10" y="8"  width="14" height="10" rx="2" fill="#d6796b" opacity="0.5"/>
+</svg>
diff --git a/archive/templates/galley/public/hero.svg b/archive/templates/galley/public/hero.svg
new file mode 100644
index 0000000..3ace538
--- /dev/null
+++ b/archive/templates/galley/public/hero.svg
@@ -0,0 +1,67 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" fill="none" role="img" aria-label="Base documentation hero">
+  <!-- Clean neutral dark background -->
+  <rect width="800" height="360" rx="10" fill="#0d0d0d"/>
+  <!-- Subtle dot grid pattern -->
+  <defs>
+    <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="1" cy="1" r="1" fill="#222222"/>
+    </pattern>
+  </defs>
+  <rect width="800" height="360" fill="url(#dots)"/>
+
+  <!-- Left: stacked-square composition (brand mark, large) -->
+  <rect x="60"  y="160" width="80" height="60" rx="6" fill="#1a1a1a" stroke="#c24e3d" stroke-width="1.5"/>
+  <rect x="80"  y="140" width="80" height="60" rx="6" fill="#141414" stroke="#333333" stroke-width="1"/>
+  <rect x="100" y="120" width="80" height="60" rx="6" fill="#111111" stroke="#222222" stroke-width="1"/>
+  <!-- Blue accent square on top layer -->
+  <rect x="108" y="128" width="20" height="20" rx="3" fill="#c24e3d" opacity="0.9"/>
+  <rect x="134" y="128" width="36" height="6"  rx="2" fill="#333333"/>
+  <rect x="134" y="140" width="26" height="6"  rx="2" fill="#2a2a2a"/>
+  <rect x="108" y="155" width="62" height="6"  rx="2" fill="#2a2a2a"/>
+
+  <!-- Right: docs/browser window mock -->
+  <rect x="440" y="55" width="310" height="230" rx="8" fill="#141414" stroke="#222222" stroke-width="1"/>
+  <!-- Window top bar -->
+  <rect x="440" y="55" width="310" height="36" rx="8" fill="#1a1a1a"/>
+  <rect x="440" y="79" width="310" height="12" fill="#1a1a1a"/>
+  <!-- Address-bar pill -->
+  <rect x="510" y="66" width="170" height="14" rx="7" fill="#222222"/>
+  <!-- Back / fwd dots (nav circles) -->
+  <circle cx="460" cy="73" r="5" fill="#2a2a2a"/>
+  <circle cx="474" cy="73" r="5" fill="#2a2a2a"/>
+  <!-- Sidebar strip -->
+  <rect x="440" y="91" width="80" height="194" rx="0" fill="#111111"/>
+  <rect x="440" y="91" width="80" height="194" rx="0" fill="#111111"/>
+  <!-- Sidebar links -->
+  <rect x="452" y="104" width="52" height="6" rx="3" fill="#333333"/>
+  <rect x="452" y="118" width="44" height="6" rx="3" fill="#c24e3d" opacity="0.7"/>
+  <rect x="452" y="132" width="48" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="146" width="40" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="160" width="50" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="182" width="52" height="6" rx="3" fill="#333333"/>
+  <rect x="452" y="196" width="44" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="210" width="48" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="224" width="36" height="6" rx="3" fill="#2a2a2a"/>
+  <!-- Active sidebar indicator -->
+  <rect x="440" y="115" width="3" height="14" rx="1.5" fill="#c24e3d"/>
+  <!-- Content area lines -->
+  <rect x="534" y="104" width="120" height="10" rx="3" fill="#222222"/>
+  <rect x="534" y="122" width="200" height="6"  rx="2" fill="#1e1e1e"/>
+  <rect x="534" y="136" width="180" height="6"  rx="2" fill="#1e1e1e"/>
+  <rect x="534" y="150" width="195" height="6"  rx="2" fill="#1e1e1e"/>
+  <!-- Code block mock -->
+  <rect x="534" y="170" width="200" height="52" rx="4" fill="#111111" stroke="#222222" stroke-width="1"/>
+  <rect x="542" y="179" width="70"  height="5"  rx="2" fill="#c24e3d" opacity="0.5"/>
+  <rect x="542" y="192" width="110" height="5"  rx="2" fill="#2a2a2a"/>
+  <rect x="542" y="205" width="90"  height="5"  rx="2" fill="#2a2a2a"/>
+  <rect x="542" y="218" width="55"  height="5"  rx="2" fill="#d6796b" opacity="0.35"/>
+
+  <!-- Bottom left: subtle text placeholder lines -->
+  <rect x="60" y="242" width="280" height="8" rx="3" fill="#1e1e1e"/>
+  <rect x="60" y="258" width="240" height="6" rx="2" fill="#1a1a1a"/>
+  <rect x="60" y="272" width="200" height="6" rx="2" fill="#1a1a1a"/>
+
+  <!-- Blue accent bottom rule -->
+  <rect x="60" y="300" width="40" height="3" rx="1.5" fill="#c24e3d"/>
+  <rect x="108" y="300" width="20" height="3" rx="1.5" fill="#c24e3d" opacity="0.35"/>
+</svg>
diff --git a/archive/templates/galley/public/logo.svg b/archive/templates/galley/public/logo.svg
new file mode 100644
index 0000000..5e9185b
--- /dev/null
+++ b/archive/templates/galley/public/logo.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 32" fill="none" role="img" aria-label="Base">
+  <!-- Stacked squares mark (base/foundation metaphor) -->
+  <rect x="2" y="12" width="12" height="12" rx="2" fill="#c24e3d"/>
+  <rect x="6" y="7"  width="12" height="12" rx="2" fill="#c24e3d" opacity="0.4"/>
+  <!-- Wordmark -->
+  <text x="24" y="21" font-family="ui-sans-serif, system-ui, -apple-system, sans-serif" font-size="14" font-weight="700" letter-spacing="-0.02em" fill="currentColor">Base</text>
+</svg>
diff --git a/templates/mono/tsconfig.json b/archive/templates/galley/tsconfig.json
similarity index 100%
rename from templates/mono/tsconfig.json
rename to archive/templates/galley/tsconfig.json
diff --git a/templates/mono/widgets/index.ts b/archive/templates/galley/widgets/index.ts
similarity index 100%
rename from templates/mono/widgets/index.ts
rename to archive/templates/galley/widgets/index.ts
diff --git a/archive/templates/mono/.env.example b/archive/templates/mono/.env.example
new file mode 100644
index 0000000..39cd584
--- /dev/null
+++ b/archive/templates/mono/.env.example
@@ -0,0 +1,14 @@
+# ── Required ─────────────────────────────────────────────────────────────────
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# ── AI assistant (disabled by default) ───────────────────────────────────────
+# Set to "true" to enable the Ask AI widget in the top bar.
+# The widget is rendered even when disabled; it shows an informational notice.
+NEXT_PUBLIC_DOCS_AI_ENABLED=false
+
+# The following vars only matter when NEXT_PUBLIC_DOCS_AI_ENABLED=true.
+# They are read by the /api/ask route at runtime (server-only, never sent to
+# the browser).
+# DOCS_AI_PROVIDER=anthropic
+# DOCS_AI_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
diff --git a/archive/templates/mono/.gitignore b/archive/templates/mono/.gitignore
new file mode 100644
index 0000000..da1f289
--- /dev/null
+++ b/archive/templates/mono/.gitignore
@@ -0,0 +1,8 @@
+node_modules
+.next
+out
+.env*.local
+.vercel
+*.tsbuildinfo
+.DS_Store
+public/_pagefind
diff --git a/templates/mono/README.md b/archive/templates/mono/README.md
similarity index 100%
rename from templates/mono/README.md
rename to archive/templates/mono/README.md
diff --git a/archive/templates/mono/app/[[...slug]]/page.tsx b/archive/templates/mono/app/[[...slug]]/page.tsx
new file mode 100644
index 0000000..5dd0aaf
--- /dev/null
+++ b/archive/templates/mono/app/[[...slug]]/page.tsx
@@ -0,0 +1,63 @@
+import { notFound } from 'next/navigation';
+import { Mdx } from '@inkform/framework/mdx';
+import { DocsShell, Sidebar, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { docNeighbours } from '@inkform/framework';
+import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
+import { siteMdxComponents } from '@/mdx-components';
+import { buildTopBar } from '@/components/top-bar';
+import { renderIcon } from '@/lib/icons';
+import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+export function generateStaticParams() {
+  const config = loadDocsConfig();
+  if (!config) return [{ slug: [] as string[] }];
+  const routes = listAllRoutes(config);
+  // Next.js optional catch-all: [] = index, [...rest] = nested. Map [] → undefined
+  // to match the [[...slug]] convention (both work, but undefined is canonical).
+  return routes.map((slug) => ({ slug: slug.length === 0 ? undefined : slug }));
+}
+
+// ── Metadata ─────────────────────────────────────────────────────────────────
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) return {};
+  return { title: route.ref.title };
+}
+
+// ── Page ──────────────────────────────────────────────────────────────────────
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) notFound();
+
+  const { config, ref, page, tab } = route;
+  const headings = extractHeadings(page.content);
+  const { prev, next } = docNeighbours(config, ref.slug);
+  const sidebar = sidebarForDoc(config, tab, ref.slug, renderIcon);
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  return (
+    <DocsShell
+      contentType="doc"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      sidebar={<Sidebar groups={sidebar} />}
+      toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
+      hideToc={headings.length === 0}
+    >
+      <Mdx source={page.content} components={siteMdxComponents} />
+      <Pagination
+        prev={prev ? { title: prev.title, href: '/' + prev.slug } : null}
+        next={next ? { title: next.title, href: '/' + next.slug } : null}
+      />
+    </DocsShell>
+  );
+}
diff --git a/archive/templates/mono/app/api-reference/[[...slug]]/page.tsx b/archive/templates/mono/app/api-reference/[[...slug]]/page.tsx
new file mode 100644
index 0000000..7c3a451
--- /dev/null
+++ b/archive/templates/mono/app/api-reference/[[...slug]]/page.tsx
@@ -0,0 +1,104 @@
+import type { ReactNode } from 'react';
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadDocsConfig, loadOpenApiSpecForBuild } from '@inkform/framework/content';
+import { findOperation, parseOpenApi } from '@inkform/framework/openapi';
+import { parseOpenApiDocument } from '@inkform/framework/openapi-engine/parse';
+import { buildNavTree } from '@inkform/framework/openapi-engine/nav';
+import { OperationPage, ReferenceSidebar } from '@inkform/framework/openapi-render';
+import { buildTopBar } from '@/components/top-bar';
+import { apiBasePath, apiTab, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+/**
+ * Loads the spec twice — once via parseOpenApi (the narrow OpenApiModel
+ * used for ApiLink-style operation lookup) and once via parseOpenApiDocument
+ * + buildNavTree (the full dereferenced document, needed for the nav tree).
+ * Both bundle/dereference the same spec independently; negligible at this
+ * spec's size and this only runs at build time, but worth consolidating
+ * into one pass if a second native-renderer consumer needs both shapes.
+ */
+async function loadReference() {
+  const config = loadDocsConfig();
+  if (!config) return null;
+  const tab = apiTab(config);
+  if (!tab?.openapi || tab.apiReference?.renderer === 'scalar') return null;
+
+  const spec = await loadOpenApiSpecForBuild(tab.openapi);
+  if (!spec) return null;
+
+  const [model, { schema }] = await Promise.all([
+    parseOpenApi(spec.raw, spec.format),
+    parseOpenApiDocument(spec.raw, { format: spec.format }),
+  ]);
+
+  return { config, tab, model, tree: buildNavTree(schema) };
+}
+
+export async function generateStaticParams() {
+  const ref = await loadReference();
+  if (!ref) return [{ slug: undefined }];
+
+  const params: { slug?: string[] }[] = [{ slug: undefined }];
+  for (const group of ref.tree.tagGroups) {
+    for (const op of group.operations) {
+      params.push({ slug: ['operations', op.operationId] });
+    }
+  }
+  return params;
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) return {};
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(ref.model, slug[1]);
+    if (op) return { title: `${op.summary} · ${ref.model.info.title}` };
+  }
+  return { title: ref.model.info.title };
+}
+
+export default async function ApiReferencePage({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) notFound();
+
+  const { config, tab, model, tree } = ref;
+  const basePath = `/${apiBasePath(config)}`;
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  let content: ReactNode;
+  let activeOperationId: string | undefined;
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(model, slug[1]);
+    if (!op) notFound();
+    activeOperationId = op.operationId;
+    content = <OperationPage operation={op} servers={model.servers} />;
+  } else {
+    content = (
+      <div className="fw-apiref">
+        <div className="fw-apiref-header">
+          <h1 className="fw-apiref-title">{model.info.title}</h1>
+          {model.info.description ? <p className="fw-apiref-desc">{model.info.description}</p> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <DocsShell
+      contentType="api"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      sidebar={<ReferenceSidebar tree={tree} basePath={basePath} activeOperationId={activeOperationId} />}
+      hideToc
+    >
+      {content}
+    </DocsShell>
+  );
+}
diff --git a/archive/templates/mono/app/api/ask/route.ts b/archive/templates/mono/app/api/ask/route.ts
new file mode 100644
index 0000000..d9da707
--- /dev/null
+++ b/archive/templates/mono/app/api/ask/route.ts
@@ -0,0 +1,60 @@
+import { askDocs } from '@inkform/framework/ai';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+export const runtime = 'nodejs';
+
+/**
+ * POST /api/ask — AI assistant endpoint (feature-flagged).
+ *
+ * Grounded in this site's own content via askDocs() (@inkform/framework/ai)
+ * — the same search/getDoc/getOperation retrieval the MCP server uses, not
+ * a separate implementation. BYO model: set DOCS_AI_PROVIDER
+ * ('anthropic' | 'openai' | 'google', default 'anthropic') and that
+ * provider's own API key env var (ANTHROPIC_API_KEY, etc.) — see
+ * packages/framework/src/ai/provider.ts.
+ *
+ * Metered billing for the platform-hosted version of this endpoint is
+ * out of scope here — see inkform/PLATFORM_MCP_SCOPING.md for the sibling
+ * MCP billing question this will eventually need the same answer to.
+ */
+export async function POST(request: Request): Promise<Response> {
+  const enabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  if (!enabled) {
+    return Response.json(
+      {
+        error:
+          'AI assistant is disabled. Set NEXT_PUBLIC_DOCS_AI_ENABLED=true to enable it (configured in a later release).',
+      },
+      { status: 503 },
+    );
+  }
+
+  let messages: unknown;
+  try {
+    const body = (await request.json()) as { messages?: unknown };
+    messages = body?.messages;
+  } catch {
+    return Response.json({ error: 'Invalid request body.' }, { status: 400 });
+  }
+
+  if (!Array.isArray(messages) || messages.some((m) => typeof m?.role !== 'string' || typeof m?.content !== 'string')) {
+    return Response.json({ error: 'messages must be an array of { role, content }.' }, { status: 400 });
+  }
+
+  const config = loadDocsConfig();
+  // apiBasePath() returns a bare slug (e.g. "api-reference"); askDocs()
+  // expects a leading-slash base path to build clickable operation links.
+  const apiBase = config && apiBasePath(config);
+  try {
+    const result = await askDocs(messages, { apiBasePath: apiBase ? `/${apiBase}` : undefined });
+    return Response.json(result);
+  } catch (e) {
+    // Most likely cause: no API key configured for DOCS_AI_PROVIDER.
+    return Response.json(
+      { error: e instanceof Error ? e.message : 'The AI assistant is not configured correctly.' },
+      { status: 500 },
+    );
+  }
+}
diff --git a/archive/templates/mono/app/blog/[slug]/page.tsx b/archive/templates/mono/app/blog/[slug]/page.tsx
new file mode 100644
index 0000000..952691f
--- /dev/null
+++ b/archive/templates/mono/app/blog/[slug]/page.tsx
@@ -0,0 +1,40 @@
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadBlogPosts, loadBlogPost } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return loadBlogPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  return { title: post?.title ?? 'Blog' };
+}
+
+export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  if (!post) notFound();
+
+  const config = loadDocsConfig();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>{post.title}</h1>
+        <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+          {post.date} · {post.readingTime} min read{post.author ? ` · ${post.author}` : ''}
+        </p>
+      </div>
+      <Mdx source={post.content} components={siteMdxComponents} />
+    </DocsShell>
+  );
+}
diff --git a/archive/templates/mono/app/blog/page.tsx b/archive/templates/mono/app/blog/page.tsx
new file mode 100644
index 0000000..79bffff
--- /dev/null
+++ b/archive/templates/mono/app/blog/page.tsx
@@ -0,0 +1,38 @@
+import Link from 'next/link';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadBlogPosts } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+
+export const metadata = { title: 'Blog' };
+
+export default function BlogIndexPage() {
+  const config = loadDocsConfig();
+  const posts = loadBlogPosts();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Blog</h1>
+        {posts.length === 0 ? (
+          <p>No posts yet — check back soon.</p>
+        ) : (
+          <ul style={{ listStyle: 'none', padding: 0 }}>
+            {posts.map((p) => (
+              <li key={p.slug} style={{ marginBottom: '2rem' }}>
+                <Link href={`/blog/${p.slug}`}>
+                  <h2 style={{ marginBottom: '0.25rem' }}>{p.title}</h2>
+                </Link>
+                <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+                  {p.date} · {p.readingTime} min read{p.author ? ` · ${p.author}` : ''}
+                </p>
+                {p.description ? <p>{p.description}</p> : null}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </DocsShell>
+  );
+}
diff --git a/archive/templates/mono/app/changelog/page.tsx b/archive/templates/mono/app/changelog/page.tsx
new file mode 100644
index 0000000..05cbac9
--- /dev/null
+++ b/archive/templates/mono/app/changelog/page.tsx
@@ -0,0 +1,33 @@
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadChangelogEntries } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const metadata = { title: 'Changelog' };
+
+export default function ChangelogPage() {
+  const config = loadDocsConfig();
+  const entries = loadChangelogEntries();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Changelog</h1>
+        {entries.length === 0 ? <p>No entries yet.</p> : null}
+      </div>
+      {entries.map((e) => (
+        <div key={e.slug} className="fw-prose" style={{ marginTop: '2rem' }}>
+          <p style={{ opacity: 0.7, fontSize: '0.875rem', marginBottom: '0.25rem' }}>
+            {e.date}
+            {e.version ? ` · v${e.version}` : ''}
+          </p>
+          <h2>{e.title}</h2>
+          <Mdx source={e.content} components={siteMdxComponents} />
+        </div>
+      ))}
+    </DocsShell>
+  );
+}
diff --git a/templates/mono/app/layout.tsx b/archive/templates/mono/app/layout.tsx
similarity index 100%
rename from templates/mono/app/layout.tsx
rename to archive/templates/mono/app/layout.tsx
diff --git a/templates/mono/app/theme.css b/archive/templates/mono/app/theme.css
similarity index 100%
rename from templates/mono/app/theme.css
rename to archive/templates/mono/app/theme.css
diff --git a/archive/templates/mono/components/top-bar.tsx b/archive/templates/mono/components/top-bar.tsx
new file mode 100644
index 0000000..61dc77a
--- /dev/null
+++ b/archive/templates/mono/components/top-bar.tsx
@@ -0,0 +1,134 @@
+import type { ReactNode } from 'react';
+import Link from 'next/link';
+import { AskAi } from '@inkform/framework/ask-ai';
+import { ThemeToggle } from '@inkform/framework/theme-toggle';
+import { SearchDialog } from '@inkform/framework/search-dialog';
+import type { DocsConfig } from '@inkform/framework';
+import { docTabs } from '@inkform/framework';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+// ── Brand logo ────────────────────────────────────────────────────────────────
+
+function Logo({ config }: { config: DocsConfig }) {
+  const logo =
+    typeof config.logo === 'string'
+      ? config.logo
+      : config.logo?.dark ?? config.logo?.light ?? null;
+
+  return (
+    <Link href="/" className="fw-shell-brand" aria-label={`${config.name} home`}>
+      {logo ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img src={logo} alt={config.name} height={24} className="fw-shell-brand-logo" />
+      ) : (
+        <span className="fw-shell-brand-name">{config.name}</span>
+      )}
+    </Link>
+  );
+}
+
+// ── Tab nav ───────────────────────────────────────────────────────────────────
+
+function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
+  const tabs = docTabs(config);
+  const apiBase = apiBasePath(config);
+
+  return (
+    <div className="fw-topnav-tabs">
+      {tabs.map((t) => {
+        const href = t.openapi && apiBase ? `/${apiBase}` : '/';
+        const isActive = t.tab === activeTab;
+        return (
+          <a
+            key={t.tab}
+            href={href}
+            className={`fw-topnav-tab${isActive ? ' fw-topnav-tab--active' : ''}`}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            {t.tab}
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── Anchor links ──────────────────────────────────────────────────────────────
+
+function AnchorLinks({ config }: { config: DocsConfig }) {
+  const anchors = config.anchors ?? [];
+  if (anchors.length === 0) return null;
+  return (
+    <div className="fw-topnav-anchors">
+      {anchors.map((a) => (
+        <a
+          key={a.href}
+          href={a.href}
+          className="fw-topnav-anchor"
+          target={a.href.startsWith('http') ? '_blank' : undefined}
+          rel={a.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {a.name}
+        </a>
+      ))}
+    </div>
+  );
+}
+
+// ── Top bar props ─────────────────────────────────────────────────────────────
+
+export interface TopBarParts {
+  logo: ReactNode;
+  topNav: ReactNode;
+  topActions: ReactNode;
+}
+
+/**
+ * Build the three DocsShell header slot contents for Aurora.
+ * Server component — client islands (SearchDialog, ThemeToggle, AskAi) are
+ * already marked 'use client' in the framework.
+ */
+export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
+  const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  const logo = <Logo config={config} />;
+
+  const topNav = (
+    <>
+      <TabNav config={config} activeTab={activeTab} />
+      <AnchorLinks config={config} />
+      {(config.navbarLinks ?? []).map((l) => (
+        <a
+          key={l.href}
+          href={l.href}
+          className="fw-topnav-navlink"
+          target={l.href.startsWith('http') ? '_blank' : undefined}
+          rel={l.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {l.name}
+        </a>
+      ))}
+    </>
+  );
+
+  const topActions = (
+    <>
+      <SearchDialog />
+      <ThemeToggle />
+      <AskAi enabled={aiEnabled} product={config.name} />
+      {config.cta ? (
+        <a
+          href={config.cta.href}
+          className="fw-topnav-cta"
+          target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+          rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {config.cta.label}
+        </a>
+      ) : null}
+    </>
+  );
+
+  return { logo, topNav, topActions };
+}
diff --git a/archive/templates/mono/content/docs/development.mdx b/archive/templates/mono/content/docs/development.mdx
new file mode 100644
index 0000000..f75f85e
--- /dev/null
+++ b/archive/templates/mono/content/docs/development.mdx
@@ -0,0 +1,60 @@
+---
+title: Development
+description: Preview your docs locally before you ship.
+---
+
+# Development
+
+Learn how to run your docs locally and preview every change before it goes live.
+
+<Info>
+  **Prerequisite:** Node.js 20 or newer.
+</Info>
+
+## Run the dev server
+
+```bash
+npm install
+npm run dev
+```
+
+Your site is now available at [http://localhost:3000](http://localhost:3000).
+Edits to MDX and `docs.json` hot-reload.
+
+## Custom ports
+
+The dev server uses port `3000` by default. Pass `-p` to change it:
+
+```bash
+npm run dev -- -p 3333
+```
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Port already in use">
+    Another process is using the port. Stop it, or start the dev server on a
+    different port with `npm run dev -- -p 3333`.
+  </Accordion>
+  <Accordion title="A page 404s">
+    Make sure the page's `file` exists under `content/docs` and its `slug` is
+    listed in `docs.json`. Slugs are case-sensitive.
+  </Accordion>
+  <Accordion title="The API Reference tab is empty">
+    Confirm `docs.json` has a tab with an `openapi` field pointing at a valid
+    spec file (JSON or YAML) inside `content/docs`.
+  </Accordion>
+</AccordionGroup>
+
+## Editor tips
+
+<Tabs>
+  <Tab title="VS Code">
+    Install the **MDX** extension for syntax highlighting and component
+    autocomplete in `.mdx` files.
+  </Tab>
+  <Tab title="Neovim">
+    Use a Treesitter MDX/Markdown parser for highlighting, and an LSP-aware
+    Markdown plugin for link checking.
+  </Tab>
+</Tabs>
diff --git a/templates/mono/content/docs/docs.json b/archive/templates/mono/content/docs/docs.json
similarity index 100%
rename from templates/mono/content/docs/docs.json
rename to archive/templates/mono/content/docs/docs.json
diff --git a/archive/templates/mono/content/docs/essentials/code-blocks.mdx b/archive/templates/mono/content/docs/essentials/code-blocks.mdx
new file mode 100644
index 0000000..c5ab15f
--- /dev/null
+++ b/archive/templates/mono/content/docs/essentials/code-blocks.mdx
@@ -0,0 +1,55 @@
+---
+title: Code Blocks
+description: Display inline code and richly highlighted code blocks.
+---
+
+# Code Blocks
+
+Display inline code and fenced code blocks with syntax highlighting.
+
+## Inline code
+
+To denote a `word` or `phrase` as code, wrap it in backticks (`` ` ``).
+
+## Code blocks
+
+Fence code with triple backticks and a language for highlighting. Add a title
+after the language to label the block:
+
+```js app.js
+export function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Code groups
+
+Group related snippets — different languages or package managers — into a single
+tabbed block:
+
+<CodeGroup>
+```bash npm
+npm install @inkform/framework
+```
+
+```bash pnpm
+pnpm add @inkform/framework
+```
+
+```bash yarn
+yarn add @inkform/framework
+```
+</CodeGroup>
+
+## Highlighting
+
+Code blocks are highlighted with [Shiki](https://shiki.style), the same engine
+VS Code uses, so colors match your editor and stay readable in light and dark
+mode.
+
+```ts server.ts
+import { parseOpenApi } from '@inkform/framework/openapi';
+
+const model = parseOpenApi(rawSpec);
+console.log(model.operations.length, 'endpoints');
+```
diff --git a/archive/templates/mono/content/docs/essentials/components.mdx b/archive/templates/mono/content/docs/essentials/components.mdx
new file mode 100644
index 0000000..1057e76
--- /dev/null
+++ b/archive/templates/mono/content/docs/essentials/components.mdx
@@ -0,0 +1,62 @@
+---
+title: Components
+description: The built-in component library for rich, interactive docs.
+---
+
+# Components
+
+Beyond Markdown, you get a library of components for richer pages — all available
+in any `.mdx` file with no imports.
+
+## Cards
+
+<CardGroup cols={2}>
+  <Card title="Fast" icon="zap">
+    Static-rendered pages, instant client-side search.
+  </Card>
+  <Card title="Themeable" icon="palette">
+    Restyle everything from one token file.
+  </Card>
+</CardGroup>
+
+## Callouts
+
+<Note>A neutral note.</Note>
+<Tip>A helpful tip.</Tip>
+<Warning>Something to be careful about.</Warning>
+<Check>A success confirmation.</Check>
+
+## Steps
+
+<Steps>
+  <Step title="Write">Add an `.mdx` file under `content/docs`.</Step>
+  <Step title="Register">List it in `docs.json`.</Step>
+  <Step title="Ship">Push and deploy.</Step>
+</Steps>
+
+## Tabs
+
+<Tabs>
+  <Tab title="macOS">Press <kbd>⌘</kbd> <kbd>K</kbd> to open search.</Tab>
+  <Tab title="Windows">Press <kbd>Ctrl</kbd> <kbd>K</kbd> to open search.</Tab>
+</Tabs>
+
+## Accordions
+
+<AccordionGroup>
+  <Accordion title="Is it responsive?">Yes — sidebar and TOC collapse on small screens.</Accordion>
+  <Accordion title="Does it support dark mode?">Yes — toggle in the top bar, persisted across visits.</Accordion>
+</AccordionGroup>
+
+## Parameter fields
+
+Use `<ParamField>` and `<ResponseField>` to document request and response shapes
+in prose (the API Reference tab generates these automatically from OpenAPI):
+
+<ParamField query="limit" type="integer" default="20">
+  The maximum number of results to return.
+</ParamField>
+
+<ResponseField name="id" type="integer" required>
+  The unique identifier of the created record.
+</ResponseField>
diff --git a/archive/templates/mono/content/docs/essentials/images.mdx b/archive/templates/mono/content/docs/essentials/images.mdx
new file mode 100644
index 0000000..5caefc6
--- /dev/null
+++ b/archive/templates/mono/content/docs/essentials/images.mdx
@@ -0,0 +1,43 @@
+---
+title: Images & Embeds
+description: Add images, video, and other media to your docs.
+---
+
+# Images & Embeds
+
+Add images, video, and rich media to bring your documentation to life.
+
+## Images
+
+Use Markdown image syntax:
+
+```md
+![A descriptive alt text](/path/to/image.jpg)
+```
+
+Wrap an image in a `<Frame>` to add a border and an optional caption:
+
+<Frame caption="Images look great framed.">
+  ![Landscape](/hero.svg)
+</Frame>
+
+<Note>
+  Keep images under ~5 MB. For larger assets, host them on a CDN and reference
+  the URL.
+</Note>
+
+## Video
+
+Embed a YouTube or Loom video with the `<Embed>` component:
+
+```mdx
+<Embed provider="youtube" url="https://youtu.be/dQw4w9WgXcQ" />
+```
+
+## iframes
+
+Embed any external page:
+
+```mdx
+<Embed provider="iframe" url="https://example.com/widget" />
+```
diff --git a/archive/templates/mono/content/docs/essentials/markdown.mdx b/archive/templates/mono/content/docs/essentials/markdown.mdx
new file mode 100644
index 0000000..c0e86da
--- /dev/null
+++ b/archive/templates/mono/content/docs/essentials/markdown.mdx
@@ -0,0 +1,65 @@
+---
+title: Markdown Syntax
+description: Text, titles, and styling in standard Markdown.
+---
+
+# Markdown Syntax
+
+Write content in standard Markdown — the framework renders it with GitHub-flavored
+extensions, callouts, and syntax-highlighted code.
+
+## Titles
+
+Use `#` headings for sections. Second- and third-level headings (`##`, `###`)
+appear in the table of contents on the right.
+
+```md
+## Section title
+### Subsection title
+```
+
+## Text formatting
+
+We support most Markdown formatting. Wrap text to style it:
+
+| Style | How to write it | Result |
+| --- | --- | --- |
+| Bold | `**bold**` | **bold** |
+| Italic | `_italic_` | _italic_ |
+| Strikethrough | `~~struck~~` | ~~struck~~ |
+| Code | `` `code` `` | `code` |
+
+## Links
+
+Link to [another page](/quickstart) with relative paths, or to
+[an external site](https://example.com) with full URLs.
+
+## Blockquotes
+
+> The best way to predict the future is to invent it.
+
+## Lists
+
+- Unordered items
+- Nest them by indenting
+  - Like this
+
+1. Ordered items
+2. Count automatically
+
+## Callouts
+
+Use callouts to draw attention. They come in several flavors:
+
+<Note>This is a note — neutral, informational.</Note>
+<Tip>This is a tip — a helpful suggestion.</Tip>
+<Warning>This is a warning — proceed carefully.</Warning>
+<Check>This is a success message — all good.</Check>
+
+You can also write callouts as directives:
+
+```md
+:::info
+An info callout written as a directive.
+:::
+```
diff --git a/archive/templates/mono/content/docs/essentials/navigation.mdx b/archive/templates/mono/content/docs/essentials/navigation.mdx
new file mode 100644
index 0000000..f85d3f2
--- /dev/null
+++ b/archive/templates/mono/content/docs/essentials/navigation.mdx
@@ -0,0 +1,68 @@
+---
+title: Navigation
+description: Configure tabs, groups, pages, and the API Reference in docs.json.
+---
+
+# Navigation
+
+Your site's structure lives in `content/docs/docs.json`. It controls the top
+tabs, the sidebar groups, and the API Reference.
+
+## Groups and pages
+
+The simplest config is a list of groups, each with pages:
+
+```json docs.json
+{
+  "name": "My Docs",
+  "navigation": [
+    {
+      "group": "Get Started",
+      "pages": [
+        { "title": "Introduction", "slug": "", "file": "index.mdx" },
+        { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx" }
+      ]
+    }
+  ]
+}
+```
+
+<Note>
+  `slug` is the URL path (an empty string is the index). `file` is the MDX file
+  relative to `content/docs`. Nest pages with a `children` array.
+</Note>
+
+## Tabs
+
+Add top-bar tabs to split Guides from your API Reference:
+
+```json docs.json
+{
+  "tabs": [
+    { "tab": "Guides", "navigation": [ /* groups */ ] },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+## API Reference from OpenAPI
+
+Point a tab's `openapi` field at a spec file (JSON or YAML) in `content/docs`.
+The framework generates the entire API Reference — endpoint list, parameters,
+request/response schemas, a cURL sample, and a live "Try it" playground — from
+the spec.
+
+<Tip>
+  This is the standard: API docs come from OpenAPI, everything else is MDX. Keep
+  your spec accurate and your reference stays accurate for free.
+</Tip>
+
+## Top bar
+
+```json docs.json
+{
+  "navbarLinks": [{ "name": "Blog", "href": "/blog" }],
+  "anchors": [{ "name": "GitHub", "href": "https://github.com/you/repo", "icon": "github" }],
+  "cta": { "label": "Dashboard", "href": "https://app.example.com" }
+}
+```
diff --git a/templates/mono/content/docs/index.mdx b/archive/templates/mono/content/docs/index.mdx
similarity index 100%
rename from templates/mono/content/docs/index.mdx
rename to archive/templates/mono/content/docs/index.mdx
diff --git a/archive/templates/mono/content/docs/openapi.json b/archive/templates/mono/content/docs/openapi.json
new file mode 100644
index 0000000..fdf12e9
--- /dev/null
+++ b/archive/templates/mono/content/docs/openapi.json
@@ -0,0 +1,125 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Sample Store API",
+    "version": "1.0.0",
+    "description": "A tiny example API used to demo the OpenAPI-powered API Reference. Replace `openapi.json` with your own spec — everything on the API Reference tab is generated from it."
+  },
+  "servers": [{ "url": "https://api.example.com/v1", "description": "Production" }],
+  "security": [{ "bearerAuth": [] }],
+  "tags": [{ "name": "Plants", "description": "Manage the plants in your store." }],
+  "paths": {
+    "/plants": {
+      "get": {
+        "operationId": "list-plants",
+        "tags": ["Plants"],
+        "summary": "List plants",
+        "description": "Returns all plants from the store that the caller has access to.",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "The maximum number of results to return.",
+            "schema": { "type": "integer", "format": "int32", "default": 20 }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of plants.",
+            "content": {
+              "application/json": {
+                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plant" } }
+              }
+            }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      },
+      "post": {
+        "operationId": "create-plant",
+        "tags": ["Plants"],
+        "summary": "Create a plant",
+        "description": "Creates a new plant in the store.",
+        "requestBody": {
+          "required": true,
+          "description": "The plant to add to the store.",
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } }
+        },
+        "responses": {
+          "200": {
+            "description": "The created plant.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plant" } } }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    },
+    "/plants/{id}": {
+      "delete": {
+        "operationId": "delete-plant",
+        "tags": ["Plants"],
+        "summary": "Delete a plant",
+        "description": "Deletes a single plant by its id.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The id of the plant to delete.",
+            "schema": { "type": "integer", "format": "int64" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Plant deleted." },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Bearer authentication header of the form `Bearer <token>`."
+      }
+    },
+    "schemas": {
+      "Plant": {
+        "type": "object",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "integer", "format": "int64", "description": "Identification number of the plant." },
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "NewPlant": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": ["error", "message"],
+        "properties": {
+          "error": { "type": "integer", "format": "int32", "description": "Error code." },
+          "message": { "type": "string", "description": "Human-readable error message." }
+        }
+      }
+    }
+  }
+}
diff --git a/archive/templates/mono/content/docs/quickstart.mdx b/archive/templates/mono/content/docs/quickstart.mdx
new file mode 100644
index 0000000..43dc359
--- /dev/null
+++ b/archive/templates/mono/content/docs/quickstart.mdx
@@ -0,0 +1,66 @@
+---
+title: Quickstart
+description: Start building beautiful documentation in minutes.
+---
+
+# Quickstart
+
+Start building beautiful documentation in minutes.
+
+## Set up your project
+
+<Steps>
+  <Step title="Scaffold a project">
+    Create a new docs site and pick a theme:
+
+    ```bash
+    npx @inkform/cli@latest init my-docs
+    cd my-docs
+    npm install
+    ```
+  </Step>
+  <Step title="Run it locally">
+    Start the dev server and open [localhost:3000](http://localhost:3000):
+
+    ```bash
+    npm run dev
+    ```
+  </Step>
+  <Step title="Edit your content">
+    Content lives in `content/docs`. Edit any `.mdx` file and the page reloads
+    instantly. Add pages by creating files and listing them in `docs.json`.
+  </Step>
+  <Step title="Deploy">
+    Push to GitHub and import the repo on Vercel — zero config. See the
+    project README for the full deploy guide (Vercel and AWS Amplify).
+  </Step>
+</Steps>
+
+## Add your first page
+
+Create `content/docs/hello.mdx`:
+
+```mdx hello.mdx
+---
+title: Hello
+description: My first page.
+---
+
+# Hello
+
+This is my first documentation page.
+```
+
+Then register it in `content/docs/docs.json`:
+
+```json docs.json
+{
+  "group": "Get Started",
+  "pages": [{ "title": "Hello", "slug": "hello", "file": "hello.mdx" }]
+}
+```
+
+<Tip>
+  The `slug` is the URL path and `file` is the MDX file relative to
+  `content/docs`. Nest pages with a `children` array.
+</Tip>
diff --git a/archive/templates/mono/content/docs/slug-history.json b/archive/templates/mono/content/docs/slug-history.json
new file mode 100644
index 0000000..0967ef4
--- /dev/null
+++ b/archive/templates/mono/content/docs/slug-history.json
@@ -0,0 +1 @@
+{}
diff --git a/archive/templates/mono/lib/icons.tsx b/archive/templates/mono/lib/icons.tsx
new file mode 100644
index 0000000..8490099
--- /dev/null
+++ b/archive/templates/mono/lib/icons.tsx
@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+import {
+  Book,
+  BookOpen,
+  Rocket,
+  Terminal,
+  Type,
+  Code,
+  Image,
+  Blocks,
+  Map,
+  Github,
+  Pencil,
+  Eye,
+  Zap,
+  Palette,
+  FileText,
+  Settings,
+  Globe,
+  Lock,
+  Key,
+  Database,
+  Cloud,
+  Mail,
+  User,
+  Users,
+  Star,
+  Heart,
+  Bell,
+  Search,
+  Home,
+  Layout,
+  Package,
+  Layers,
+  Link,
+  ChevronRight,
+  Play,
+  Download,
+  Upload,
+} from 'lucide-react';
+
+const ICON_MAP: Record<string, React.ComponentType<{ size?: number; strokeWidth?: number }>> = {
+  book: Book,
+  'book-open': BookOpen,
+  rocket: Rocket,
+  terminal: Terminal,
+  type: Type,
+  code: Code,
+  image: Image,
+  blocks: Blocks,
+  map: Map,
+  github: Github,
+  pencil: Pencil,
+  eye: Eye,
+  zap: Zap,
+  palette: Palette,
+  file: FileText,
+  'file-text': FileText,
+  settings: Settings,
+  globe: Globe,
+  lock: Lock,
+  key: Key,
+  database: Database,
+  cloud: Cloud,
+  mail: Mail,
+  user: User,
+  users: Users,
+  star: Star,
+  heart: Heart,
+  bell: Bell,
+  search: Search,
+  home: Home,
+  layout: Layout,
+  package: Package,
+  layers: Layers,
+  link: Link,
+  'chevron-right': ChevronRight,
+  play: Play,
+  download: Download,
+  upload: Upload,
+};
+
+/**
+ * Map a docs.json icon name to a Lucide icon ReactNode.
+ * Returns null for unknown or empty names.
+ */
+export function renderIcon(name?: string): ReactNode {
+  if (!name) return null;
+  const Icon = ICON_MAP[name.toLowerCase()];
+  if (!Icon) return null;
+  return <Icon size={16} strokeWidth={1.75} />;
+}
diff --git a/archive/templates/mono/lib/route.tsx b/archive/templates/mono/lib/route.tsx
new file mode 100644
index 0000000..db313d1
--- /dev/null
+++ b/archive/templates/mono/lib/route.tsx
@@ -0,0 +1,134 @@
+/**
+ * lib/route.ts — Aurora routing core.
+ *
+ * Resolves a slug array from the catch-all route into a doc page, generates
+ * static params, and builds sidebar groups. The API Reference tab is NOT
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
+ */
+
+import type { ReactNode } from 'react';
+import { docTabs, listDocPages, findDocPage, tabNavigation } from '@inkform/framework';
+import type { DocsConfig, DocsTab, FlatDocPage } from '@inkform/framework';
+import { loadDocsConfig, loadDocPage, loadBlogPosts, loadChangelogEntries, slugify } from '@inkform/framework/content';
+import type { SidebarGroup, SidebarItem } from '@inkform/framework/docs-shell';
+
+// ── Re-export for convenience ─────────────────────────────────────────────────
+
+export { loadDocsConfig, loadDocPage };
+
+// ── Content nav links (Blog / Changelog) ──────────────────────────────────────
+
+/**
+ * Extends config.navbarLinks with "Blog" / "Changelog" entries, but only when
+ * content actually exists under content/blog or content/changelog — a
+ * docs-only site stays clean by default (see app/blog, app/changelog).
+ */
+export function withContentNavLinks(config: DocsConfig): DocsConfig {
+  const extra: DocsConfig['navbarLinks'] = [];
+  if (loadBlogPosts().length > 0) extra.push({ name: 'Blog', href: '/blog' });
+  if (loadChangelogEntries().length > 0) extra.push({ name: 'Changelog', href: '/changelog' });
+  if (extra.length === 0) return config;
+  return { ...config, navbarLinks: [...(config.navbarLinks ?? []), ...extra] };
+}
+
+// ── API tab helpers ───────────────────────────────────────────────────────────
+
+/** Find the tab that has an openapi spec (the API Reference tab). */
+export function apiTab(config: DocsConfig): DocsTab | null {
+  return docTabs(config).find((t) => !!t.openapi) ?? null;
+}
+
+/**
+ * The URL slug base for the API Reference tab, derived from slugifying its
+ * tab label (e.g. "API Reference" → "api-reference"). Used by top-bar.tsx to
+ * link to app/api-reference/route.ts — keep the two in sync if you rename
+ * the tab.
+ */
+export function apiBasePath(config: DocsConfig): string | null {
+  const tab = apiTab(config);
+  if (!tab) return null;
+  return slugify(tab.tab);
+}
+
+// ── Route resolution ──────────────────────────────────────────────────────────
+
+export type DocRoute = {
+  kind: 'doc';
+  ref: FlatDocPage;
+  page: { data: Record<string, unknown>; content: string };
+  config: DocsConfig;
+  tab: DocsTab;
+};
+
+/**
+ * Resolve a catch-all slug array to a doc page descriptor.
+ * Returns null if no page is found (→ notFound()).
+ */
+export function resolveRoute(slugParts: string[] | undefined): DocRoute | null {
+  const config = loadDocsConfig();
+  if (!config) return null;
+
+  const path = (slugParts ?? []).join('/');
+  const ref = findDocPage(config, path);
+  if (!ref) return null;
+
+  const page = loadDocPage(ref.file);
+  if (!page) return null;
+
+  const docTabEntry = docTabs(config).find((t) => t.tab === ref.tab) ?? docTabs(config)[0];
+  return { kind: 'doc', ref, page, config, tab: docTabEntry };
+}
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+/**
+ * All static slugs for generateStaticParams.
+ * Each entry is a string[] (the catch-all segments).
+ * The index page has slug = [] (empty array).
+ */
+export function listAllRoutes(config: DocsConfig): string[][] {
+  const routes: string[][] = [];
+  const seen = new Set<string>();
+
+  function addSlug(slug: string) {
+    if (seen.has(slug)) return;
+    seen.add(slug);
+    routes.push(slug === '' ? [] : slug.split('/'));
+  }
+
+  for (const page of listDocPages(config)) {
+    addSlug(page.slug);
+  }
+
+  return routes;
+}
+
+// ── Sidebar builders ──────────────────────────────────────────────────────────
+
+/**
+ * Build SidebarGroup[] for a doc tab.
+ * renderIcon maps a docs.json icon name to a ReactNode.
+ */
+export function sidebarForDoc(
+  config: DocsConfig,
+  tab: DocsTab,
+  activeSlug: string,
+  renderIcon: (name?: string) => ReactNode,
+): SidebarGroup[] {
+  const groups = tabNavigation(config, tab.tab);
+  return groups.map((g) => ({
+    group: g.group,
+    icon: renderIcon(g.icon),
+    items: (g.pages ?? []).map((p): SidebarItem => ({
+      title: p.title,
+      href: p.href ?? '/' + p.slug,
+      active: p.slug === activeSlug,
+      icon: renderIcon(p.icon),
+      external: !!p.href,
+    })),
+  }));
+}
diff --git a/archive/templates/mono/mdx-components.tsx b/archive/templates/mono/mdx-components.tsx
new file mode 100644
index 0000000..70bba3b
--- /dev/null
+++ b/archive/templates/mono/mdx-components.tsx
@@ -0,0 +1,11 @@
+import { mdxComponents } from '@inkform/framework/components';
+import widgets from '@/widgets';
+
+/**
+ * Site-level MDX component map.
+ * The framework's defaults cover all built-in blocks (Callout, Card, Steps,
+ * Tabs, CodeGroup, Accordion, ParamField, …). Custom widgets registered in
+ * widgets/index.ts are merged in here, so <YourWidget /> in MDX/CMS content
+ * resolves to the real component instead of the unknown-component fallback.
+ */
+export const siteMdxComponents = mdxComponents(widgets);
diff --git a/archive/templates/mono/next-env.d.ts b/archive/templates/mono/next-env.d.ts
new file mode 100644
index 0000000..9edff1c
--- /dev/null
+++ b/archive/templates/mono/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/archive/templates/mono/next.config.ts b/archive/templates/mono/next.config.ts
new file mode 100644
index 0000000..02714a1
--- /dev/null
+++ b/archive/templates/mono/next.config.ts
@@ -0,0 +1,17 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  transpilePackages: ['@inkform/framework'],
+  images: { remotePatterns: [{ protocol: 'https', hostname: '**' }] },
+  // Pagefind indexes .next/server/app's built .html files directly, so its
+  // search results carry a trailing .html this app doesn't actually serve
+  // (e.g. /essentials/markdown.html) — this app's real routes are
+  // extensionless. Redirect (not rewrite) so the address bar ends up on the
+  // real, shareable permalink; query params (?q=... for highlighting) are
+  // preserved automatically.
+  async redirects() {
+    return [{ source: '/:path*.html', destination: '/:path*', permanent: false }];
+  },
+};
+
+export default nextConfig;
diff --git a/templates/mono/package.json b/archive/templates/mono/package.json
similarity index 100%
rename from templates/mono/package.json
rename to archive/templates/mono/package.json
diff --git a/archive/templates/mono/proxy.ts b/archive/templates/mono/proxy.ts
new file mode 100644
index 0000000..a0fd617
--- /dev/null
+++ b/archive/templates/mono/proxy.ts
@@ -0,0 +1,22 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { resolveSlugRedirect } from '@inkform/framework';
+import slugHistory from './content/docs/slug-history.json';
+
+/** Docs are served at the root, so slug-history redirects use the '/' base. */
+export function proxy(req: NextRequest) {
+  const target = resolveSlugRedirect(
+    req.nextUrl.pathname,
+    slugHistory as Record<string, string>,
+    '/',
+  );
+  if (target) {
+    return NextResponse.redirect(new URL(target, req.url), 301);
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+};
diff --git a/templates/mono/public/favicon.svg b/archive/templates/mono/public/favicon.svg
similarity index 100%
rename from templates/mono/public/favicon.svg
rename to archive/templates/mono/public/favicon.svg
diff --git a/templates/mono/public/hero.svg b/archive/templates/mono/public/hero.svg
similarity index 100%
rename from templates/mono/public/hero.svg
rename to archive/templates/mono/public/hero.svg
diff --git a/templates/mono/public/logo.svg b/archive/templates/mono/public/logo.svg
similarity index 100%
rename from templates/mono/public/logo.svg
rename to archive/templates/mono/public/logo.svg
diff --git a/archive/templates/mono/tsconfig.json b/archive/templates/mono/tsconfig.json
new file mode 100644
index 0000000..e7ff3a2
--- /dev/null
+++ b/archive/templates/mono/tsconfig.json
@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
diff --git a/archive/templates/mono/widgets/index.ts b/archive/templates/mono/widgets/index.ts
new file mode 100644
index 0000000..e529973
--- /dev/null
+++ b/archive/templates/mono/widgets/index.ts
@@ -0,0 +1,12 @@
+import type { ComponentType } from 'react';
+
+/**
+ * Custom widget registry. Put your component at widgets/<Name>.tsx, import
+ * it here, and add it to this map — the key becomes the JSX tag name your
+ * MDX/CMS content uses (<Name ... />). Framework docs: "Custom Widgets."
+ */
+const widgets: Record<string, ComponentType<any>> = {
+  // Example: MyChart,
+};
+
+export default widgets;
diff --git a/examples/inkform-docs/app/[[...slug]]/page.tsx b/examples/inkform-docs/app/[[...slug]]/page.tsx
index 5dd0aaf..ff89b53 100644
--- a/examples/inkform-docs/app/[[...slug]]/page.tsx
+++ b/examples/inkform-docs/app/[[...slug]]/page.tsx
@@ -1,10 +1,12 @@
 import { notFound } from 'next/navigation';
 import { Mdx } from '@inkform/framework/mdx';
-import { DocsShell, Sidebar, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
 import { docNeighbours } from '@inkform/framework';
 import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
 import { siteMdxComponents } from '@/mdx-components';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { renderIcon } from '@/lib/icons';
 import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
 
@@ -49,7 +51,8 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<Sidebar groups={sidebar} />}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
       toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
       hideToc={headings.length === 0}
     >
diff --git a/examples/inkform-docs/app/blog/[slug]/page.tsx b/examples/inkform-docs/app/blog/[slug]/page.tsx
index 952691f..9282d33 100644
--- a/examples/inkform-docs/app/blog/[slug]/page.tsx
+++ b/examples/inkform-docs/app/blog/[slug]/page.tsx
@@ -27,7 +27,7 @@ export default async function BlogPostPage({ params }: { params: Promise<{ slug:
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>{post.title}</h1>
         <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
diff --git a/examples/inkform-docs/app/blog/page.tsx b/examples/inkform-docs/app/blog/page.tsx
index 79bffff..7a04806 100644
--- a/examples/inkform-docs/app/blog/page.tsx
+++ b/examples/inkform-docs/app/blog/page.tsx
@@ -12,7 +12,7 @@ export default function BlogIndexPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Blog</h1>
         {posts.length === 0 ? (
diff --git a/examples/inkform-docs/app/changelog/page.tsx b/examples/inkform-docs/app/changelog/page.tsx
index 05cbac9..890f6a9 100644
--- a/examples/inkform-docs/app/changelog/page.tsx
+++ b/examples/inkform-docs/app/changelog/page.tsx
@@ -13,7 +13,7 @@ export default function ChangelogPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Changelog</h1>
         {entries.length === 0 ? <p>No entries yet.</p> : null}
diff --git a/examples/inkform-docs/app/theme.css b/examples/inkform-docs/app/theme.css
index cdfc6c3..f4c28f2 100644
--- a/examples/inkform-docs/app/theme.css
+++ b/examples/inkform-docs/app/theme.css
@@ -1,16 +1,14 @@
 /*
  * Galley theme — token overrides for @inkform/framework.
+ * Structure (header/sidebar/drawer/nav) is Canopy's, unchanged — see the
+ * sections below. This file only replaces the TOKENS: Inkform's own design
+ * system, a printer's galley. Warm opaque paper + ink, one editorial
+ * "Proof" red-pencil accent (#C24E3D, unchanged between light/dark). Depth
+ * from paper layering + hairlines, never heavy shadow or gradient. Values
+ * below are lifted directly from the `inkform-design` skill's
+ * tokens/{colors,effects,typography}.css — the authoritative source; do not
+ * hand-tune a value here without checking there first.
  * This file is imported AFTER framework/styles.css so its declarations win.
- * Only --fw-* tokens and small Galley-specific accents are set here.
- * The framework's structural CSS is untouched.
- *
- * Identity: Inkform's own design system — a printer's galley. Warm opaque
- * paper + ink, one editorial "Proof" red-pencil accent (#C24E3D, unchanged
- * between light/dark). Depth from paper layering + hairlines, never heavy
- * shadow or gradient. Values below are lifted directly from the
- * `inkform-design` skill's tokens/{colors,effects,typography}.css — the
- * authoritative source; do not hand-tune a value here without checking there
- * first.
  */
 
 /* ── Font variables ───────────────────────────────────────────────────────
@@ -97,8 +95,305 @@ html.dark {
   --fw-method-options: #aba79a;
 }
 
-/* Top bar (tabs/anchors/nav links/CTA/brand) is now styled by the shared
-   framework layer (packages/framework/src/styles/layout.css) — it only
-   ever consumed --fw-* tokens here, so there was nothing theme-specific
-   left to override for Galley. See Mono's theme.css for an example of a
-   theme that DOES need a delta on top of the shared base. */
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Galley's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-galley-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-galley-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-galley-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-galley-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-galley-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-galley-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-galley-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-galley-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-galley-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-galley-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-galley-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-galley-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-galley-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-galley-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-galley-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-galley-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-galley-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 1rem;
+  overflow: hidden;
+}
diff --git a/examples/inkform-docs/components/collapsible-sidebar.tsx b/examples/inkform-docs/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..8e2d20c
--- /dev/null
+++ b/examples/inkform-docs/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Galley's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-galley-sidebar-rail">
+        <button
+          type="button"
+          className="fw-galley-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-galley-sidebar-heading">
+        <span className="fw-galley-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-galley-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/examples/inkform-docs/components/sidebar-footer.tsx b/examples/inkform-docs/components/sidebar-footer.tsx
new file mode 100644
index 0000000..7280ec9
--- /dev/null
+++ b/examples/inkform-docs/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Galley doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-galley-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-galley-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-galley-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-galley-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-galley-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-galley-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/examples/inkform-docs/components/top-bar.tsx b/examples/inkform-docs/components/top-bar.tsx
index 61dc77a..13d637f 100644
--- a/examples/inkform-docs/components/top-bar.tsx
+++ b/examples/inkform-docs/components/top-bar.tsx
@@ -1,7 +1,6 @@
 import type { ReactNode } from 'react';
 import Link from 'next/link';
 import { AskAi } from '@inkform/framework/ask-ai';
-import { ThemeToggle } from '@inkform/framework/theme-toggle';
 import { SearchDialog } from '@inkform/framework/search-dialog';
 import type { DocsConfig } from '@inkform/framework';
 import { docTabs } from '@inkform/framework';
@@ -29,6 +28,12 @@ function Logo({ config }: { config: DocsConfig }) {
 }
 
 // ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Galley's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Galley-specific CSS.
 
 function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
   const tabs = docTabs(config);
@@ -82,12 +87,27 @@ export interface TopBarParts {
   logo: ReactNode;
   topNav: ReactNode;
   topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
 }
 
 /**
- * Build the three DocsShell header slot contents for Aurora.
- * Server component — client islands (SearchDialog, ThemeToggle, AskAi) are
- * already marked 'use client' in the framework.
+ * Build the three DocsShell header slot contents for Galley.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-galley-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
  */
 export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
   const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
@@ -114,21 +134,23 @@ export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts
 
   const topActions = (
     <>
-      <SearchDialog />
-      <ThemeToggle />
-      <AskAi enabled={aiEnabled} product={config.name} />
-      {config.cta ? (
-        <a
-          href={config.cta.href}
-          className="fw-topnav-cta"
-          target={config.cta.href.startsWith('http') ? '_blank' : undefined}
-          rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
-        >
-          {config.cta.label}
-        </a>
-      ) : null}
+      <div className="fw-galley-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
     </>
   );
 
-  return { logo, topNav, topActions };
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
 }
diff --git a/examples/inkform-docs/content/docs/docs.json b/examples/inkform-docs/content/docs/docs.json
index 7c8d76f..6a4a945 100644
--- a/examples/inkform-docs/content/docs/docs.json
+++ b/examples/inkform-docs/content/docs/docs.json
@@ -34,6 +34,7 @@
       "pages": [
         { "title": "Docs", "slug": "guides/docs", "file": "guides/docs.mdx", "icon": "book-open" },
         { "title": "Blog", "slug": "guides/blog", "file": "guides/blog.mdx", "icon": "pencil" },
+        { "title": "Add a Blog to an Existing Site", "slug": "guides/blog-in-existing-site", "file": "guides/blog-in-existing-site.mdx", "icon": "layers" },
         { "title": "Changelog", "slug": "guides/changelog", "file": "guides/changelog.mdx", "icon": "map" },
         { "title": "Widgets", "slug": "guides/widgets", "file": "guides/widgets.mdx", "icon": "blocks" },
         { "title": "Comments, Reactions & Subscribe Forms", "slug": "guides/interactive", "file": "guides/interactive.mdx", "icon": "heart" }
diff --git a/examples/inkform-docs/content/docs/guides/blog-in-existing-site.mdx b/examples/inkform-docs/content/docs/guides/blog-in-existing-site.mdx
new file mode 100644
index 0000000..8851aeb
--- /dev/null
+++ b/examples/inkform-docs/content/docs/guides/blog-in-existing-site.mdx
@@ -0,0 +1,203 @@
+---
+title: Add a Blog to an Existing Next.js Site
+description: Bolt the framework's MDX blog engine onto a Next.js app you already have, using your own layout and design system — no docs site required.
+---
+
+# Add a blog to an existing Next.js site
+
+This is for a different situation than the rest of these guides: you already
+have a Next.js website — your own layout, header, footer, design system —
+and you just want `/blog` and `/blog/[slug]` added to it. You are **not**
+adopting the framework's docs shell, sidebar, or theming. You're using two
+standalone pieces — MDX-with-frontmatter loading, and MDX rendering — and
+wiring them into pages that look like the rest of your site.
+
+## What you're adding
+
+- `@inkform/framework/content` — reads `content/blog/*.mdx` (frontmatter +
+  body) off disk at build time. No database, no CMS required.
+- `@inkform/framework/mdx` — renders a post's MDX body to React, with syntax
+  highlighting and the framework's built-in content blocks (`<Callout>`,
+  `<Card>`, `<Steps>`, `<Tabs>`, `<CodeGroup>`, `<Accordion>`, and more).
+
+Nothing else. `DocsShell`, the sidebar, search, and the theme tokens are a
+separate, optional layer for people building a full docs site — skip all of
+it here.
+
+## 1. Install
+
+```bash
+npm install @inkform/framework
+```
+
+It expects the same major versions of `react`, `react-dom`, and `next` your
+project already has (React 19, Next 16) — no separate copies get pulled in.
+
+## 2. Point Next at the package
+
+Add `transpilePackages` to your **existing** `next.config.ts` — don't
+replace the file, just merge this key in:
+
+```ts
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // ...whatever you already have
+  transpilePackages: ['@inkform/framework'],
+};
+
+export default nextConfig;
+```
+
+The package ships TypeScript/JSX source rather than pre-compiled output, so
+Next needs to know to transpile it.
+
+## 3. Add your content folder
+
+```
+content/
+  blog/
+    my-first-post.mdx
+    another-post.mdx
+```
+
+By default this is read from `<project root>/content/blog`. If you'd rather
+keep content somewhere else in your repo, set `DOCS_CONTENT_ROOT` (env var)
+to that directory instead — everything downstream still just calls
+`loadBlogPosts()`/`loadBlogPost()`.
+
+Each file needs frontmatter:
+
+```mdx
+---
+title: My First Post
+date: 2026-01-15
+author: Jane Doe
+description: A one-line summary for the list page.
+---
+
+Post body in MDX. Regular markdown, plus `<Callout>`, `<Card>`, fenced code
+blocks with syntax highlighting, etc.
+```
+
+See the [Blog guide](/docs/guides/blog) for the full frontmatter reference
+(tags, series, scheduled/draft posts via `status`, cover images) — it's the
+same loader, so every field there works here too.
+
+## 4. Register your MDX component map
+
+```tsx
+// mdx-components.tsx
+import { mdxComponents } from '@inkform/framework/components';
+
+export const blogMdxComponents = mdxComponents();
+```
+
+If you want to use a custom React component inside post MDX (a chart, an
+embed, anything project-specific), pass a `{ Name: Component }` map into
+`mdxComponents()` and it merges with the built-ins.
+
+## 5. The list page — `app/blog/page.tsx`
+
+Use **your own** page shell here (whatever wraps the rest of your site's
+pages) instead of the framework's `DocsShell`:
+
+```tsx
+import Link from 'next/link';
+import { loadBlogPosts } from '@inkform/framework/content';
+import { SiteLayout } from '@/components/site-layout'; // your own layout
+
+export const metadata = { title: 'Blog' };
+
+export default function BlogIndexPage() {
+  const posts = loadBlogPosts();
+
+  return (
+    <SiteLayout>
+      <h1>Blog</h1>
+      <ul>
+        {posts.map((p) => (
+          <li key={p.slug}>
+            <Link href={`/blog/${p.slug}`}>{p.title}</Link>
+            <p>{p.date} · {p.readingTime} min read{p.author ? ` · ${p.author}` : ''}</p>
+            {p.description ? <p>{p.description}</p> : null}
+          </li>
+        ))}
+      </ul>
+    </SiteLayout>
+  );
+}
+```
+
+## 6. The post page — `app/blog/[slug]/page.tsx`
+
+```tsx
+import { notFound } from 'next/navigation';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadBlogPosts, loadBlogPost } from '@inkform/framework/content';
+import { blogMdxComponents } from '@/mdx-components';
+import { SiteLayout } from '@/components/site-layout';
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return loadBlogPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  return { title: loadBlogPost(slug)?.title ?? 'Blog' };
+}
+
+export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  if (!post) notFound();
+
+  return (
+    <SiteLayout>
+      <h1>{post.title}</h1>
+      <p>{post.date} · {post.readingTime} min read{post.author ? ` · ${post.author}` : ''}</p>
+      <Mdx source={post.content} components={blogMdxComponents} />
+    </SiteLayout>
+  );
+}
+```
+
+`Mdx` is an async server component — it compiles and highlights the MDX at
+request/build time, so nothing extra to await at the call site.
+
+## 7. Styling
+
+`Mdx` outputs plain semantic HTML (`h1`–`h6`, `p`, `pre`/`code`, `ul`/`ol`,
+`blockquote`, `table`, plus the block components from step 4) — no required
+class names, so it inherits your site's existing global styles/Tailwind
+typography plugin for free in most cases. Two options:
+
+- **Fastest**: also import `@inkform/framework/styles.css` and wrap the
+  rendered post in `<div className="fw-prose">`. You get the framework's
+  full typography/code-block/callout styling with zero CSS of your own, but
+  it brings its own `--fw-*` design tokens (defaults are set, but for a
+  matching look you'd override them — see any `templates/*/app/theme.css`
+  in the framework repo for the token list).
+- **Better fit for an existing design system**: skip the framework
+  stylesheet entirely and style the plain HTML output the way you already
+  style everything else on your site (a Tailwind `prose` class from
+  `@tailwindcss/typography`, your own CSS, etc.).
+
+## 8. Verify
+
+```bash
+npm run build
+```
+
+`generateStaticParams` prerenders every post at build time, so a successful
+build means every post in `content/blog/` compiled and rendered without
+errors. Visit `/blog` and `/blog/<slug>` to confirm.
+
+## What you didn't need
+
+No `docs.json`, no `DocsShell`, no sidebar, no search setup, no theme
+tokens, no CLI scaffold. Those all exist for people building a complete docs
+site on the framework — a blog bolted onto an existing site is a much
+smaller slice of it: two loader functions and a renderer.
diff --git a/examples/inkform-docs/lib/route.tsx b/examples/inkform-docs/lib/route.tsx
index 7e543e7..4a7f976 100644
--- a/examples/inkform-docs/lib/route.tsx
+++ b/examples/inkform-docs/lib/route.tsx
@@ -1,12 +1,13 @@
 /**
- * lib/route.ts — Aurora routing core.
+ * lib/route.ts — Galley routing core.
  *
  * Resolves a slug array from the catch-all route into a doc page, generates
  * static params, and builds sidebar groups. The API Reference tab is NOT
- * handled here — it's served by app/api-reference/route.ts, a separate route
- * handler that renders Scalar's own UI directly from the OpenAPI spec.
- * apiBasePath() is still needed by components/top-bar.tsx to build that tab's
- * nav link.
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
  */
 
 import type { ReactNode } from 'react';
@@ -37,7 +38,7 @@ export function withContentNavLinks(config: DocsConfig): DocsConfig {
 // ── API tab helpers ───────────────────────────────────────────────────────────
 
 /** Find the tab that has an openapi spec (the API Reference tab). */
-function apiTab(config: DocsConfig): DocsTab | null {
+export function apiTab(config: DocsConfig): DocsTab | null {
   return docTabs(config).find((t) => !!t.openapi) ?? null;
 }
 
diff --git a/examples/markdown-docs/app/[[...slug]]/page.tsx b/examples/markdown-docs/app/[[...slug]]/page.tsx
index 5dd0aaf..ff89b53 100644
--- a/examples/markdown-docs/app/[[...slug]]/page.tsx
+++ b/examples/markdown-docs/app/[[...slug]]/page.tsx
@@ -1,10 +1,12 @@
 import { notFound } from 'next/navigation';
 import { Mdx } from '@inkform/framework/mdx';
-import { DocsShell, Sidebar, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
 import { docNeighbours } from '@inkform/framework';
 import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
 import { siteMdxComponents } from '@/mdx-components';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { renderIcon } from '@/lib/icons';
 import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
 
@@ -49,7 +51,8 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<Sidebar groups={sidebar} />}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
       toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
       hideToc={headings.length === 0}
     >
diff --git a/examples/markdown-docs/app/blog/[slug]/page.tsx b/examples/markdown-docs/app/blog/[slug]/page.tsx
index 952691f..9282d33 100644
--- a/examples/markdown-docs/app/blog/[slug]/page.tsx
+++ b/examples/markdown-docs/app/blog/[slug]/page.tsx
@@ -27,7 +27,7 @@ export default async function BlogPostPage({ params }: { params: Promise<{ slug:
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>{post.title}</h1>
         <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
diff --git a/examples/markdown-docs/app/blog/page.tsx b/examples/markdown-docs/app/blog/page.tsx
index 79bffff..7a04806 100644
--- a/examples/markdown-docs/app/blog/page.tsx
+++ b/examples/markdown-docs/app/blog/page.tsx
@@ -12,7 +12,7 @@ export default function BlogIndexPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Blog</h1>
         {posts.length === 0 ? (
diff --git a/examples/markdown-docs/app/changelog/page.tsx b/examples/markdown-docs/app/changelog/page.tsx
index 05cbac9..890f6a9 100644
--- a/examples/markdown-docs/app/changelog/page.tsx
+++ b/examples/markdown-docs/app/changelog/page.tsx
@@ -13,7 +13,7 @@ export default function ChangelogPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Changelog</h1>
         {entries.length === 0 ? <p>No entries yet.</p> : null}
diff --git a/examples/markdown-docs/app/theme.css b/examples/markdown-docs/app/theme.css
index 889c288..be59356 100644
--- a/examples/markdown-docs/app/theme.css
+++ b/examples/markdown-docs/app/theme.css
@@ -1,11 +1,11 @@
 /*
  * Mono theme — token overrides for @inkform/framework.
- * This file is imported AFTER framework/styles.css so its declarations win.
- * Only --fw-* tokens and small Mono-specific accents are set here.
- * The framework's structural CSS is untouched.
- *
+ * Structure (header/sidebar/drawer/nav) is Canopy's, unchanged — see the
+ * sections below. This file only replaces the TOKENS + a handful of
+ * additive prose/typography accents further down.
  * Identity: monospace · brutalist · terminal. Markdown green accent.
  * Sharp corners (radius 0), strong 1.5px borders, hard-offset shadows.
+ * This file is imported AFTER framework/styles.css so its declarations win.
  */
 
 /* ── Font variables (set by next/font in layout.tsx) ─────────────────────── */
@@ -88,26 +88,326 @@ html.dark {
   --fw-method-options: #737373;
 }
 
-/* ── Mono top-bar accents ────────────────────────────────────────────────────
-   Base structure/layout/tokens now come from the shared framework layer
-   (packages/framework/src/styles/layout.css) — only Mono's genuine
-   stylistic deltas (uppercase, tracked letter-spacing, sharp corners, a
-   visible CTA border) are overridden here, on top of that shared base. */
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Mono's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-mono-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-mono-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-mono-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-mono-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-mono-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-mono-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-mono-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-mono-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-mono-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-mono-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-mono-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-mono-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-mono-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-mono-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-mono-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-mono-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-mono-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-mono-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-mono-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-mono-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 0;
+  overflow: hidden;
+}
+
+/* ── Mono tab typography ──────────────────────────────────────────────────
+   Additive only (font-size/letter-spacing/text-transform/weight) — layered
+   on top of Canopy's underline-tab mechanism (.fw-topnav-tab's own
+   border-bottom + .fw-topnav-tab--active in layout.css) without touching
+   `border`/`border-radius`, which would replace that mechanism instead of
+   just restyling it. */
 
 .fw-topnav-tab {
   font-size: 0.8125rem;
   letter-spacing: 0.04em;
   text-transform: uppercase;
-  border-radius: 0;
-  border: 1.5px solid transparent;
-  transition: color 0.1s, background 0.1s;
 }
 
 .fw-topnav-anchor,
 .fw-topnav-navlink {
   font-size: 0.8125rem;
   letter-spacing: 0.02em;
-  transition: color 0.1s;
 }
 
 .fw-topnav-cta {
@@ -116,17 +416,14 @@ html.dark {
   letter-spacing: 0.06em;
   text-transform: uppercase;
   border-radius: 0;
-  border: 1.5px solid var(--fw-primary);
-  transition: opacity 0.1s, box-shadow 0.1s;
+  border-color: var(--fw-primary);
 }
 
 .fw-shell-brand-name {
-  font-size: 0.9375rem;
   letter-spacing: 0.08em;
   text-transform: uppercase;
 }
 
-
 /* ── Mono prose overrides ────────────────────────────────────────────────── */
 /* Headings tracked-out and uppercase for the brutalist terminal look */
 .fw-prose h1,
diff --git a/examples/markdown-docs/components/collapsible-sidebar.tsx b/examples/markdown-docs/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..32194da
--- /dev/null
+++ b/examples/markdown-docs/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Mono's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-mono-sidebar-rail">
+        <button
+          type="button"
+          className="fw-mono-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-mono-sidebar-heading">
+        <span className="fw-mono-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-mono-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/examples/markdown-docs/components/sidebar-footer.tsx b/examples/markdown-docs/components/sidebar-footer.tsx
new file mode 100644
index 0000000..ba89f78
--- /dev/null
+++ b/examples/markdown-docs/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Mono doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-mono-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-mono-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-mono-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-mono-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-mono-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-mono-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/examples/markdown-docs/components/top-bar.tsx b/examples/markdown-docs/components/top-bar.tsx
index 61dc77a..953b83b 100644
--- a/examples/markdown-docs/components/top-bar.tsx
+++ b/examples/markdown-docs/components/top-bar.tsx
@@ -1,7 +1,6 @@
 import type { ReactNode } from 'react';
 import Link from 'next/link';
 import { AskAi } from '@inkform/framework/ask-ai';
-import { ThemeToggle } from '@inkform/framework/theme-toggle';
 import { SearchDialog } from '@inkform/framework/search-dialog';
 import type { DocsConfig } from '@inkform/framework';
 import { docTabs } from '@inkform/framework';
@@ -29,6 +28,12 @@ function Logo({ config }: { config: DocsConfig }) {
 }
 
 // ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Mono's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Mono-specific CSS.
 
 function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
   const tabs = docTabs(config);
@@ -82,12 +87,27 @@ export interface TopBarParts {
   logo: ReactNode;
   topNav: ReactNode;
   topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
 }
 
 /**
- * Build the three DocsShell header slot contents for Aurora.
- * Server component — client islands (SearchDialog, ThemeToggle, AskAi) are
- * already marked 'use client' in the framework.
+ * Build the three DocsShell header slot contents for Mono.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-mono-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
  */
 export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
   const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
@@ -114,21 +134,23 @@ export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts
 
   const topActions = (
     <>
-      <SearchDialog />
-      <ThemeToggle />
-      <AskAi enabled={aiEnabled} product={config.name} />
-      {config.cta ? (
-        <a
-          href={config.cta.href}
-          className="fw-topnav-cta"
-          target={config.cta.href.startsWith('http') ? '_blank' : undefined}
-          rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
-        >
-          {config.cta.label}
-        </a>
-      ) : null}
+      <div className="fw-mono-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
     </>
   );
 
-  return { logo, topNav, topActions };
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
 }
diff --git a/examples/markdown-docs/lib/route.tsx b/examples/markdown-docs/lib/route.tsx
index 7e543e7..d3651e2 100644
--- a/examples/markdown-docs/lib/route.tsx
+++ b/examples/markdown-docs/lib/route.tsx
@@ -1,12 +1,13 @@
 /**
- * lib/route.ts — Aurora routing core.
+ * lib/route.ts — Mono routing core.
  *
  * Resolves a slug array from the catch-all route into a doc page, generates
  * static params, and builds sidebar groups. The API Reference tab is NOT
- * handled here — it's served by app/api-reference/route.ts, a separate route
- * handler that renders Scalar's own UI directly from the OpenAPI spec.
- * apiBasePath() is still needed by components/top-bar.tsx to build that tab's
- * nav link.
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
  */
 
 import type { ReactNode } from 'react';
@@ -37,7 +38,7 @@ export function withContentNavLinks(config: DocsConfig): DocsConfig {
 // ── API tab helpers ───────────────────────────────────────────────────────────
 
 /** Find the tab that has an openapi spec (the API Reference tab). */
-function apiTab(config: DocsConfig): DocsTab | null {
+export function apiTab(config: DocsConfig): DocsTab | null {
   return docTabs(config).find((t) => !!t.openapi) ?? null;
 }
 
diff --git a/examples/pokeapi-docs/app/[[...slug]]/page.tsx b/examples/pokeapi-docs/app/[[...slug]]/page.tsx
index 5dd0aaf..ff89b53 100644
--- a/examples/pokeapi-docs/app/[[...slug]]/page.tsx
+++ b/examples/pokeapi-docs/app/[[...slug]]/page.tsx
@@ -1,10 +1,12 @@
 import { notFound } from 'next/navigation';
 import { Mdx } from '@inkform/framework/mdx';
-import { DocsShell, Sidebar, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
 import { docNeighbours } from '@inkform/framework';
 import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
 import { siteMdxComponents } from '@/mdx-components';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { renderIcon } from '@/lib/icons';
 import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
 
@@ -49,7 +51,8 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<Sidebar groups={sidebar} />}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
       toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
       hideToc={headings.length === 0}
     >
diff --git a/examples/pokeapi-docs/app/api-reference/[[...slug]]/page.tsx b/examples/pokeapi-docs/app/api-reference/[[...slug]]/page.tsx
index 7c3a451..304010d 100644
--- a/examples/pokeapi-docs/app/api-reference/[[...slug]]/page.tsx
+++ b/examples/pokeapi-docs/app/api-reference/[[...slug]]/page.tsx
@@ -5,8 +5,10 @@ import { loadDocsConfig, loadOpenApiSpecForBuild } from '@inkform/framework/cont
 import { findOperation, parseOpenApi } from '@inkform/framework/openapi';
 import { parseOpenApiDocument } from '@inkform/framework/openapi-engine/parse';
 import { buildNavTree } from '@inkform/framework/openapi-engine/nav';
-import { OperationPage, ReferenceSidebar } from '@inkform/framework/openapi-render';
+import { OperationPage, buildReferenceSidebarGroups } from '@inkform/framework/openapi-render';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { apiBasePath, apiTab, withContentNavLinks } from '@/lib/route';
 
 export const dynamicParams = false;
@@ -95,7 +97,14 @@ export default async function ApiReferencePage({ params }: { params: Promise<{ s
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<ReferenceSidebar tree={tree} basePath={basePath} activeOperationId={activeOperationId} />}
+      cta={topBar.cta}
+      sidebar={
+        <CollapsibleSidebar
+          title={tab.tab}
+          groups={buildReferenceSidebarGroups(tree, basePath, activeOperationId)}
+          footer={<SidebarFooter />}
+        />
+      }
       hideToc
     >
       {content}
diff --git a/examples/pokeapi-docs/app/blog/[slug]/page.tsx b/examples/pokeapi-docs/app/blog/[slug]/page.tsx
index 952691f..9282d33 100644
--- a/examples/pokeapi-docs/app/blog/[slug]/page.tsx
+++ b/examples/pokeapi-docs/app/blog/[slug]/page.tsx
@@ -27,7 +27,7 @@ export default async function BlogPostPage({ params }: { params: Promise<{ slug:
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>{post.title}</h1>
         <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
diff --git a/examples/pokeapi-docs/app/blog/page.tsx b/examples/pokeapi-docs/app/blog/page.tsx
index 79bffff..7a04806 100644
--- a/examples/pokeapi-docs/app/blog/page.tsx
+++ b/examples/pokeapi-docs/app/blog/page.tsx
@@ -12,7 +12,7 @@ export default function BlogIndexPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Blog</h1>
         {posts.length === 0 ? (
diff --git a/examples/pokeapi-docs/app/changelog/page.tsx b/examples/pokeapi-docs/app/changelog/page.tsx
index 05cbac9..890f6a9 100644
--- a/examples/pokeapi-docs/app/changelog/page.tsx
+++ b/examples/pokeapi-docs/app/changelog/page.tsx
@@ -13,7 +13,7 @@ export default function ChangelogPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Changelog</h1>
         {entries.length === 0 ? <p>No entries yet.</p> : null}
diff --git a/examples/pokeapi-docs/app/theme.css b/examples/pokeapi-docs/app/theme.css
index 5ad67c4..00e473f 100644
--- a/examples/pokeapi-docs/app/theme.css
+++ b/examples/pokeapi-docs/app/theme.css
@@ -1,13 +1,12 @@
 /*
  * Aurora theme — token overrides for @inkform/framework.
+ * Structure (header/sidebar/drawer/nav) is Canopy's, unchanged. This file
+ * only replaces the TOKENS: Pokédex red accent, hard-offset shadows, a
+ * serif display voice for headings distinct from the sans body/UI voice.
  * This file is imported AFTER framework/styles.css so its declarations win.
- * Only --fw-* tokens and small Aurora-specific accents are set here.
- * The framework's structural CSS is untouched.
  */
 
 /* ── Font variables (set by next/font in layout.tsx) ─────────────────────── */
-/* The variables --font-sans, --font-heading, and --font-mono are injected  */
-/* onto <html> by Next.                                                     */
 :root {
   --fw-font: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
   --fw-font-heading: var(--font-heading, ui-serif, Georgia, "Times New Roman", serif);
@@ -68,8 +67,305 @@ html.dark {
   --fw-ring: 0 0 0 3px rgba(248, 113, 113, 0.28);
 }
 
-/* Top bar (tabs/anchors/nav links/CTA/brand) is now styled by the shared
-   framework layer (packages/framework/src/styles/layout.css) — it only
-   ever consumed --fw-* tokens here, so there was nothing theme-specific
-   left to override for Aurora. See Mono's theme.css for an example of a
-   theme that DOES need a delta on top of the shared base. */
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Aurora's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-aurora-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-aurora-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-aurora-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-aurora-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-aurora-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-aurora-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-aurora-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-aurora-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-aurora-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-aurora-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-aurora-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-aurora-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-aurora-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-aurora-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-aurora-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-aurora-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-aurora-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-aurora-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-aurora-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-aurora-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 1rem;
+  overflow: hidden;
+}
diff --git a/examples/pokeapi-docs/components/collapsible-sidebar.tsx b/examples/pokeapi-docs/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..f9876e2
--- /dev/null
+++ b/examples/pokeapi-docs/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Aurora's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-aurora-sidebar-rail">
+        <button
+          type="button"
+          className="fw-aurora-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-aurora-sidebar-heading">
+        <span className="fw-aurora-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-aurora-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/examples/pokeapi-docs/components/sidebar-footer.tsx b/examples/pokeapi-docs/components/sidebar-footer.tsx
new file mode 100644
index 0000000..e2166c8
--- /dev/null
+++ b/examples/pokeapi-docs/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Aurora doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-aurora-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-aurora-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-aurora-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-aurora-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-aurora-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-aurora-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/examples/pokeapi-docs/components/top-bar.tsx b/examples/pokeapi-docs/components/top-bar.tsx
index 61dc77a..b8df02c 100644
--- a/examples/pokeapi-docs/components/top-bar.tsx
+++ b/examples/pokeapi-docs/components/top-bar.tsx
@@ -1,7 +1,6 @@
 import type { ReactNode } from 'react';
 import Link from 'next/link';
 import { AskAi } from '@inkform/framework/ask-ai';
-import { ThemeToggle } from '@inkform/framework/theme-toggle';
 import { SearchDialog } from '@inkform/framework/search-dialog';
 import type { DocsConfig } from '@inkform/framework';
 import { docTabs } from '@inkform/framework';
@@ -29,6 +28,12 @@ function Logo({ config }: { config: DocsConfig }) {
 }
 
 // ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Aurora's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Aurora-specific CSS.
 
 function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
   const tabs = docTabs(config);
@@ -82,12 +87,27 @@ export interface TopBarParts {
   logo: ReactNode;
   topNav: ReactNode;
   topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
 }
 
 /**
  * Build the three DocsShell header slot contents for Aurora.
- * Server component — client islands (SearchDialog, ThemeToggle, AskAi) are
- * already marked 'use client' in the framework.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-aurora-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
  */
 export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
   const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
@@ -114,21 +134,23 @@ export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts
 
   const topActions = (
     <>
-      <SearchDialog />
-      <ThemeToggle />
-      <AskAi enabled={aiEnabled} product={config.name} />
-      {config.cta ? (
-        <a
-          href={config.cta.href}
-          className="fw-topnav-cta"
-          target={config.cta.href.startsWith('http') ? '_blank' : undefined}
-          rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
-        >
-          {config.cta.label}
-        </a>
-      ) : null}
+      <div className="fw-aurora-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
     </>
   );
 
-  return { logo, topNav, topActions };
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
 }
diff --git a/examples/pokeapi-docs/lib/route.tsx b/examples/pokeapi-docs/lib/route.tsx
index e49a5a6..db313d1 100644
--- a/examples/pokeapi-docs/lib/route.tsx
+++ b/examples/pokeapi-docs/lib/route.tsx
@@ -3,11 +3,11 @@
  *
  * Resolves a slug array from the catch-all route into a doc page, generates
  * static params, and builds sidebar groups. The API Reference tab is NOT
- * handled here — it's served by app/api-reference/[[...slug]]/page.tsx, the
- * framework's own React/Galley renderer (@inkform/framework/openapi-render),
- * native by default (docs.json's `apiReference.renderer` doesn't need to be
- * set) — no Scalar/Vue dependency. apiBasePath() is still needed by
- * components/top-bar.tsx to build the tab's nav link either way.
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
  */
 
 import type { ReactNode } from 'react';
diff --git a/package-lock.json b/package-lock.json
index e991598..c71b78c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1282,28 +1282,16 @@
       "resolved": "packages/framework",
       "link": true
     },
-    "node_modules/@inkform/theme-aurora": {
-      "resolved": "templates/aurora",
-      "link": true
-    },
-    "node_modules/@inkform/theme-base": {
-      "resolved": "templates/base",
-      "link": true
-    },
-    "node_modules/@inkform/theme-cedar": {
-      "resolved": "templates/cedar",
-      "link": true
-    },
-    "node_modules/@inkform/theme-fern": {
-      "resolved": "templates/fern",
+    "node_modules/@inkform/theme-canopy": {
+      "resolved": "templates/canopy",
       "link": true
     },
     "node_modules/@inkform/theme-galley": {
       "resolved": "templates/galley",
       "link": true
     },
-    "node_modules/@inkform/theme-mono": {
-      "resolved": "templates/mono",
+    "node_modules/@inkform/theme-shadcn": {
+      "resolved": "templates/shadcn",
       "link": true
     },
     "node_modules/@jridgewell/sourcemap-codec": {
@@ -7371,9 +7359,9 @@
         "react-dom": ">=19"
       }
     },
-    "templates/aurora": {
-      "name": "@inkform/theme-aurora",
-      "version": "0.2.0",
+    "templates/canopy": {
+      "name": "@inkform/theme-canopy",
+      "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
         "@inkform/framework": "^0.3.0",
@@ -7390,130 +7378,7 @@
         "typescript": "^5"
       }
     },
-    "templates/aurora/node_modules/@inkform/framework": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/@inkform/framework/-/framework-0.3.0.tgz",
-      "integrity": "sha512-BRLtjNPS5UT06IToODYWHm1nSg6MYJSDMXe6qWnSNqPexFCDlLDbbeq5BreDNHR+ASJGQ2Q9t3ckukT+0tVu0A==",
-      "license": "MIT",
-      "dependencies": {
-        "gray-matter": "^4.0.3",
-        "next-mdx-remote": "^6.0.0",
-        "rehype-pretty-code": "^0.14.1",
-        "rehype-slug": "^6.0.0",
-        "remark-directive": "^3.0.0",
-        "remark-gfm": "^4.0.1",
-        "shiki": "^1.24.0",
-        "unist-util-visit": "^5.0.0",
-        "yaml": "^2.6.0"
-      },
-      "peerDependencies": {
-        "next": ">=16",
-        "react": ">=19",
-        "react-dom": ">=19"
-      }
-    },
-    "templates/base": {
-      "name": "@inkform/theme-base",
-      "version": "0.2.0",
-      "license": "MIT",
-      "dependencies": {
-        "@inkform/framework": "^0.3.0",
-        "lucide-react": "^0.483.0",
-        "next": "16.2.10",
-        "react": "19.2.1",
-        "react-dom": "19.2.1"
-      },
-      "devDependencies": {
-        "@types/node": "^20",
-        "@types/react": "^19",
-        "@types/react-dom": "^19",
-        "pagefind": "^1.5.0",
-        "typescript": "^5"
-      }
-    },
-    "templates/base/node_modules/@inkform/framework": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/@inkform/framework/-/framework-0.3.0.tgz",
-      "integrity": "sha512-BRLtjNPS5UT06IToODYWHm1nSg6MYJSDMXe6qWnSNqPexFCDlLDbbeq5BreDNHR+ASJGQ2Q9t3ckukT+0tVu0A==",
-      "license": "MIT",
-      "dependencies": {
-        "gray-matter": "^4.0.3",
-        "next-mdx-remote": "^6.0.0",
-        "rehype-pretty-code": "^0.14.1",
-        "rehype-slug": "^6.0.0",
-        "remark-directive": "^3.0.0",
-        "remark-gfm": "^4.0.1",
-        "shiki": "^1.24.0",
-        "unist-util-visit": "^5.0.0",
-        "yaml": "^2.6.0"
-      },
-      "peerDependencies": {
-        "next": ">=16",
-        "react": ">=19",
-        "react-dom": ">=19"
-      }
-    },
-    "templates/cedar": {
-      "name": "@inkform/theme-cedar",
-      "version": "0.2.0",
-      "license": "MIT",
-      "dependencies": {
-        "@inkform/framework": "^0.3.0",
-        "lucide-react": "^0.483.0",
-        "next": "16.2.10",
-        "react": "19.2.1",
-        "react-dom": "19.2.1"
-      },
-      "devDependencies": {
-        "@types/node": "^20",
-        "@types/react": "^19",
-        "@types/react-dom": "^19",
-        "pagefind": "^1.5.0",
-        "typescript": "^5"
-      }
-    },
-    "templates/cedar/node_modules/@inkform/framework": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/@inkform/framework/-/framework-0.3.0.tgz",
-      "integrity": "sha512-BRLtjNPS5UT06IToODYWHm1nSg6MYJSDMXe6qWnSNqPexFCDlLDbbeq5BreDNHR+ASJGQ2Q9t3ckukT+0tVu0A==",
-      "license": "MIT",
-      "dependencies": {
-        "gray-matter": "^4.0.3",
-        "next-mdx-remote": "^6.0.0",
-        "rehype-pretty-code": "^0.14.1",
-        "rehype-slug": "^6.0.0",
-        "remark-directive": "^3.0.0",
-        "remark-gfm": "^4.0.1",
-        "shiki": "^1.24.0",
-        "unist-util-visit": "^5.0.0",
-        "yaml": "^2.6.0"
-      },
-      "peerDependencies": {
-        "next": ">=16",
-        "react": ">=19",
-        "react-dom": ">=19"
-      }
-    },
-    "templates/fern": {
-      "name": "@inkform/theme-fern",
-      "version": "0.2.0",
-      "license": "MIT",
-      "dependencies": {
-        "@inkform/framework": "^0.3.0",
-        "lucide-react": "^0.483.0",
-        "next": "16.2.10",
-        "react": "19.2.1",
-        "react-dom": "19.2.1"
-      },
-      "devDependencies": {
-        "@types/node": "^20",
-        "@types/react": "^19",
-        "@types/react-dom": "^19",
-        "pagefind": "^1.5.2",
-        "typescript": "^5"
-      }
-    },
-    "templates/fern/node_modules/@inkform/framework": {
+    "templates/canopy/node_modules/@inkform/framework": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/@inkform/framework/-/framework-0.3.0.tgz",
       "integrity": "sha512-BRLtjNPS5UT06IToODYWHm1nSg6MYJSDMXe6qWnSNqPexFCDlLDbbeq5BreDNHR+ASJGQ2Q9t3ckukT+0tVu0A==",
@@ -7537,7 +7402,7 @@
     },
     "templates/galley": {
       "name": "@inkform/theme-galley",
-      "version": "0.2.0",
+      "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
         "@inkform/framework": "^0.3.0",
@@ -7550,7 +7415,7 @@
         "@types/node": "^20",
         "@types/react": "^19",
         "@types/react-dom": "^19",
-        "pagefind": "^1.5.0",
+        "pagefind": "^1.5.2",
         "typescript": "^5"
       }
     },
@@ -7576,9 +7441,9 @@
         "react-dom": ">=19"
       }
     },
-    "templates/mono": {
-      "name": "@inkform/theme-mono",
-      "version": "0.2.0",
+    "templates/shadcn": {
+      "name": "@inkform/theme-shadcn",
+      "version": "0.1.0",
       "license": "MIT",
       "dependencies": {
         "@inkform/framework": "^0.3.0",
@@ -7591,11 +7456,11 @@
         "@types/node": "^20",
         "@types/react": "^19",
         "@types/react-dom": "^19",
-        "pagefind": "^1.5.0",
+        "pagefind": "^1.5.2",
         "typescript": "^5"
       }
     },
-    "templates/mono/node_modules/@inkform/framework": {
+    "templates/shadcn/node_modules/@inkform/framework": {
       "version": "0.3.0",
       "resolved": "https://registry.npmjs.org/@inkform/framework/-/framework-0.3.0.tgz",
       "integrity": "sha512-BRLtjNPS5UT06IToODYWHm1nSg6MYJSDMXe6qWnSNqPexFCDlLDbbeq5BreDNHR+ASJGQ2Q9t3ckukT+0tVu0A==",
diff --git a/packages/cli/src/scaffold.mjs b/packages/cli/src/scaffold.mjs
index a569b63..eb4e608 100644
--- a/packages/cli/src/scaffold.mjs
+++ b/packages/cli/src/scaffold.mjs
@@ -19,13 +19,19 @@ import pc from 'picocolors';
 const REPO = 'inkform-dev/framework';
 const TEMPLATE_REF = process.env.INKFORM_DOCS_REF || 'main';
 
+// Consolidated to one proven structure (Canopy: collapsible sidebar,
+// mobile-drawer nav that actually stays reachable, theme trio) with theme
+// variants on top, instead of maintaining N structurally-independent
+// templates. The previous 9-template set (birch, rowan, folio, glyph,
+// harbor, meadow, feather + the old canopy) is gone, not archived — each
+// had its own hand-rolled, independently-buggy header/nav. The 6 themes
+// before THAT (aurora, fern, cedar, mono, base, galley) are still archived
+// under archive/templates/, not scaffoldable; galley's tokens live on in
+// the new galley entry below.
 const THEMES = [
-  { value: 'aurora', label: 'Aurora', hint: 'classic dark docs (Nextra-style)' },
-  { value: 'fern', label: 'Fern', hint: 'clean & friendly, emerald green' },
-  { value: 'cedar', label: 'Cedar', hint: 'warm & editorial, burnt orange' },
-  { value: 'mono', label: 'Mono', hint: 'monospace / brutalist / terminal' },
-  { value: 'base', label: 'Base', hint: 'minimal & neutral (start simple)' },
-  { value: 'galley', label: 'Galley', hint: 'warm paper & ink, one editorial red accent' },
+  { value: 'canopy', label: 'Canopy', hint: 'centered search, collapsible sidebar — dark, bright green' },
+  { value: 'shadcn', label: 'Shadcn', hint: "reproduces shadcn/ui's own default look — Zinc, monochrome" },
+  { value: 'galley', label: 'Galley', hint: "Inkform's own design system — warm paper + ink, proof-red" },
 ];
 const THEME_VALUES = new Set(THEMES.map((t) => t.value));
 
@@ -211,7 +217,7 @@ export async function run(argv) {
     theme = undefined;
   }
   if (!theme) {
-    const v = await p.select({ message: 'Pick a theme', options: THEMES, initialValue: 'aurora' });
+    const v = await p.select({ message: 'Pick a theme', options: THEMES, initialValue: 'canopy' });
     if (p.isCancel(v)) onCancel();
     theme = v;
   }
diff --git a/packages/framework/package.json b/packages/framework/package.json
index 79c3950..722c378 100644
--- a/packages/framework/package.json
+++ b/packages/framework/package.json
@@ -38,6 +38,7 @@
     "./openapi": "./src/openapi.ts",
     "./openapi-engine/nav": "./src/openapi-engine/nav.ts",
     "./openapi-engine/parse": "./src/openapi-engine/parse.ts",
+    "./openapi-engine/markdown": "./src/openapi-engine/markdown.ts",
     "./openapi-engine/breaking-changes": "./src/openapi-engine/breaking-changes.ts",
     "./openapi-render": "./src/openapi-render/index.ts",
     "./mcp": "./src/mcp/index.ts",
@@ -50,6 +51,7 @@
     "./search-dialog": "./src/search-dialog.tsx",
     "./pagefind-highlight": "./src/pagefind-highlight-mount.tsx",
     "./ask-ai": "./src/ask-ai.tsx",
+    "./ai-tool-menu": "./src/ai-tool-menu.tsx",
     "./theme-toggle": "./src/theme-toggle.tsx",
     "./subscribe-form": "./src/subscribe-form.tsx",
     "./analytics-script": "./src/analytics-script.tsx",
diff --git a/packages/framework/src/ai-tool-menu.tsx b/packages/framework/src/ai-tool-menu.tsx
new file mode 100644
index 0000000..7ae6373
--- /dev/null
+++ b/packages/framework/src/ai-tool-menu.tsx
@@ -0,0 +1,306 @@
+'use client';
+
+import * as React from 'react';
+
+/**
+ * AiToolMenu — a right-rail list of "hand this page to an AI tool" actions:
+ * Copy page (raw Markdown), Open in ChatGPT/Claude/Perplexity/Grok (a
+ * pre-filled prompt), Connect to Cursor/VS Code (installs THIS SITE'S OWN
+ * MCP server — see '@inkform/framework/mcp' — into the reader's editor).
+ *
+ * Modeled on the right-rail menu at sequoia.mintlify.site (verified by
+ * directly inspecting that site's own shipped implementation — intercepting
+ * `window.open`/`navigator.clipboard.writeText` calls rather than guessing —
+ * see the comment on each URL builder below for what was actually observed).
+ * Ties into this framework's existing llms.txt/MCP work: the Cursor/VS Code
+ * items are only meaningful because a theme can mount `createMcpHandler()`
+ * (./mcp) at a real route in a couple of lines; this component is otherwise
+ * independent of that and degrades gracefully (see `mcpUrl`) if no MCP route
+ * exists.
+ *
+ * Framework components don't bundle an icon library (see ARCHITECTURE.md
+ * §5) — `renderIcon` follows the same convention as Sidebar/DocsShell's own
+ * `renderIcon` prop. Without one, a small brand-neutral built-in glyph is
+ * used (a generic "copy" icon, and a generic external-link arrow for every
+ * other item) rather than reproducing any tool's actual logo mark.
+ */
+
+/* ─────────────────────────────────────────────
+   Types
+───────────────────────────────────────────── */
+
+export type AiToolId = 'copy' | 'chatgpt' | 'claude' | 'cursor' | 'vscode' | 'perplexity' | 'grok';
+
+export interface AiToolMenuProps {
+  /**
+   * Raw Markdown/MDX of the current page. "Copy page" writes this verbatim
+   * to the clipboard — the same idea as GitHub/Mintlify's own "Copy page"
+   * buttons. Falls back to copying the page URL when omitted.
+   */
+  pageContent?: string;
+  /**
+   * Absolute URL of the current page (e.g. "https://docs.example.com/quickstart").
+   * Used as the pre-hydration href so links aren't briefly blank; every link
+   * recomputes from `window.location.href` right after mount regardless, so
+   * this is correct even when omitted or stale — it only prevents a same-URL
+   * flash on first paint. (SSG pages don't have request context to compute
+   * this server-side without opting the whole page out of static generation,
+   * so the framework doesn't do that for you — see Canopy's page.tsx for the
+   * "pass nothing, let it self-resolve client-side" default.)
+   */
+  pageUrl?: string;
+  /**
+   * Absolute URL of this site's own MCP endpoint (mount one via
+   * `createMcpHandler()` from '@inkform/framework/mcp' — ARCHITECTURE.md
+   * §8). Defaults to `${location.origin}/api/mcp`. Pass `null` to omit
+   * "Connect to Cursor" / "Connect to VS Code" entirely, e.g. a site that
+   * hasn't mounted an MCP route.
+   */
+  mcpUrl?: string | null;
+  /** Shown to Cursor/VS Code as the installed MCP server's label. Defaults to 'Docs'. */
+  siteName?: string;
+  /** Section heading, or `null` to omit it (e.g. stacking under a TocList that already renders "On this page"). */
+  title?: string | null;
+  /**
+   * Pre-rendered icon per tool (e.g. Lucide elements), keyed by `AiToolId`.
+   * A plain ReactNode map rather than a `renderIcon` callback — this
+   * component is a Client Component, and a live function prop can't cross
+   * the Server → Client Component boundary from a page.tsx that builds this
+   * server-side (confirmed the hard way: `next build` fails with "Functions
+   * cannot be passed directly to Client Components" if you try). Build the
+   * map once with real icons (e.g. a small constant in lib/icons.tsx) and
+   * pass it down as data, the same way Sidebar/DocsShell's own `renderIcon`
+   * convention resolves icons into ReactNode server-side before they ever
+   * reach a component. Falls back to a small built-in glyph per tool for any
+   * id not present in the map.
+   */
+  icons?: Partial<Record<AiToolId, React.ReactNode>>;
+  /** Extra class name on the root <nav>. */
+  className?: string;
+}
+
+/* ─────────────────────────────────────────────
+   Link builders
+
+   Verified 2026-07 against sequoia.mintlify.site's own production build —
+   intercepted `window.open()` there rather than guessing, since its actions
+   are onClick handlers, not plain <a href>. Findings behind each comment.
+───────────────────────────────────────────── */
+
+function buildPrompt(pageUrl: string): string {
+  return `Read ${pageUrl} and help me understand it`;
+}
+
+/** Unicode-safe base64 (btoa() alone only handles Latin1) — guards a siteName with non-ASCII characters. */
+function safeBase64(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary);
+}
+
+function safeOrigin(url: string): string | undefined {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function chatGptUrl(pageUrl: string): string {
+  // https://chat.openai.com/?hints=search&q=<prompt> — `q` pre-fills (but
+  // doesn't auto-submit) the composer. `hints=search` is undocumented but
+  // present in Sequoia's real link; left in since it's what was observed
+  // actually shipping, not a guess.
+  return `https://chat.openai.com/?hints=search&q=${encodeURIComponent(buildPrompt(pageUrl))}`;
+}
+
+function claudeUrl(pageUrl: string): string {
+  // https://claude.ai/new?q=<prompt> — same pre-fill convention as ChatGPT.
+  return `https://claude.ai/new?q=${encodeURIComponent(buildPrompt(pageUrl))}`;
+}
+
+function perplexityUrl(pageUrl: string): string {
+  return `https://www.perplexity.ai/search?q=${encodeURIComponent(buildPrompt(pageUrl))}`;
+}
+
+function grokUrl(pageUrl: string): string {
+  // grok.com's `q` param isn't publicly documented anywhere findable, but it
+  // demonstrably pre-fills the composer on Sequoia's real production site
+  // (confirmed the same way as chatGptUrl above) — real and working, just
+  // unofficial, unlike the other three.
+  return `https://grok.com/?q=${encodeURIComponent(buildPrompt(pageUrl))}`;
+}
+
+function cursorDeeplink(siteName: string, mcpUrl: string): string {
+  // Cursor's documented one-click MCP install deep link:
+  //   cursor://anysphere.cursor-deeplink/mcp/install?name=<name>&config=<base64 JSON>
+  // This deliberately does NOT open the doc page — it registers THIS SITE'S
+  // OWN MCP server (see '@inkform/framework/mcp') in the reader's Cursor, so
+  // they can point Cursor's agent at these docs directly. Chosen over a
+  // guessed `cursor://open?url=...` scheme because this is what Sequoia's
+  // real button actually does (confirmed by decoding its intercepted
+  // window.open call) and it's a materially more useful feature.
+  const config = safeBase64(JSON.stringify({ url: mcpUrl }));
+  return `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(siteName)}&config=${config}`;
+}
+
+function vscodeDeeplink(siteName: string, mcpUrl: string): string {
+  // VS Code's documented MCP install URI: vscode:mcp/install?<url-encoded JSON>
+  // — note the query segment IS the encoded JSON, not key=value pairs. Same
+  // "install this site's MCP server" idea as cursorDeeplink above.
+  return `vscode:mcp/install?${encodeURIComponent(JSON.stringify({ name: siteName, url: mcpUrl }))}`;
+}
+
+/* ─────────────────────────────────────────────
+   Default icons — dependency-free, brand-neutral (no framework package
+   bundles an icon library; see ARCHITECTURE.md §5). A theme can pass real
+   per-tool icons via `renderIcon`.
+───────────────────────────────────────────── */
+
+function CopyGlyph() {
+  return (
+    <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <rect x="9" y="9" width="12" height="12" rx="2" />
+      <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+    </svg>
+  );
+}
+
+function CheckGlyph() {
+  return (
+    <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M20 6 9 17l-5-5" />
+    </svg>
+  );
+}
+
+function ExternalGlyph() {
+  return (
+    <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.75" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M7 17 17 7" />
+      <path d="M8 7h9v9" />
+    </svg>
+  );
+}
+
+function defaultIcon(tool: AiToolId): React.ReactNode {
+  return tool === 'copy' ? <CopyGlyph /> : <ExternalGlyph />;
+}
+
+/* ─────────────────────────────────────────────
+   Copy-to-clipboard, with a fallback for contexts without the async
+   Clipboard API (e.g. non-HTTPS dev over a LAN IP).
+───────────────────────────────────────────── */
+
+async function copyText(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard?.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    }
+  } catch {
+    // fall through to the legacy path below
+  }
+  try {
+    const el = document.createElement('textarea');
+    el.value = text;
+    el.style.position = 'fixed';
+    el.style.opacity = '0';
+    document.body.appendChild(el);
+    el.select();
+    document.execCommand('copy');
+    document.body.removeChild(el);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/* ─────────────────────────────────────────────
+   AiToolMenu
+───────────────────────────────────────────── */
+
+export function AiToolMenu({
+  pageContent,
+  pageUrl,
+  mcpUrl,
+  siteName = 'Docs',
+  title = 'Ask AI',
+  icons,
+  className,
+}: AiToolMenuProps): React.ReactNode {
+  const [copied, setCopied] = React.useState(false);
+
+  // See the `pageUrl` prop doc above: both the server pass and the first
+  // client pass (before the effect below fires) render from the same
+  // `pageUrl` fallback, so there's no hydration mismatch — the effect's
+  // setState only triggers an ordinary post-hydration re-render, same as
+  // any other client-only data (TocList's own scroll-spy state works the
+  // same way).
+  const [liveUrl, setLiveUrl] = React.useState<string | undefined>(pageUrl);
+  const [liveOrigin, setLiveOrigin] = React.useState<string | undefined>(() => (pageUrl ? safeOrigin(pageUrl) : undefined));
+
+  React.useEffect(() => {
+    setLiveUrl(window.location.href);
+    setLiveOrigin(window.location.origin);
+  }, []);
+
+  const resolvedUrl = liveUrl ?? '';
+  const resolvedMcpUrl = mcpUrl === null ? null : (mcpUrl ?? (liveOrigin ? `${liveOrigin}/api/mcp` : null));
+
+  async function handleCopy() {
+    const ok = await copyText(pageContent || resolvedUrl);
+    if (ok) {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    }
+  }
+
+  function icon(tool: AiToolId): React.ReactNode {
+    return icons?.[tool] ?? defaultIcon(tool);
+  }
+
+  // Built once per render instead of hand-repeating six near-identical <li>
+  // blocks — the promptable web tools and the MCP-install tools each gate on
+  // a different prerequisite (a resolved page URL vs. a resolved MCP URL).
+  const links: { id: AiToolId; label: string; href: string }[] = [];
+  if (resolvedUrl) {
+    links.push({ id: 'chatgpt', label: 'Open in ChatGPT', href: chatGptUrl(resolvedUrl) });
+    links.push({ id: 'claude', label: 'Open in Claude', href: claudeUrl(resolvedUrl) });
+  }
+  if (resolvedMcpUrl) {
+    links.push({ id: 'cursor', label: 'Connect to Cursor', href: cursorDeeplink(siteName, resolvedMcpUrl) });
+    links.push({ id: 'vscode', label: 'Connect to VS Code', href: vscodeDeeplink(siteName, resolvedMcpUrl) });
+  }
+  if (resolvedUrl) {
+    links.push({ id: 'perplexity', label: 'Open in Perplexity', href: perplexityUrl(resolvedUrl) });
+    links.push({ id: 'grok', label: 'Open in Grok', href: grokUrl(resolvedUrl) });
+  }
+
+  return (
+    <nav className={`fw-aitoolmenu${className ? ` ${className}` : ''}`} aria-label="AI tools">
+      {title ? <p className="fw-aitoolmenu-title">{title}</p> : null}
+      <ul className="fw-aitoolmenu-list">
+        <li className="fw-aitoolmenu-item">
+          <button
+            type="button"
+            className={`fw-aitoolmenu-link${copied ? ' fw-aitoolmenu-link--copied' : ''}`}
+            onClick={() => void handleCopy()}
+          >
+            <span className="fw-aitoolmenu-icon">{copied ? <CheckGlyph /> : icon('copy')}</span>
+            <span className="fw-aitoolmenu-label">{copied ? 'Copied!' : 'Copy page'}</span>
+          </button>
+        </li>
+        {links.map((l) => (
+          <li key={l.id} className="fw-aitoolmenu-item">
+            <a className="fw-aitoolmenu-link" href={l.href} target="_blank" rel="noopener noreferrer">
+              <span className="fw-aitoolmenu-icon">{icon(l.id)}</span>
+              <span className="fw-aitoolmenu-label">{l.label}</span>
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}
diff --git a/packages/framework/src/components.tsx b/packages/framework/src/components.tsx
index 25afad3..785321e 100644
--- a/packages/framework/src/components.tsx
+++ b/packages/framework/src/components.tsx
@@ -255,20 +255,20 @@ export function ParamField({
   const location = query ? 'query' : path ? 'path' : body ? 'body' : header ? 'header' : undefined;
 
   return (
-    <div className={`fw-param${deprecated ? ' fw-param--deprecated' : ''}`}>
-      <div className="fw-param-header">
-        <code className="fw-param-name">{fieldName}</code>
-        {type && <span className="fw-param-type">{type}</span>}
-        {location && <span className="fw-param-location">{location}</span>}
-        {required && <span className="fw-param-required">required</span>}
-        {deprecated && <span className="fw-param-deprecated">deprecated</span>}
+    <div className={`fw-mdx-param${deprecated ? ' fw-mdx-param--deprecated' : ''}`}>
+      <div className="fw-mdx-param-header">
+        <code className="fw-mdx-param-name">{fieldName}</code>
+        {type && <span className="fw-mdx-param-type">{type}</span>}
+        {location && <span className="fw-mdx-param-location">{location}</span>}
+        {required && <span className="fw-mdx-param-required">required</span>}
+        {deprecated && <span className="fw-mdx-param-deprecated">deprecated</span>}
         {defaultValue !== undefined && (
-          <span className="fw-param-default">
+          <span className="fw-mdx-param-default">
             default: <code>{String(defaultValue)}</code>
           </span>
         )}
       </div>
-      {children && <div className="fw-param-body">{children}</div>}
+      {children && <div className="fw-mdx-param-body">{children}</div>}
     </div>
   );
 }
@@ -284,11 +284,11 @@ export function ResponseField({ name, type, required = false, children }: Respon
   return (
     <div className="fw-response-field">
       <div className="fw-response-field-header">
-        <code className="fw-param-name">{name}</code>
-        {type && <span className="fw-param-type">{type}</span>}
-        {required && <span className="fw-param-required">required</span>}
+        <code className="fw-mdx-param-name">{name}</code>
+        {type && <span className="fw-mdx-param-type">{type}</span>}
+        {required && <span className="fw-mdx-param-required">required</span>}
       </div>
-      {children && <div className="fw-param-body">{children}</div>}
+      {children && <div className="fw-mdx-param-body">{children}</div>}
     </div>
   );
 }
@@ -460,12 +460,12 @@ export function NewsletterCTA({
 export function ApiReference({ spec, endpoint }: { spec?: string; endpoint?: string }) {
   const [method, ...rest] = (endpoint ?? 'GET /').split(' ');
   return (
-    <div className="fw-apiref">
-      <div className="fw-apiref-head">
+    <div className="fw-mdx-apiref">
+      <div className="fw-mdx-apiref-head">
         <span className={`fw-method-pill fw-method-${(method ?? 'get').toLowerCase()}`}>{method}</span>
-        <code className="fw-apiref-path">{rest.join(' ')}</code>
+        <code className="fw-mdx-apiref-path">{rest.join(' ')}</code>
       </div>
-      {spec ? <p className="fw-apiref-note">from {spec}</p> : null}
+      {spec ? <p className="fw-mdx-apiref-note">from {spec}</p> : null}
     </div>
   );
 }
diff --git a/packages/framework/src/docs-shell.tsx b/packages/framework/src/docs-shell.tsx
index 92a86d2..897ba1a 100644
--- a/packages/framework/src/docs-shell.tsx
+++ b/packages/framework/src/docs-shell.tsx
@@ -179,6 +179,13 @@ export interface DocsShellProps {
   logo?: ReactNode;
   topNav?: ReactNode;
   topActions?: ReactNode;
+  /**
+   * Optional CTA, rendered at the end of the header actions row AND
+   * (unlike topActions, which stays header-only — see MobileSidebarToggle's
+   * doc comment) duplicated into the mobile drawer, since it's usually the
+   * one part of the header worth keeping reachable once collapsed.
+   */
+  cta?: ReactNode;
   sidebar?: ReactNode;
   toc?: ReactNode;
   children: ReactNode;
@@ -193,6 +200,7 @@ export function DocsShell({
   logo,
   topNav,
   topActions,
+  cta,
   sidebar,
   toc,
   children,
@@ -201,6 +209,12 @@ export function DocsShell({
   hideSidebar,
   contentType,
 }: DocsShellProps): ReactNode {
+  // The hamburger/drawer is also how topNav + cta stay reachable once the
+  // header hides them past a width (see layout.css) — so it has to render
+  // whenever there's a sidebar OR nav content to reveal, not just for the
+  // sidebar tree alone.
+  const showMobileMenu = (!hideSidebar && sidebar) || topNav || cta;
+
   return (
     <div className={`fw-shell${hideSidebar ? ' fw-shell--no-sidebar' : ''}${hideToc ? ' fw-shell--no-toc' : ''}`}>
       {/* ── Top header ── */}
@@ -210,8 +224,10 @@ export function DocsShell({
           <div className="fw-shell-header-start">
             {logo ? <div className="fw-shell-logo">{logo}</div> : null}
             {/* Mobile drawer toggle — client component */}
-            {!hideSidebar && sidebar ? (
-              <MobileSidebarToggle>{sidebar}</MobileSidebarToggle>
+            {showMobileMenu ? (
+              <MobileSidebarToggle nav={topNav} cta={cta}>
+                {!hideSidebar ? sidebar : null}
+              </MobileSidebarToggle>
             ) : null}
           </div>
 
@@ -223,8 +239,11 @@ export function DocsShell({
           ) : null}
 
           {/* Right actions */}
-          {topActions ? (
-            <div className="fw-shell-actions">{topActions}</div>
+          {topActions || cta ? (
+            <div className="fw-shell-actions">
+              {topActions}
+              {cta}
+            </div>
           ) : null}
         </div>
       </header>
diff --git a/packages/framework/src/openapi-render/CodeSamples.test.tsx b/packages/framework/src/openapi-render/CodeSamples.test.tsx
index f6ca73e..f03f219 100644
--- a/packages/framework/src/openapi-render/CodeSamples.test.tsx
+++ b/packages/framework/src/openapi-render/CodeSamples.test.tsx
@@ -1,7 +1,8 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderToStaticMarkup } from 'react-dom/server';
+import type { ReactElement } from 'react';
+import { renderToReadableStream } from 'react-dom/server';
 import { describe, expect, it } from 'vitest';
 import { findOperation, parseOpenApi } from '../openapi';
 import { CodeSamples } from './CodeSamples';
@@ -9,6 +10,21 @@ import { CodeSamples } from './CodeSamples';
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 const POKEAPI_SPEC = path.join(REPO_ROOT, 'examples', 'pokeapi-docs', 'content', 'docs', 'openapi.json');
 
+/** CodeSamples is an async Server Component (shiki highlighting) — renderToStaticMarkup can't render it; this can, and `stream.allReady` ensures highlighting has actually finished before reading. */
+async function renderAsync(node: ReactElement): Promise<string> {
+  const stream = await renderToReadableStream(node);
+  await stream.allReady;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let html = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    html += decoder.decode(value, { stream: true });
+  }
+  return html;
+}
+
 describe('CodeSamples (real pokeapi spec, real snippetz generation)', () => {
   it('generates real, correct code for a GET operation with a path param, across 4 languages', async () => {
     const raw = readFileSync(POKEAPI_SPEC, 'utf-8');
@@ -17,19 +33,24 @@ describe('CodeSamples (real pokeapi spec, real snippetz generation)', () => {
     expect(op).not.toBeNull();
     if (!op) return;
 
-    const html = renderToStaticMarkup(<CodeSamples operation={op} servers={model.servers} />);
+    const html = await renderAsync(<CodeSamples operation={op} servers={model.servers} />);
 
-    // cURL: real substituted path param (not a literal "{name}"), real host.
-    // No explicit -X GET — curl defaults to GET, and snippetz correctly omits it.
+    // Real substituted path param (not a literal "{name}"), real host — each
+    // as a real, syntax-highlighted <span> now (shiki breaks a line into
+    // per-token spans), not one contiguous run, so check the meaningful
+    // pieces rather than one exact string.
     expect(html).toContain('cURL');
-    expect(html).toContain('curl https://pokeapi.co/api/v2/pokemon/pikachu');
+    expect(html).toContain('pokeapi.co');
+    expect(html).toContain('pikachu');
     expect(html).not.toContain('{name}');
+    // Real shiki output, not a plain-text fallback.
+    expect(html).toContain('class="shiki');
 
     // JavaScript fetch and Python requests both present with real syntax.
     expect(html).toContain('JavaScript');
-    expect(html).toMatch(/fetch\(/);
+    expect(html).toMatch(/fetch/);
     expect(html).toContain('Python');
-    expect(html).toMatch(/requests\.get/);
+    expect(html).toMatch(/requests/);
     expect(html).toContain('Node.js');
   });
 
@@ -52,8 +73,8 @@ describe('CodeSamples (real pokeapi spec, real snippetz generation)', () => {
       security: [],
     };
 
-    const html = renderToStaticMarkup(<CodeSamples operation={op} servers={[{ url: 'https://api.example.com' }]} />);
+    const html = await renderAsync(<CodeSamples operation={op} servers={[{ url: 'https://api.example.com' }]} />);
     expect(html).toContain('Gizmo');
-    expect(html).toMatch(/-X POST|--request POST/);
+    expect(html).toMatch(/POST/);
   });
 });
diff --git a/packages/framework/src/openapi-render/CodeSamples.tsx b/packages/framework/src/openapi-render/CodeSamples.tsx
index 18629fc..75e2624 100644
--- a/packages/framework/src/openapi-render/CodeSamples.tsx
+++ b/packages/framework/src/openapi-render/CodeSamples.tsx
@@ -13,15 +13,21 @@
 
 import { snippetz } from '@scalar/snippetz';
 import type { ApiOperation, OpenApiServer } from '../openapi';
+import { CodeSamplesPanel } from './CodeSamplesPanel';
+import { highlightCode } from './highlight';
 import { sampleFromSchema } from './sample';
 
-type SampleTarget = { target: 'shell'; client: 'curl'; label: 'cURL' } | { target: 'js'; client: 'fetch'; label: 'JavaScript' } | { target: 'python'; client: 'requests'; label: 'Python' } | { target: 'node'; client: 'fetch'; label: 'Node.js' };
+type SampleTarget =
+  | { target: 'shell'; client: 'curl'; label: 'cURL'; lang: 'bash' }
+  | { target: 'js'; client: 'fetch'; label: 'JavaScript'; lang: 'javascript' }
+  | { target: 'python'; client: 'requests'; label: 'Python'; lang: 'python' }
+  | { target: 'node'; client: 'fetch'; label: 'Node.js'; lang: 'javascript' };
 
 const DEFAULT_TARGETS: SampleTarget[] = [
-  { target: 'shell', client: 'curl', label: 'cURL' },
-  { target: 'js', client: 'fetch', label: 'JavaScript' },
-  { target: 'python', client: 'requests', label: 'Python' },
-  { target: 'node', client: 'fetch', label: 'Node.js' },
+  { target: 'shell', client: 'curl', label: 'cURL', lang: 'bash' },
+  { target: 'js', client: 'fetch', label: 'JavaScript', lang: 'javascript' },
+  { target: 'python', client: 'requests', label: 'Python', lang: 'python' },
+  { target: 'node', client: 'fetch', label: 'Node.js', lang: 'javascript' },
 ];
 
 function buildHarRequest(operation: ApiOperation, serverUrl: string) {
@@ -65,7 +71,7 @@ function buildHarRequest(operation: ApiOperation, serverUrl: string) {
   return request;
 }
 
-export function CodeSamples({
+export async function CodeSamples({
   operation,
   servers,
   baseUrl,
@@ -78,22 +84,17 @@ export function CodeSamples({
   const request = buildHarRequest(operation, serverUrl);
   const generator = snippetz();
 
-  return (
-    <div className="fw-apiref-rail">
-      {DEFAULT_TARGETS.map(({ target, client, label }) => {
-        const code = generator.hasPlugin(target, client) ? generator.print(target, client, request) : undefined;
-        if (!code) return null;
-        return (
-          <div key={`${target}/${client}`} className="fw-apiref-sample-block">
-            <div className="fw-apiref-sample-header">
-              <span className="fw-apiref-sample-lang">{label}</span>
-            </div>
-            <pre className="fw-apiref-curl">
-              <code>{code}</code>
-            </pre>
-          </div>
-        );
-      })}
-    </div>
+  const samples = await Promise.all(
+    DEFAULT_TARGETS.map(async ({ target, client, label, lang }) => {
+      const code = generator.hasPlugin(target, client) ? generator.print(target, client, request) : undefined;
+      if (!code) return null;
+      const html = await highlightCode(code, lang);
+      return { label, lang: `${target}/${client}`, code, html };
+    }),
   );
+
+  const real = samples.filter((s): s is NonNullable<typeof s> => s !== null);
+  if (real.length === 0) return null;
+
+  return <CodeSamplesPanel samples={real} />;
 }
diff --git a/packages/framework/src/openapi-render/CodeSamplesPanel.tsx b/packages/framework/src/openapi-render/CodeSamplesPanel.tsx
new file mode 100644
index 0000000..43040c2
--- /dev/null
+++ b/packages/framework/src/openapi-render/CodeSamplesPanel.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import * as React from 'react';
+
+export interface CodeSample {
+  label: string;
+  lang: string;
+  /** Raw, unhighlighted source — what "Copy" actually copies. */
+  code: string;
+  /** shiki-highlighted HTML — what's actually displayed. */
+  html: string;
+}
+
+/**
+ * One card, one visible sample at a time, switched via a <select> — matches
+ * the reference layout (a single "cURL ▾" panel, not four stacked always-
+ * visible blocks). All samples render into the DOM simultaneously (only
+ * `hidden` toggles) rather than conditionally mounting just the selected
+ * one — this is a 'use client' island, but the page around it is still
+ * SSG; mounting only the active sample would mean the other 3 languages'
+ * code exists nowhere in the static HTML at all (invisible to Pagefind, to
+ * no-JS clients, to view-source) purely as a side effect of how the
+ * switcher is implemented, not anything the reference design calls for.
+ * `html` is shiki output generated server-side in CodeSamples.tsx (trusted,
+ * not user input) — dangerouslySetInnerHTML is the only way to render
+ * pre-highlighted markup without re-parsing it client-side.
+ */
+export function CodeSamplesPanel({ samples }: { samples: CodeSample[] }) {
+  const [index, setIndex] = React.useState(0);
+  const [copied, setCopied] = React.useState(false);
+  const active = samples[index];
+  if (!active) return null;
+
+  async function handleCopy() {
+    try {
+      await navigator.clipboard.writeText(active.code);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // clipboard unavailable — not fatal, just no visual confirmation
+    }
+  }
+
+  return (
+    <div className="fw-apiref-sample-block">
+      <div className="fw-apiref-sample-header">
+        <select
+          className="fw-apiref-sample-select"
+          value={index}
+          onChange={(e) => setIndex(Number(e.target.value))}
+          aria-label="Code sample language"
+        >
+          {samples.map((s, i) => (
+            <option key={s.lang} value={i}>
+              {s.label}
+            </option>
+          ))}
+        </select>
+        <button type="button" className="fw-apiref-sample-copy" onClick={() => void handleCopy()} aria-label="Copy code">
+          {copied ? 'Copied' : 'Copy'}
+        </button>
+      </div>
+      {samples.map((s, i) => (
+        <div
+          key={s.lang}
+          className="fw-apiref-sample-code"
+          hidden={i !== index}
+          dangerouslySetInnerHTML={{ __html: s.html }}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/packages/framework/src/openapi-render/OperationPage.test.tsx b/packages/framework/src/openapi-render/OperationPage.test.tsx
index f6254a1..56c2dbe 100644
--- a/packages/framework/src/openapi-render/OperationPage.test.tsx
+++ b/packages/framework/src/openapi-render/OperationPage.test.tsx
@@ -1,7 +1,8 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderToStaticMarkup } from 'react-dom/server';
+import type { ReactElement } from 'react';
+import { renderToReadableStream } from 'react-dom/server';
 import { describe, expect, it } from 'vitest';
 import { findOperation, parseOpenApi } from '../openapi';
 import { OperationPage } from './OperationPage';
@@ -9,6 +10,21 @@ import { OperationPage } from './OperationPage';
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
 const POKEAPI_SPEC = path.join(REPO_ROOT, 'examples', 'pokeapi-docs', 'content', 'docs', 'openapi.json');
 
+/** OperationPage is an async Server Component (shiki highlighting) — renderToStaticMarkup can't render it; this can, and `stream.allReady` ensures highlighting has actually finished before reading. */
+async function renderAsync(node: ReactElement): Promise<string> {
+  const stream = await renderToReadableStream(node);
+  await stream.allReady;
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let html = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    html += decoder.decode(value, { stream: true });
+  }
+  return html;
+}
+
 describe('OperationPage (real pokeapi spec, full composition)', () => {
   it('renders every real operation without crashing, with correct core content', async () => {
     const raw = readFileSync(POKEAPI_SPEC, 'utf-8');
@@ -16,7 +32,7 @@ describe('OperationPage (real pokeapi spec, full composition)', () => {
     expect(model.operations.length).toBeGreaterThan(0);
 
     for (const op of model.operations) {
-      const html = renderToStaticMarkup(<OperationPage operation={op} servers={model.servers} />);
+      const html = await renderAsync(<OperationPage operation={op} servers={model.servers} />);
       expect(html.length).toBeGreaterThan(0);
       expect(html).toContain(op.summary);
       expect(html).toContain(`fw-method-${op.method}`);
@@ -36,7 +52,7 @@ describe('OperationPage (real pokeapi spec, full composition)', () => {
     expect(op).not.toBeNull();
     if (!op) return;
 
-    const html = renderToStaticMarkup(<OperationPage operation={op} servers={model.servers} />);
+    const html = await renderAsync(<OperationPage operation={op} servers={model.servers} />);
 
     // Path Parameters section — the "name" path param.
     expect(html).toContain('Path Parameters');
@@ -64,7 +80,7 @@ describe('OperationPage (real pokeapi spec, full composition)', () => {
     expect(op).not.toBeNull();
     if (!op) return;
 
-    const html = renderToStaticMarkup(<OperationPage operation={op} servers={model.servers} />);
+    const html = await renderAsync(<OperationPage operation={op} servers={model.servers} />);
     expect(html).toContain('damage_relations');
     expect(html).toContain('no_damage_to');
   });
diff --git a/packages/framework/src/openapi-render/OperationPage.tsx b/packages/framework/src/openapi-render/OperationPage.tsx
index 23e76e9..476298d 100644
--- a/packages/framework/src/openapi-render/OperationPage.tsx
+++ b/packages/framework/src/openapi-render/OperationPage.tsx
@@ -16,12 +16,13 @@ import { MethodPill } from './badges';
 import { CodeSamples } from './CodeSamples';
 import { ParamsSection } from './Parameters';
 import { RequestBody } from './RequestBody';
+import { ResponseSamples } from './ResponseSamples';
 import { Responses } from './Responses';
 import { SecuritySchemes } from './SecuritySchemes';
 import { Servers } from './Servers';
 import { TryItConsole } from './TryIt/TryItConsole';
 
-export function OperationPage({
+export async function OperationPage({
   operation,
   servers,
   baseUrl,
@@ -29,7 +30,7 @@ export function OperationPage({
   operation: ApiOperation;
   servers: OpenApiServer[];
   baseUrl?: string;
-}): ReactNode {
+}): Promise<ReactNode> {
   const pathParams = operation.parameters.filter((p) => p.in === 'path');
   const queryParams = operation.parameters.filter((p) => p.in === 'query');
   const headerParams = operation.parameters.filter((p) => p.in === 'header');
@@ -37,7 +38,25 @@ export function OperationPage({
   return (
     <div className="fw-apiref">
       <div className="fw-apiref-header">
-        <div className="fw-apiref-endpoint">
+        {operation.tag ? <p className="fw-apiref-eyebrow">{operation.tag}</p> : null}
+        {operation.deprecated ? <span className="fw-apiref-deprecated">deprecated</span> : null}
+        <div className="fw-apiref-title-row">
+          <h1 className="fw-apiref-title">{operation.summary}</h1>
+        </div>
+        {operation.description ? <p className="fw-apiref-desc">{operation.description}</p> : null}
+
+        {/* One bordered row — method, path, and Try It together, matching
+            the reference layout (previously three separate pieces: a plain
+            .fw-apiref-endpoint row with its own small path badge, and the
+            Try It button off in the title row next to the H1). */}
+        <div
+          className="fw-apiref-endpoint"
+          // Lets search results show this operation's real method pill
+          // (SearchDialog reads Pagefind's per-result `filters.method`) —
+          // distinct from the type:API facet (docs-shell.tsx), which only
+          // says "this is an API page," not which method.
+          data-pagefind-filter={`method:${operation.method.toUpperCase()}`}
+        >
           <MethodPill method={operation.method} />
           {/* data-pagefind-weight boosts exact operationId/path matches (e.g.
               searching "get-pokemon" or "/pokemon/{name}") above pages that
@@ -48,13 +67,8 @@ export function OperationPage({
           <code className="fw-apiref-operation-id" data-pagefind-weight="2">
             {operation.operationId}
           </code>
-          {operation.deprecated ? <span className="fw-apiref-deprecated">deprecated</span> : null}
-        </div>
-        <div className="fw-apiref-title-row">
-          <h1 className="fw-apiref-title">{operation.summary}</h1>
           <TryItConsole operation={operation} servers={servers} />
         </div>
-        {operation.description ? <p className="fw-apiref-desc">{operation.description}</p> : null}
       </div>
 
       <div className="fw-apiref-body-layout">
@@ -68,7 +82,10 @@ export function OperationPage({
           <Responses responses={operation.responses} />
         </div>
 
-        <CodeSamples operation={operation} servers={servers} baseUrl={baseUrl} />
+        <div className="fw-apiref-rail-stack">
+          <CodeSamples operation={operation} servers={servers} baseUrl={baseUrl} />
+          <ResponseSamples responses={operation.responses} />
+        </div>
       </div>
     </div>
   );
diff --git a/packages/framework/src/openapi-render/ResponseSamples.tsx b/packages/framework/src/openapi-render/ResponseSamples.tsx
new file mode 100644
index 0000000..034d217
--- /dev/null
+++ b/packages/framework/src/openapi-render/ResponseSamples.tsx
@@ -0,0 +1,21 @@
+import type { ApiResponse } from '../openapi';
+import { highlightCode } from './highlight';
+import { ResponseSamplesPanel } from './ResponseSamplesPanel';
+import { sampleFromSchema } from './sample';
+
+/** Right-rail counterpart to CodeSamples: one highlighted JSON sample per response status, tab-switched. Lives alongside the request's CodeSamples, not inside the left column's schema docs (see Responses.tsx). */
+export async function ResponseSamples({ responses }: { responses: ApiResponse[] }) {
+  const samples = await Promise.all(
+    responses.map(async (r) => {
+      const sample = sampleFromSchema(r.schema);
+      if (sample == null) return null;
+      const html = await highlightCode(JSON.stringify(sample, null, 2), 'json');
+      return { status: r.status, ok: r.status.startsWith('2'), html };
+    }),
+  );
+
+  const real = samples.filter((s): s is NonNullable<typeof s> => s !== null);
+  if (real.length === 0) return null;
+
+  return <ResponseSamplesPanel samples={real} />;
+}
diff --git a/packages/framework/src/openapi-render/ResponseSamplesPanel.tsx b/packages/framework/src/openapi-render/ResponseSamplesPanel.tsx
new file mode 100644
index 0000000..374175b
--- /dev/null
+++ b/packages/framework/src/openapi-render/ResponseSamplesPanel.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import * as React from 'react';
+
+export interface ResponseSample {
+  status: string;
+  ok: boolean;
+  html: string;
+}
+
+/**
+ * Status-code tabs over one highlighted JSON sample at a time — mirrors
+ * CodeSamplesPanel's card, tabs instead of a language <select>. Same
+ * all-samples-render-just-hidden approach as CodeSamplesPanel — every
+ * status's real sample stays in the static HTML, not just whichever tab
+ * happened to be active.
+ */
+export function ResponseSamplesPanel({ samples }: { samples: ResponseSample[] }) {
+  const [index, setIndex] = React.useState(0);
+  const active = samples[index];
+  if (!active) return null;
+
+  return (
+    <div className="fw-apiref-sample-block">
+      <div className="fw-apiref-response-tabs" role="tablist" aria-label="Response status">
+        {samples.map((s, i) => (
+          <button
+            key={s.status}
+            type="button"
+            role="tab"
+            aria-selected={i === index}
+            className={`fw-apiref-response-tab${i === index ? ' fw-apiref-response-tab--active' : ''}${s.ok ? '' : ' fw-apiref-response-tab--err'}`}
+            onClick={() => setIndex(i)}
+          >
+            {s.status}
+          </button>
+        ))}
+      </div>
+      {samples.map((s, i) => (
+        <div
+          key={s.status}
+          className="fw-apiref-sample-code"
+          hidden={i !== index}
+          dangerouslySetInnerHTML={{ __html: s.html }}
+        />
+      ))}
+    </div>
+  );
+}
diff --git a/packages/framework/src/openapi-render/Responses.tsx b/packages/framework/src/openapi-render/Responses.tsx
index 499ad12..81c5a52 100644
--- a/packages/framework/src/openapi-render/Responses.tsx
+++ b/packages/framework/src/openapi-render/Responses.tsx
@@ -7,11 +7,9 @@
 
 import type { ApiResponse } from '../openapi';
 import { Section } from './Parameters';
-import { sampleFromSchema } from './sample';
 import { SchemaFields } from './SchemaObject';
 
 function ResponsePanel({ response }: { response: ApiResponse }) {
-  const sample = sampleFromSchema(response.schema);
   const isOk = response.status.startsWith('2');
 
   return (
@@ -21,18 +19,16 @@ function ResponsePanel({ response }: { response: ApiResponse }) {
         {response.description ? <span className="fw-response-desc">{response.description}</span> : null}
         {response.contentType ? <span className="fw-response-ct">{response.contentType}</span> : null}
       </summary>
-      {response.schema || sample != null ? (
+      {/* The actual JSON sample renders in the right rail (ResponseSamples,
+          alongside the request's CodeSamples) with syntax highlighting and
+          a status-code tab switcher, matching the reference layout — this
+          column stays schema documentation only, not a second copy of the
+          same sample. */}
+      {response.schema?.properties ? (
         <div className="fw-response-body">
-          {response.schema?.properties ? (
-            <div className="fw-response-fields">
-              <SchemaFields schema={response.schema} depth={0} />
-            </div>
-          ) : null}
-          {sample != null ? (
-            <pre className="fw-response-sample">
-              <code>{JSON.stringify(sample, null, 2)}</code>
-            </pre>
-          ) : null}
+          <div className="fw-response-fields">
+            <SchemaFields schema={response.schema} depth={0} />
+          </div>
         </div>
       ) : null}
     </details>
diff --git a/packages/framework/src/openapi-render/TryIt/TryItConsole.tsx b/packages/framework/src/openapi-render/TryIt/TryItConsole.tsx
index c216f26..089df34 100644
--- a/packages/framework/src/openapi-render/TryIt/TryItConsole.tsx
+++ b/packages/framework/src/openapi-render/TryIt/TryItConsole.tsx
@@ -128,6 +128,7 @@ function PlaygroundModal({
         </div>
 
         <div className="fw-playground-body">
+        <div className="fw-playground-form">
           {servers.length > 1 ? (
             <label className="fw-playground-field">
               <span className="fw-playground-label">Server</span>
@@ -267,8 +268,15 @@ function PlaygroundModal({
           <button type="button" className="fw-playground-send" onClick={send} disabled={state === 'loading' || state === 'streaming'}>
             {state === 'loading' ? 'Sending…' : state === 'streaming' ? 'Receiving…' : 'Send Request'}
           </button>
+        </div>
 
-          {result ? <ResponseViewer result={result} streaming={state === 'streaming'} /> : null}
+          <div className="fw-playground-result">
+            {result ? (
+              <ResponseViewer result={result} streaming={state === 'streaming'} />
+            ) : (
+              <p className="fw-playground-result-placeholder">Send a request to see the response here.</p>
+            )}
+          </div>
         </div>
       </div>
     </div>
diff --git a/packages/framework/src/openapi-render/highlight.ts b/packages/framework/src/openapi-render/highlight.ts
new file mode 100644
index 0000000..cecfb6a
--- /dev/null
+++ b/packages/framework/src/openapi-render/highlight.ts
@@ -0,0 +1,33 @@
+/**
+ * Syntax highlighting for the API reference's dynamically-generated code
+ * (request samples, response bodies) — these are plain strings built at
+ * render time from the OpenAPI spec, not static MDX, so the MDX pipeline's
+ * rehype-pretty-code (mdx.tsx) doesn't apply. Uses shiki directly instead,
+ * with the same dual-theme mechanism rehype-pretty-code uses under the hood
+ * (themes: { light, dark }, defaultColor: false -> --shiki-light/-dark CSS
+ * vars per token; see prose.css's `[data-rehype-pretty-code-figure] code
+ * span` rule for the sibling CSS this mirrors) so both stay visually
+ * consistent and both correctly re-tint on theme toggle without JS.
+ *
+ * One highlighter instance, created lazily and cached — shiki's startup
+ * (loading themes/grammars) is real cost, not something to pay per code
+ * block.
+ */
+
+import { getSingletonHighlighter } from 'shiki';
+
+const THEMES = { light: 'github-light', dark: 'github-dark' } as const;
+const LANGS = ['bash', 'javascript', 'python', 'json', 'http'] as const;
+
+/** Highlights `code` as `lang`, returning shiki's HTML (a `<pre class="shiki">...</pre>` tree with per-token --shiki-light/-dark vars). Falls back to escaped plain text if the language isn't loaded or highlighting fails. */
+export async function highlightCode(code: string, lang: string): Promise<string> {
+  try {
+    const highlighter = await getSingletonHighlighter({ themes: [THEMES.light, THEMES.dark], langs: [...LANGS] });
+    const loaded = highlighter.getLoadedLanguages();
+    const safeLang = loaded.includes(lang) ? lang : 'text';
+    return highlighter.codeToHtml(code, { lang: safeLang, themes: THEMES, defaultColor: false });
+  } catch {
+    const escaped = code.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<pre class="shiki"><code>${escaped}</code></pre>`;
+  }
+}
diff --git a/packages/framework/src/pagefind-highlight-mount.tsx b/packages/framework/src/pagefind-highlight-mount.tsx
index 464c108..405da1c 100644
--- a/packages/framework/src/pagefind-highlight-mount.tsx
+++ b/packages/framework/src/pagefind-highlight-mount.tsx
@@ -4,11 +4,17 @@ import * as React from 'react';
 
 /**
  * Mounted once by <DocsShell> on every content page. On load, if the URL
- * carries `?q=` (repeated, one value per word — see search-dialog.tsx), highlights
- * each word within the page's `[data-pagefind-body]` region using Pagefind's
- * own generated pagefind-highlight.js (mark.js under the hood) and scrolls to
- * the first match. This is the Mintlify-style "land on the highlighted
- * result" behavior.
+ * carries `?highlight=` (repeated, one value per word — see
+ * search-dialog.tsx), highlights each word within the page's
+ * `[data-pagefind-body]` region using Pagefind's own generated
+ * pagefind-highlight.js (mark.js under the hood) and scrolls to the first
+ * match. This is the Mintlify-style "land on the highlighted result"
+ * behavior.
+ *
+ * Deliberately a different param than SearchDialog's own `?q=` (which
+ * re-opens the dialog itself on mount) — they used to share `?q=`, so
+ * clicking a search result carried it to the destination page, whose own
+ * SearchDialog then saw `?q=` on load and re-opened itself every time.
  *
  * Degrades silently (no highlight, no error) if the script is missing — same
  * postbuild-dependent availability as the search dialog itself.
@@ -52,14 +58,14 @@ export function PagefindHighlightMount() {
   React.useEffect(() => {
     if (typeof window === 'undefined') return;
     const params = new URLSearchParams(window.location.search);
-    if (!params.has('q')) return;
+    if (!params.has('highlight')) return;
 
     let cancelled = false;
     (async () => {
       const PagefindHighlight = await loadPagefindHighlightCtor();
       if (cancelled || !PagefindHighlight) return;
       new PagefindHighlight({
-        highlightParam: 'q',
+        highlightParam: 'highlight',
         addStyles: false, // we style .fw-search-highlight ourselves (widgets.css) — Pagefind's default is inline yellow
         markOptions: {
           className: 'fw-search-highlight',
diff --git a/packages/framework/src/search-dialog.tsx b/packages/framework/src/search-dialog.tsx
index 057fd90..9421794 100644
--- a/packages/framework/src/search-dialog.tsx
+++ b/packages/framework/src/search-dialog.tsx
@@ -22,7 +22,13 @@ import * as React from 'react';
 
 type PagefindSearchResult = {
   id: string;
-  data: () => Promise<{ url: string; meta: { title?: string }; excerpt: string }>;
+  data: () => Promise<{
+    url: string;
+    meta: { title?: string };
+    excerpt: string;
+    /** Populated from data-pagefind-filter attributes (docs-shell.tsx's type:*, OperationPage.tsx's method:*). */
+    filters: Record<string, string[]>;
+  }>;
 };
 
 type PagefindModule = {
@@ -30,9 +36,18 @@ type PagefindModule = {
   search: (query: string) => Promise<{ results: PagefindSearchResult[] }>;
 };
 
-type Result = { url: string; title: string; excerpt: string };
+type Result = { url: string; title: string; excerpt: string; method?: string };
 
 const QUERY_PARAM = 'q';
+// Separate from QUERY_PARAM deliberately: QUERY_PARAM re-opens the dialog
+// itself on mount (a shareable "deep link into a search-in-progress").
+// HIGHLIGHT_PARAM only tells PagefindHighlightMount which words to
+// highlight on a destination page. They used to be the same `?q=` param —
+// clicking a result carried it to the destination, whose own SearchDialog
+// then saw `?q=` on mount and re-opened itself, every time, with no way to
+// dismiss it short of clearing the query first (which finally emptied the
+// URL param). Two params, two independent behaviors, bug gone.
+const HIGHLIGHT_PARAM = 'highlight';
 
 let pagefindPromise: Promise<PagefindModule | null> | null = null;
 
@@ -97,11 +112,11 @@ function syncQueryParam(value: string) {
   window.history.replaceState(window.history.state, '', url.toString());
 }
 
-/** Builds a destination URL carrying the query for PagefindHighlightMount to pick up. */
+/** Builds a destination URL carrying the query under HIGHLIGHT_PARAM for PagefindHighlightMount to pick up — not QUERY_PARAM, so landing on the destination doesn't also re-open the dialog. */
 function withQueryParam(url: string, value: string): string {
   const dest = new URL(url, typeof window === 'undefined' ? 'http://localhost' : window.location.origin);
-  dest.searchParams.delete(QUERY_PARAM);
-  for (const w of wordsFromQuery(value)) dest.searchParams.append(QUERY_PARAM, w);
+  dest.searchParams.delete(HIGHLIGHT_PARAM);
+  for (const w of wordsFromQuery(value)) dest.searchParams.append(HIGHLIGHT_PARAM, w);
   return dest.pathname + dest.search + dest.hash;
 }
 
@@ -168,7 +183,14 @@ export function SearchDialog({
       if (cancelled) return;
       const data = await Promise.all(hits.slice(0, 12).map((r) => r.data()));
       if (cancelled) return;
-      setResults(data.map((d) => ({ url: d.url, title: d.meta.title ?? d.url, excerpt: d.excerpt })));
+      setResults(
+        data.map((d) => ({
+          url: d.url,
+          title: d.meta.title ?? d.url,
+          excerpt: d.excerpt,
+          method: d.filters?.method?.[0],
+        })),
+      );
     }, 120);
 
     return () => {
@@ -230,7 +252,10 @@ export function SearchDialog({
                         goTo(r.url);
                       }}
                     >
-                      <span className="fw-search-result-title">{r.title}</span>
+                      <span className="fw-search-result-title">
+                        {r.method ? <span className={`fw-method-pill fw-method-${r.method.toLowerCase()}`}>{r.method}</span> : null}
+                        {r.title}
+                      </span>
                       {/* Pagefind's own excerpt already wraps matches in <mark> — safe, generated
                           from our own indexed content, not user input. */}
                       <span className="fw-search-result-excerpt" dangerouslySetInnerHTML={{ __html: r.excerpt }} />
diff --git a/packages/framework/src/shell-client.tsx b/packages/framework/src/shell-client.tsx
index e9c8409..91b86dc 100644
--- a/packages/framework/src/shell-client.tsx
+++ b/packages/framework/src/shell-client.tsx
@@ -16,8 +16,27 @@ export interface TocHeading {
 /**
  * Thin client wrapper used by DocsShell to toggle the mobile sidebar drawer.
  * The sidebar content is passed as children so the server can render it.
+ *
+ * `nav`/`cta` are DocsShell's own `topNav`/`cta` slots, rendered a second
+ * time here (above the sidebar tree, styled as a vertical stack by
+ * .fw-drawer-nav in layout.css) — not a mobile-specific nav authored
+ * separately. The header's own copies of these get hidden past a width
+ * (layout.css, scoped to .fw-shell-header) to avoid overflow in the
+ * cramped mobile header row; without a second copy somewhere, that CSS
+ * would just delete them from reach entirely on mobile, which is exactly
+ * the bug this fixes. `topActions` (search, AI assistant) is deliberately
+ * NOT duplicated here — those are stateful widgets, not links, and
+ * mounting two independent copies would be confusing rather than helpful.
  */
-export function MobileSidebarToggle({ children }: { children: React.ReactNode }) {
+export function MobileSidebarToggle({
+  nav,
+  cta,
+  children,
+}: {
+  nav?: React.ReactNode;
+  cta?: React.ReactNode;
+  children: React.ReactNode;
+}) {
   const [open, setOpen] = React.useState(false);
 
   React.useEffect(() => {
@@ -60,6 +79,12 @@ export function MobileSidebarToggle({ children }: { children: React.ReactNode })
 
       {/* Drawer */}
       <div className={`fw-sidebar-drawer${open ? ' fw-sidebar-drawer--open' : ''}`} aria-hidden={!open}>
+        {nav || cta ? (
+          <nav className="fw-drawer-nav" aria-label="Primary">
+            {nav}
+            {cta}
+          </nav>
+        ) : null}
         {children}
       </div>
     </>
diff --git a/packages/framework/src/styles/api.css b/packages/framework/src/styles/api.css
index e6f73b7..aed651d 100644
--- a/packages/framework/src/styles/api.css
+++ b/packages/framework/src/styles/api.css
@@ -56,37 +56,46 @@
   display: flex;
   flex-direction: column;
   gap: 0;
+  /* 60/40 docs:rail split, shared by the header below (title/desc/endpoint
+     row) and the body grid's left column further down, so both stay
+     left- AND right-aligned with each other. A real percentage of
+     whatever width .fw-shell-content actually ends up with (not a fixed
+     rem value) — 60% minus this column's share of the 3rem gap, which is
+     exactly what a `3fr` track in a `3fr 2fr` grid with a 3rem gap would
+     resolve to; expressed this way (rather than fr units) because it also
+     has to work as a plain max-width on .fw-apiref-header, which isn't a
+     grid item. The body grid's rail column is plain `1fr`, which — once
+     this fixed-and-percentage first column is subtracted, gap included —
+     lands on exactly the remaining 40% on its own; no matching calc()
+     needed there. */
+  --fw-apiref-docs-w: calc(60% - 1.8rem);
+}
+
+/* .fw-shell-content's own max-width (layout.css) is the right measure for
+   plain prose pages, but on an operation page it wastes exactly the width
+   .fw-shell-main already reclaimed from the hidden TOC column (hideToc's
+   .fw-shell--no-toc removes the TOC's own reserved space, but
+   .fw-shell-content's cap doesn't know that and clamps straight back down
+   to prose measure) — freed here so the rail can use it instead of it
+   sitting empty on both sides. Scoped to :has(.fw-apiref-body-layout), not
+   just "any API-reference-tab page", so the tab's own overview page (title
+   + description only, no rail to fill the extra width) is unaffected. */
+.fw-shell-content:has(.fw-apiref-body-layout) {
+  max-width: none;
 }
 
 /* ── Endpoint header ─────────────────────────────────────────── */
 
 .fw-apiref-header {
-  padding: 1.5rem 0 1.5rem;
-  border-bottom: 1px solid var(--fw-border);
-  margin-bottom: 2rem;
+  padding: 1.5rem 0 2rem;
+  max-width: var(--fw-apiref-docs-w);
 }
 
-.fw-apiref-endpoint {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  margin-bottom: 0.75rem;
-}
-
-.fw-apiref-path {
-  font-family: var(--fw-mono);
-  font-size: 0.9375rem;
-  color: var(--fw-fg);
-  background: var(--fw-code-bg);
-  padding: 0.2em 0.5em;
-  border-radius: var(--fw-radius-sm);
-  word-break: break-all;
-}
-
-.fw-apiref-operation-id {
-  font-family: var(--fw-mono);
+.fw-apiref-eyebrow {
   font-size: 0.8125rem;
-  color: var(--fw-muted);
+  font-weight: 600;
+  color: var(--fw-primary);
+  margin: 0 0 0.5rem;
 }
 
 .fw-apiref-deprecated {
@@ -100,6 +109,7 @@
   border: 1px solid var(--fw-method-delete);
   border-radius: var(--fw-radius-sm);
   opacity: 0.8;
+  margin-bottom: 0.5rem;
 }
 
 .fw-apiref-title-row {
@@ -123,14 +133,46 @@
   color: var(--fw-muted);
   font-size: 0.9375rem;
   line-height: 1.6;
-  margin: 0;
+  margin: 0 0 1.5rem;
+}
+
+/* Method + path + Try It — one bordered row, not three separate pieces. */
+.fw-apiref-endpoint {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  padding: 0.625rem 0.625rem 0.625rem 0.875rem;
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius);
+  background: var(--fw-bg-subtle);
+}
+
+.fw-apiref-path {
+  font-family: var(--fw-mono);
+  font-size: 0.9375rem;
+  color: var(--fw-fg);
+  word-break: break-all;
+}
+
+.fw-apiref-operation-id {
+  font-family: var(--fw-mono);
+  font-size: 0.75rem;
+  color: var(--fw-muted);
+}
+
+.fw-apiref-endpoint .fw-apiref-tryit {
+  margin-left: auto;
 }
 
 /* ── Two-column body layout ──────────────────────────────────── */
 
 .fw-apiref-body-layout {
   display: grid;
-  grid-template-columns: 1fr var(--fw-toc-w, 22rem);
+  /* Docs column fixed at the same measure as the header above it (not 1fr)
+     — the rail is the flexible one now, so it's what actually absorbs the
+     width .fw-shell-content just released, instead of both columns
+     growing and the docs column silently getting wider than before. */
+  grid-template-columns: var(--fw-apiref-docs-w) 1fr;
   gap: 3rem;
   align-items: start;
 }
@@ -156,11 +198,9 @@
 }
 
 .fw-apiref-section-title {
-  font-size: 0.8125rem;
+  font-size: 1.125rem;
   font-weight: 700;
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-  color: var(--fw-muted);
+  color: var(--fw-fg);
   margin: 0 0 1rem;
 }
 
@@ -233,9 +273,15 @@
 }
 
 .fw-param-type {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.1em 0.4em;
   font-family: var(--fw-mono);
   font-size: 0.75rem;
   color: var(--fw-muted);
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
 }
 
 .fw-param-required {
@@ -247,6 +293,7 @@
   letter-spacing: 0.05em;
   text-transform: uppercase;
   color: var(--fw-method-delete);
+  background: color-mix(in srgb, var(--fw-method-delete) 10%, transparent);
   border: 1px solid var(--fw-method-delete);
   border-radius: var(--fw-radius-sm);
 }
@@ -456,12 +503,12 @@
 
 /* ── Right rail ──────────────────────────────────────────────── */
 
-.fw-apiref-rail {
+.fw-apiref-rail-stack {
   position: sticky;
   top: calc(var(--fw-header-h) + 1.5rem);
   display: flex;
   flex-direction: column;
-  gap: 1rem;
+  gap: 1.25rem;
 }
 
 .fw-apiref-sample-block {
@@ -474,45 +521,90 @@
 .fw-apiref-sample-header {
   display: flex;
   align-items: center;
+  justify-content: space-between;
   gap: 0.5rem;
-  padding: 0.5rem 0.875rem;
+  padding: 0.5rem 0.625rem 0.5rem 0.875rem;
   background: var(--fw-card);
   border-bottom: 1px solid var(--fw-border);
 }
 
-.fw-apiref-sample-lang {
+.fw-apiref-sample-select {
+  border: none;
+  background: none;
+  color: var(--fw-fg);
   font-size: 0.75rem;
   font-weight: 600;
+  padding: 0.2rem 0;
+  cursor: pointer;
+}
+
+.fw-apiref-sample-copy {
+  border: none;
+  background: none;
   color: var(--fw-muted);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
+  font-size: 0.75rem;
+  padding: 0.2rem 0.5rem;
+  border-radius: var(--fw-radius-sm);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+.fw-apiref-sample-copy:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
 }
 
-.fw-apiref-curl {
+/* shiki's own output (highlight.ts) — .shiki sets its own background-color
+   + --shiki-dark-bg inline (its dual-theme convention); overridden here so
+   the code area matches --fw-code-bg exactly instead of shiki's raw github
+   theme background, keeping one continuous surface with the header above.
+   Per-token color follows the same --shiki-light/-dark toggle prose.css
+   already uses for regular MDX code blocks (rehype-pretty-code) — same
+   mechanism, different selector, so both stay visually consistent. */
+.fw-apiref-sample-code pre.shiki {
   margin: 0;
   padding: 1rem;
   font-family: var(--fw-mono);
   font-size: 0.78125rem;
   line-height: 1.65;
   overflow-x: auto;
-  color: var(--fw-fg);
-  white-space: pre;
+  background-color: var(--fw-code-bg) !important;
+}
+.fw-apiref-sample-code pre.shiki code span {
+  color: var(--shiki-light);
+}
+html.dark .fw-apiref-sample-code pre.shiki code span {
+  color: var(--shiki-dark);
 }
 
-.fw-apiref-response-sample {
+/* ── Response status tabs (right rail) ───────────────────────── */
+
+.fw-apiref-response-tabs {
   display: flex;
-  flex-direction: column;
-  gap: 0;
+  align-items: center;
+  gap: 1rem;
+  padding: 0.625rem 0.875rem;
+  background: var(--fw-card);
+  border-bottom: 1px solid var(--fw-border);
 }
 
-.fw-apiref-status-badge {
-  display: inline-flex;
-  align-items: center;
-  padding: 0.25rem 0.75rem;
+.fw-apiref-response-tab {
+  border: none;
+  background: none;
+  padding: 0.2rem 0;
   font-family: var(--fw-mono);
-  font-size: 0.75rem;
-  font-weight: 700;
-  border-bottom: 1px solid var(--fw-border);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--fw-muted);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+}
+.fw-apiref-response-tab--active {
+  color: var(--fw-method-get-text);
+  border-bottom-color: var(--fw-method-get);
+}
+.fw-apiref-response-tab--err.fw-apiref-response-tab--active {
+  color: var(--fw-method-delete-text);
+  border-bottom-color: var(--fw-method-delete);
 }
 
 .fw-apiref-status-ok  { color: var(--fw-method-get); background: color-mix(in srgb, var(--fw-method-get) 14%, transparent); }
@@ -535,7 +627,10 @@
   align-items: center;
   gap: 0.4rem;
   padding: 0.35em 0.9em;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
@@ -559,20 +654,27 @@
    API PLAYGROUND MODAL
 ═══════════════════════════════════════════════════════════════ */
 
+/* A panel that drops down from the header, not a full-height sidebar —
+   position: fixed and top-anchored (not tied to scroll position within the
+   page), full page width up to a max, rounded BOTTOM corners only (flush
+   against the header above it), page content stays fully visible around
+   and below it (no dimming backdrop — the backdrop element is kept only
+   as an invisible click-outside-to-close catcher). */
 .fw-playground-overlay {
   position: fixed;
-  inset: 0;
+  top: var(--fw-header-h);
+  left: 0;
+  right: 0;
+  bottom: 0;
   z-index: 50;
   display: flex;
-  align-items: stretch;
-  justify-content: flex-end;
+  justify-content: center;
 }
 
 .fw-playground-backdrop {
   position: absolute;
   inset: 0;
-  background: rgba(11, 15, 23, 0.5);
-  backdrop-filter: blur(2px);
+  background: transparent;
 }
 
 .fw-playground-panel {
@@ -580,10 +682,14 @@
   z-index: 1;
   display: flex;
   flex-direction: column;
-  width: min(42rem, 90vw);
-  height: 100%;
+  width: 100%;
+  max-width: 90rem;
+  max-height: calc(100vh - var(--fw-header-h) - 2rem);
+  margin: 0 1.5rem;
   background: var(--fw-bg);
-  border-left: 1px solid var(--fw-border);
+  border: 1px solid var(--fw-border);
+  border-top: none;
+  border-radius: 0 0 var(--fw-radius) var(--fw-radius);
   box-shadow: var(--fw-shadow-lg);
   overflow: hidden;
 }
@@ -640,15 +746,73 @@
   background: var(--fw-card-hover);
 }
 
+/* Slim, token-colored scrollbars for small scrollable surfaces (code
+   blocks, the Try It panel body) instead of the browser's chunky default.
+   scrollbar-width/-color covers Firefox and current Chromium; the
+   ::-webkit-scrollbar rules cover Safari and older Chromium, which ignore
+   those properties entirely. */
+.fw-playground-body,
+.fw-apiref-sample-code pre.shiki {
+  scrollbar-width: thin;
+  scrollbar-color: var(--fw-border-strong) transparent;
+}
+.fw-playground-body::-webkit-scrollbar,
+.fw-apiref-sample-code pre.shiki::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+.fw-playground-body::-webkit-scrollbar-track,
+.fw-apiref-sample-code pre.shiki::-webkit-scrollbar-track {
+  background: transparent;
+}
+.fw-playground-body::-webkit-scrollbar-thumb,
+.fw-apiref-sample-code pre.shiki::-webkit-scrollbar-thumb {
+  background-color: var(--fw-border-strong);
+  border-radius: 999px;
+  border: 2px solid transparent;
+  background-clip: padding-box;
+}
+.fw-playground-body::-webkit-scrollbar-thumb:hover,
+.fw-apiref-sample-code pre.shiki::-webkit-scrollbar-thumb:hover {
+  background-color: var(--fw-muted);
+}
+
+/* Two columns — request form on the left, response on the right — matching
+   the reference's wide layout, rather than one narrow stacked column. */
 .fw-playground-body {
   flex: 1;
   overflow-y: auto;
   padding: 1.25rem;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1.5rem;
+}
+
+.fw-playground-form {
   display: flex;
   flex-direction: column;
   gap: 1rem;
-  scrollbar-width: thin;
-  scrollbar-color: var(--fw-border) transparent;
+  min-width: 0;
+}
+
+.fw-playground-result {
+  min-width: 0;
+}
+
+.fw-playground-result-placeholder {
+  color: var(--fw-muted);
+  font-size: 0.875rem;
+  margin: 0;
+  padding: 1rem;
+  border: 1px dashed var(--fw-border);
+  border-radius: var(--fw-radius);
+  text-align: center;
+}
+
+@media (max-width: 48rem) {
+  .fw-playground-body {
+    grid-template-columns: 1fr;
+  }
 }
 
 /* Form fields */
@@ -764,7 +928,10 @@
 .fw-playground-send {
   width: 100%;
   padding: 0.6rem 1rem;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
@@ -820,11 +987,19 @@
 /* ── Responsive ──────────────────────────────────────────────── */
 
 @media (max-width: 80rem) {
+  /* Header's fixed docs-measure only makes sense stacked next to a
+     same-width docs column — once body-layout below goes full-width
+     single-column (next rule), the header needs to match or it reads as
+     narrower than everything under it. */
+  .fw-apiref-header {
+    max-width: none;
+  }
+
   .fw-apiref-body-layout {
     grid-template-columns: 1fr;
   }
 
-  .fw-apiref-rail {
+  .fw-apiref-rail-stack {
     position: static;
     order: -1; /* Show code samples above docs on narrow screens */
   }
@@ -833,14 +1008,8 @@
 @media (max-width: 40rem) {
   .fw-playground-panel {
     /* Not 100vw: that includes the scrollbar gutter on most desktop
-       browsers, overflowing the actual viewport. The parent overlay is
-       already `position: fixed; inset: 0`, so 100% of it is exactly right. */
-    width: 100%;
-    border-left: none;
-    border-top: 1px solid var(--fw-border);
-  }
-
-  .fw-playground-overlay {
-    align-items: flex-end;
+       browsers, overflowing the actual viewport. */
+    margin: 0 0.75rem;
+    max-height: calc(100vh - var(--fw-header-h) - 1rem);
   }
 }
diff --git a/packages/framework/src/styles/components.css b/packages/framework/src/styles/components.css
index a15961c..a47ce37 100644
--- a/packages/framework/src/styles/components.css
+++ b/packages/framework/src/styles/components.css
@@ -122,6 +122,16 @@ html.dark {
   text-decoration: none;
   color: inherit;
 }
+/* .fw-prose a's underline (prose.css) has higher specificity than the rule
+   above alone (.fw-prose + type-selector a beats one class) — Cards are
+   meant to be used inside MDX prose content, so without this, every card
+   title/body rendered as a real link inside a doc page prose block showed
+   a stray link-underline that had nothing to do with the card being a link
+   (found while building Birch: a real rendering bug, not a false alarm —
+   confirmed by checking specificity, not just eyeballing it). */
+.fw-prose a.fw-card-link {
+  text-decoration: none;
+}
 .fw-card-link:hover .fw-card {
   background: var(--fw-card-hover);
   box-shadow: var(--fw-shadow-lg, var(--fw-shadow));
@@ -270,7 +280,10 @@ html.dark {
   width: 2.1em;
   height: 2.1em;
   border-radius: var(--fw-radius-sm);
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   font-size: 0.82rem;
   font-weight: 700;
@@ -506,10 +519,19 @@ html.dark {
 }
 
 /* ===========================================================================
- * PARAM FIELD  (.fw-param, .fw-param-*)
+ * PARAM FIELD (inline MDX shortcode — ParamField/ResponseField in
+ * components.tsx)  (.fw-mdx-param, .fw-mdx-param-*)
+ *
+ * Namespaced fw-mdx-param-* (not fw-param-*) deliberately: openapi-render's
+ * full-page ParamsSection (api.css) used to share these exact class names.
+ * Since neither rule declared every property the other did, the browser
+ * merged them instead of one cleanly overriding the other — the full-page
+ * param rows were silently inheriting this widget's pill/badge treatment.
+ * Two unrelated components must never share a class name; see api.css's
+ * .fw-param-type/.fw-param-required for the full-page side of this fix.
  * =========================================================================*/
 
-.fw-param {
+.fw-mdx-param {
   border: 1px solid var(--fw-border);
   border-radius: var(--fw-radius);
   padding: 0.8em 1em;
@@ -517,17 +539,17 @@ html.dark {
   font-size: 0.88rem;
   transition: border-color 0.12s;
 }
-.fw-param:hover { border-color: var(--fw-border-strong); }
-.fw-param--deprecated { opacity: 0.55; }
+.fw-mdx-param:hover { border-color: var(--fw-border-strong); }
+.fw-mdx-param--deprecated { opacity: 0.55; }
 
-.fw-param-header {
+.fw-mdx-param-header {
   display: flex;
   align-items: center;
   gap: 0.45em;
   flex-wrap: wrap;
   margin-bottom: 0.3em;
 }
-.fw-param-name {
+.fw-mdx-param-name {
   font-family: var(--fw-mono);
   font-size: 0.875em;
   font-weight: 600;
@@ -536,11 +558,11 @@ html.dark {
 }
 
 /* Pill tags */
-.fw-param-type,
-.fw-param-location,
-.fw-param-required,
-.fw-param-deprecated,
-.fw-param-default {
+.fw-mdx-param-type,
+.fw-mdx-param-location,
+.fw-mdx-param-required,
+.fw-mdx-param-deprecated,
+.fw-mdx-param-default {
   display: inline-flex;
   align-items: center;
   padding: 0.15em 0.5em;
@@ -550,33 +572,33 @@ html.dark {
   line-height: 1.4;
 }
 
-.fw-param-type {
+.fw-mdx-param-type {
   background: var(--fw-bg-subtle);
   border: 1px solid var(--fw-border);
   color: var(--fw-muted);
   font-family: var(--fw-mono);
 }
 
-.fw-param-location {
+.fw-mdx-param-location {
   background: color-mix(in srgb, var(--fw-primary) 10%, transparent);
   border: 1px solid color-mix(in srgb, var(--fw-primary) 25%, transparent);
   color: var(--fw-primary);
   font-family: var(--fw-mono);
 }
 
-.fw-param-required {
+.fw-mdx-param-required {
   background: color-mix(in srgb, var(--fw-callout-error-hue) 10%, transparent);
   border: 1px solid color-mix(in srgb, var(--fw-callout-error-hue) 25%, transparent);
   color: var(--fw-callout-error-hue);
 }
 
-.fw-param-deprecated {
+.fw-mdx-param-deprecated {
   background: color-mix(in srgb, var(--fw-callout-warning-hue) 10%, transparent);
   border: 1px solid color-mix(in srgb, var(--fw-callout-warning-hue) 25%, transparent);
   color: var(--fw-callout-warning-hue);
 }
 
-.fw-param-default {
+.fw-mdx-param-default {
   color: var(--fw-muted);
   font-style: italic;
   background: transparent;
@@ -584,7 +606,7 @@ html.dark {
   padding: 0;
   font-family: inherit;
 }
-.fw-param-default code {
+.fw-mdx-param-default code {
   font-family: var(--fw-mono);
   background: var(--fw-code-bg);
   border: 1px solid var(--fw-border);
@@ -592,14 +614,14 @@ html.dark {
   padding: 0.1em 0.3em;
 }
 
-.fw-param-body {
+.fw-mdx-param-body {
   font-size: 0.9em;
   color: var(--fw-muted);
   line-height: 1.6;
   margin-top: 0.4em;
 }
-.fw-param-body > *:first-child { margin-top: 0; }
-.fw-param-body > *:last-child { margin-bottom: 0; }
+.fw-mdx-param-body > *:first-child { margin-top: 0; }
+.fw-mdx-param-body > *:last-child { margin-bottom: 0; }
 
 /* ===========================================================================
  * RESPONSE FIELD  (.fw-response-field)
@@ -935,7 +957,10 @@ html.dark {
 
 .fw-subscribe button[type='submit'] {
   padding: 0.55em 1.1em;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
@@ -966,10 +991,19 @@ html.dark {
 }
 
 /* ===========================================================================
- * API REFERENCE (inline)  (.fw-apiref)
+ * API REFERENCE (inline MDX shortcode — ApiReference in components.tsx)
+ * (.fw-mdx-apiref)
+ *
+ * Namespaced fw-mdx-apiref-* (not fw-apiref-*) deliberately: this used to
+ * share its root class with openapi-render's full-page OperationPage
+ * (.fw-apiref in api.css). api.css's .fw-apiref never declared border/
+ * background/margin, so this rule's card treatment was never overridden —
+ * only merged in — and the full-page API reference silently inherited a
+ * boxed-card look it was never designed to have. Two unrelated components
+ * must never share a class name.
  * =========================================================================*/
 
-.fw-apiref {
+.fw-mdx-apiref {
   border: 1px solid var(--fw-border);
   border-radius: var(--fw-radius);
   overflow: hidden;
@@ -977,7 +1011,7 @@ html.dark {
   background: var(--fw-card);
 }
 
-.fw-apiref-head {
+.fw-mdx-apiref-head {
   display: flex;
   align-items: center;
   gap: 0.75em;
@@ -986,21 +1020,14 @@ html.dark {
   border-bottom: 1px solid var(--fw-border);
 }
 
-/* .fw-apiref-method + the .fw-method-* background overrides that used to
-   live here were an exact duplicate of .fw-method-pill + its variants in
-   api.css (which loads after this file in styles.css, so it always won the
-   cascade anyway — this was dead weight, not a live conflict). The inline
-   <ApiReference> component (components.tsx) now uses fw-method-pill
-   directly instead of fw-apiref-method. */
-
-.fw-apiref-path {
+.fw-mdx-apiref-path {
   font-family: var(--fw-mono);
   font-size: 0.875rem;
   color: var(--fw-fg);
   word-break: break-all;
 }
 
-.fw-apiref-note {
+.fw-mdx-apiref-note {
   padding: 0.6em 1em;
   font-size: 0.8rem;
   color: var(--fw-muted);
@@ -1029,7 +1056,10 @@ html.dark {
   display: inline-flex;
   align-items: center;
   padding: 0.25em 0.75em;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border-radius: 999px;
   font-size: 0.78rem;
diff --git a/packages/framework/src/styles/layout.css b/packages/framework/src/styles/layout.css
index 91c4948..1720ada 100644
--- a/packages/framework/src/styles/layout.css
+++ b/packages/framework/src/styles/layout.css
@@ -185,16 +185,73 @@
   letter-spacing: -0.01em;
 }
 
-/* Hide secondary top-nav links on mobile (prevents overflow) — the tab row
-   itself now scrolls (above) rather than needing to hide. */
+/* Hide secondary top-nav links from the HEADER specifically on mobile
+   (prevents overflow in the now-cramped row) — the tab row itself scrolls
+   (above) rather than needing to hide. Scoped to .fw-shell-header, not
+   global: DocsShell also renders topNav (and cta, if given) a second time
+   inside the hamburger drawer — see .fw-drawer-nav below and
+   MobileSidebarToggle in shell-client.tsx — so hiding them here doesn't
+   remove them from reach entirely. It used to: plain display:none with no
+   second copy anywhere meant these links were completely inaccessible on
+   mobile, not just relocated. */
 @media (max-width: 60rem) {
-  .fw-topnav-anchors,
-  .fw-topnav-navlink,
-  .fw-topnav-cta {
+  .fw-shell-header .fw-topnav-anchors,
+  .fw-shell-header .fw-topnav-navlink,
+  .fw-shell-header .fw-topnav-cta {
     display: none;
   }
 }
 
+/* ── Mobile drawer nav ────────────────────────────────────────────────────
+   The drawer copy of topNav/cta (see above) — same tabs/anchors/navlinks/
+   cta markup and classes as the header, restyled here from a horizontal
+   row into a vertical stack of full-width, real-touch-target rows, which
+   is what a drawer actually wants regardless of which theme is active. */
+
+.fw-drawer-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+  padding-bottom: var(--fw-space-4);
+  margin-bottom: var(--fw-space-4);
+  border-bottom: 1px solid var(--fw-border);
+}
+
+.fw-drawer-nav .fw-topnav-tabs,
+.fw-drawer-nav .fw-topnav-anchors {
+  flex-direction: column;
+  align-items: stretch;
+  overflow-x: visible;
+  gap: 0.125rem;
+}
+
+.fw-drawer-nav .fw-topnav-tab,
+.fw-drawer-nav .fw-topnav-anchor,
+.fw-drawer-nav .fw-topnav-navlink {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  min-height: 2.75rem; /* ~44px real touch target, not just a compact header link */
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--fw-radius-sm);
+  font-size: 0.9375rem;
+  white-space: normal;
+}
+
+.fw-drawer-nav .fw-topnav-tab:hover,
+.fw-drawer-nav .fw-topnav-anchor:hover,
+.fw-drawer-nav .fw-topnav-navlink:hover {
+  background: var(--fw-card-hover);
+}
+
+.fw-drawer-nav .fw-topnav-cta {
+  justify-content: center;
+  width: 100%;
+  min-height: 2.75rem;
+  margin-top: 0.375rem;
+  box-sizing: border-box;
+}
+
 /* ── Body (sidebar + main + toc) ────────────────────────────── */
 
 .fw-shell-body {
@@ -439,6 +496,103 @@
 .fw-toc-depth-3 .fw-toc-link { padding-left: 1.5rem; }
 .fw-toc-depth-4 .fw-toc-link { padding-left: 2.25rem; }
 
+/* ═══════════════════════════════════════════════════════════════
+   AI TOOL MENU — right-rail "Copy page / Open in ChatGPT / …" list
+   (see ai-tool-menu.tsx). Sits below TocList inside the same
+   .fw-shell-toc rail; reuses .fw-toc's spacing/type scale so the two
+   read as one continuous rail instead of a bolted-on block.
+═══════════════════════════════════════════════════════════════ */
+
+.fw-aitoolmenu {
+  font-size: 0.8125rem;
+  margin-top: 1.25rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--fw-border);
+}
+
+/* No TocList above it (e.g. a page with no headings) — don't double the rail's top inset. */
+.fw-shell-toc > .fw-aitoolmenu:first-child {
+  margin-top: 0;
+  padding-top: 0;
+  border-top: none;
+}
+
+.fw-aitoolmenu-title {
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.07em;
+  text-transform: uppercase;
+  color: var(--fw-muted);
+  margin: 0 0 0.6rem;
+  padding: 0;
+}
+
+.fw-aitoolmenu-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.125rem;
+}
+
+.fw-aitoolmenu-item {
+  margin: 0;
+}
+
+.fw-aitoolmenu-link {
+  display: flex;
+  align-items: center;
+  gap: 0.55rem;
+  width: 100%;
+  padding: 0.375rem 0;
+  border: none;
+  background: none;
+  color: var(--fw-muted);
+  font: inherit;
+  font-size: 0.8125rem;
+  text-decoration: none;
+  cursor: pointer;
+  transition: color 0.12s ease;
+}
+
+.fw-aitoolmenu-link:hover {
+  color: var(--fw-fg);
+}
+
+.fw-aitoolmenu-link:focus-visible {
+  outline: none;
+  box-shadow: var(--fw-ring);
+  border-radius: var(--fw-radius-sm);
+}
+
+.fw-aitoolmenu-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 15px;
+  height: 15px;
+  color: var(--fw-muted);
+}
+
+.fw-aitoolmenu-link:hover .fw-aitoolmenu-icon {
+  color: var(--fw-primary);
+}
+
+.fw-aitoolmenu-label {
+  flex: 1;
+  text-align: left;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.fw-aitoolmenu-link--copied,
+.fw-aitoolmenu-link--copied .fw-aitoolmenu-icon {
+  color: var(--fw-primary);
+}
+
 /* ═══════════════════════════════════════════════════════════════
    PAGINATION
 ═══════════════════════════════════════════════════════════════ */
diff --git a/packages/framework/src/styles/widgets.css b/packages/framework/src/styles/widgets.css
index 250f895..125c8f4 100644
--- a/packages/framework/src/styles/widgets.css
+++ b/packages/framework/src/styles/widgets.css
@@ -271,7 +271,10 @@
 .fw-comment-compose button {
   align-self: flex-end;
   padding: 0.35rem 0.875rem;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
@@ -386,7 +389,10 @@
 
 .fw-subscribe button {
   padding: 0.5rem 1.125rem;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
@@ -606,7 +612,10 @@
 }
 
 .fw-askai-message--user .fw-askai-message-content {
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border-bottom-right-radius: var(--fw-radius-sm);
 }
@@ -787,7 +796,10 @@
   width: 2.25rem;
   height: 2.25rem;
   flex-shrink: 0;
-  background: var(--fw-primary);
+  /* --fw-primary-cta-bg, not --fw-primary directly — see tokens.css: white
+     --fw-primary-fg text on an un-darkened --fw-primary fails WCAG AA for
+     several themes' light-mode primary (as low as 3.3:1). */
+  background: var(--fw-primary-cta-bg);
   color: var(--fw-primary-fg);
   border: none;
   border-radius: var(--fw-radius-sm);
diff --git a/templates/canopy/.env.example b/templates/canopy/.env.example
new file mode 100644
index 0000000..39cd584
--- /dev/null
+++ b/templates/canopy/.env.example
@@ -0,0 +1,14 @@
+# ── Required ─────────────────────────────────────────────────────────────────
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# ── AI assistant (disabled by default) ───────────────────────────────────────
+# Set to "true" to enable the Ask AI widget in the top bar.
+# The widget is rendered even when disabled; it shows an informational notice.
+NEXT_PUBLIC_DOCS_AI_ENABLED=false
+
+# The following vars only matter when NEXT_PUBLIC_DOCS_AI_ENABLED=true.
+# They are read by the /api/ask route at runtime (server-only, never sent to
+# the browser).
+# DOCS_AI_PROVIDER=anthropic
+# DOCS_AI_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
diff --git a/templates/canopy/.gitignore b/templates/canopy/.gitignore
new file mode 100644
index 0000000..da1f289
--- /dev/null
+++ b/templates/canopy/.gitignore
@@ -0,0 +1,8 @@
+node_modules
+.next
+out
+.env*.local
+.vercel
+*.tsbuildinfo
+.DS_Store
+public/_pagefind
diff --git a/templates/canopy/README.md b/templates/canopy/README.md
new file mode 100644
index 0000000..18ce3cd
--- /dev/null
+++ b/templates/canopy/README.md
@@ -0,0 +1,164 @@
+# Canopy — @inkform/theme-canopy
+
+Canopy is a dark-mode-forward documentation theme built on
+`@inkform/framework` — inspired by Mintlify's Palm starter kit. Vivid lime
+green accent, a centered header search bar, underline tab indicators, no
+header CTA, a whole-sidebar collapse toggle, and a sidebar-footer language +
+theme switcher. Inter throughout, JetBrains Mono for code. It supports
+Guides + API Reference tabs out of the box.
+
+---
+
+## Run locally
+
+```bash
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+If this is a fresh clone, copy the env file first:
+
+```bash
+cp .env.example .env.local
+# Edit NEXT_PUBLIC_SITE_URL if needed, then:
+npm run dev
+```
+
+---
+
+## Add content
+
+All content lives in `content/docs/`.
+
+### Navigation — `content/docs/docs.json`
+
+`docs.json` controls the site name, logo, tabs, and page hierarchy:
+
+```jsonc
+{
+  "name": "Your Docs",
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx" },
+            { "title": "Quickstart",   "slug": "quickstart", "file": "quickstart.mdx" }
+          ]
+        }
+      ]
+    },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+- `slug` is the URL path (empty string = the index `/`).
+- `file` is the MDX file path relative to `content/docs/`.
+- The `openapi` field on a tab points to a JSON/YAML spec file in `content/docs/`.
+- Canopy's header has no CTA button and no extra anchor/nav links by design
+  (matching Palm) — `cta`, `anchors`, and `navbarLinks` are all still
+  supported by the schema and will render if you add them back, they're
+  just omitted from this theme's sample `docs.json`.
+
+### Writing MDX
+
+Add `.mdx` files under `content/docs/` and register them in `docs.json`. Canopy
+supports all built-in blocks: `<Note>`, `<Tip>`, `<Warning>`, `<Card>`,
+`<CardGroup>`, `<Steps>`, `<Step>`, `<Tabs>`, `<Tab>`, `<CodeGroup>`,
+`<Accordion>`, `<ParamField>`, `<Frame>`, and more.
+
+### API Reference
+
+Replace `content/docs/openapi.json` with your own OpenAPI 3.x spec (JSON or
+YAML). The site auto-generates a sidebar and per-operation pages. No extra
+configuration needed — just point the `openapi` tab field at your spec file.
+
+### Blog and Changelog
+
+Both ship wired and ready — `/blog` (list + post pages) and `/changelog`
+(single dated list) render automatically once you add content:
+
+```
+content/
+  blog/
+    my-first-post.mdx    # frontmatter: title, date, author, tags, description
+    series.json          # optional — group posts into a series
+  changelog/
+    2026-01-15-v1.mdx     # frontmatter: title, date, version
+```
+
+Both nav links only appear once at least one entry exists — an empty
+`content/blog`/`content/changelog` (or no folder at all) keeps the top nav
+clean and the pages still render a "no posts yet" state if visited directly.
+
+---
+
+## Maintain
+
+### Slug redirects
+
+When a page's URL changes, record the old → new slug mapping in
+`content/docs/slug-history.json` to issue a 301 redirect:
+
+```json
+{
+  "old-page-slug": "new-page-slug",
+  "essentials/old-name": "essentials/new-name"
+}
+```
+
+### Sidebar collapse + footer
+
+`components/collapsible-sidebar.tsx` is Canopy-specific (not part of the
+shared framework): a single toggle collapses the whole nav column to a thin
+rail and back — real `useState`, not a static arrow — matching what
+palm.mintlify.site actually does (verified directly: its arrow collapses the
+entire sidebar, not one group at a time). `components/sidebar-footer.tsx`
+renders the language label and the system/light/dark theme trio at the
+bottom of the sidebar; the theme trio reads and writes the same
+`localStorage['fw-theme']` + `dark` class the framework's own theme init
+script already uses, so there's no flash on load and no shared-framework
+change was needed to add the third "system" state.
+
+### Ask AI widget
+
+The Ask AI button is built in but **disabled by default**. Enable it by setting
+`NEXT_PUBLIC_DOCS_AI_ENABLED=true` in `.env.local`, plus `DOCS_AI_PROVIDER`
+(`anthropic` | `openai` | `google`, default `anthropic`) and that provider's
+API key (e.g. `ANTHROPIC_API_KEY`) — see `.env.example`. Answers are grounded
+in this site's own content (`@inkform/framework/ai`'s `askDocs()`), not a
+generic chatbot.
+
+---
+
+## Deploy to Vercel
+
+1. Push this directory (or the whole monorepo) to a GitHub repository.
+2. In the Vercel dashboard, click **Add New → Project** and import the repo.
+3. **Framework preset**: Next.js.
+4. **Root directory**: set to the path of this folder if deploying as a
+   standalone (e.g. `templates/canopy`), or leave blank if deploying the
+   directory itself.
+5. Add the environment variable `NEXT_PUBLIC_SITE_URL` (your production URL,
+   e.g. `https://docs.example.com`).
+6. Click **Deploy**.
+
+For a custom domain, go to **Settings → Domains** in your Vercel project and add
+your domain. Vercel handles SSL automatically.
+
+---
+
+## Deploy to AWS Amplify
+
+1. Connect the repo in the Amplify console.
+2. Set the **Build settings** manually if auto-detection picks the wrong preset:
+   - **Build command**: `npm ci && npm run build`
+   - **Output directory**: `.next`
+   - **Framework**: Next.js (SSR)
+3. Add the `NEXT_PUBLIC_SITE_URL` environment variable under
+   **Environment variables**.
+4. Deploy. Amplify Hosting supports Next.js SSR/ISR natively since Gen 2.
diff --git a/templates/canopy/app/[[...slug]]/page.tsx b/templates/canopy/app/[[...slug]]/page.tsx
new file mode 100644
index 0000000..ff89b53
--- /dev/null
+++ b/templates/canopy/app/[[...slug]]/page.tsx
@@ -0,0 +1,66 @@
+import { notFound } from 'next/navigation';
+import { Mdx } from '@inkform/framework/mdx';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { docNeighbours } from '@inkform/framework';
+import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
+import { siteMdxComponents } from '@/mdx-components';
+import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
+import { renderIcon } from '@/lib/icons';
+import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+export function generateStaticParams() {
+  const config = loadDocsConfig();
+  if (!config) return [{ slug: [] as string[] }];
+  const routes = listAllRoutes(config);
+  // Next.js optional catch-all: [] = index, [...rest] = nested. Map [] → undefined
+  // to match the [[...slug]] convention (both work, but undefined is canonical).
+  return routes.map((slug) => ({ slug: slug.length === 0 ? undefined : slug }));
+}
+
+// ── Metadata ─────────────────────────────────────────────────────────────────
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) return {};
+  return { title: route.ref.title };
+}
+
+// ── Page ──────────────────────────────────────────────────────────────────────
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) notFound();
+
+  const { config, ref, page, tab } = route;
+  const headings = extractHeadings(page.content);
+  const { prev, next } = docNeighbours(config, ref.slug);
+  const sidebar = sidebarForDoc(config, tab, ref.slug, renderIcon);
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  return (
+    <DocsShell
+      contentType="doc"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
+      toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
+      hideToc={headings.length === 0}
+    >
+      <Mdx source={page.content} components={siteMdxComponents} />
+      <Pagination
+        prev={prev ? { title: prev.title, href: '/' + prev.slug } : null}
+        next={next ? { title: next.title, href: '/' + next.slug } : null}
+      />
+    </DocsShell>
+  );
+}
diff --git a/templates/canopy/app/api-reference/[[...slug]]/page.tsx b/templates/canopy/app/api-reference/[[...slug]]/page.tsx
new file mode 100644
index 0000000..304010d
--- /dev/null
+++ b/templates/canopy/app/api-reference/[[...slug]]/page.tsx
@@ -0,0 +1,113 @@
+import type { ReactNode } from 'react';
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadDocsConfig, loadOpenApiSpecForBuild } from '@inkform/framework/content';
+import { findOperation, parseOpenApi } from '@inkform/framework/openapi';
+import { parseOpenApiDocument } from '@inkform/framework/openapi-engine/parse';
+import { buildNavTree } from '@inkform/framework/openapi-engine/nav';
+import { OperationPage, buildReferenceSidebarGroups } from '@inkform/framework/openapi-render';
+import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
+import { apiBasePath, apiTab, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+/**
+ * Loads the spec twice — once via parseOpenApi (the narrow OpenApiModel
+ * used for ApiLink-style operation lookup) and once via parseOpenApiDocument
+ * + buildNavTree (the full dereferenced document, needed for the nav tree).
+ * Both bundle/dereference the same spec independently; negligible at this
+ * spec's size and this only runs at build time, but worth consolidating
+ * into one pass if a second native-renderer consumer needs both shapes.
+ */
+async function loadReference() {
+  const config = loadDocsConfig();
+  if (!config) return null;
+  const tab = apiTab(config);
+  if (!tab?.openapi || tab.apiReference?.renderer === 'scalar') return null;
+
+  const spec = await loadOpenApiSpecForBuild(tab.openapi);
+  if (!spec) return null;
+
+  const [model, { schema }] = await Promise.all([
+    parseOpenApi(spec.raw, spec.format),
+    parseOpenApiDocument(spec.raw, { format: spec.format }),
+  ]);
+
+  return { config, tab, model, tree: buildNavTree(schema) };
+}
+
+export async function generateStaticParams() {
+  const ref = await loadReference();
+  if (!ref) return [{ slug: undefined }];
+
+  const params: { slug?: string[] }[] = [{ slug: undefined }];
+  for (const group of ref.tree.tagGroups) {
+    for (const op of group.operations) {
+      params.push({ slug: ['operations', op.operationId] });
+    }
+  }
+  return params;
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) return {};
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(ref.model, slug[1]);
+    if (op) return { title: `${op.summary} · ${ref.model.info.title}` };
+  }
+  return { title: ref.model.info.title };
+}
+
+export default async function ApiReferencePage({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) notFound();
+
+  const { config, tab, model, tree } = ref;
+  const basePath = `/${apiBasePath(config)}`;
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  let content: ReactNode;
+  let activeOperationId: string | undefined;
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(model, slug[1]);
+    if (!op) notFound();
+    activeOperationId = op.operationId;
+    content = <OperationPage operation={op} servers={model.servers} />;
+  } else {
+    content = (
+      <div className="fw-apiref">
+        <div className="fw-apiref-header">
+          <h1 className="fw-apiref-title">{model.info.title}</h1>
+          {model.info.description ? <p className="fw-apiref-desc">{model.info.description}</p> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <DocsShell
+      contentType="api"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      cta={topBar.cta}
+      sidebar={
+        <CollapsibleSidebar
+          title={tab.tab}
+          groups={buildReferenceSidebarGroups(tree, basePath, activeOperationId)}
+          footer={<SidebarFooter />}
+        />
+      }
+      hideToc
+    >
+      {content}
+    </DocsShell>
+  );
+}
diff --git a/templates/canopy/app/api/ask/route.ts b/templates/canopy/app/api/ask/route.ts
new file mode 100644
index 0000000..d9da707
--- /dev/null
+++ b/templates/canopy/app/api/ask/route.ts
@@ -0,0 +1,60 @@
+import { askDocs } from '@inkform/framework/ai';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+export const runtime = 'nodejs';
+
+/**
+ * POST /api/ask — AI assistant endpoint (feature-flagged).
+ *
+ * Grounded in this site's own content via askDocs() (@inkform/framework/ai)
+ * — the same search/getDoc/getOperation retrieval the MCP server uses, not
+ * a separate implementation. BYO model: set DOCS_AI_PROVIDER
+ * ('anthropic' | 'openai' | 'google', default 'anthropic') and that
+ * provider's own API key env var (ANTHROPIC_API_KEY, etc.) — see
+ * packages/framework/src/ai/provider.ts.
+ *
+ * Metered billing for the platform-hosted version of this endpoint is
+ * out of scope here — see inkform/PLATFORM_MCP_SCOPING.md for the sibling
+ * MCP billing question this will eventually need the same answer to.
+ */
+export async function POST(request: Request): Promise<Response> {
+  const enabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  if (!enabled) {
+    return Response.json(
+      {
+        error:
+          'AI assistant is disabled. Set NEXT_PUBLIC_DOCS_AI_ENABLED=true to enable it (configured in a later release).',
+      },
+      { status: 503 },
+    );
+  }
+
+  let messages: unknown;
+  try {
+    const body = (await request.json()) as { messages?: unknown };
+    messages = body?.messages;
+  } catch {
+    return Response.json({ error: 'Invalid request body.' }, { status: 400 });
+  }
+
+  if (!Array.isArray(messages) || messages.some((m) => typeof m?.role !== 'string' || typeof m?.content !== 'string')) {
+    return Response.json({ error: 'messages must be an array of { role, content }.' }, { status: 400 });
+  }
+
+  const config = loadDocsConfig();
+  // apiBasePath() returns a bare slug (e.g. "api-reference"); askDocs()
+  // expects a leading-slash base path to build clickable operation links.
+  const apiBase = config && apiBasePath(config);
+  try {
+    const result = await askDocs(messages, { apiBasePath: apiBase ? `/${apiBase}` : undefined });
+    return Response.json(result);
+  } catch (e) {
+    // Most likely cause: no API key configured for DOCS_AI_PROVIDER.
+    return Response.json(
+      { error: e instanceof Error ? e.message : 'The AI assistant is not configured correctly.' },
+      { status: 500 },
+    );
+  }
+}
diff --git a/templates/canopy/app/blog/[slug]/page.tsx b/templates/canopy/app/blog/[slug]/page.tsx
new file mode 100644
index 0000000..9282d33
--- /dev/null
+++ b/templates/canopy/app/blog/[slug]/page.tsx
@@ -0,0 +1,40 @@
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadBlogPosts, loadBlogPost } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return loadBlogPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  return { title: post?.title ?? 'Blog' };
+}
+
+export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  if (!post) notFound();
+
+  const config = loadDocsConfig();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>{post.title}</h1>
+        <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+          {post.date} · {post.readingTime} min read{post.author ? ` · ${post.author}` : ''}
+        </p>
+      </div>
+      <Mdx source={post.content} components={siteMdxComponents} />
+    </DocsShell>
+  );
+}
diff --git a/templates/canopy/app/blog/page.tsx b/templates/canopy/app/blog/page.tsx
new file mode 100644
index 0000000..7a04806
--- /dev/null
+++ b/templates/canopy/app/blog/page.tsx
@@ -0,0 +1,38 @@
+import Link from 'next/link';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadBlogPosts } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+
+export const metadata = { title: 'Blog' };
+
+export default function BlogIndexPage() {
+  const config = loadDocsConfig();
+  const posts = loadBlogPosts();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Blog</h1>
+        {posts.length === 0 ? (
+          <p>No posts yet — check back soon.</p>
+        ) : (
+          <ul style={{ listStyle: 'none', padding: 0 }}>
+            {posts.map((p) => (
+              <li key={p.slug} style={{ marginBottom: '2rem' }}>
+                <Link href={`/blog/${p.slug}`}>
+                  <h2 style={{ marginBottom: '0.25rem' }}>{p.title}</h2>
+                </Link>
+                <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+                  {p.date} · {p.readingTime} min read{p.author ? ` · ${p.author}` : ''}
+                </p>
+                {p.description ? <p>{p.description}</p> : null}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </DocsShell>
+  );
+}
diff --git a/templates/canopy/app/changelog/page.tsx b/templates/canopy/app/changelog/page.tsx
new file mode 100644
index 0000000..890f6a9
--- /dev/null
+++ b/templates/canopy/app/changelog/page.tsx
@@ -0,0 +1,33 @@
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadChangelogEntries } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const metadata = { title: 'Changelog' };
+
+export default function ChangelogPage() {
+  const config = loadDocsConfig();
+  const entries = loadChangelogEntries();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Changelog</h1>
+        {entries.length === 0 ? <p>No entries yet.</p> : null}
+      </div>
+      {entries.map((e) => (
+        <div key={e.slug} className="fw-prose" style={{ marginTop: '2rem' }}>
+          <p style={{ opacity: 0.7, fontSize: '0.875rem', marginBottom: '0.25rem' }}>
+            {e.date}
+            {e.version ? ` · v${e.version}` : ''}
+          </p>
+          <h2>{e.title}</h2>
+          <Mdx source={e.content} components={siteMdxComponents} />
+        </div>
+      ))}
+    </DocsShell>
+  );
+}
diff --git a/templates/canopy/app/layout.tsx b/templates/canopy/app/layout.tsx
new file mode 100644
index 0000000..5b96730
--- /dev/null
+++ b/templates/canopy/app/layout.tsx
@@ -0,0 +1,44 @@
+import type { Metadata } from 'next';
+import { Inter, JetBrains_Mono } from 'next/font/google';
+import '@inkform/framework/styles.css';
+import './theme.css';
+import { themeInitScript } from '@inkform/framework/theme-toggle';
+import { loadDocsConfig } from '@inkform/framework/content';
+
+// One clean sans voice throughout — headings are the same face at heavier
+// weight, not a second typeface. Matches Palm's real typography (confirmed
+// on palm.mintlify.site: <html> carries a single Inter variable class, no
+// separate serif/display family).
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-sans',
+  display: 'swap',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ['latin'],
+  variable: '--font-mono',
+  display: 'swap',
+});
+
+export async function generateMetadata(): Promise<Metadata> {
+  const config = loadDocsConfig();
+  const name = config?.name ?? 'Canopy Docs';
+  return {
+    title: { default: name, template: `%s · ${name}` },
+    description: `Documentation for ${name}`,
+    icons: { icon: config?.favicon ?? '/favicon.svg' },
+  };
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${jetbrainsMono.variable}`} suppressHydrationWarning>
+      <head>
+        {/* No-flash theme init — must run synchronously before first paint */}
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
diff --git a/templates/canopy/app/theme.css b/templates/canopy/app/theme.css
new file mode 100644
index 0000000..5da81e3
--- /dev/null
+++ b/templates/canopy/app/theme.css
@@ -0,0 +1,369 @@
+/*
+ * Canopy theme — token overrides for @inkform/framework.
+ * Inspired by Palm (a Mintlify starter kit): dark-mode-forward, vivid lime
+ * green accent, centered header search, underline tabs, no header CTA, a
+ * whole-sidebar collapse toggle, and a language + theme-trio sidebar footer.
+ * Colors below were read directly off palm.mintlify.site's computed styles
+ * (its own `--primary`/`--primary-light`/`--background-dark`/`--gray-*` CSS
+ * vars), not guessed — light-mode primary #329100, dark-mode primary
+ * #43c200, dark bg #0a0d0b.
+ * This file is imported AFTER framework/styles.css so its declarations win.
+ * Only --fw-* tokens and small Canopy-specific accents are set here.
+ */
+
+/* ── Font variables (set by next/font in layout.tsx) ─────────────────────── */
+:root {
+  --fw-font: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  --fw-font-heading: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  --fw-mono: var(--font-mono, ui-monospace, "Menlo", "Consolas", monospace);
+}
+
+/* ── Light mode ──────────────────────────────────────────────────────────── */
+:root {
+  --fw-bg: #ffffff;
+  --fw-bg-subtle: #f4f7f2;
+  --fw-fg: #10130f;
+  --fw-muted: #5c6259;
+  --fw-border: #e0e2de;
+  --fw-border-strong: #c7cac2;
+  --fw-card: #ffffff;
+  --fw-card-hover: #f4f7f2;
+  --fw-code-bg: #f4f7f2;
+  --fw-kbd-bg: #eef0ea;
+
+  --fw-primary: #329100;
+  --fw-primary-fg: #ffffff;
+  --fw-primary-subtle: rgba(50, 145, 0, 0.08);
+
+  --fw-radius: 10px;
+  --fw-radius-sm: 7px;
+
+  --fw-shadow: 2px 2px 0 rgba(16, 19, 15, 0.06);
+  --fw-shadow-lg: 4px 4px 0 rgba(16, 19, 15, 0.08);
+  --fw-ring: 0 0 0 3px rgba(50, 145, 0, 0.28);
+}
+
+/* ── Dark mode (Palm's actual default) ──────────────────────────────────── */
+html.dark {
+  --fw-bg: #0a0d0b;
+  --fw-bg-subtle: #10130f;
+  --fw-fg: #f4f7f2;
+  --fw-muted: #a0a29e;
+  --fw-border: #262925;
+  --fw-border-strong: #383c36;
+  --fw-card: #10130f;
+  --fw-card-hover: #161a15;
+  --fw-code-bg: #0e110d;
+  --fw-kbd-bg: #1a1e19;
+
+  --fw-primary: #43c200;
+  --fw-primary-fg: #0b2400;
+  --fw-primary-subtle: rgba(67, 194, 0, 0.14);
+
+  --fw-shadow: 2px 2px 0 rgba(0, 0, 0, 0.4);
+  --fw-shadow-lg: 4px 4px 0 rgba(0, 0, 0, 0.6);
+  --fw-ring: 0 0 0 3px rgba(67, 194, 0, 0.28);
+}
+
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Canopy's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-canopy-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-canopy-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-canopy-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-canopy-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-canopy-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-canopy-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-canopy-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-canopy-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-canopy-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-canopy-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-canopy-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-canopy-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-canopy-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-canopy-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-canopy-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-canopy-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-canopy-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-canopy-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-canopy-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-canopy-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 1rem;
+  overflow: hidden;
+}
diff --git a/templates/canopy/components/collapsible-sidebar.tsx b/templates/canopy/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..4e4818a
--- /dev/null
+++ b/templates/canopy/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Canopy's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-canopy-sidebar-rail">
+        <button
+          type="button"
+          className="fw-canopy-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-canopy-sidebar-heading">
+        <span className="fw-canopy-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-canopy-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/templates/canopy/components/sidebar-footer.tsx b/templates/canopy/components/sidebar-footer.tsx
new file mode 100644
index 0000000..a7643a4
--- /dev/null
+++ b/templates/canopy/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Canopy doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-canopy-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-canopy-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-canopy-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-canopy-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-canopy-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-canopy-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/templates/canopy/components/top-bar.tsx b/templates/canopy/components/top-bar.tsx
new file mode 100644
index 0000000..f72b924
--- /dev/null
+++ b/templates/canopy/components/top-bar.tsx
@@ -0,0 +1,156 @@
+import type { ReactNode } from 'react';
+import Link from 'next/link';
+import { AskAi } from '@inkform/framework/ask-ai';
+import { SearchDialog } from '@inkform/framework/search-dialog';
+import type { DocsConfig } from '@inkform/framework';
+import { docTabs } from '@inkform/framework';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+// ── Brand logo ────────────────────────────────────────────────────────────────
+
+function Logo({ config }: { config: DocsConfig }) {
+  const logo =
+    typeof config.logo === 'string'
+      ? config.logo
+      : config.logo?.dark ?? config.logo?.light ?? null;
+
+  return (
+    <Link href="/" className="fw-shell-brand" aria-label={`${config.name} home`}>
+      {logo ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img src={logo} alt={config.name} height={24} className="fw-shell-brand-logo" />
+      ) : (
+        <span className="fw-shell-brand-name">{config.name}</span>
+      )}
+    </Link>
+  );
+}
+
+// ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Canopy's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Canopy-specific CSS.
+
+function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
+  const tabs = docTabs(config);
+  const apiBase = apiBasePath(config);
+
+  return (
+    <div className="fw-topnav-tabs">
+      {tabs.map((t) => {
+        const href = t.openapi && apiBase ? `/${apiBase}` : '/';
+        const isActive = t.tab === activeTab;
+        return (
+          <a
+            key={t.tab}
+            href={href}
+            className={`fw-topnav-tab${isActive ? ' fw-topnav-tab--active' : ''}`}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            {t.tab}
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── Anchor links ──────────────────────────────────────────────────────────────
+
+function AnchorLinks({ config }: { config: DocsConfig }) {
+  const anchors = config.anchors ?? [];
+  if (anchors.length === 0) return null;
+  return (
+    <div className="fw-topnav-anchors">
+      {anchors.map((a) => (
+        <a
+          key={a.href}
+          href={a.href}
+          className="fw-topnav-anchor"
+          target={a.href.startsWith('http') ? '_blank' : undefined}
+          rel={a.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {a.name}
+        </a>
+      ))}
+    </div>
+  );
+}
+
+// ── Top bar props ─────────────────────────────────────────────────────────────
+
+export interface TopBarParts {
+  logo: ReactNode;
+  topNav: ReactNode;
+  topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
+}
+
+/**
+ * Build the three DocsShell header slot contents for Canopy.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-canopy-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
+ */
+export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
+  const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  const logo = <Logo config={config} />;
+
+  const topNav = (
+    <>
+      <TabNav config={config} activeTab={activeTab} />
+      <AnchorLinks config={config} />
+      {(config.navbarLinks ?? []).map((l) => (
+        <a
+          key={l.href}
+          href={l.href}
+          className="fw-topnav-navlink"
+          target={l.href.startsWith('http') ? '_blank' : undefined}
+          rel={l.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {l.name}
+        </a>
+      ))}
+    </>
+  );
+
+  const topActions = (
+    <>
+      <div className="fw-canopy-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
+    </>
+  );
+
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
+}
diff --git a/templates/canopy/content/docs/development.mdx b/templates/canopy/content/docs/development.mdx
new file mode 100644
index 0000000..f75f85e
--- /dev/null
+++ b/templates/canopy/content/docs/development.mdx
@@ -0,0 +1,60 @@
+---
+title: Development
+description: Preview your docs locally before you ship.
+---
+
+# Development
+
+Learn how to run your docs locally and preview every change before it goes live.
+
+<Info>
+  **Prerequisite:** Node.js 20 or newer.
+</Info>
+
+## Run the dev server
+
+```bash
+npm install
+npm run dev
+```
+
+Your site is now available at [http://localhost:3000](http://localhost:3000).
+Edits to MDX and `docs.json` hot-reload.
+
+## Custom ports
+
+The dev server uses port `3000` by default. Pass `-p` to change it:
+
+```bash
+npm run dev -- -p 3333
+```
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Port already in use">
+    Another process is using the port. Stop it, or start the dev server on a
+    different port with `npm run dev -- -p 3333`.
+  </Accordion>
+  <Accordion title="A page 404s">
+    Make sure the page's `file` exists under `content/docs` and its `slug` is
+    listed in `docs.json`. Slugs are case-sensitive.
+  </Accordion>
+  <Accordion title="The API Reference tab is empty">
+    Confirm `docs.json` has a tab with an `openapi` field pointing at a valid
+    spec file (JSON or YAML) inside `content/docs`.
+  </Accordion>
+</AccordionGroup>
+
+## Editor tips
+
+<Tabs>
+  <Tab title="VS Code">
+    Install the **MDX** extension for syntax highlighting and component
+    autocomplete in `.mdx` files.
+  </Tab>
+  <Tab title="Neovim">
+    Use a Treesitter MDX/Markdown parser for highlighting, and an LSP-aware
+    Markdown plugin for link checking.
+  </Tab>
+</Tabs>
diff --git a/templates/canopy/content/docs/docs.json b/templates/canopy/content/docs/docs.json
new file mode 100644
index 0000000..7c829e3
--- /dev/null
+++ b/templates/canopy/content/docs/docs.json
@@ -0,0 +1,37 @@
+{
+  "name": "Canopy",
+  "version": "1.0.0",
+  "logo": "/logo.svg",
+  "favicon": "/favicon.svg",
+  "colors": { "primary": "#43c200" },
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx", "icon": "book-open" },
+            { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx", "icon": "rocket" },
+            { "title": "Development", "slug": "development", "file": "development.mdx", "icon": "terminal" }
+          ]
+        },
+        {
+          "group": "Essentials",
+          "pages": [
+            { "title": "Markdown Syntax", "slug": "essentials/markdown", "file": "essentials/markdown.mdx", "icon": "type" },
+            { "title": "Code Blocks", "slug": "essentials/code-blocks", "file": "essentials/code-blocks.mdx", "icon": "code" },
+            { "title": "Images & Embeds", "slug": "essentials/images", "file": "essentials/images.mdx", "icon": "image" },
+            { "title": "Components", "slug": "essentials/components", "file": "essentials/components.mdx", "icon": "blocks" },
+            { "title": "Navigation", "slug": "essentials/navigation", "file": "essentials/navigation.mdx", "icon": "map" }
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "API Reference",
+      "openapi": "openapi.json",
+      "apiReference": { "renderer": "native" }
+    }
+  ]
+}
diff --git a/templates/canopy/content/docs/essentials/code-blocks.mdx b/templates/canopy/content/docs/essentials/code-blocks.mdx
new file mode 100644
index 0000000..c5ab15f
--- /dev/null
+++ b/templates/canopy/content/docs/essentials/code-blocks.mdx
@@ -0,0 +1,55 @@
+---
+title: Code Blocks
+description: Display inline code and richly highlighted code blocks.
+---
+
+# Code Blocks
+
+Display inline code and fenced code blocks with syntax highlighting.
+
+## Inline code
+
+To denote a `word` or `phrase` as code, wrap it in backticks (`` ` ``).
+
+## Code blocks
+
+Fence code with triple backticks and a language for highlighting. Add a title
+after the language to label the block:
+
+```js app.js
+export function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Code groups
+
+Group related snippets — different languages or package managers — into a single
+tabbed block:
+
+<CodeGroup>
+```bash npm
+npm install @inkform/framework
+```
+
+```bash pnpm
+pnpm add @inkform/framework
+```
+
+```bash yarn
+yarn add @inkform/framework
+```
+</CodeGroup>
+
+## Highlighting
+
+Code blocks are highlighted with [Shiki](https://shiki.style), the same engine
+VS Code uses, so colors match your editor and stay readable in light and dark
+mode.
+
+```ts server.ts
+import { parseOpenApi } from '@inkform/framework/openapi';
+
+const model = parseOpenApi(rawSpec);
+console.log(model.operations.length, 'endpoints');
+```
diff --git a/templates/canopy/content/docs/essentials/components.mdx b/templates/canopy/content/docs/essentials/components.mdx
new file mode 100644
index 0000000..1057e76
--- /dev/null
+++ b/templates/canopy/content/docs/essentials/components.mdx
@@ -0,0 +1,62 @@
+---
+title: Components
+description: The built-in component library for rich, interactive docs.
+---
+
+# Components
+
+Beyond Markdown, you get a library of components for richer pages — all available
+in any `.mdx` file with no imports.
+
+## Cards
+
+<CardGroup cols={2}>
+  <Card title="Fast" icon="zap">
+    Static-rendered pages, instant client-side search.
+  </Card>
+  <Card title="Themeable" icon="palette">
+    Restyle everything from one token file.
+  </Card>
+</CardGroup>
+
+## Callouts
+
+<Note>A neutral note.</Note>
+<Tip>A helpful tip.</Tip>
+<Warning>Something to be careful about.</Warning>
+<Check>A success confirmation.</Check>
+
+## Steps
+
+<Steps>
+  <Step title="Write">Add an `.mdx` file under `content/docs`.</Step>
+  <Step title="Register">List it in `docs.json`.</Step>
+  <Step title="Ship">Push and deploy.</Step>
+</Steps>
+
+## Tabs
+
+<Tabs>
+  <Tab title="macOS">Press <kbd>⌘</kbd> <kbd>K</kbd> to open search.</Tab>
+  <Tab title="Windows">Press <kbd>Ctrl</kbd> <kbd>K</kbd> to open search.</Tab>
+</Tabs>
+
+## Accordions
+
+<AccordionGroup>
+  <Accordion title="Is it responsive?">Yes — sidebar and TOC collapse on small screens.</Accordion>
+  <Accordion title="Does it support dark mode?">Yes — toggle in the top bar, persisted across visits.</Accordion>
+</AccordionGroup>
+
+## Parameter fields
+
+Use `<ParamField>` and `<ResponseField>` to document request and response shapes
+in prose (the API Reference tab generates these automatically from OpenAPI):
+
+<ParamField query="limit" type="integer" default="20">
+  The maximum number of results to return.
+</ParamField>
+
+<ResponseField name="id" type="integer" required>
+  The unique identifier of the created record.
+</ResponseField>
diff --git a/templates/canopy/content/docs/essentials/images.mdx b/templates/canopy/content/docs/essentials/images.mdx
new file mode 100644
index 0000000..5caefc6
--- /dev/null
+++ b/templates/canopy/content/docs/essentials/images.mdx
@@ -0,0 +1,43 @@
+---
+title: Images & Embeds
+description: Add images, video, and other media to your docs.
+---
+
+# Images & Embeds
+
+Add images, video, and rich media to bring your documentation to life.
+
+## Images
+
+Use Markdown image syntax:
+
+```md
+![A descriptive alt text](/path/to/image.jpg)
+```
+
+Wrap an image in a `<Frame>` to add a border and an optional caption:
+
+<Frame caption="Images look great framed.">
+  ![Landscape](/hero.svg)
+</Frame>
+
+<Note>
+  Keep images under ~5 MB. For larger assets, host them on a CDN and reference
+  the URL.
+</Note>
+
+## Video
+
+Embed a YouTube or Loom video with the `<Embed>` component:
+
+```mdx
+<Embed provider="youtube" url="https://youtu.be/dQw4w9WgXcQ" />
+```
+
+## iframes
+
+Embed any external page:
+
+```mdx
+<Embed provider="iframe" url="https://example.com/widget" />
+```
diff --git a/templates/canopy/content/docs/essentials/markdown.mdx b/templates/canopy/content/docs/essentials/markdown.mdx
new file mode 100644
index 0000000..c0e86da
--- /dev/null
+++ b/templates/canopy/content/docs/essentials/markdown.mdx
@@ -0,0 +1,65 @@
+---
+title: Markdown Syntax
+description: Text, titles, and styling in standard Markdown.
+---
+
+# Markdown Syntax
+
+Write content in standard Markdown — the framework renders it with GitHub-flavored
+extensions, callouts, and syntax-highlighted code.
+
+## Titles
+
+Use `#` headings for sections. Second- and third-level headings (`##`, `###`)
+appear in the table of contents on the right.
+
+```md
+## Section title
+### Subsection title
+```
+
+## Text formatting
+
+We support most Markdown formatting. Wrap text to style it:
+
+| Style | How to write it | Result |
+| --- | --- | --- |
+| Bold | `**bold**` | **bold** |
+| Italic | `_italic_` | _italic_ |
+| Strikethrough | `~~struck~~` | ~~struck~~ |
+| Code | `` `code` `` | `code` |
+
+## Links
+
+Link to [another page](/quickstart) with relative paths, or to
+[an external site](https://example.com) with full URLs.
+
+## Blockquotes
+
+> The best way to predict the future is to invent it.
+
+## Lists
+
+- Unordered items
+- Nest them by indenting
+  - Like this
+
+1. Ordered items
+2. Count automatically
+
+## Callouts
+
+Use callouts to draw attention. They come in several flavors:
+
+<Note>This is a note — neutral, informational.</Note>
+<Tip>This is a tip — a helpful suggestion.</Tip>
+<Warning>This is a warning — proceed carefully.</Warning>
+<Check>This is a success message — all good.</Check>
+
+You can also write callouts as directives:
+
+```md
+:::info
+An info callout written as a directive.
+:::
+```
diff --git a/templates/canopy/content/docs/essentials/navigation.mdx b/templates/canopy/content/docs/essentials/navigation.mdx
new file mode 100644
index 0000000..f85d3f2
--- /dev/null
+++ b/templates/canopy/content/docs/essentials/navigation.mdx
@@ -0,0 +1,68 @@
+---
+title: Navigation
+description: Configure tabs, groups, pages, and the API Reference in docs.json.
+---
+
+# Navigation
+
+Your site's structure lives in `content/docs/docs.json`. It controls the top
+tabs, the sidebar groups, and the API Reference.
+
+## Groups and pages
+
+The simplest config is a list of groups, each with pages:
+
+```json docs.json
+{
+  "name": "My Docs",
+  "navigation": [
+    {
+      "group": "Get Started",
+      "pages": [
+        { "title": "Introduction", "slug": "", "file": "index.mdx" },
+        { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx" }
+      ]
+    }
+  ]
+}
+```
+
+<Note>
+  `slug` is the URL path (an empty string is the index). `file` is the MDX file
+  relative to `content/docs`. Nest pages with a `children` array.
+</Note>
+
+## Tabs
+
+Add top-bar tabs to split Guides from your API Reference:
+
+```json docs.json
+{
+  "tabs": [
+    { "tab": "Guides", "navigation": [ /* groups */ ] },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+## API Reference from OpenAPI
+
+Point a tab's `openapi` field at a spec file (JSON or YAML) in `content/docs`.
+The framework generates the entire API Reference — endpoint list, parameters,
+request/response schemas, a cURL sample, and a live "Try it" playground — from
+the spec.
+
+<Tip>
+  This is the standard: API docs come from OpenAPI, everything else is MDX. Keep
+  your spec accurate and your reference stays accurate for free.
+</Tip>
+
+## Top bar
+
+```json docs.json
+{
+  "navbarLinks": [{ "name": "Blog", "href": "/blog" }],
+  "anchors": [{ "name": "GitHub", "href": "https://github.com/you/repo", "icon": "github" }],
+  "cta": { "label": "Dashboard", "href": "https://app.example.com" }
+}
+```
diff --git a/templates/canopy/content/docs/index.mdx b/templates/canopy/content/docs/index.mdx
new file mode 100644
index 0000000..5165c61
--- /dev/null
+++ b/templates/canopy/content/docs/index.mdx
@@ -0,0 +1,46 @@
+---
+title: Introduction
+description: Welcome to your new documentation site.
+---
+
+# Introduction
+
+Welcome to the home of your new documentation. This starter is a complete,
+deployable docs site powered by [`@inkform/framework`](https://github.com/inkform-dev/framework):
+write Markdown, commit it, and ship a fast, searchable, themeable site — no CMS,
+no database.
+
+<Frame caption="Your docs, your repo, your deploy.">
+  ![Hero](/hero.svg)
+</Frame>
+
+## Set up
+
+The first step to world-class documentation is setting up your editing
+environment and making the site your own.
+
+<CardGroup cols={2}>
+  <Card title="Edit your docs" icon="pencil" href="/quickstart">
+    Get your docs running locally for fast iteration.
+  </Card>
+  <Card title="Preview changes" icon="eye" href="/development">
+    Preview every change before you push so it's always right.
+  </Card>
+  <Card title="Write in MDX" icon="type" href="/essentials/markdown">
+    Markdown with components — callouts, cards, steps, tabs, and more.
+  </Card>
+  <Card title="API Reference" icon="terminal" href="/essentials/navigation">
+    Point `docs.json` at an OpenAPI spec and get a full API reference.
+  </Card>
+</CardGroup>
+
+## Make it yours
+
+Every theme is driven by the same engine and a single `theme.css` token file, so
+you can recolor, re-font, and restyle the whole site without touching layout
+code.
+
+<Note>
+  New here? Start with the [Quickstart](/quickstart) — you'll have a site running
+  in under five minutes.
+</Note>
diff --git a/templates/canopy/content/docs/openapi.json b/templates/canopy/content/docs/openapi.json
new file mode 100644
index 0000000..fdf12e9
--- /dev/null
+++ b/templates/canopy/content/docs/openapi.json
@@ -0,0 +1,125 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Sample Store API",
+    "version": "1.0.0",
+    "description": "A tiny example API used to demo the OpenAPI-powered API Reference. Replace `openapi.json` with your own spec — everything on the API Reference tab is generated from it."
+  },
+  "servers": [{ "url": "https://api.example.com/v1", "description": "Production" }],
+  "security": [{ "bearerAuth": [] }],
+  "tags": [{ "name": "Plants", "description": "Manage the plants in your store." }],
+  "paths": {
+    "/plants": {
+      "get": {
+        "operationId": "list-plants",
+        "tags": ["Plants"],
+        "summary": "List plants",
+        "description": "Returns all plants from the store that the caller has access to.",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "The maximum number of results to return.",
+            "schema": { "type": "integer", "format": "int32", "default": 20 }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of plants.",
+            "content": {
+              "application/json": {
+                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plant" } }
+              }
+            }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      },
+      "post": {
+        "operationId": "create-plant",
+        "tags": ["Plants"],
+        "summary": "Create a plant",
+        "description": "Creates a new plant in the store.",
+        "requestBody": {
+          "required": true,
+          "description": "The plant to add to the store.",
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } }
+        },
+        "responses": {
+          "200": {
+            "description": "The created plant.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plant" } } }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    },
+    "/plants/{id}": {
+      "delete": {
+        "operationId": "delete-plant",
+        "tags": ["Plants"],
+        "summary": "Delete a plant",
+        "description": "Deletes a single plant by its id.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The id of the plant to delete.",
+            "schema": { "type": "integer", "format": "int64" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Plant deleted." },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Bearer authentication header of the form `Bearer <token>`."
+      }
+    },
+    "schemas": {
+      "Plant": {
+        "type": "object",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "integer", "format": "int64", "description": "Identification number of the plant." },
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "NewPlant": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": ["error", "message"],
+        "properties": {
+          "error": { "type": "integer", "format": "int32", "description": "Error code." },
+          "message": { "type": "string", "description": "Human-readable error message." }
+        }
+      }
+    }
+  }
+}
diff --git a/templates/canopy/content/docs/quickstart.mdx b/templates/canopy/content/docs/quickstart.mdx
new file mode 100644
index 0000000..b047822
--- /dev/null
+++ b/templates/canopy/content/docs/quickstart.mdx
@@ -0,0 +1,76 @@
+---
+title: Quickstart
+description: Start building beautiful documentation in minutes.
+---
+
+# Quickstart
+
+Start building beautiful documentation in minutes.
+
+## Set up your project
+
+<Steps>
+  <Step title="Scaffold a project">
+    Create a new docs site and pick a theme:
+
+    ```bash
+    npx @inkform/cli@latest init my-docs
+    cd my-docs
+    npm install
+    ```
+  </Step>
+  <Step title="Run it locally">
+    Start the dev server and open [localhost:3000](http://localhost:3000):
+
+    ```bash
+    npm run dev
+    ```
+  </Step>
+  <Step title="Edit your content">
+    Content lives in `content/docs`. Edit any `.mdx` file and the page reloads
+    instantly. Add pages by creating files and listing them in `docs.json`.
+  </Step>
+  <Step title="Deploy">
+    Push to GitHub and import the repo on Vercel — zero config. See the
+    project README for the full deploy guide (Vercel and AWS Amplify).
+  </Step>
+</Steps>
+
+## Add your first page
+
+Create `content/docs/hello.mdx`:
+
+```mdx hello.mdx
+---
+title: Hello
+description: My first page.
+---
+
+# Hello
+
+This is my first documentation page.
+```
+
+Then register it in `content/docs/docs.json`:
+
+```json docs.json
+{
+  "group": "Get Started",
+  "pages": [{ "title": "Hello", "slug": "hello", "file": "hello.mdx" }]
+}
+```
+
+<Tip>
+  The `slug` is the URL path and `file` is the MDX file relative to
+  `content/docs`. Nest pages with a `children` array.
+</Tip>
+
+## Cross-linking to the API Reference
+
+If a project has an OpenAPI spec configured, <ApiLink operationId="list-plants">any doc page can link straight to a specific operation</ApiLink> with `<ApiLink operationId="...">`. The link is validated against the spec at build time — a typo or renamed operation fails the build instead of shipping a dead link.
+
+## Custom widgets
+
+Put a component at `widgets/<Name>.tsx`, register it in `widgets/index.ts`, and use it directly in MDX (or from the CMS's widget block) as `<Name />`:
+
+<Counter start={3} />
diff --git a/templates/canopy/content/docs/slug-history.json b/templates/canopy/content/docs/slug-history.json
new file mode 100644
index 0000000..0967ef4
--- /dev/null
+++ b/templates/canopy/content/docs/slug-history.json
@@ -0,0 +1 @@
+{}
diff --git a/templates/canopy/lib/icons.tsx b/templates/canopy/lib/icons.tsx
new file mode 100644
index 0000000..8490099
--- /dev/null
+++ b/templates/canopy/lib/icons.tsx
@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+import {
+  Book,
+  BookOpen,
+  Rocket,
+  Terminal,
+  Type,
+  Code,
+  Image,
+  Blocks,
+  Map,
+  Github,
+  Pencil,
+  Eye,
+  Zap,
+  Palette,
+  FileText,
+  Settings,
+  Globe,
+  Lock,
+  Key,
+  Database,
+  Cloud,
+  Mail,
+  User,
+  Users,
+  Star,
+  Heart,
+  Bell,
+  Search,
+  Home,
+  Layout,
+  Package,
+  Layers,
+  Link,
+  ChevronRight,
+  Play,
+  Download,
+  Upload,
+} from 'lucide-react';
+
+const ICON_MAP: Record<string, React.ComponentType<{ size?: number; strokeWidth?: number }>> = {
+  book: Book,
+  'book-open': BookOpen,
+  rocket: Rocket,
+  terminal: Terminal,
+  type: Type,
+  code: Code,
+  image: Image,
+  blocks: Blocks,
+  map: Map,
+  github: Github,
+  pencil: Pencil,
+  eye: Eye,
+  zap: Zap,
+  palette: Palette,
+  file: FileText,
+  'file-text': FileText,
+  settings: Settings,
+  globe: Globe,
+  lock: Lock,
+  key: Key,
+  database: Database,
+  cloud: Cloud,
+  mail: Mail,
+  user: User,
+  users: Users,
+  star: Star,
+  heart: Heart,
+  bell: Bell,
+  search: Search,
+  home: Home,
+  layout: Layout,
+  package: Package,
+  layers: Layers,
+  link: Link,
+  'chevron-right': ChevronRight,
+  play: Play,
+  download: Download,
+  upload: Upload,
+};
+
+/**
+ * Map a docs.json icon name to a Lucide icon ReactNode.
+ * Returns null for unknown or empty names.
+ */
+export function renderIcon(name?: string): ReactNode {
+  if (!name) return null;
+  const Icon = ICON_MAP[name.toLowerCase()];
+  if (!Icon) return null;
+  return <Icon size={16} strokeWidth={1.75} />;
+}
diff --git a/templates/canopy/lib/route.tsx b/templates/canopy/lib/route.tsx
new file mode 100644
index 0000000..371401d
--- /dev/null
+++ b/templates/canopy/lib/route.tsx
@@ -0,0 +1,134 @@
+/**
+ * lib/route.ts — Canopy routing core.
+ *
+ * Resolves a slug array from the catch-all route into a doc page, generates
+ * static params, and builds sidebar groups. The API Reference tab is NOT
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
+ */
+
+import type { ReactNode } from 'react';
+import { docTabs, listDocPages, findDocPage, tabNavigation } from '@inkform/framework';
+import type { DocsConfig, DocsTab, FlatDocPage } from '@inkform/framework';
+import { loadDocsConfig, loadDocPage, loadBlogPosts, loadChangelogEntries, slugify } from '@inkform/framework/content';
+import type { SidebarGroup, SidebarItem } from '@inkform/framework/docs-shell';
+
+// ── Re-export for convenience ─────────────────────────────────────────────────
+
+export { loadDocsConfig, loadDocPage };
+
+// ── Content nav links (Blog / Changelog) ──────────────────────────────────────
+
+/**
+ * Extends config.navbarLinks with "Blog" / "Changelog" entries, but only when
+ * content actually exists under content/blog or content/changelog — a
+ * docs-only site stays clean by default (see app/blog, app/changelog).
+ */
+export function withContentNavLinks(config: DocsConfig): DocsConfig {
+  const extra: DocsConfig['navbarLinks'] = [];
+  if (loadBlogPosts().length > 0) extra.push({ name: 'Blog', href: '/blog' });
+  if (loadChangelogEntries().length > 0) extra.push({ name: 'Changelog', href: '/changelog' });
+  if (extra.length === 0) return config;
+  return { ...config, navbarLinks: [...(config.navbarLinks ?? []), ...extra] };
+}
+
+// ── API tab helpers ───────────────────────────────────────────────────────────
+
+/** Find the tab that has an openapi spec (the API Reference tab). */
+export function apiTab(config: DocsConfig): DocsTab | null {
+  return docTabs(config).find((t) => !!t.openapi) ?? null;
+}
+
+/**
+ * The URL slug base for the API Reference tab, derived from slugifying its
+ * tab label (e.g. "API Reference" → "api-reference"). Used by top-bar.tsx to
+ * link to app/api-reference/route.ts — keep the two in sync if you rename
+ * the tab.
+ */
+export function apiBasePath(config: DocsConfig): string | null {
+  const tab = apiTab(config);
+  if (!tab) return null;
+  return slugify(tab.tab);
+}
+
+// ── Route resolution ──────────────────────────────────────────────────────────
+
+export type DocRoute = {
+  kind: 'doc';
+  ref: FlatDocPage;
+  page: { data: Record<string, unknown>; content: string };
+  config: DocsConfig;
+  tab: DocsTab;
+};
+
+/**
+ * Resolve a catch-all slug array to a doc page descriptor.
+ * Returns null if no page is found (→ notFound()).
+ */
+export function resolveRoute(slugParts: string[] | undefined): DocRoute | null {
+  const config = loadDocsConfig();
+  if (!config) return null;
+
+  const path = (slugParts ?? []).join('/');
+  const ref = findDocPage(config, path);
+  if (!ref) return null;
+
+  const page = loadDocPage(ref.file);
+  if (!page) return null;
+
+  const docTabEntry = docTabs(config).find((t) => t.tab === ref.tab) ?? docTabs(config)[0];
+  return { kind: 'doc', ref, page, config, tab: docTabEntry };
+}
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+/**
+ * All static slugs for generateStaticParams.
+ * Each entry is a string[] (the catch-all segments).
+ * The index page has slug = [] (empty array).
+ */
+export function listAllRoutes(config: DocsConfig): string[][] {
+  const routes: string[][] = [];
+  const seen = new Set<string>();
+
+  function addSlug(slug: string) {
+    if (seen.has(slug)) return;
+    seen.add(slug);
+    routes.push(slug === '' ? [] : slug.split('/'));
+  }
+
+  for (const page of listDocPages(config)) {
+    addSlug(page.slug);
+  }
+
+  return routes;
+}
+
+// ── Sidebar builders ──────────────────────────────────────────────────────────
+
+/**
+ * Build SidebarGroup[] for a doc tab.
+ * renderIcon maps a docs.json icon name to a ReactNode.
+ */
+export function sidebarForDoc(
+  config: DocsConfig,
+  tab: DocsTab,
+  activeSlug: string,
+  renderIcon: (name?: string) => ReactNode,
+): SidebarGroup[] {
+  const groups = tabNavigation(config, tab.tab);
+  return groups.map((g) => ({
+    group: g.group,
+    icon: renderIcon(g.icon),
+    items: (g.pages ?? []).map((p): SidebarItem => ({
+      title: p.title,
+      href: p.href ?? '/' + p.slug,
+      active: p.slug === activeSlug,
+      icon: renderIcon(p.icon),
+      external: !!p.href,
+    })),
+  }));
+}
diff --git a/templates/canopy/mdx-components.tsx b/templates/canopy/mdx-components.tsx
new file mode 100644
index 0000000..70bba3b
--- /dev/null
+++ b/templates/canopy/mdx-components.tsx
@@ -0,0 +1,11 @@
+import { mdxComponents } from '@inkform/framework/components';
+import widgets from '@/widgets';
+
+/**
+ * Site-level MDX component map.
+ * The framework's defaults cover all built-in blocks (Callout, Card, Steps,
+ * Tabs, CodeGroup, Accordion, ParamField, …). Custom widgets registered in
+ * widgets/index.ts are merged in here, so <YourWidget /> in MDX/CMS content
+ * resolves to the real component instead of the unknown-component fallback.
+ */
+export const siteMdxComponents = mdxComponents(widgets);
diff --git a/templates/canopy/next-env.d.ts b/templates/canopy/next-env.d.ts
new file mode 100644
index 0000000..9edff1c
--- /dev/null
+++ b/templates/canopy/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/templates/canopy/next.config.ts b/templates/canopy/next.config.ts
new file mode 100644
index 0000000..02714a1
--- /dev/null
+++ b/templates/canopy/next.config.ts
@@ -0,0 +1,17 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  transpilePackages: ['@inkform/framework'],
+  images: { remotePatterns: [{ protocol: 'https', hostname: '**' }] },
+  // Pagefind indexes .next/server/app's built .html files directly, so its
+  // search results carry a trailing .html this app doesn't actually serve
+  // (e.g. /essentials/markdown.html) — this app's real routes are
+  // extensionless. Redirect (not rewrite) so the address bar ends up on the
+  // real, shareable permalink; query params (?q=... for highlighting) are
+  // preserved automatically.
+  async redirects() {
+    return [{ source: '/:path*.html', destination: '/:path*', permanent: false }];
+  },
+};
+
+export default nextConfig;
diff --git a/templates/canopy/package.json b/templates/canopy/package.json
new file mode 100644
index 0000000..edf6e05
--- /dev/null
+++ b/templates/canopy/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@inkform/theme-canopy",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Canopy — a dark-mode-forward documentation theme for @inkform/framework with a vivid green accent, inspired by Mintlify's Palm starter kit.",
+  "license": "MIT",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inkform/framework": "^0.3.0",
+    "lucide-react": "^0.483.0",
+    "next": "16.2.10",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "pagefind": "^1.5.2",
+    "typescript": "^5"
+  }
+}
diff --git a/templates/canopy/proxy.ts b/templates/canopy/proxy.ts
new file mode 100644
index 0000000..a0fd617
--- /dev/null
+++ b/templates/canopy/proxy.ts
@@ -0,0 +1,22 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { resolveSlugRedirect } from '@inkform/framework';
+import slugHistory from './content/docs/slug-history.json';
+
+/** Docs are served at the root, so slug-history redirects use the '/' base. */
+export function proxy(req: NextRequest) {
+  const target = resolveSlugRedirect(
+    req.nextUrl.pathname,
+    slugHistory as Record<string, string>,
+    '/',
+  );
+  if (target) {
+    return NextResponse.redirect(new URL(target, req.url), 301);
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+};
diff --git a/templates/canopy/public/favicon.svg b/templates/canopy/public/favicon.svg
new file mode 100644
index 0000000..90fa40d
--- /dev/null
+++ b/templates/canopy/public/favicon.svg
@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="Canopy favicon">
+  <rect width="32" height="32" rx="8" fill="#0a0d0b"/>
+  <!-- Canopy rosette mark -->
+  <path d="M14 26 Q13 16 16 6 Q19 16 18 26 Z" fill="#329100" transform="rotate(-55 16 26)"/>
+  <path d="M14 26 Q13 15 16 5 Q19 15 18 26 Z" fill="#43c200" transform="rotate(-27 16 26)"/>
+  <path d="M14 26 Q13 14 16 4 Q19 14 18 26 Z" fill="#43c200"/>
+  <path d="M14 26 Q13 15 16 5 Q19 15 18 26 Z" fill="#43c200" transform="rotate(27 16 26)"/>
+  <path d="M14 26 Q13 16 16 6 Q19 16 18 26 Z" fill="#329100" transform="rotate(55 16 26)"/>
+</svg>
diff --git a/templates/canopy/public/hero.svg b/templates/canopy/public/hero.svg
new file mode 100644
index 0000000..2f0562f
--- /dev/null
+++ b/templates/canopy/public/hero.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" fill="none" role="img" aria-label="Canopy documentation hero">
+  <rect width="800" height="360" rx="20" fill="#0f2e08"/>
+  <circle cx="130" cy="70" r="190" fill="#153a0d"/>
+  <circle cx="670" cy="300" r="180" fill="#0c2606"/>
+  <circle cx="650" cy="50" r="110" fill="#173f0e"/>
+  <circle cx="110" cy="320" r="120" fill="#0f2e08"/>
+  <circle cx="400" cy="180" r="86" fill="#329100"/>
+  <path d="M394 220 Q391 178 400 140 Q409 178 406 220 Z" fill="#f4f7f2" transform="rotate(-55 400 220)"/>
+  <path d="M394 220 Q391 176 400 136 Q409 176 406 220 Z" fill="#f4f7f2" transform="rotate(-27 400 220)"/>
+  <path d="M394 220 Q391 174 400 132 Q409 174 406 220 Z" fill="#f4f7f2"/>
+  <path d="M394 220 Q391 176 400 136 Q409 176 406 220 Z" fill="#f4f7f2" transform="rotate(27 400 220)"/>
+  <path d="M394 220 Q391 178 400 140 Q409 178 406 220 Z" fill="#f4f7f2" transform="rotate(55 400 220)"/>
+</svg>
diff --git a/templates/canopy/public/logo.svg b/templates/canopy/public/logo.svg
new file mode 100644
index 0000000..68911e0
--- /dev/null
+++ b/templates/canopy/public/logo.svg
@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 32" fill="none" role="img" aria-label="Canopy">
+  <!-- Canopy rosette mark: five pointed blades fanning from a base point -->
+  <path d="M12 28 Q11 17 14 6 Q17 17 16 28 Z" fill="#329100" transform="rotate(-55 14 28)"/>
+  <path d="M12 28 Q11 16 14 5 Q17 16 16 28 Z" fill="#43c200" transform="rotate(-27 14 28)"/>
+  <path d="M12 28 Q11 15 14 4 Q17 15 16 28 Z" fill="#43c200"/>
+  <path d="M12 28 Q11 16 14 5 Q17 16 16 28 Z" fill="#43c200" transform="rotate(27 14 28)"/>
+  <path d="M12 28 Q11 17 14 6 Q17 17 16 28 Z" fill="#329100" transform="rotate(55 14 28)"/>
+  <!-- Wordmark -->
+  <text x="32" y="21" font-family="system-ui, -apple-system, sans-serif" font-size="14" font-weight="700" letter-spacing="-0.02em" fill="currentColor">Canopy</text>
+</svg>
diff --git a/templates/canopy/tsconfig.json b/templates/canopy/tsconfig.json
new file mode 100644
index 0000000..e7ff3a2
--- /dev/null
+++ b/templates/canopy/tsconfig.json
@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
diff --git a/templates/canopy/widgets/Counter.tsx b/templates/canopy/widgets/Counter.tsx
new file mode 100644
index 0000000..d786325
--- /dev/null
+++ b/templates/canopy/widgets/Counter.tsx
@@ -0,0 +1,13 @@
+'use client';
+
+import { useState } from 'react';
+
+/** Real test widget proving MDX/CMS content can render a user-registered component, not the Fallback placeholder. */
+export function Counter({ start = 0 }: { start?: number }) {
+  const [count, setCount] = useState(start);
+  return (
+    <button type="button" className="fw-widget-counter" onClick={() => setCount((c) => c + 1)}>
+      Widget count: {count}
+    </button>
+  );
+}
diff --git a/templates/canopy/widgets/index.ts b/templates/canopy/widgets/index.ts
new file mode 100644
index 0000000..a04190f
--- /dev/null
+++ b/templates/canopy/widgets/index.ts
@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react';
+import { Counter } from './Counter';
+
+/**
+ * Custom widget registry. Put your component at widgets/<Name>.tsx, import
+ * it here, and add it to this map — the key becomes the JSX tag name your
+ * MDX/CMS content uses (<Name ... />). Framework docs: "Custom Widgets."
+ */
+const widgets: Record<string, ComponentType<any>> = {
+  Counter,
+};
+
+export default widgets;
diff --git a/templates/galley/README.md b/templates/galley/README.md
index ba38899..cbd0c66 100644
--- a/templates/galley/README.md
+++ b/templates/galley/README.md
@@ -4,8 +4,11 @@ Galley is Inkform's own design system, built on `@inkform/framework`. Warm
 opaque paper + ink, one editorial "Proof" red-pencil accent, a serif prose
 voice (Newsreader) beside a mono machine voice (JetBrains Mono) and a sans UI
 voice (General Sans). Depth comes from paper layering and hairlines, never
-heavy shadow or gradient. It supports Guides + API Reference tabs, plus Blog
-and Changelog, out of the box.
+heavy shadow or gradient. Structurally identical to Canopy (same header,
+sidebar, mobile drawer, and search patterns — only the token layer differs):
+a centered header search bar, underline tab indicators, no header CTA, a
+whole-sidebar collapse toggle, and a sidebar-footer language + theme
+switcher. It supports Guides + API Reference tabs out of the box.
 
 ---
 
@@ -59,11 +62,15 @@ All content lives in `content/docs/`.
 - `slug` is the URL path (empty string = the index `/`).
 - `file` is the MDX file path relative to `content/docs/`.
 - The `openapi` field on a tab points to a JSON/YAML spec file in `content/docs/`.
+- Galley's header has no CTA button and no extra anchor/nav links by design
+  (matching Palm) — `cta`, `anchors`, and `navbarLinks` are all still
+  supported by the schema and will render if you add them back, they're
+  just omitted from this theme's sample `docs.json`.
 
 ### Writing MDX
 
-Add `.mdx` files under `content/docs/` and register them in `docs.json`.
-Galley supports all built-in blocks: `<Note>`, `<Tip>`, `<Warning>`, `<Card>`,
+Add `.mdx` files under `content/docs/` and register them in `docs.json`. Galley
+supports all built-in blocks: `<Note>`, `<Tip>`, `<Warning>`, `<Card>`,
 `<CardGroup>`, `<Steps>`, `<Step>`, `<Tabs>`, `<Tab>`, `<CodeGroup>`,
 `<Accordion>`, `<ParamField>`, `<Frame>`, and more.
 
@@ -107,11 +114,27 @@ When a page's URL changes, record the old → new slug mapping in
 }
 ```
 
+### Sidebar collapse + footer
+
+`components/collapsible-sidebar.tsx` is Galley-specific (not part of the
+shared framework): a single toggle collapses the whole nav column to a thin
+rail and back — real `useState`, not a static arrow — matching what
+palm.mintlify.site actually does (verified directly: its arrow collapses the
+entire sidebar, not one group at a time). `components/sidebar-footer.tsx`
+renders the language label and the system/light/dark theme trio at the
+bottom of the sidebar; the theme trio reads and writes the same
+`localStorage['fw-theme']` + `dark` class the framework's own theme init
+script already uses, so there's no flash on load and no shared-framework
+change was needed to add the third "system" state.
+
 ### Ask AI widget
 
 The Ask AI button is built in but **disabled by default**. Enable it by setting
-`NEXT_PUBLIC_DOCS_AI_ENABLED=true` in `.env.local`. Wire up a real LLM provider
-in `app/api/ask/route.ts` (see the TODO comment there; currently returns a stub).
+`NEXT_PUBLIC_DOCS_AI_ENABLED=true` in `.env.local`, plus `DOCS_AI_PROVIDER`
+(`anthropic` | `openai` | `google`, default `anthropic`) and that provider's
+API key (e.g. `ANTHROPIC_API_KEY`) — see `.env.example`. Answers are grounded
+in this site's own content (`@inkform/framework/ai`'s `askDocs()`), not a
+generic chatbot.
 
 ---
 
@@ -121,7 +144,7 @@ in `app/api/ask/route.ts` (see the TODO comment there; currently returns a stub)
 2. In the Vercel dashboard, click **Add New → Project** and import the repo.
 3. **Framework preset**: Next.js.
 4. **Root directory**: set to the path of this folder if deploying as a
-   standalone (e.g. `oss/templates/galley`), or leave blank if deploying the
+   standalone (e.g. `templates/galley`), or leave blank if deploying the
    directory itself.
 5. Add the environment variable `NEXT_PUBLIC_SITE_URL` (your production URL,
    e.g. `https://docs.example.com`).
@@ -142,16 +165,3 @@ your domain. Vercel handles SSL automatically.
 3. Add the `NEXT_PUBLIC_SITE_URL` environment variable under
    **Environment variables**.
 4. Deploy. Amplify Hosting supports Next.js SSR/ISR natively since Gen 2.
-
----
-
-## Ask AI (deferred)
-
-The `<AskAi />` widget in the top bar is built in. To activate it:
-
-1. Set `NEXT_PUBLIC_DOCS_AI_ENABLED=true`.
-2. Implement the LLM call in `app/api/ask/route.ts`.
-3. Add `ANTHROPIC_API_KEY` (or your provider key) as a server-side env var.
-
-The widget renders in both enabled and disabled states — it just shows an
-informational notice when disabled.
diff --git a/templates/galley/app/[[...slug]]/page.tsx b/templates/galley/app/[[...slug]]/page.tsx
index 5dd0aaf..ff89b53 100644
--- a/templates/galley/app/[[...slug]]/page.tsx
+++ b/templates/galley/app/[[...slug]]/page.tsx
@@ -1,10 +1,12 @@
 import { notFound } from 'next/navigation';
 import { Mdx } from '@inkform/framework/mdx';
-import { DocsShell, Sidebar, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
 import { docNeighbours } from '@inkform/framework';
 import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
 import { siteMdxComponents } from '@/mdx-components';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { renderIcon } from '@/lib/icons';
 import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
 
@@ -49,7 +51,8 @@ export default async function Page({ params }: { params: Promise<{ slug?: string
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<Sidebar groups={sidebar} />}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
       toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
       hideToc={headings.length === 0}
     >
diff --git a/templates/galley/app/api-reference/[[...slug]]/page.tsx b/templates/galley/app/api-reference/[[...slug]]/page.tsx
index 7c3a451..304010d 100644
--- a/templates/galley/app/api-reference/[[...slug]]/page.tsx
+++ b/templates/galley/app/api-reference/[[...slug]]/page.tsx
@@ -5,8 +5,10 @@ import { loadDocsConfig, loadOpenApiSpecForBuild } from '@inkform/framework/cont
 import { findOperation, parseOpenApi } from '@inkform/framework/openapi';
 import { parseOpenApiDocument } from '@inkform/framework/openapi-engine/parse';
 import { buildNavTree } from '@inkform/framework/openapi-engine/nav';
-import { OperationPage, ReferenceSidebar } from '@inkform/framework/openapi-render';
+import { OperationPage, buildReferenceSidebarGroups } from '@inkform/framework/openapi-render';
 import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
 import { apiBasePath, apiTab, withContentNavLinks } from '@/lib/route';
 
 export const dynamicParams = false;
@@ -95,7 +97,14 @@ export default async function ApiReferencePage({ params }: { params: Promise<{ s
       logo={topBar.logo}
       topNav={topBar.topNav}
       topActions={topBar.topActions}
-      sidebar={<ReferenceSidebar tree={tree} basePath={basePath} activeOperationId={activeOperationId} />}
+      cta={topBar.cta}
+      sidebar={
+        <CollapsibleSidebar
+          title={tab.tab}
+          groups={buildReferenceSidebarGroups(tree, basePath, activeOperationId)}
+          footer={<SidebarFooter />}
+        />
+      }
       hideToc
     >
       {content}
diff --git a/templates/galley/app/blog/[slug]/page.tsx b/templates/galley/app/blog/[slug]/page.tsx
index 952691f..9282d33 100644
--- a/templates/galley/app/blog/[slug]/page.tsx
+++ b/templates/galley/app/blog/[slug]/page.tsx
@@ -27,7 +27,7 @@ export default async function BlogPostPage({ params }: { params: Promise<{ slug:
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>{post.title}</h1>
         <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
diff --git a/templates/galley/app/blog/page.tsx b/templates/galley/app/blog/page.tsx
index 79bffff..7a04806 100644
--- a/templates/galley/app/blog/page.tsx
+++ b/templates/galley/app/blog/page.tsx
@@ -12,7 +12,7 @@ export default function BlogIndexPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Blog</h1>
         {posts.length === 0 ? (
diff --git a/templates/galley/app/changelog/page.tsx b/templates/galley/app/changelog/page.tsx
index 05cbac9..890f6a9 100644
--- a/templates/galley/app/changelog/page.tsx
+++ b/templates/galley/app/changelog/page.tsx
@@ -13,7 +13,7 @@ export default function ChangelogPage() {
   const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
 
   return (
-    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} hideSidebar hideToc>
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
       <div className="fw-prose">
         <h1>Changelog</h1>
         {entries.length === 0 ? <p>No entries yet.</p> : null}
diff --git a/templates/galley/app/theme.css b/templates/galley/app/theme.css
index cdfc6c3..f4c28f2 100644
--- a/templates/galley/app/theme.css
+++ b/templates/galley/app/theme.css
@@ -1,16 +1,14 @@
 /*
  * Galley theme — token overrides for @inkform/framework.
+ * Structure (header/sidebar/drawer/nav) is Canopy's, unchanged — see the
+ * sections below. This file only replaces the TOKENS: Inkform's own design
+ * system, a printer's galley. Warm opaque paper + ink, one editorial
+ * "Proof" red-pencil accent (#C24E3D, unchanged between light/dark). Depth
+ * from paper layering + hairlines, never heavy shadow or gradient. Values
+ * below are lifted directly from the `inkform-design` skill's
+ * tokens/{colors,effects,typography}.css — the authoritative source; do not
+ * hand-tune a value here without checking there first.
  * This file is imported AFTER framework/styles.css so its declarations win.
- * Only --fw-* tokens and small Galley-specific accents are set here.
- * The framework's structural CSS is untouched.
- *
- * Identity: Inkform's own design system — a printer's galley. Warm opaque
- * paper + ink, one editorial "Proof" red-pencil accent (#C24E3D, unchanged
- * between light/dark). Depth from paper layering + hairlines, never heavy
- * shadow or gradient. Values below are lifted directly from the
- * `inkform-design` skill's tokens/{colors,effects,typography}.css — the
- * authoritative source; do not hand-tune a value here without checking there
- * first.
  */
 
 /* ── Font variables ───────────────────────────────────────────────────────
@@ -97,8 +95,305 @@ html.dark {
   --fw-method-options: #aba79a;
 }
 
-/* Top bar (tabs/anchors/nav links/CTA/brand) is now styled by the shared
-   framework layer (packages/framework/src/styles/layout.css) — it only
-   ever consumed --fw-* tokens here, so there was nothing theme-specific
-   left to override for Galley. See Mono's theme.css for an example of a
-   theme that DOES need a delta on top of the shared base. */
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Galley's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-galley-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-galley-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-galley-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-galley-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-galley-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-galley-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-galley-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-galley-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-galley-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-galley-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-galley-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-galley-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-galley-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-galley-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-galley-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-galley-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-galley-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-galley-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 1rem;
+  overflow: hidden;
+}
diff --git a/templates/galley/components/collapsible-sidebar.tsx b/templates/galley/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..8e2d20c
--- /dev/null
+++ b/templates/galley/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Galley's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-galley-sidebar-rail">
+        <button
+          type="button"
+          className="fw-galley-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-galley-sidebar-heading">
+        <span className="fw-galley-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-galley-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/templates/galley/components/sidebar-footer.tsx b/templates/galley/components/sidebar-footer.tsx
new file mode 100644
index 0000000..7280ec9
--- /dev/null
+++ b/templates/galley/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Galley doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-galley-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-galley-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-galley-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-galley-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-galley-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-galley-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/templates/galley/components/top-bar.tsx b/templates/galley/components/top-bar.tsx
index 61dc77a..13d637f 100644
--- a/templates/galley/components/top-bar.tsx
+++ b/templates/galley/components/top-bar.tsx
@@ -1,7 +1,6 @@
 import type { ReactNode } from 'react';
 import Link from 'next/link';
 import { AskAi } from '@inkform/framework/ask-ai';
-import { ThemeToggle } from '@inkform/framework/theme-toggle';
 import { SearchDialog } from '@inkform/framework/search-dialog';
 import type { DocsConfig } from '@inkform/framework';
 import { docTabs } from '@inkform/framework';
@@ -29,6 +28,12 @@ function Logo({ config }: { config: DocsConfig }) {
 }
 
 // ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Galley's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Galley-specific CSS.
 
 function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
   const tabs = docTabs(config);
@@ -82,12 +87,27 @@ export interface TopBarParts {
   logo: ReactNode;
   topNav: ReactNode;
   topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
 }
 
 /**
- * Build the three DocsShell header slot contents for Aurora.
- * Server component — client islands (SearchDialog, ThemeToggle, AskAi) are
- * already marked 'use client' in the framework.
+ * Build the three DocsShell header slot contents for Galley.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-galley-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
  */
 export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
   const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
@@ -114,21 +134,23 @@ export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts
 
   const topActions = (
     <>
-      <SearchDialog />
-      <ThemeToggle />
-      <AskAi enabled={aiEnabled} product={config.name} />
-      {config.cta ? (
-        <a
-          href={config.cta.href}
-          className="fw-topnav-cta"
-          target={config.cta.href.startsWith('http') ? '_blank' : undefined}
-          rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
-        >
-          {config.cta.label}
-        </a>
-      ) : null}
+      <div className="fw-galley-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
     </>
   );
 
-  return { logo, topNav, topActions };
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
 }
diff --git a/templates/galley/content/docs/docs.json b/templates/galley/content/docs/docs.json
index bb4e9e7..74bd396 100644
--- a/templates/galley/content/docs/docs.json
+++ b/templates/galley/content/docs/docs.json
@@ -3,15 +3,7 @@
   "version": "1.0.0",
   "logo": "/logo.svg",
   "favicon": "/favicon.svg",
-  "colors": { "primary": "#c24e3d" },
-  "navbarLinks": [
-    { "name": "Support", "href": "mailto:support@example.com" }
-  ],
-  "anchors": [
-    { "name": "Documentation", "href": "/", "icon": "book" },
-    { "name": "GitHub", "href": "https://github.com/inkform-dev/framework", "icon": "github" }
-  ],
-  "cta": { "label": "Dashboard", "href": "https://example.com/dashboard" },
+  "colors": { "primary": "#43c200" },
   "tabs": [
     {
       "tab": "Guides",
diff --git a/templates/galley/content/docs/index.mdx b/templates/galley/content/docs/index.mdx
index d851ecc..5165c61 100644
--- a/templates/galley/content/docs/index.mdx
+++ b/templates/galley/content/docs/index.mdx
@@ -1,15 +1,14 @@
 ---
 title: Introduction
-description: Welcome to Galley — Inkform's own warm paper-and-ink documentation theme.
+description: Welcome to your new documentation site.
 ---
 
-# Welcome to Galley
+# Introduction
 
-Galley is Inkform's own design system for documentation — warm paper + ink, one
-editorial "Proof" red-pencil accent, a serif prose voice beside a mono machine
-voice. Powered by [`@inkform/framework`](https://github.com/inkform-dev/framework):
+Welcome to the home of your new documentation. This starter is a complete,
+deployable docs site powered by [`@inkform/framework`](https://github.com/inkform-dev/framework):
 write Markdown, commit it, and ship a fast, searchable, themeable site — no CMS,
-no database, no visual opinions in the way.
+no database.
 
 <Frame caption="Your docs, your repo, your deploy.">
   ![Hero](/hero.svg)
diff --git a/templates/galley/content/docs/quickstart.mdx b/templates/galley/content/docs/quickstart.mdx
index 43dc359..b047822 100644
--- a/templates/galley/content/docs/quickstart.mdx
+++ b/templates/galley/content/docs/quickstart.mdx
@@ -64,3 +64,13 @@ Then register it in `content/docs/docs.json`:
   The `slug` is the URL path and `file` is the MDX file relative to
   `content/docs`. Nest pages with a `children` array.
 </Tip>
+
+## Cross-linking to the API Reference
+
+If a project has an OpenAPI spec configured, <ApiLink operationId="list-plants">any doc page can link straight to a specific operation</ApiLink> with `<ApiLink operationId="...">`. The link is validated against the spec at build time — a typo or renamed operation fails the build instead of shipping a dead link.
+
+## Custom widgets
+
+Put a component at `widgets/<Name>.tsx`, register it in `widgets/index.ts`, and use it directly in MDX (or from the CMS's widget block) as `<Name />`:
+
+<Counter start={3} />
diff --git a/templates/galley/lib/route.tsx b/templates/galley/lib/route.tsx
index db313d1..4a7f976 100644
--- a/templates/galley/lib/route.tsx
+++ b/templates/galley/lib/route.tsx
@@ -1,5 +1,5 @@
 /**
- * lib/route.ts — Aurora routing core.
+ * lib/route.ts — Galley routing core.
  *
  * Resolves a slug array from the catch-all route into a doc page, generates
  * static params, and builds sidebar groups. The API Reference tab is NOT
diff --git a/templates/galley/package.json b/templates/galley/package.json
index 6e2340f..ac4118d 100644
--- a/templates/galley/package.json
+++ b/templates/galley/package.json
@@ -1,8 +1,8 @@
 {
   "name": "@inkform/theme-galley",
-  "version": "0.2.0",
+  "version": "0.1.0",
   "private": true,
-  "description": "Galley — the warm paper-and-ink editorial theme for @inkform/framework (Inkform's own design system).",
+  "description": "Galley — Inkform's own design system as a documentation theme for @inkform/framework. Warm paper + ink, a single editorial proof-red accent, Newsreader serif prose beside a General Sans UI voice.",
   "license": "MIT",
   "scripts": {
     "dev": "next dev",
@@ -20,9 +20,9 @@
   },
   "devDependencies": {
     "@types/node": "^20",
-    "pagefind": "^1.5.0",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "pagefind": "^1.5.2",
     "typescript": "^5"
   }
 }
diff --git a/templates/galley/public/favicon.svg b/templates/galley/public/favicon.svg
index 43d31e9..c32dc4f 100644
--- a/templates/galley/public/favicon.svg
+++ b/templates/galley/public/favicon.svg
@@ -1,7 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="Base favicon">
-  <!-- Neutral dark background square -->
-  <rect width="32" height="32" rx="7" fill="#0d0d0d"/>
-  <!-- Stacked squares mark -->
-  <rect x="8"  y="14" width="14" height="10" rx="2" fill="#c24e3d"/>
-  <rect x="10" y="8"  width="14" height="10" rx="2" fill="#d6796b" opacity="0.5"/>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="Galley favicon">
+  <!-- Ink-1 background square, matching the wordmark's letter + accent-period pattern in miniature. -->
+  <rect width="32" height="32" rx="7" fill="#191813"/>
+  <text x="7" y="23" font-family="Newsreader, Georgia, 'Times New Roman', serif" font-size="19" font-weight="500" fill="#fcfbf7">G</text>
+  <circle cx="24.5" cy="21.5" r="2.25" fill="#c24e3d"/>
 </svg>
diff --git a/templates/galley/public/hero.svg b/templates/galley/public/hero.svg
index 3ace538..2185115 100644
--- a/templates/galley/public/hero.svg
+++ b/templates/galley/public/hero.svg
@@ -1,65 +1,65 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" fill="none" role="img" aria-label="Base documentation hero">
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" fill="none" role="img" aria-label="Galley documentation hero">
   <!-- Clean neutral dark background -->
-  <rect width="800" height="360" rx="10" fill="#0d0d0d"/>
+  <rect width="800" height="360" rx="10" fill="#131210"/>
   <!-- Subtle dot grid pattern -->
   <defs>
     <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
-      <circle cx="1" cy="1" r="1" fill="#222222"/>
+      <circle cx="1" cy="1" r="1" fill="#242320"/>
     </pattern>
   </defs>
   <rect width="800" height="360" fill="url(#dots)"/>
 
   <!-- Left: stacked-square composition (brand mark, large) -->
-  <rect x="60"  y="160" width="80" height="60" rx="6" fill="#1a1a1a" stroke="#c24e3d" stroke-width="1.5"/>
-  <rect x="80"  y="140" width="80" height="60" rx="6" fill="#141414" stroke="#333333" stroke-width="1"/>
-  <rect x="100" y="120" width="80" height="60" rx="6" fill="#111111" stroke="#222222" stroke-width="1"/>
+  <rect x="60"  y="160" width="80" height="60" rx="6" fill="#1b1a17" stroke="#c24e3d" stroke-width="1.5"/>
+  <rect x="80"  y="140" width="80" height="60" rx="6" fill="#1b1a17" stroke="#3b3833" stroke-width="1"/>
+  <rect x="100" y="120" width="80" height="60" rx="6" fill="#131210" stroke="#242320" stroke-width="1"/>
   <!-- Blue accent square on top layer -->
   <rect x="108" y="128" width="20" height="20" rx="3" fill="#c24e3d" opacity="0.9"/>
-  <rect x="134" y="128" width="36" height="6"  rx="2" fill="#333333"/>
-  <rect x="134" y="140" width="26" height="6"  rx="2" fill="#2a2a2a"/>
-  <rect x="108" y="155" width="62" height="6"  rx="2" fill="#2a2a2a"/>
+  <rect x="134" y="128" width="36" height="6"  rx="2" fill="#3b3833"/>
+  <rect x="134" y="140" width="26" height="6"  rx="2" fill="#3b3833"/>
+  <rect x="108" y="155" width="62" height="6"  rx="2" fill="#3b3833"/>
 
   <!-- Right: docs/browser window mock -->
-  <rect x="440" y="55" width="310" height="230" rx="8" fill="#141414" stroke="#222222" stroke-width="1"/>
+  <rect x="440" y="55" width="310" height="230" rx="8" fill="#1b1a17" stroke="#242320" stroke-width="1"/>
   <!-- Window top bar -->
-  <rect x="440" y="55" width="310" height="36" rx="8" fill="#1a1a1a"/>
-  <rect x="440" y="79" width="310" height="12" fill="#1a1a1a"/>
+  <rect x="440" y="55" width="310" height="36" rx="8" fill="#1b1a17"/>
+  <rect x="440" y="79" width="310" height="12" fill="#1b1a17"/>
   <!-- Address-bar pill -->
-  <rect x="510" y="66" width="170" height="14" rx="7" fill="#222222"/>
+  <rect x="510" y="66" width="170" height="14" rx="7" fill="#242320"/>
   <!-- Back / fwd dots (nav circles) -->
-  <circle cx="460" cy="73" r="5" fill="#2a2a2a"/>
-  <circle cx="474" cy="73" r="5" fill="#2a2a2a"/>
+  <circle cx="460" cy="73" r="5" fill="#3b3833"/>
+  <circle cx="474" cy="73" r="5" fill="#3b3833"/>
   <!-- Sidebar strip -->
-  <rect x="440" y="91" width="80" height="194" rx="0" fill="#111111"/>
-  <rect x="440" y="91" width="80" height="194" rx="0" fill="#111111"/>
+  <rect x="440" y="91" width="80" height="194" rx="0" fill="#131210"/>
+  <rect x="440" y="91" width="80" height="194" rx="0" fill="#131210"/>
   <!-- Sidebar links -->
-  <rect x="452" y="104" width="52" height="6" rx="3" fill="#333333"/>
+  <rect x="452" y="104" width="52" height="6" rx="3" fill="#3b3833"/>
   <rect x="452" y="118" width="44" height="6" rx="3" fill="#c24e3d" opacity="0.7"/>
-  <rect x="452" y="132" width="48" height="6" rx="3" fill="#2a2a2a"/>
-  <rect x="452" y="146" width="40" height="6" rx="3" fill="#2a2a2a"/>
-  <rect x="452" y="160" width="50" height="6" rx="3" fill="#2a2a2a"/>
-  <rect x="452" y="182" width="52" height="6" rx="3" fill="#333333"/>
-  <rect x="452" y="196" width="44" height="6" rx="3" fill="#2a2a2a"/>
-  <rect x="452" y="210" width="48" height="6" rx="3" fill="#2a2a2a"/>
-  <rect x="452" y="224" width="36" height="6" rx="3" fill="#2a2a2a"/>
+  <rect x="452" y="132" width="48" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="146" width="40" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="160" width="50" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="182" width="52" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="196" width="44" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="210" width="48" height="6" rx="3" fill="#3b3833"/>
+  <rect x="452" y="224" width="36" height="6" rx="3" fill="#3b3833"/>
   <!-- Active sidebar indicator -->
   <rect x="440" y="115" width="3" height="14" rx="1.5" fill="#c24e3d"/>
   <!-- Content area lines -->
-  <rect x="534" y="104" width="120" height="10" rx="3" fill="#222222"/>
-  <rect x="534" y="122" width="200" height="6"  rx="2" fill="#1e1e1e"/>
-  <rect x="534" y="136" width="180" height="6"  rx="2" fill="#1e1e1e"/>
-  <rect x="534" y="150" width="195" height="6"  rx="2" fill="#1e1e1e"/>
+  <rect x="534" y="104" width="120" height="10" rx="3" fill="#242320"/>
+  <rect x="534" y="122" width="200" height="6"  rx="2" fill="#242320"/>
+  <rect x="534" y="136" width="180" height="6"  rx="2" fill="#242320"/>
+  <rect x="534" y="150" width="195" height="6"  rx="2" fill="#242320"/>
   <!-- Code block mock -->
-  <rect x="534" y="170" width="200" height="52" rx="4" fill="#111111" stroke="#222222" stroke-width="1"/>
+  <rect x="534" y="170" width="200" height="52" rx="4" fill="#131210" stroke="#242320" stroke-width="1"/>
   <rect x="542" y="179" width="70"  height="5"  rx="2" fill="#c24e3d" opacity="0.5"/>
-  <rect x="542" y="192" width="110" height="5"  rx="2" fill="#2a2a2a"/>
-  <rect x="542" y="205" width="90"  height="5"  rx="2" fill="#2a2a2a"/>
+  <rect x="542" y="192" width="110" height="5"  rx="2" fill="#3b3833"/>
+  <rect x="542" y="205" width="90"  height="5"  rx="2" fill="#3b3833"/>
   <rect x="542" y="218" width="55"  height="5"  rx="2" fill="#d6796b" opacity="0.35"/>
 
   <!-- Bottom left: subtle text placeholder lines -->
-  <rect x="60" y="242" width="280" height="8" rx="3" fill="#1e1e1e"/>
-  <rect x="60" y="258" width="240" height="6" rx="2" fill="#1a1a1a"/>
-  <rect x="60" y="272" width="200" height="6" rx="2" fill="#1a1a1a"/>
+  <rect x="60" y="242" width="280" height="8" rx="3" fill="#242320"/>
+  <rect x="60" y="258" width="240" height="6" rx="2" fill="#1b1a17"/>
+  <rect x="60" y="272" width="200" height="6" rx="2" fill="#1b1a17"/>
 
   <!-- Blue accent bottom rule -->
   <rect x="60" y="300" width="40" height="3" rx="1.5" fill="#c24e3d"/>
diff --git a/templates/galley/public/logo.svg b/templates/galley/public/logo.svg
index 5e9185b..c4c4753 100644
--- a/templates/galley/public/logo.svg
+++ b/templates/galley/public/logo.svg
@@ -1,7 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 32" fill="none" role="img" aria-label="Base">
-  <!-- Stacked squares mark (base/foundation metaphor) -->
-  <rect x="2" y="12" width="12" height="12" rx="2" fill="#c24e3d"/>
-  <rect x="6" y="7"  width="12" height="12" rx="2" fill="#c24e3d" opacity="0.4"/>
-  <!-- Wordmark -->
-  <text x="24" y="21" font-family="ui-sans-serif, system-ui, -apple-system, sans-serif" font-size="14" font-weight="700" letter-spacing="-0.02em" fill="currentColor">Base</text>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 110 32" fill="none" role="img" aria-label="Galley">
+  <!-- Typographic wordmark only — per the inkform-design skill's own
+       brand-wordmark spec: no logo was provided, the mark is the name set
+       in the serif display face with a proof-red accent period. -->
+  <text x="0" y="22" font-family="Newsreader, Georgia, 'Times New Roman', serif" font-size="20" font-weight="500" letter-spacing="-0.02em" fill="#191813">Galley<tspan fill="#c24e3d">.</tspan></text>
 </svg>
diff --git a/templates/galley/widgets/Counter.tsx b/templates/galley/widgets/Counter.tsx
new file mode 100644
index 0000000..d786325
--- /dev/null
+++ b/templates/galley/widgets/Counter.tsx
@@ -0,0 +1,13 @@
+'use client';
+
+import { useState } from 'react';
+
+/** Real test widget proving MDX/CMS content can render a user-registered component, not the Fallback placeholder. */
+export function Counter({ start = 0 }: { start?: number }) {
+  const [count, setCount] = useState(start);
+  return (
+    <button type="button" className="fw-widget-counter" onClick={() => setCount((c) => c + 1)}>
+      Widget count: {count}
+    </button>
+  );
+}
diff --git a/templates/galley/widgets/index.ts b/templates/galley/widgets/index.ts
index e529973..a04190f 100644
--- a/templates/galley/widgets/index.ts
+++ b/templates/galley/widgets/index.ts
@@ -1,4 +1,5 @@
 import type { ComponentType } from 'react';
+import { Counter } from './Counter';
 
 /**
  * Custom widget registry. Put your component at widgets/<Name>.tsx, import
@@ -6,7 +7,7 @@ import type { ComponentType } from 'react';
  * MDX/CMS content uses (<Name ... />). Framework docs: "Custom Widgets."
  */
 const widgets: Record<string, ComponentType<any>> = {
-  // Example: MyChart,
+  Counter,
 };
 
 export default widgets;
diff --git a/templates/shadcn/.env.example b/templates/shadcn/.env.example
new file mode 100644
index 0000000..39cd584
--- /dev/null
+++ b/templates/shadcn/.env.example
@@ -0,0 +1,14 @@
+# ── Required ─────────────────────────────────────────────────────────────────
+NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# ── AI assistant (disabled by default) ───────────────────────────────────────
+# Set to "true" to enable the Ask AI widget in the top bar.
+# The widget is rendered even when disabled; it shows an informational notice.
+NEXT_PUBLIC_DOCS_AI_ENABLED=false
+
+# The following vars only matter when NEXT_PUBLIC_DOCS_AI_ENABLED=true.
+# They are read by the /api/ask route at runtime (server-only, never sent to
+# the browser).
+# DOCS_AI_PROVIDER=anthropic
+# DOCS_AI_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
diff --git a/templates/shadcn/.gitignore b/templates/shadcn/.gitignore
new file mode 100644
index 0000000..da1f289
--- /dev/null
+++ b/templates/shadcn/.gitignore
@@ -0,0 +1,8 @@
+node_modules
+.next
+out
+.env*.local
+.vercel
+*.tsbuildinfo
+.DS_Store
+public/_pagefind
diff --git a/templates/shadcn/README.md b/templates/shadcn/README.md
new file mode 100644
index 0000000..7ea0974
--- /dev/null
+++ b/templates/shadcn/README.md
@@ -0,0 +1,168 @@
+# Shadcn — @inkform/theme-shadcn
+
+Shadcn reproduces shadcn/ui's own default look on `@inkform/framework`: Zinc
+grayscale surfaces, a monochrome primary that inverts between light and dark
+(a near-black button on white, a near-white button on black — shadcn ships
+no brand hue by default), 0.5rem radius, and Tailwind's own soft shadow
+scale. Structurally identical to Canopy (same header, sidebar, mobile
+drawer, and search patterns — only the token layer differs): a centered
+header search bar, underline tab indicators, no header CTA, a whole-sidebar
+collapse toggle, and a sidebar-footer language + theme switcher. Inter
+throughout, JetBrains Mono for code. It supports Guides + API Reference tabs
+out of the box.
+
+---
+
+## Run locally
+
+```bash
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+If this is a fresh clone, copy the env file first:
+
+```bash
+cp .env.example .env.local
+# Edit NEXT_PUBLIC_SITE_URL if needed, then:
+npm run dev
+```
+
+---
+
+## Add content
+
+All content lives in `content/docs/`.
+
+### Navigation — `content/docs/docs.json`
+
+`docs.json` controls the site name, logo, tabs, and page hierarchy:
+
+```jsonc
+{
+  "name": "Your Docs",
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx" },
+            { "title": "Quickstart",   "slug": "quickstart", "file": "quickstart.mdx" }
+          ]
+        }
+      ]
+    },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+- `slug` is the URL path (empty string = the index `/`).
+- `file` is the MDX file path relative to `content/docs/`.
+- The `openapi` field on a tab points to a JSON/YAML spec file in `content/docs/`.
+- Shadcn's header has no CTA button and no extra anchor/nav links by design
+  (matching Palm) — `cta`, `anchors`, and `navbarLinks` are all still
+  supported by the schema and will render if you add them back, they're
+  just omitted from this theme's sample `docs.json`.
+
+### Writing MDX
+
+Add `.mdx` files under `content/docs/` and register them in `docs.json`. Shadcn
+supports all built-in blocks: `<Note>`, `<Tip>`, `<Warning>`, `<Card>`,
+`<CardGroup>`, `<Steps>`, `<Step>`, `<Tabs>`, `<Tab>`, `<CodeGroup>`,
+`<Accordion>`, `<ParamField>`, `<Frame>`, and more.
+
+### API Reference
+
+Replace `content/docs/openapi.json` with your own OpenAPI 3.x spec (JSON or
+YAML). The site auto-generates a sidebar and per-operation pages. No extra
+configuration needed — just point the `openapi` tab field at your spec file.
+
+### Blog and Changelog
+
+Both ship wired and ready — `/blog` (list + post pages) and `/changelog`
+(single dated list) render automatically once you add content:
+
+```
+content/
+  blog/
+    my-first-post.mdx    # frontmatter: title, date, author, tags, description
+    series.json          # optional — group posts into a series
+  changelog/
+    2026-01-15-v1.mdx     # frontmatter: title, date, version
+```
+
+Both nav links only appear once at least one entry exists — an empty
+`content/blog`/`content/changelog` (or no folder at all) keeps the top nav
+clean and the pages still render a "no posts yet" state if visited directly.
+
+---
+
+## Maintain
+
+### Slug redirects
+
+When a page's URL changes, record the old → new slug mapping in
+`content/docs/slug-history.json` to issue a 301 redirect:
+
+```json
+{
+  "old-page-slug": "new-page-slug",
+  "essentials/old-name": "essentials/new-name"
+}
+```
+
+### Sidebar collapse + footer
+
+`components/collapsible-sidebar.tsx` is Shadcn-specific (not part of the
+shared framework): a single toggle collapses the whole nav column to a thin
+rail and back — real `useState`, not a static arrow — matching what
+palm.mintlify.site actually does (verified directly: its arrow collapses the
+entire sidebar, not one group at a time). `components/sidebar-footer.tsx`
+renders the language label and the system/light/dark theme trio at the
+bottom of the sidebar; the theme trio reads and writes the same
+`localStorage['fw-theme']` + `dark` class the framework's own theme init
+script already uses, so there's no flash on load and no shared-framework
+change was needed to add the third "system" state.
+
+### Ask AI widget
+
+The Ask AI button is built in but **disabled by default**. Enable it by setting
+`NEXT_PUBLIC_DOCS_AI_ENABLED=true` in `.env.local`, plus `DOCS_AI_PROVIDER`
+(`anthropic` | `openai` | `google`, default `anthropic`) and that provider's
+API key (e.g. `ANTHROPIC_API_KEY`) — see `.env.example`. Answers are grounded
+in this site's own content (`@inkform/framework/ai`'s `askDocs()`), not a
+generic chatbot.
+
+---
+
+## Deploy to Vercel
+
+1. Push this directory (or the whole monorepo) to a GitHub repository.
+2. In the Vercel dashboard, click **Add New → Project** and import the repo.
+3. **Framework preset**: Next.js.
+4. **Root directory**: set to the path of this folder if deploying as a
+   standalone (e.g. `templates/shadcn`), or leave blank if deploying the
+   directory itself.
+5. Add the environment variable `NEXT_PUBLIC_SITE_URL` (your production URL,
+   e.g. `https://docs.example.com`).
+6. Click **Deploy**.
+
+For a custom domain, go to **Settings → Domains** in your Vercel project and add
+your domain. Vercel handles SSL automatically.
+
+---
+
+## Deploy to AWS Amplify
+
+1. Connect the repo in the Amplify console.
+2. Set the **Build settings** manually if auto-detection picks the wrong preset:
+   - **Build command**: `npm ci && npm run build`
+   - **Output directory**: `.next`
+   - **Framework**: Next.js (SSR)
+3. Add the `NEXT_PUBLIC_SITE_URL` environment variable under
+   **Environment variables**.
+4. Deploy. Amplify Hosting supports Next.js SSR/ISR natively since Gen 2.
diff --git a/templates/shadcn/app/[[...slug]]/page.tsx b/templates/shadcn/app/[[...slug]]/page.tsx
new file mode 100644
index 0000000..ff89b53
--- /dev/null
+++ b/templates/shadcn/app/[[...slug]]/page.tsx
@@ -0,0 +1,66 @@
+import { notFound } from 'next/navigation';
+import { Mdx } from '@inkform/framework/mdx';
+import { DocsShell, TocList, Pagination } from '@inkform/framework/docs-shell';
+import { docNeighbours } from '@inkform/framework';
+import { loadDocsConfig, extractHeadings } from '@inkform/framework/content';
+import { siteMdxComponents } from '@/mdx-components';
+import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
+import { renderIcon } from '@/lib/icons';
+import { resolveRoute, listAllRoutes, sidebarForDoc, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+export function generateStaticParams() {
+  const config = loadDocsConfig();
+  if (!config) return [{ slug: [] as string[] }];
+  const routes = listAllRoutes(config);
+  // Next.js optional catch-all: [] = index, [...rest] = nested. Map [] → undefined
+  // to match the [[...slug]] convention (both work, but undefined is canonical).
+  return routes.map((slug) => ({ slug: slug.length === 0 ? undefined : slug }));
+}
+
+// ── Metadata ─────────────────────────────────────────────────────────────────
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) return {};
+  return { title: route.ref.title };
+}
+
+// ── Page ──────────────────────────────────────────────────────────────────────
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const route = resolveRoute(slug);
+  if (!route) notFound();
+
+  const { config, ref, page, tab } = route;
+  const headings = extractHeadings(page.content);
+  const { prev, next } = docNeighbours(config, ref.slug);
+  const sidebar = sidebarForDoc(config, tab, ref.slug, renderIcon);
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  return (
+    <DocsShell
+      contentType="doc"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      cta={topBar.cta}
+      sidebar={<CollapsibleSidebar title={tab.tab} groups={sidebar} footer={<SidebarFooter />} />}
+      toc={headings.length > 0 ? <TocList headings={headings} /> : undefined}
+      hideToc={headings.length === 0}
+    >
+      <Mdx source={page.content} components={siteMdxComponents} />
+      <Pagination
+        prev={prev ? { title: prev.title, href: '/' + prev.slug } : null}
+        next={next ? { title: next.title, href: '/' + next.slug } : null}
+      />
+    </DocsShell>
+  );
+}
diff --git a/templates/shadcn/app/api-reference/[[...slug]]/page.tsx b/templates/shadcn/app/api-reference/[[...slug]]/page.tsx
new file mode 100644
index 0000000..304010d
--- /dev/null
+++ b/templates/shadcn/app/api-reference/[[...slug]]/page.tsx
@@ -0,0 +1,113 @@
+import type { ReactNode } from 'react';
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadDocsConfig, loadOpenApiSpecForBuild } from '@inkform/framework/content';
+import { findOperation, parseOpenApi } from '@inkform/framework/openapi';
+import { parseOpenApiDocument } from '@inkform/framework/openapi-engine/parse';
+import { buildNavTree } from '@inkform/framework/openapi-engine/nav';
+import { OperationPage, buildReferenceSidebarGroups } from '@inkform/framework/openapi-render';
+import { buildTopBar } from '@/components/top-bar';
+import { CollapsibleSidebar } from '@/components/collapsible-sidebar';
+import { SidebarFooter } from '@/components/sidebar-footer';
+import { apiBasePath, apiTab, withContentNavLinks } from '@/lib/route';
+
+export const dynamicParams = false;
+
+/**
+ * Loads the spec twice — once via parseOpenApi (the narrow OpenApiModel
+ * used for ApiLink-style operation lookup) and once via parseOpenApiDocument
+ * + buildNavTree (the full dereferenced document, needed for the nav tree).
+ * Both bundle/dereference the same spec independently; negligible at this
+ * spec's size and this only runs at build time, but worth consolidating
+ * into one pass if a second native-renderer consumer needs both shapes.
+ */
+async function loadReference() {
+  const config = loadDocsConfig();
+  if (!config) return null;
+  const tab = apiTab(config);
+  if (!tab?.openapi || tab.apiReference?.renderer === 'scalar') return null;
+
+  const spec = await loadOpenApiSpecForBuild(tab.openapi);
+  if (!spec) return null;
+
+  const [model, { schema }] = await Promise.all([
+    parseOpenApi(spec.raw, spec.format),
+    parseOpenApiDocument(spec.raw, { format: spec.format }),
+  ]);
+
+  return { config, tab, model, tree: buildNavTree(schema) };
+}
+
+export async function generateStaticParams() {
+  const ref = await loadReference();
+  if (!ref) return [{ slug: undefined }];
+
+  const params: { slug?: string[] }[] = [{ slug: undefined }];
+  for (const group of ref.tree.tagGroups) {
+    for (const op of group.operations) {
+      params.push({ slug: ['operations', op.operationId] });
+    }
+  }
+  return params;
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) return {};
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(ref.model, slug[1]);
+    if (op) return { title: `${op.summary} · ${ref.model.info.title}` };
+  }
+  return { title: ref.model.info.title };
+}
+
+export default async function ApiReferencePage({ params }: { params: Promise<{ slug?: string[] }> }) {
+  const { slug } = await params;
+  const ref = await loadReference();
+  if (!ref) notFound();
+
+  const { config, tab, model, tree } = ref;
+  const basePath = `/${apiBasePath(config)}`;
+  const topBar = buildTopBar(withContentNavLinks(config), tab.tab);
+
+  let content: ReactNode;
+  let activeOperationId: string | undefined;
+
+  if (slug?.[0] === 'operations' && slug[1]) {
+    const op = findOperation(model, slug[1]);
+    if (!op) notFound();
+    activeOperationId = op.operationId;
+    content = <OperationPage operation={op} servers={model.servers} />;
+  } else {
+    content = (
+      <div className="fw-apiref">
+        <div className="fw-apiref-header">
+          <h1 className="fw-apiref-title">{model.info.title}</h1>
+          {model.info.description ? <p className="fw-apiref-desc">{model.info.description}</p> : null}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <DocsShell
+      contentType="api"
+      logo={topBar.logo}
+      topNav={topBar.topNav}
+      topActions={topBar.topActions}
+      cta={topBar.cta}
+      sidebar={
+        <CollapsibleSidebar
+          title={tab.tab}
+          groups={buildReferenceSidebarGroups(tree, basePath, activeOperationId)}
+          footer={<SidebarFooter />}
+        />
+      }
+      hideToc
+    >
+      {content}
+    </DocsShell>
+  );
+}
diff --git a/templates/shadcn/app/api/ask/route.ts b/templates/shadcn/app/api/ask/route.ts
new file mode 100644
index 0000000..d9da707
--- /dev/null
+++ b/templates/shadcn/app/api/ask/route.ts
@@ -0,0 +1,60 @@
+import { askDocs } from '@inkform/framework/ai';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+export const runtime = 'nodejs';
+
+/**
+ * POST /api/ask — AI assistant endpoint (feature-flagged).
+ *
+ * Grounded in this site's own content via askDocs() (@inkform/framework/ai)
+ * — the same search/getDoc/getOperation retrieval the MCP server uses, not
+ * a separate implementation. BYO model: set DOCS_AI_PROVIDER
+ * ('anthropic' | 'openai' | 'google', default 'anthropic') and that
+ * provider's own API key env var (ANTHROPIC_API_KEY, etc.) — see
+ * packages/framework/src/ai/provider.ts.
+ *
+ * Metered billing for the platform-hosted version of this endpoint is
+ * out of scope here — see inkform/PLATFORM_MCP_SCOPING.md for the sibling
+ * MCP billing question this will eventually need the same answer to.
+ */
+export async function POST(request: Request): Promise<Response> {
+  const enabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  if (!enabled) {
+    return Response.json(
+      {
+        error:
+          'AI assistant is disabled. Set NEXT_PUBLIC_DOCS_AI_ENABLED=true to enable it (configured in a later release).',
+      },
+      { status: 503 },
+    );
+  }
+
+  let messages: unknown;
+  try {
+    const body = (await request.json()) as { messages?: unknown };
+    messages = body?.messages;
+  } catch {
+    return Response.json({ error: 'Invalid request body.' }, { status: 400 });
+  }
+
+  if (!Array.isArray(messages) || messages.some((m) => typeof m?.role !== 'string' || typeof m?.content !== 'string')) {
+    return Response.json({ error: 'messages must be an array of { role, content }.' }, { status: 400 });
+  }
+
+  const config = loadDocsConfig();
+  // apiBasePath() returns a bare slug (e.g. "api-reference"); askDocs()
+  // expects a leading-slash base path to build clickable operation links.
+  const apiBase = config && apiBasePath(config);
+  try {
+    const result = await askDocs(messages, { apiBasePath: apiBase ? `/${apiBase}` : undefined });
+    return Response.json(result);
+  } catch (e) {
+    // Most likely cause: no API key configured for DOCS_AI_PROVIDER.
+    return Response.json(
+      { error: e instanceof Error ? e.message : 'The AI assistant is not configured correctly.' },
+      { status: 500 },
+    );
+  }
+}
diff --git a/templates/shadcn/app/blog/[slug]/page.tsx b/templates/shadcn/app/blog/[slug]/page.tsx
new file mode 100644
index 0000000..9282d33
--- /dev/null
+++ b/templates/shadcn/app/blog/[slug]/page.tsx
@@ -0,0 +1,40 @@
+import { notFound } from 'next/navigation';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadBlogPosts, loadBlogPost } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+  return loadBlogPosts().map((p) => ({ slug: p.slug }));
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  return { title: post?.title ?? 'Blog' };
+}
+
+export default async function BlogPostPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = loadBlogPost(slug);
+  if (!post) notFound();
+
+  const config = loadDocsConfig();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>{post.title}</h1>
+        <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+          {post.date} · {post.readingTime} min read{post.author ? ` · ${post.author}` : ''}
+        </p>
+      </div>
+      <Mdx source={post.content} components={siteMdxComponents} />
+    </DocsShell>
+  );
+}
diff --git a/templates/shadcn/app/blog/page.tsx b/templates/shadcn/app/blog/page.tsx
new file mode 100644
index 0000000..7a04806
--- /dev/null
+++ b/templates/shadcn/app/blog/page.tsx
@@ -0,0 +1,38 @@
+import Link from 'next/link';
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { loadBlogPosts } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+
+export const metadata = { title: 'Blog' };
+
+export default function BlogIndexPage() {
+  const config = loadDocsConfig();
+  const posts = loadBlogPosts();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="blog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Blog</h1>
+        {posts.length === 0 ? (
+          <p>No posts yet — check back soon.</p>
+        ) : (
+          <ul style={{ listStyle: 'none', padding: 0 }}>
+            {posts.map((p) => (
+              <li key={p.slug} style={{ marginBottom: '2rem' }}>
+                <Link href={`/blog/${p.slug}`}>
+                  <h2 style={{ marginBottom: '0.25rem' }}>{p.title}</h2>
+                </Link>
+                <p style={{ opacity: 0.7, fontSize: '0.875rem' }}>
+                  {p.date} · {p.readingTime} min read{p.author ? ` · ${p.author}` : ''}
+                </p>
+                {p.description ? <p>{p.description}</p> : null}
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </DocsShell>
+  );
+}
diff --git a/templates/shadcn/app/changelog/page.tsx b/templates/shadcn/app/changelog/page.tsx
new file mode 100644
index 0000000..890f6a9
--- /dev/null
+++ b/templates/shadcn/app/changelog/page.tsx
@@ -0,0 +1,33 @@
+import { DocsShell } from '@inkform/framework/docs-shell';
+import { Mdx } from '@inkform/framework/mdx';
+import { loadChangelogEntries } from '@inkform/framework/content';
+import { loadDocsConfig, withContentNavLinks } from '@/lib/route';
+import { buildTopBar } from '@/components/top-bar';
+import { siteMdxComponents } from '@/mdx-components';
+
+export const metadata = { title: 'Changelog' };
+
+export default function ChangelogPage() {
+  const config = loadDocsConfig();
+  const entries = loadChangelogEntries();
+  const topBar = config ? buildTopBar(withContentNavLinks(config), '') : null;
+
+  return (
+    <DocsShell contentType="changelog" logo={topBar?.logo} topNav={topBar?.topNav} topActions={topBar?.topActions} cta={topBar?.cta} hideSidebar hideToc>
+      <div className="fw-prose">
+        <h1>Changelog</h1>
+        {entries.length === 0 ? <p>No entries yet.</p> : null}
+      </div>
+      {entries.map((e) => (
+        <div key={e.slug} className="fw-prose" style={{ marginTop: '2rem' }}>
+          <p style={{ opacity: 0.7, fontSize: '0.875rem', marginBottom: '0.25rem' }}>
+            {e.date}
+            {e.version ? ` · v${e.version}` : ''}
+          </p>
+          <h2>{e.title}</h2>
+          <Mdx source={e.content} components={siteMdxComponents} />
+        </div>
+      ))}
+    </DocsShell>
+  );
+}
diff --git a/templates/shadcn/app/layout.tsx b/templates/shadcn/app/layout.tsx
new file mode 100644
index 0000000..ec39024
--- /dev/null
+++ b/templates/shadcn/app/layout.tsx
@@ -0,0 +1,43 @@
+import type { Metadata } from 'next';
+import { Inter, JetBrains_Mono } from 'next/font/google';
+import '@inkform/framework/styles.css';
+import './theme.css';
+import { themeInitScript } from '@inkform/framework/theme-toggle';
+import { loadDocsConfig } from '@inkform/framework/content';
+
+// One clean sans voice throughout — headings are the same face at heavier
+// weight, not a second typeface, matching shadcn/ui's own default
+// typography (no separate serif/display family).
+const inter = Inter({
+  subsets: ['latin'],
+  variable: '--font-sans',
+  display: 'swap',
+});
+
+const jetbrainsMono = JetBrains_Mono({
+  subsets: ['latin'],
+  variable: '--font-mono',
+  display: 'swap',
+});
+
+export async function generateMetadata(): Promise<Metadata> {
+  const config = loadDocsConfig();
+  const name = config?.name ?? 'Shadcn Docs';
+  return {
+    title: { default: name, template: `%s · ${name}` },
+    description: `Documentation for ${name}`,
+    icons: { icon: config?.favicon ?? '/favicon.svg' },
+  };
+}
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" className={`${inter.variable} ${jetbrainsMono.variable}`} suppressHydrationWarning>
+      <head>
+        {/* No-flash theme init — must run synchronously before first paint */}
+        <script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
diff --git a/templates/shadcn/app/theme.css b/templates/shadcn/app/theme.css
new file mode 100644
index 0000000..9658876
--- /dev/null
+++ b/templates/shadcn/app/theme.css
@@ -0,0 +1,394 @@
+/*
+ * Shadcn theme — token overrides for @inkform/framework.
+ * Reproduces shadcn/ui's own default look (the "Zinc" base color +
+ * default radius/shadow scale you get from `npx shadcn@latest init` with
+ * no customization) rather than a generic neutral palette: a monochrome
+ * primary that INVERTS between modes (near-black button on white in light
+ * mode, near-white button on black in dark mode — shadcn ships no brand
+ * hue at all by default, that's the whole point of the "unstyled, you add
+ * color yourself" pitch), the Zinc grayscale for every surface/border, and
+ * Tailwind's own shadow-sm/shadow-lg values (soft, barely-there — not this
+ * codebase's usual hard-offset default, deliberately: the goal here is to
+ * look genuinely like stock shadcn, not like our house style in gray).
+ * This file is imported AFTER framework/styles.css so its declarations win.
+ */
+
+/* ── Font variables (set by next/font in layout.tsx) ─────────────────────── */
+:root {
+  --fw-font: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  --fw-font-heading: var(--font-sans, ui-sans-serif, system-ui, sans-serif);
+  --fw-mono: var(--font-mono, ui-monospace, "Menlo", "Consolas", monospace);
+}
+
+/* ── Light mode — shadcn's default Zinc base color ───────────────────────── */
+:root {
+  --fw-bg: #ffffff;
+  --fw-bg-subtle: #fafafa;
+  --fw-fg: #09090b;
+  --fw-muted: #71717a;
+  --fw-border: #e4e4e7;
+  --fw-border-strong: #d4d4d8;
+  --fw-card: #ffffff;
+  --fw-card-hover: #f4f4f5;
+  --fw-code-bg: #f4f4f5;
+  --fw-kbd-bg: #f4f4f5;
+
+  /* Brand — shadcn's own default primary IS the foreground color, not a
+     hue: a near-black button in light mode. */
+  --fw-primary: #18181b;
+  --fw-primary-fg: #fafafa;
+  --fw-primary-subtle: rgba(24, 24, 27, 0.06);
+
+  --fw-radius: 8px;
+  --fw-radius-sm: 6px;
+
+  --fw-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --fw-shadow-lg: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
+  --fw-ring: 0 0 0 3px rgba(24, 24, 27, 0.16);
+
+  /* HTTP method pills — shadcn defines no API-method colors (out of scope
+     for a component library), so these are plain Tailwind-600 hues, the
+     natural choice on a Zinc/Tailwind-native palette. */
+  --fw-method-get: #16a34a;
+  --fw-method-post: #2563eb;
+  --fw-method-put: #d97706;
+  --fw-method-patch: #9333ea;
+  --fw-method-delete: #dc2626;
+  --fw-method-head: #0891b2;
+  --fw-method-options: #71717a;
+}
+
+/* ── Dark mode — primary inverts to near-white, same as shadcn's own dark
+   theme (it doesn't just darken the light palette, the button flips) ───── */
+html.dark {
+  --fw-bg: #09090b;
+  --fw-bg-subtle: #18181b;
+  --fw-fg: #fafafa;
+  --fw-muted: #a1a1aa;
+  --fw-border: #27272a;
+  --fw-border-strong: #3f3f46;
+  --fw-card: #18181b;
+  --fw-card-hover: #27272a;
+  --fw-code-bg: #27272a;
+  --fw-kbd-bg: #27272a;
+
+  --fw-primary: #fafafa;
+  --fw-primary-fg: #18181b;
+  --fw-primary-subtle: rgba(250, 250, 250, 0.08);
+
+  --fw-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
+  --fw-shadow-lg: 0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -2px rgba(0, 0, 0, 0.4);
+  --fw-ring: 0 0 0 3px rgba(250, 250, 250, 0.16);
+
+  /* HTTP method pills — lifted a step for dark stock, same hue family */
+  --fw-method-get: #4ade80;
+  --fw-method-post: #60a5fa;
+  --fw-method-put: #fbbf24;
+  --fw-method-patch: #c084fc;
+  --fw-method-delete: #f87171;
+  --fw-method-head: #22d3ee;
+  --fw-method-options: #a1a1aa;
+}
+
+/* ── Header: two rows, like Palm's real header ─────────────────────────────
+   Verified on palm.mintlify.site: row 1 is logo · centered search · Ask
+   Assistant (no theme toggle, no CTA); row 2 is the tab row, left-aligned
+   under the logo, underlined when active. The shared DocsShell only exposes
+   one header row (logo/topNav/topActions in one flex line — see layout.css's
+   .fw-shell-header-inner), so this reflows it with flex-wrap + explicit
+   `order` rather than forking the shell: topNav (which Shadcn's top-bar.tsx
+   fills with ONLY the tabs) is pushed to `flex-basis: 100%`, which both
+   forces it onto its own line AND makes it span the header's full width
+   (so the tabs land flush with the logo's own left edge, same as Palm) —
+   and topActions (search + Ask Assistant) stays on row 1 by getting an
+   `order` lower than topNav's. --fw-header-h grows to fit both rows; every
+   sticky offset elsewhere (.fw-shell-sidebar/.fw-shell-toc top + height)
+   reads that same token, so they follow automatically. ────────────────── */
+
+:root {
+  --fw-header-h: 7rem;
+}
+
+.fw-shell-header {
+  height: auto;
+  min-height: var(--fw-header-h);
+}
+
+.fw-shell-header-inner {
+  flex-wrap: wrap;
+  row-gap: 0.625rem;
+  align-items: center;
+  padding-top: 0.875rem;
+  padding-bottom: 0.75rem;
+}
+
+.fw-shell-header-start {
+  order: 1;
+}
+
+.fw-shell-actions {
+  order: 2;
+  flex: 1;
+  margin-left: 0;
+  display: flex;
+  align-items: center;
+  gap: var(--fw-space-2);
+}
+
+.fw-shell-topnav {
+  order: 3;
+  flex-basis: 100%;
+  justify-content: flex-start;
+}
+
+/* Search trigger: centered within the row-1 space between the logo and Ask
+   Assistant (mathematically exact centering isn't possible without a 4th
+   DocsShell slot — see comment above — but the logo and Ask Assistant
+   buttons are close enough in width that this reads as centered, matching
+   the source screenshot). */
+.fw-shadcn-search-center {
+  flex: 1;
+  display: flex;
+  justify-content: center;
+  min-width: 0;
+}
+
+.fw-shadcn-search-center .fw-search-trigger {
+  width: 100%;
+  max-width: 26rem;
+  justify-content: space-between;
+  padding: 0.5rem 0.875rem;
+  background: var(--fw-bg-subtle);
+}
+
+.fw-shadcn-search-center .fw-search-trigger::before {
+  content: "";
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Ccircle cx='11' cy='11' r='8'/%3E%3Cline x1='21' y1='21' x2='16.65' y2='16.65'/%3E%3C/svg%3E") no-repeat center / contain;
+}
+
+/* Ask Assistant trigger reads neutral on Palm (muted border/text), not
+   primary-tinted like the framework default — measured directly:
+   border rgb(38,41,37) = --fw-border, text rgb(160,162,158) = --fw-muted. */
+.fw-askai-trigger {
+  background: var(--fw-bg);
+  border-color: var(--fw-border);
+  color: var(--fw-muted);
+  font-weight: 500;
+}
+
+.fw-askai-trigger:hover {
+  background: var(--fw-card-hover);
+  border-color: var(--fw-border-strong);
+  color: var(--fw-fg);
+}
+
+/* ── Tabs: underline indicator, not a pill/chip background ────────────────── */
+
+.fw-topnav-tabs {
+  gap: 1.5rem;
+}
+
+.fw-topnav-tab {
+  padding: 0.4rem 0.0625rem 0.6rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  border-radius: 0;
+  font-weight: 600;
+}
+
+.fw-topnav-tab:hover {
+  background: none;
+  color: var(--fw-fg);
+}
+
+.fw-topnav-tab--active {
+  background: none;
+  border-bottom-color: var(--fw-primary);
+  color: var(--fw-fg);
+}
+
+/* ── Sidebar: collapse chrome + Palm's plain (non-uppercase) group labels ── */
+
+.fw-sidebar-group-label {
+  font-size: 0.8125rem;
+  font-weight: 700;
+  letter-spacing: normal;
+  text-transform: none;
+  color: var(--fw-fg);
+}
+
+.fw-shadcn-sidebar-heading {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.fw-shadcn-sidebar-heading-text {
+  font-size: 0.9375rem;
+  font-weight: 700;
+  color: var(--fw-fg);
+}
+
+.fw-shadcn-sidebar-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-shadcn-sidebar-toggle:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+/* Collapsed rail — real state change (see components/collapsible-sidebar.tsx),
+   not a decorative arrow: the whole nav column shrinks via :has() so the
+   content column reflows into the freed space, same as the live site. */
+.fw-shadcn-sidebar-rail {
+  display: flex;
+  justify-content: center;
+  padding-top: var(--fw-space-6);
+  width: 100%;
+}
+
+.fw-shell-sidebar:has(.fw-shadcn-sidebar-rail) {
+  width: 3rem;
+  padding-right: 0;
+}
+
+@media (max-width: 60rem) {
+  /* Mobile already has its own collapse mechanism (the hamburger drawer) —
+     don't offer a second, redundant one inside the drawer. */
+  .fw-shadcn-sidebar-toggle {
+    display: none;
+  }
+}
+
+/* ── Sidebar footer: language switcher + system/light/dark theme trio ─────── */
+
+.fw-shadcn-sidebar-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+  /* Neither child has an intrinsic minimum below which it still reads —
+     "English" as a bare word and three 1.75rem icon buttons are both
+     already about as small as they can go. Without flex-shrink:0 the
+     default flex-shrink:1 on both let a narrow sidebar (mobile drawer at
+     an unlucky width, a collapsed rail transitioning, a long language
+     label in translation) squeeze the trio's buttons narrower than their
+     declared 1.75rem, crushing the icons inside instead of the row just
+     wrapping. Wrap is the fallback once even flex-shrink:0 can't fit both. */
+  flex-wrap: wrap;
+}
+
+.fw-shadcn-lang {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.fw-shadcn-lang-trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  padding: 0.3rem 0.5rem;
+  background: none;
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-shadcn-lang-trigger:hover {
+  color: var(--fw-fg);
+  background: var(--fw-card-hover);
+}
+
+.fw-shadcn-lang-menu {
+  position: absolute;
+  bottom: calc(100% + 0.375rem);
+  left: 0;
+  z-index: 10;
+  min-width: 8rem;
+  padding: 0.375rem;
+  background: var(--fw-card);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  box-shadow: var(--fw-shadow-lg);
+}
+
+.fw-shadcn-lang-option {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.35rem 0.5rem;
+  background: var(--fw-primary-subtle);
+  border: none;
+  border-radius: var(--fw-radius-sm);
+  color: var(--fw-primary);
+  font-size: 0.8125rem;
+  font-weight: 500;
+  cursor: pointer;
+}
+
+.fw-shadcn-theme-trio {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.125rem;
+  padding: 0.1875rem;
+  background: var(--fw-bg-subtle);
+  border: 1px solid var(--fw-border);
+  border-radius: var(--fw-radius-sm);
+  flex-shrink: 0;
+}
+
+.fw-shadcn-theme-trio button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  flex-shrink: 0;
+  padding: 0;
+  background: none;
+  border: none;
+  border-radius: calc(var(--fw-radius-sm) - 2px);
+  color: var(--fw-muted);
+  cursor: pointer;
+  transition: color 0.12s, background 0.12s;
+}
+
+.fw-shadcn-theme-trio button:hover {
+  color: var(--fw-fg);
+}
+
+.fw-shadcn-theme-trio button[aria-pressed="true"] {
+  background: var(--fw-card);
+  color: var(--fw-primary);
+  box-shadow: var(--fw-shadow);
+}
+
+/* Hero/media frames get a moderate rounded corner, matching Palm's welcome-page hero card. */
+.fw-frame,
+.fw-hero {
+  border-radius: 1rem;
+  overflow: hidden;
+}
diff --git a/templates/shadcn/components/collapsible-sidebar.tsx b/templates/shadcn/components/collapsible-sidebar.tsx
new file mode 100644
index 0000000..95bf682
--- /dev/null
+++ b/templates/shadcn/components/collapsible-sidebar.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+import { PanelLeftClose, PanelLeftOpen } from 'lucide-react';
+import type { SidebarGroup } from '@inkform/framework/docs-shell';
+
+/**
+ * Shadcn's own sidebar — NOT the framework's shared `Sidebar` component.
+ *
+ * Verified directly on palm.mintlify.site (2026-07-21, both the "Get
+ * Started" and "API Reference" tabs): the small arrow icon that sits next to
+ * the sidebar's top heading collapses the ENTIRE sidebar, not one group at a
+ * time — clicking it hides every group (confirmed: the whole `aside` column
+ * disappeared and the content column reflowed to fill the space) and hovering
+ * the second group's heading ("Essentials") revealed no per-group affordance
+ * at all. There is no independently-collapsible-group feature on the real
+ * site to reproduce. This component builds the real behavior instead: one
+ * collapse/expand toggle for the whole nav column, with a real `useState`
+ * behind it (not just a static arrow glyph) and a thin re-expand rail left
+ * behind when collapsed, matching what the live site actually does.
+ *
+ * The framework's `Sidebar` (docs-shell.tsx) has no `collapsible` prop and
+ * isn't parameterized for this, so rather than add one-theme-only state to a
+ * component every other theme also renders, this reimplements the group/item
+ * markup locally (identical `fw-sidebar-*` classes — same look for free) and
+ * layers the collapse chrome on top. `groups`/`title` come from the same
+ * `SidebarGroup[]` builders every theme already uses
+ * (`sidebarForDoc`, `buildReferenceSidebarGroups`), so no duplicate data
+ * shape is introduced.
+ */
+
+export interface CollapsibleSidebarProps {
+  /** The active tab's own label, shown as the sidebar's own heading (mirrors Palm's "Get Started" / "API Reference" heading above the group list). */
+  title: string;
+  groups: SidebarGroup[];
+  footer?: ReactNode;
+}
+
+export function CollapsibleSidebar({ title, groups, footer }: CollapsibleSidebarProps): ReactNode {
+  const [collapsed, setCollapsed] = React.useState(false);
+
+  if (collapsed) {
+    return (
+      <div className="fw-shadcn-sidebar-rail">
+        <button
+          type="button"
+          className="fw-shadcn-sidebar-toggle"
+          onClick={() => setCollapsed(false)}
+          aria-label="Expand sidebar"
+          title="Expand sidebar"
+        >
+          <PanelLeftOpen size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <aside className="fw-sidebar">
+      <div className="fw-sidebar-header fw-shadcn-sidebar-heading">
+        <span className="fw-shadcn-sidebar-heading-text">{title}</span>
+        <button
+          type="button"
+          className="fw-shadcn-sidebar-toggle"
+          onClick={() => setCollapsed(true)}
+          aria-label="Collapse sidebar"
+          title="Collapse sidebar"
+        >
+          <PanelLeftClose size={15} strokeWidth={1.75} aria-hidden />
+        </button>
+      </div>
+      <nav className="fw-sidebar-nav" aria-label="Documentation navigation">
+        {groups.map((g) => (
+          <div key={g.group} className="fw-sidebar-group">
+            <p className="fw-sidebar-group-label">
+              {g.icon ? (
+                <span className="fw-sidebar-group-icon" aria-hidden>
+                  {g.icon}
+                </span>
+              ) : null}
+              {g.group}
+            </p>
+            <ul className="fw-sidebar-items">
+              {g.items.map((item) => (
+                <li
+                  key={item.href}
+                  className={`fw-sidebar-item${item.active ? ' fw-sidebar-item--active' : ''}${item.depth ? ` fw-sidebar-depth-${item.depth}` : ''}`}
+                >
+                  <a
+                    href={item.href}
+                    className="fw-sidebar-link"
+                    {...(item.external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+                    aria-current={item.active ? 'page' : undefined}
+                  >
+                    {item.icon ? (
+                      <span className="fw-sidebar-item-icon" aria-hidden>
+                        {item.icon}
+                      </span>
+                    ) : null}
+                    <span className="fw-sidebar-item-title">{item.title}</span>
+                    {item.external ? (
+                      <span className="fw-sidebar-item-ext" aria-hidden>
+                        ↗
+                      </span>
+                    ) : null}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </div>
+        ))}
+      </nav>
+      {footer ? <div className="fw-sidebar-footer">{footer}</div> : null}
+    </aside>
+  );
+}
diff --git a/templates/shadcn/components/sidebar-footer.tsx b/templates/shadcn/components/sidebar-footer.tsx
new file mode 100644
index 0000000..cffbd31
--- /dev/null
+++ b/templates/shadcn/components/sidebar-footer.tsx
@@ -0,0 +1,164 @@
+'use client';
+
+import * as React from 'react';
+import { Monitor, Sun, Moon, ChevronDown } from 'lucide-react';
+
+/**
+ * Sidebar-bottom widget: language label + a system/light/dark theme trio.
+ * Verified directly on palm.mintlify.site: the sidebar footer shows
+ * "English ⌄" beside three icon buttons whose accessible names are "Switch
+ * to system/light/dark theme" — not the framework's single light/dark
+ * `ThemeToggle` button (which Shadcn doesn't render in the header at all, to
+ * match Palm's real header, which has no theme control up top).
+ *
+ * Reuses the exact same contract the framework's own `themeInitScript` /
+ * `ThemeToggle` read and write (`localStorage['fw-theme']` + the `dark`
+ * class + `data-theme` attribute on <html>), just with a third "system"
+ * state layered on top: "system" means no stored override, which is already
+ * what themeInitScript falls back to via `prefers-color-scheme` — so this
+ * doesn't need any shared framework change to stay in sync on first paint.
+ */
+
+type ThemePref = 'system' | 'light' | 'dark';
+
+const STORAGE_KEY = 'fw-theme';
+const PREF_EVENT = 'fw-theme-pref-change';
+
+function readStoredPref(): ThemePref {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === 'dark' || stored === 'light') return stored;
+  } catch {
+    /* localStorage unavailable — fall through to 'system' */
+  }
+  return 'system';
+}
+
+function applyTheme(pref: ThemePref) {
+  const root = document.documentElement;
+  const isDark = pref === 'dark' || (pref === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+
+  root.classList.toggle('dark', isDark);
+  root.setAttribute('data-theme', isDark ? 'dark' : 'light');
+  try {
+    if (pref === 'system') localStorage.removeItem(STORAGE_KEY);
+    else localStorage.setItem(STORAGE_KEY, pref);
+  } catch {
+    /* localStorage unavailable — theme still applies for this page load */
+  }
+  window.dispatchEvent(new CustomEvent<ThemePref>(PREF_EVENT, { detail: pref }));
+}
+
+function ThemeTrio() {
+  const [pref, setPref] = React.useState<ThemePref>('system');
+  const [mounted, setMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    setPref(readStoredPref());
+    setMounted(true);
+
+    // Two sidebar instances mount at once (desktop aside + mobile drawer —
+    // DocsShell renders the `sidebar` prop into both); keep them in sync
+    // without a shared store.
+    function onExternalChange(e: Event) {
+      setPref((e as CustomEvent<ThemePref>).detail);
+    }
+    window.addEventListener(PREF_EVENT, onExternalChange);
+    return () => window.removeEventListener(PREF_EVENT, onExternalChange);
+  }, []);
+
+  React.useEffect(() => {
+    if (pref !== 'system') return;
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    const onChange = () => applyTheme('system');
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [pref]);
+
+  function choose(next: ThemePref) {
+    setPref(next);
+    applyTheme(next);
+  }
+
+  return (
+    <div className="fw-shadcn-theme-trio" role="group" aria-label="Theme preference">
+      <button
+        type="button"
+        aria-label="Switch to system theme"
+        aria-pressed={mounted && pref === 'system'}
+        onClick={() => choose('system')}
+      >
+        <Monitor size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to light theme"
+        aria-pressed={mounted && pref === 'light'}
+        onClick={() => choose('light')}
+      >
+        <Sun size={14} strokeWidth={1.75} />
+      </button>
+      <button
+        type="button"
+        aria-label="Switch to dark theme"
+        aria-pressed={mounted && pref === 'dark'}
+        onClick={() => choose('dark')}
+      >
+        <Moon size={14} strokeWidth={1.75} />
+      </button>
+    </div>
+  );
+}
+
+/** Real open/close state, honestly scoped: the framework has no i18n, so the menu's only entry is the language already in use. */
+function LanguageMenu() {
+  const [open, setOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+
+  React.useEffect(() => {
+    if (!open) return;
+    function onPointerDown(e: PointerEvent) {
+      if (!rootRef.current?.contains(e.target as Node)) setOpen(false);
+    }
+    function onKey(e: KeyboardEvent) {
+      if (e.key === 'Escape') setOpen(false);
+    }
+    document.addEventListener('pointerdown', onPointerDown);
+    document.addEventListener('keydown', onKey);
+    return () => {
+      document.removeEventListener('pointerdown', onPointerDown);
+      document.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  return (
+    <div className="fw-shadcn-lang" ref={rootRef}>
+      <button
+        type="button"
+        className="fw-shadcn-lang-trigger"
+        onClick={() => setOpen((o) => !o)}
+        aria-expanded={open}
+        aria-haspopup="menu"
+      >
+        English
+        <ChevronDown size={13} strokeWidth={1.75} />
+      </button>
+      {open ? (
+        <div className="fw-shadcn-lang-menu" role="menu">
+          <button type="button" role="menuitemradio" aria-checked="true" className="fw-shadcn-lang-option" onClick={() => setOpen(false)}>
+            English
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+export function SidebarFooter() {
+  return (
+    <div className="fw-shadcn-sidebar-footer">
+      <LanguageMenu />
+      <ThemeTrio />
+    </div>
+  );
+}
diff --git a/templates/shadcn/components/top-bar.tsx b/templates/shadcn/components/top-bar.tsx
new file mode 100644
index 0000000..4ca3a6d
--- /dev/null
+++ b/templates/shadcn/components/top-bar.tsx
@@ -0,0 +1,156 @@
+import type { ReactNode } from 'react';
+import Link from 'next/link';
+import { AskAi } from '@inkform/framework/ask-ai';
+import { SearchDialog } from '@inkform/framework/search-dialog';
+import type { DocsConfig } from '@inkform/framework';
+import { docTabs } from '@inkform/framework';
+import { loadDocsConfig } from '@inkform/framework/content';
+import { apiBasePath } from '@/lib/route';
+
+// ── Brand logo ────────────────────────────────────────────────────────────────
+
+function Logo({ config }: { config: DocsConfig }) {
+  const logo =
+    typeof config.logo === 'string'
+      ? config.logo
+      : config.logo?.dark ?? config.logo?.light ?? null;
+
+  return (
+    <Link href="/" className="fw-shell-brand" aria-label={`${config.name} home`}>
+      {logo ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img src={logo} alt={config.name} height={24} className="fw-shell-brand-logo" />
+      ) : (
+        <span className="fw-shell-brand-name">{config.name}</span>
+      )}
+    </Link>
+  );
+}
+
+// ── Tab nav ───────────────────────────────────────────────────────────────────
+// Rendered into the `topNav` slot, but pushed onto its own full-width row
+// below the logo/search/assistant row by Shadcn's own theme.css (see the
+// "header" section there) — verified on palm.mintlify.site: the tabs sit on
+// a second line, left-aligned under the logo, underlined when active (no
+// pill background). `.fw-topnav-tab`/`--active` classes are shared with
+// every other theme; only the underline treatment is Shadcn-specific CSS.
+
+function TabNav({ config, activeTab }: { config: DocsConfig; activeTab: string }) {
+  const tabs = docTabs(config);
+  const apiBase = apiBasePath(config);
+
+  return (
+    <div className="fw-topnav-tabs">
+      {tabs.map((t) => {
+        const href = t.openapi && apiBase ? `/${apiBase}` : '/';
+        const isActive = t.tab === activeTab;
+        return (
+          <a
+            key={t.tab}
+            href={href}
+            className={`fw-topnav-tab${isActive ? ' fw-topnav-tab--active' : ''}`}
+            aria-current={isActive ? 'page' : undefined}
+          >
+            {t.tab}
+          </a>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── Anchor links ──────────────────────────────────────────────────────────────
+
+function AnchorLinks({ config }: { config: DocsConfig }) {
+  const anchors = config.anchors ?? [];
+  if (anchors.length === 0) return null;
+  return (
+    <div className="fw-topnav-anchors">
+      {anchors.map((a) => (
+        <a
+          key={a.href}
+          href={a.href}
+          className="fw-topnav-anchor"
+          target={a.href.startsWith('http') ? '_blank' : undefined}
+          rel={a.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {a.name}
+        </a>
+      ))}
+    </div>
+  );
+}
+
+// ── Top bar props ─────────────────────────────────────────────────────────────
+
+export interface TopBarParts {
+  logo: ReactNode;
+  topNav: ReactNode;
+  topActions: ReactNode;
+  /** Separate from topActions so DocsShell can duplicate just this into the mobile drawer without also duplicating the (stateful) search/AI widgets. */
+  cta: ReactNode;
+}
+
+/**
+ * Build the three DocsShell header slot contents for Shadcn.
+ * Server component — client islands (SearchDialog, AskAi) are already
+ * marked 'use client' in the framework.
+ *
+ * Notes, verified directly on palm.mintlify.site:
+ *  - No `<ThemeToggle>` here — Palm's header carries no theme control at
+ *    all; the theme switcher lives at the bottom of the sidebar instead
+ *    (see components/sidebar-footer.tsx), wired into page.tsx via
+ *    CollapsibleSidebar's `footer` slot.
+ *  - The search trigger is wrapped in `.fw-shadcn-search-center` so it reads
+ *    as centered in the header instead of flush right (CSS in theme.css).
+ *  - `config.cta` is simply never set in this theme's docs.json — Palm's
+ *    header has no CTA button at all. The render-if-present branch below is
+ *    left in place (confirmed `buildTopBar` already no-ops with no `cta`)
+ *    so a fork of this theme can still opt back in without touching this
+ *    file.
+ */
+export function buildTopBar(config: DocsConfig, activeTab: string): TopBarParts {
+  const aiEnabled = process.env.NEXT_PUBLIC_DOCS_AI_ENABLED === 'true';
+
+  const logo = <Logo config={config} />;
+
+  const topNav = (
+    <>
+      <TabNav config={config} activeTab={activeTab} />
+      <AnchorLinks config={config} />
+      {(config.navbarLinks ?? []).map((l) => (
+        <a
+          key={l.href}
+          href={l.href}
+          className="fw-topnav-navlink"
+          target={l.href.startsWith('http') ? '_blank' : undefined}
+          rel={l.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+        >
+          {l.name}
+        </a>
+      ))}
+    </>
+  );
+
+  const topActions = (
+    <>
+      <div className="fw-shadcn-search-center">
+        <SearchDialog />
+      </div>
+      <AskAi enabled={aiEnabled} product={config.name} label="Ask Assistant" />
+    </>
+  );
+
+  const cta = config.cta ? (
+    <a
+      href={config.cta.href}
+      className="fw-topnav-cta"
+      target={config.cta.href.startsWith('http') ? '_blank' : undefined}
+      rel={config.cta.href.startsWith('http') ? 'noopener noreferrer' : undefined}
+    >
+      {config.cta.label}
+    </a>
+  ) : null;
+
+  return { logo, topNav, topActions, cta };
+}
diff --git a/templates/shadcn/content/docs/development.mdx b/templates/shadcn/content/docs/development.mdx
new file mode 100644
index 0000000..f75f85e
--- /dev/null
+++ b/templates/shadcn/content/docs/development.mdx
@@ -0,0 +1,60 @@
+---
+title: Development
+description: Preview your docs locally before you ship.
+---
+
+# Development
+
+Learn how to run your docs locally and preview every change before it goes live.
+
+<Info>
+  **Prerequisite:** Node.js 20 or newer.
+</Info>
+
+## Run the dev server
+
+```bash
+npm install
+npm run dev
+```
+
+Your site is now available at [http://localhost:3000](http://localhost:3000).
+Edits to MDX and `docs.json` hot-reload.
+
+## Custom ports
+
+The dev server uses port `3000` by default. Pass `-p` to change it:
+
+```bash
+npm run dev -- -p 3333
+```
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Port already in use">
+    Another process is using the port. Stop it, or start the dev server on a
+    different port with `npm run dev -- -p 3333`.
+  </Accordion>
+  <Accordion title="A page 404s">
+    Make sure the page's `file` exists under `content/docs` and its `slug` is
+    listed in `docs.json`. Slugs are case-sensitive.
+  </Accordion>
+  <Accordion title="The API Reference tab is empty">
+    Confirm `docs.json` has a tab with an `openapi` field pointing at a valid
+    spec file (JSON or YAML) inside `content/docs`.
+  </Accordion>
+</AccordionGroup>
+
+## Editor tips
+
+<Tabs>
+  <Tab title="VS Code">
+    Install the **MDX** extension for syntax highlighting and component
+    autocomplete in `.mdx` files.
+  </Tab>
+  <Tab title="Neovim">
+    Use a Treesitter MDX/Markdown parser for highlighting, and an LSP-aware
+    Markdown plugin for link checking.
+  </Tab>
+</Tabs>
diff --git a/templates/shadcn/content/docs/docs.json b/templates/shadcn/content/docs/docs.json
new file mode 100644
index 0000000..c98296b
--- /dev/null
+++ b/templates/shadcn/content/docs/docs.json
@@ -0,0 +1,37 @@
+{
+  "name": "Shadcn",
+  "version": "1.0.0",
+  "logo": "/logo.svg",
+  "favicon": "/favicon.svg",
+  "colors": { "primary": "#43c200" },
+  "tabs": [
+    {
+      "tab": "Guides",
+      "navigation": [
+        {
+          "group": "Get Started",
+          "pages": [
+            { "title": "Introduction", "slug": "", "file": "index.mdx", "icon": "book-open" },
+            { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx", "icon": "rocket" },
+            { "title": "Development", "slug": "development", "file": "development.mdx", "icon": "terminal" }
+          ]
+        },
+        {
+          "group": "Essentials",
+          "pages": [
+            { "title": "Markdown Syntax", "slug": "essentials/markdown", "file": "essentials/markdown.mdx", "icon": "type" },
+            { "title": "Code Blocks", "slug": "essentials/code-blocks", "file": "essentials/code-blocks.mdx", "icon": "code" },
+            { "title": "Images & Embeds", "slug": "essentials/images", "file": "essentials/images.mdx", "icon": "image" },
+            { "title": "Components", "slug": "essentials/components", "file": "essentials/components.mdx", "icon": "blocks" },
+            { "title": "Navigation", "slug": "essentials/navigation", "file": "essentials/navigation.mdx", "icon": "map" }
+          ]
+        }
+      ]
+    },
+    {
+      "tab": "API Reference",
+      "openapi": "openapi.json",
+      "apiReference": { "renderer": "native" }
+    }
+  ]
+}
diff --git a/templates/shadcn/content/docs/essentials/code-blocks.mdx b/templates/shadcn/content/docs/essentials/code-blocks.mdx
new file mode 100644
index 0000000..c5ab15f
--- /dev/null
+++ b/templates/shadcn/content/docs/essentials/code-blocks.mdx
@@ -0,0 +1,55 @@
+---
+title: Code Blocks
+description: Display inline code and richly highlighted code blocks.
+---
+
+# Code Blocks
+
+Display inline code and fenced code blocks with syntax highlighting.
+
+## Inline code
+
+To denote a `word` or `phrase` as code, wrap it in backticks (`` ` ``).
+
+## Code blocks
+
+Fence code with triple backticks and a language for highlighting. Add a title
+after the language to label the block:
+
+```js app.js
+export function greet(name) {
+  return `Hello, ${name}!`;
+}
+```
+
+## Code groups
+
+Group related snippets — different languages or package managers — into a single
+tabbed block:
+
+<CodeGroup>
+```bash npm
+npm install @inkform/framework
+```
+
+```bash pnpm
+pnpm add @inkform/framework
+```
+
+```bash yarn
+yarn add @inkform/framework
+```
+</CodeGroup>
+
+## Highlighting
+
+Code blocks are highlighted with [Shiki](https://shiki.style), the same engine
+VS Code uses, so colors match your editor and stay readable in light and dark
+mode.
+
+```ts server.ts
+import { parseOpenApi } from '@inkform/framework/openapi';
+
+const model = parseOpenApi(rawSpec);
+console.log(model.operations.length, 'endpoints');
+```
diff --git a/templates/shadcn/content/docs/essentials/components.mdx b/templates/shadcn/content/docs/essentials/components.mdx
new file mode 100644
index 0000000..1057e76
--- /dev/null
+++ b/templates/shadcn/content/docs/essentials/components.mdx
@@ -0,0 +1,62 @@
+---
+title: Components
+description: The built-in component library for rich, interactive docs.
+---
+
+# Components
+
+Beyond Markdown, you get a library of components for richer pages — all available
+in any `.mdx` file with no imports.
+
+## Cards
+
+<CardGroup cols={2}>
+  <Card title="Fast" icon="zap">
+    Static-rendered pages, instant client-side search.
+  </Card>
+  <Card title="Themeable" icon="palette">
+    Restyle everything from one token file.
+  </Card>
+</CardGroup>
+
+## Callouts
+
+<Note>A neutral note.</Note>
+<Tip>A helpful tip.</Tip>
+<Warning>Something to be careful about.</Warning>
+<Check>A success confirmation.</Check>
+
+## Steps
+
+<Steps>
+  <Step title="Write">Add an `.mdx` file under `content/docs`.</Step>
+  <Step title="Register">List it in `docs.json`.</Step>
+  <Step title="Ship">Push and deploy.</Step>
+</Steps>
+
+## Tabs
+
+<Tabs>
+  <Tab title="macOS">Press <kbd>⌘</kbd> <kbd>K</kbd> to open search.</Tab>
+  <Tab title="Windows">Press <kbd>Ctrl</kbd> <kbd>K</kbd> to open search.</Tab>
+</Tabs>
+
+## Accordions
+
+<AccordionGroup>
+  <Accordion title="Is it responsive?">Yes — sidebar and TOC collapse on small screens.</Accordion>
+  <Accordion title="Does it support dark mode?">Yes — toggle in the top bar, persisted across visits.</Accordion>
+</AccordionGroup>
+
+## Parameter fields
+
+Use `<ParamField>` and `<ResponseField>` to document request and response shapes
+in prose (the API Reference tab generates these automatically from OpenAPI):
+
+<ParamField query="limit" type="integer" default="20">
+  The maximum number of results to return.
+</ParamField>
+
+<ResponseField name="id" type="integer" required>
+  The unique identifier of the created record.
+</ResponseField>
diff --git a/templates/shadcn/content/docs/essentials/images.mdx b/templates/shadcn/content/docs/essentials/images.mdx
new file mode 100644
index 0000000..5caefc6
--- /dev/null
+++ b/templates/shadcn/content/docs/essentials/images.mdx
@@ -0,0 +1,43 @@
+---
+title: Images & Embeds
+description: Add images, video, and other media to your docs.
+---
+
+# Images & Embeds
+
+Add images, video, and rich media to bring your documentation to life.
+
+## Images
+
+Use Markdown image syntax:
+
+```md
+![A descriptive alt text](/path/to/image.jpg)
+```
+
+Wrap an image in a `<Frame>` to add a border and an optional caption:
+
+<Frame caption="Images look great framed.">
+  ![Landscape](/hero.svg)
+</Frame>
+
+<Note>
+  Keep images under ~5 MB. For larger assets, host them on a CDN and reference
+  the URL.
+</Note>
+
+## Video
+
+Embed a YouTube or Loom video with the `<Embed>` component:
+
+```mdx
+<Embed provider="youtube" url="https://youtu.be/dQw4w9WgXcQ" />
+```
+
+## iframes
+
+Embed any external page:
+
+```mdx
+<Embed provider="iframe" url="https://example.com/widget" />
+```
diff --git a/templates/shadcn/content/docs/essentials/markdown.mdx b/templates/shadcn/content/docs/essentials/markdown.mdx
new file mode 100644
index 0000000..c0e86da
--- /dev/null
+++ b/templates/shadcn/content/docs/essentials/markdown.mdx
@@ -0,0 +1,65 @@
+---
+title: Markdown Syntax
+description: Text, titles, and styling in standard Markdown.
+---
+
+# Markdown Syntax
+
+Write content in standard Markdown — the framework renders it with GitHub-flavored
+extensions, callouts, and syntax-highlighted code.
+
+## Titles
+
+Use `#` headings for sections. Second- and third-level headings (`##`, `###`)
+appear in the table of contents on the right.
+
+```md
+## Section title
+### Subsection title
+```
+
+## Text formatting
+
+We support most Markdown formatting. Wrap text to style it:
+
+| Style | How to write it | Result |
+| --- | --- | --- |
+| Bold | `**bold**` | **bold** |
+| Italic | `_italic_` | _italic_ |
+| Strikethrough | `~~struck~~` | ~~struck~~ |
+| Code | `` `code` `` | `code` |
+
+## Links
+
+Link to [another page](/quickstart) with relative paths, or to
+[an external site](https://example.com) with full URLs.
+
+## Blockquotes
+
+> The best way to predict the future is to invent it.
+
+## Lists
+
+- Unordered items
+- Nest them by indenting
+  - Like this
+
+1. Ordered items
+2. Count automatically
+
+## Callouts
+
+Use callouts to draw attention. They come in several flavors:
+
+<Note>This is a note — neutral, informational.</Note>
+<Tip>This is a tip — a helpful suggestion.</Tip>
+<Warning>This is a warning — proceed carefully.</Warning>
+<Check>This is a success message — all good.</Check>
+
+You can also write callouts as directives:
+
+```md
+:::info
+An info callout written as a directive.
+:::
+```
diff --git a/templates/shadcn/content/docs/essentials/navigation.mdx b/templates/shadcn/content/docs/essentials/navigation.mdx
new file mode 100644
index 0000000..f85d3f2
--- /dev/null
+++ b/templates/shadcn/content/docs/essentials/navigation.mdx
@@ -0,0 +1,68 @@
+---
+title: Navigation
+description: Configure tabs, groups, pages, and the API Reference in docs.json.
+---
+
+# Navigation
+
+Your site's structure lives in `content/docs/docs.json`. It controls the top
+tabs, the sidebar groups, and the API Reference.
+
+## Groups and pages
+
+The simplest config is a list of groups, each with pages:
+
+```json docs.json
+{
+  "name": "My Docs",
+  "navigation": [
+    {
+      "group": "Get Started",
+      "pages": [
+        { "title": "Introduction", "slug": "", "file": "index.mdx" },
+        { "title": "Quickstart", "slug": "quickstart", "file": "quickstart.mdx" }
+      ]
+    }
+  ]
+}
+```
+
+<Note>
+  `slug` is the URL path (an empty string is the index). `file` is the MDX file
+  relative to `content/docs`. Nest pages with a `children` array.
+</Note>
+
+## Tabs
+
+Add top-bar tabs to split Guides from your API Reference:
+
+```json docs.json
+{
+  "tabs": [
+    { "tab": "Guides", "navigation": [ /* groups */ ] },
+    { "tab": "API Reference", "openapi": "openapi.json" }
+  ]
+}
+```
+
+## API Reference from OpenAPI
+
+Point a tab's `openapi` field at a spec file (JSON or YAML) in `content/docs`.
+The framework generates the entire API Reference — endpoint list, parameters,
+request/response schemas, a cURL sample, and a live "Try it" playground — from
+the spec.
+
+<Tip>
+  This is the standard: API docs come from OpenAPI, everything else is MDX. Keep
+  your spec accurate and your reference stays accurate for free.
+</Tip>
+
+## Top bar
+
+```json docs.json
+{
+  "navbarLinks": [{ "name": "Blog", "href": "/blog" }],
+  "anchors": [{ "name": "GitHub", "href": "https://github.com/you/repo", "icon": "github" }],
+  "cta": { "label": "Dashboard", "href": "https://app.example.com" }
+}
+```
diff --git a/templates/shadcn/content/docs/index.mdx b/templates/shadcn/content/docs/index.mdx
new file mode 100644
index 0000000..5165c61
--- /dev/null
+++ b/templates/shadcn/content/docs/index.mdx
@@ -0,0 +1,46 @@
+---
+title: Introduction
+description: Welcome to your new documentation site.
+---
+
+# Introduction
+
+Welcome to the home of your new documentation. This starter is a complete,
+deployable docs site powered by [`@inkform/framework`](https://github.com/inkform-dev/framework):
+write Markdown, commit it, and ship a fast, searchable, themeable site — no CMS,
+no database.
+
+<Frame caption="Your docs, your repo, your deploy.">
+  ![Hero](/hero.svg)
+</Frame>
+
+## Set up
+
+The first step to world-class documentation is setting up your editing
+environment and making the site your own.
+
+<CardGroup cols={2}>
+  <Card title="Edit your docs" icon="pencil" href="/quickstart">
+    Get your docs running locally for fast iteration.
+  </Card>
+  <Card title="Preview changes" icon="eye" href="/development">
+    Preview every change before you push so it's always right.
+  </Card>
+  <Card title="Write in MDX" icon="type" href="/essentials/markdown">
+    Markdown with components — callouts, cards, steps, tabs, and more.
+  </Card>
+  <Card title="API Reference" icon="terminal" href="/essentials/navigation">
+    Point `docs.json` at an OpenAPI spec and get a full API reference.
+  </Card>
+</CardGroup>
+
+## Make it yours
+
+Every theme is driven by the same engine and a single `theme.css` token file, so
+you can recolor, re-font, and restyle the whole site without touching layout
+code.
+
+<Note>
+  New here? Start with the [Quickstart](/quickstart) — you'll have a site running
+  in under five minutes.
+</Note>
diff --git a/templates/shadcn/content/docs/openapi.json b/templates/shadcn/content/docs/openapi.json
new file mode 100644
index 0000000..fdf12e9
--- /dev/null
+++ b/templates/shadcn/content/docs/openapi.json
@@ -0,0 +1,125 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Sample Store API",
+    "version": "1.0.0",
+    "description": "A tiny example API used to demo the OpenAPI-powered API Reference. Replace `openapi.json` with your own spec — everything on the API Reference tab is generated from it."
+  },
+  "servers": [{ "url": "https://api.example.com/v1", "description": "Production" }],
+  "security": [{ "bearerAuth": [] }],
+  "tags": [{ "name": "Plants", "description": "Manage the plants in your store." }],
+  "paths": {
+    "/plants": {
+      "get": {
+        "operationId": "list-plants",
+        "tags": ["Plants"],
+        "summary": "List plants",
+        "description": "Returns all plants from the store that the caller has access to.",
+        "parameters": [
+          {
+            "name": "limit",
+            "in": "query",
+            "required": false,
+            "description": "The maximum number of results to return.",
+            "schema": { "type": "integer", "format": "int32", "default": 20 }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A list of plants.",
+            "content": {
+              "application/json": {
+                "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Plant" } }
+              }
+            }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      },
+      "post": {
+        "operationId": "create-plant",
+        "tags": ["Plants"],
+        "summary": "Create a plant",
+        "description": "Creates a new plant in the store.",
+        "requestBody": {
+          "required": true,
+          "description": "The plant to add to the store.",
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPlant" } } }
+        },
+        "responses": {
+          "200": {
+            "description": "The created plant.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plant" } } }
+          },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    },
+    "/plants/{id}": {
+      "delete": {
+        "operationId": "delete-plant",
+        "tags": ["Plants"],
+        "summary": "Delete a plant",
+        "description": "Deletes a single plant by its id.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The id of the plant to delete.",
+            "schema": { "type": "integer", "format": "int64" }
+          }
+        ],
+        "responses": {
+          "204": { "description": "Plant deleted." },
+          "400": {
+            "description": "Unexpected error.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "description": "Bearer authentication header of the form `Bearer <token>`."
+      }
+    },
+    "schemas": {
+      "Plant": {
+        "type": "object",
+        "required": ["id", "name"],
+        "properties": {
+          "id": { "type": "integer", "format": "int64", "description": "Identification number of the plant." },
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "NewPlant": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "description": "The name of the plant." },
+          "tag": { "type": "string", "description": "Tag to specify the type." }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": ["error", "message"],
+        "properties": {
+          "error": { "type": "integer", "format": "int32", "description": "Error code." },
+          "message": { "type": "string", "description": "Human-readable error message." }
+        }
+      }
+    }
+  }
+}
diff --git a/templates/shadcn/content/docs/quickstart.mdx b/templates/shadcn/content/docs/quickstart.mdx
new file mode 100644
index 0000000..b047822
--- /dev/null
+++ b/templates/shadcn/content/docs/quickstart.mdx
@@ -0,0 +1,76 @@
+---
+title: Quickstart
+description: Start building beautiful documentation in minutes.
+---
+
+# Quickstart
+
+Start building beautiful documentation in minutes.
+
+## Set up your project
+
+<Steps>
+  <Step title="Scaffold a project">
+    Create a new docs site and pick a theme:
+
+    ```bash
+    npx @inkform/cli@latest init my-docs
+    cd my-docs
+    npm install
+    ```
+  </Step>
+  <Step title="Run it locally">
+    Start the dev server and open [localhost:3000](http://localhost:3000):
+
+    ```bash
+    npm run dev
+    ```
+  </Step>
+  <Step title="Edit your content">
+    Content lives in `content/docs`. Edit any `.mdx` file and the page reloads
+    instantly. Add pages by creating files and listing them in `docs.json`.
+  </Step>
+  <Step title="Deploy">
+    Push to GitHub and import the repo on Vercel — zero config. See the
+    project README for the full deploy guide (Vercel and AWS Amplify).
+  </Step>
+</Steps>
+
+## Add your first page
+
+Create `content/docs/hello.mdx`:
+
+```mdx hello.mdx
+---
+title: Hello
+description: My first page.
+---
+
+# Hello
+
+This is my first documentation page.
+```
+
+Then register it in `content/docs/docs.json`:
+
+```json docs.json
+{
+  "group": "Get Started",
+  "pages": [{ "title": "Hello", "slug": "hello", "file": "hello.mdx" }]
+}
+```
+
+<Tip>
+  The `slug` is the URL path and `file` is the MDX file relative to
+  `content/docs`. Nest pages with a `children` array.
+</Tip>
+
+## Cross-linking to the API Reference
+
+If a project has an OpenAPI spec configured, <ApiLink operationId="list-plants">any doc page can link straight to a specific operation</ApiLink> with `<ApiLink operationId="...">`. The link is validated against the spec at build time — a typo or renamed operation fails the build instead of shipping a dead link.
+
+## Custom widgets
+
+Put a component at `widgets/<Name>.tsx`, register it in `widgets/index.ts`, and use it directly in MDX (or from the CMS's widget block) as `<Name />`:
+
+<Counter start={3} />
diff --git a/templates/shadcn/content/docs/slug-history.json b/templates/shadcn/content/docs/slug-history.json
new file mode 100644
index 0000000..0967ef4
--- /dev/null
+++ b/templates/shadcn/content/docs/slug-history.json
@@ -0,0 +1 @@
+{}
diff --git a/templates/shadcn/lib/icons.tsx b/templates/shadcn/lib/icons.tsx
new file mode 100644
index 0000000..8490099
--- /dev/null
+++ b/templates/shadcn/lib/icons.tsx
@@ -0,0 +1,92 @@
+import type { ReactNode } from 'react';
+import {
+  Book,
+  BookOpen,
+  Rocket,
+  Terminal,
+  Type,
+  Code,
+  Image,
+  Blocks,
+  Map,
+  Github,
+  Pencil,
+  Eye,
+  Zap,
+  Palette,
+  FileText,
+  Settings,
+  Globe,
+  Lock,
+  Key,
+  Database,
+  Cloud,
+  Mail,
+  User,
+  Users,
+  Star,
+  Heart,
+  Bell,
+  Search,
+  Home,
+  Layout,
+  Package,
+  Layers,
+  Link,
+  ChevronRight,
+  Play,
+  Download,
+  Upload,
+} from 'lucide-react';
+
+const ICON_MAP: Record<string, React.ComponentType<{ size?: number; strokeWidth?: number }>> = {
+  book: Book,
+  'book-open': BookOpen,
+  rocket: Rocket,
+  terminal: Terminal,
+  type: Type,
+  code: Code,
+  image: Image,
+  blocks: Blocks,
+  map: Map,
+  github: Github,
+  pencil: Pencil,
+  eye: Eye,
+  zap: Zap,
+  palette: Palette,
+  file: FileText,
+  'file-text': FileText,
+  settings: Settings,
+  globe: Globe,
+  lock: Lock,
+  key: Key,
+  database: Database,
+  cloud: Cloud,
+  mail: Mail,
+  user: User,
+  users: Users,
+  star: Star,
+  heart: Heart,
+  bell: Bell,
+  search: Search,
+  home: Home,
+  layout: Layout,
+  package: Package,
+  layers: Layers,
+  link: Link,
+  'chevron-right': ChevronRight,
+  play: Play,
+  download: Download,
+  upload: Upload,
+};
+
+/**
+ * Map a docs.json icon name to a Lucide icon ReactNode.
+ * Returns null for unknown or empty names.
+ */
+export function renderIcon(name?: string): ReactNode {
+  if (!name) return null;
+  const Icon = ICON_MAP[name.toLowerCase()];
+  if (!Icon) return null;
+  return <Icon size={16} strokeWidth={1.75} />;
+}
diff --git a/templates/shadcn/lib/route.tsx b/templates/shadcn/lib/route.tsx
new file mode 100644
index 0000000..dbcd524
--- /dev/null
+++ b/templates/shadcn/lib/route.tsx
@@ -0,0 +1,134 @@
+/**
+ * lib/route.ts — Shadcn routing core.
+ *
+ * Resolves a slug array from the catch-all route into a doc page, generates
+ * static params, and builds sidebar groups. The API Reference tab is NOT
+ * handled here — this project's tab has `apiReference.renderer: 'native'`
+ * (docs.json), so it's served by app/api-reference/[[...slug]]/page.tsx,
+ * the framework's own React/Galley renderer (@inkform/framework/openapi-render)
+ * — no Scalar/Vue dependency. apiBasePath() is still needed by
+ * components/top-bar.tsx to build that tab's nav link.
+ */
+
+import type { ReactNode } from 'react';
+import { docTabs, listDocPages, findDocPage, tabNavigation } from '@inkform/framework';
+import type { DocsConfig, DocsTab, FlatDocPage } from '@inkform/framework';
+import { loadDocsConfig, loadDocPage, loadBlogPosts, loadChangelogEntries, slugify } from '@inkform/framework/content';
+import type { SidebarGroup, SidebarItem } from '@inkform/framework/docs-shell';
+
+// ── Re-export for convenience ─────────────────────────────────────────────────
+
+export { loadDocsConfig, loadDocPage };
+
+// ── Content nav links (Blog / Changelog) ──────────────────────────────────────
+
+/**
+ * Extends config.navbarLinks with "Blog" / "Changelog" entries, but only when
+ * content actually exists under content/blog or content/changelog — a
+ * docs-only site stays clean by default (see app/blog, app/changelog).
+ */
+export function withContentNavLinks(config: DocsConfig): DocsConfig {
+  const extra: DocsConfig['navbarLinks'] = [];
+  if (loadBlogPosts().length > 0) extra.push({ name: 'Blog', href: '/blog' });
+  if (loadChangelogEntries().length > 0) extra.push({ name: 'Changelog', href: '/changelog' });
+  if (extra.length === 0) return config;
+  return { ...config, navbarLinks: [...(config.navbarLinks ?? []), ...extra] };
+}
+
+// ── API tab helpers ───────────────────────────────────────────────────────────
+
+/** Find the tab that has an openapi spec (the API Reference tab). */
+export function apiTab(config: DocsConfig): DocsTab | null {
+  return docTabs(config).find((t) => !!t.openapi) ?? null;
+}
+
+/**
+ * The URL slug base for the API Reference tab, derived from slugifying its
+ * tab label (e.g. "API Reference" → "api-reference"). Used by top-bar.tsx to
+ * link to app/api-reference/route.ts — keep the two in sync if you rename
+ * the tab.
+ */
+export function apiBasePath(config: DocsConfig): string | null {
+  const tab = apiTab(config);
+  if (!tab) return null;
+  return slugify(tab.tab);
+}
+
+// ── Route resolution ──────────────────────────────────────────────────────────
+
+export type DocRoute = {
+  kind: 'doc';
+  ref: FlatDocPage;
+  page: { data: Record<string, unknown>; content: string };
+  config: DocsConfig;
+  tab: DocsTab;
+};
+
+/**
+ * Resolve a catch-all slug array to a doc page descriptor.
+ * Returns null if no page is found (→ notFound()).
+ */
+export function resolveRoute(slugParts: string[] | undefined): DocRoute | null {
+  const config = loadDocsConfig();
+  if (!config) return null;
+
+  const path = (slugParts ?? []).join('/');
+  const ref = findDocPage(config, path);
+  if (!ref) return null;
+
+  const page = loadDocPage(ref.file);
+  if (!page) return null;
+
+  const docTabEntry = docTabs(config).find((t) => t.tab === ref.tab) ?? docTabs(config)[0];
+  return { kind: 'doc', ref, page, config, tab: docTabEntry };
+}
+
+// ── Static params ─────────────────────────────────────────────────────────────
+
+/**
+ * All static slugs for generateStaticParams.
+ * Each entry is a string[] (the catch-all segments).
+ * The index page has slug = [] (empty array).
+ */
+export function listAllRoutes(config: DocsConfig): string[][] {
+  const routes: string[][] = [];
+  const seen = new Set<string>();
+
+  function addSlug(slug: string) {
+    if (seen.has(slug)) return;
+    seen.add(slug);
+    routes.push(slug === '' ? [] : slug.split('/'));
+  }
+
+  for (const page of listDocPages(config)) {
+    addSlug(page.slug);
+  }
+
+  return routes;
+}
+
+// ── Sidebar builders ──────────────────────────────────────────────────────────
+
+/**
+ * Build SidebarGroup[] for a doc tab.
+ * renderIcon maps a docs.json icon name to a ReactNode.
+ */
+export function sidebarForDoc(
+  config: DocsConfig,
+  tab: DocsTab,
+  activeSlug: string,
+  renderIcon: (name?: string) => ReactNode,
+): SidebarGroup[] {
+  const groups = tabNavigation(config, tab.tab);
+  return groups.map((g) => ({
+    group: g.group,
+    icon: renderIcon(g.icon),
+    items: (g.pages ?? []).map((p): SidebarItem => ({
+      title: p.title,
+      href: p.href ?? '/' + p.slug,
+      active: p.slug === activeSlug,
+      icon: renderIcon(p.icon),
+      external: !!p.href,
+    })),
+  }));
+}
diff --git a/templates/shadcn/mdx-components.tsx b/templates/shadcn/mdx-components.tsx
new file mode 100644
index 0000000..70bba3b
--- /dev/null
+++ b/templates/shadcn/mdx-components.tsx
@@ -0,0 +1,11 @@
+import { mdxComponents } from '@inkform/framework/components';
+import widgets from '@/widgets';
+
+/**
+ * Site-level MDX component map.
+ * The framework's defaults cover all built-in blocks (Callout, Card, Steps,
+ * Tabs, CodeGroup, Accordion, ParamField, …). Custom widgets registered in
+ * widgets/index.ts are merged in here, so <YourWidget /> in MDX/CMS content
+ * resolves to the real component instead of the unknown-component fallback.
+ */
+export const siteMdxComponents = mdxComponents(widgets);
diff --git a/templates/shadcn/next-env.d.ts b/templates/shadcn/next-env.d.ts
new file mode 100644
index 0000000..9edff1c
--- /dev/null
+++ b/templates/shadcn/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/templates/shadcn/next.config.ts b/templates/shadcn/next.config.ts
new file mode 100644
index 0000000..02714a1
--- /dev/null
+++ b/templates/shadcn/next.config.ts
@@ -0,0 +1,17 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  transpilePackages: ['@inkform/framework'],
+  images: { remotePatterns: [{ protocol: 'https', hostname: '**' }] },
+  // Pagefind indexes .next/server/app's built .html files directly, so its
+  // search results carry a trailing .html this app doesn't actually serve
+  // (e.g. /essentials/markdown.html) — this app's real routes are
+  // extensionless. Redirect (not rewrite) so the address bar ends up on the
+  // real, shareable permalink; query params (?q=... for highlighting) are
+  // preserved automatically.
+  async redirects() {
+    return [{ source: '/:path*.html', destination: '/:path*', permanent: false }];
+  },
+};
+
+export default nextConfig;
diff --git a/templates/shadcn/package.json b/templates/shadcn/package.json
new file mode 100644
index 0000000..a4964eb
--- /dev/null
+++ b/templates/shadcn/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@inkform/theme-shadcn",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Shadcn — a documentation theme for @inkform/framework that reproduces shadcn/ui's own default look: Zinc grayscale, a monochrome primary that inverts between light and dark, 0.5rem radius.",
+  "license": "MIT",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "postbuild": "pagefind --site .next/server/app --output-path public/_pagefind",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inkform/framework": "^0.3.0",
+    "lucide-react": "^0.483.0",
+    "next": "16.2.10",
+    "react": "19.2.1",
+    "react-dom": "19.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "pagefind": "^1.5.2",
+    "typescript": "^5"
+  }
+}
diff --git a/templates/shadcn/proxy.ts b/templates/shadcn/proxy.ts
new file mode 100644
index 0000000..a0fd617
--- /dev/null
+++ b/templates/shadcn/proxy.ts
@@ -0,0 +1,22 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { resolveSlugRedirect } from '@inkform/framework';
+import slugHistory from './content/docs/slug-history.json';
+
+/** Docs are served at the root, so slug-history redirects use the '/' base. */
+export function proxy(req: NextRequest) {
+  const target = resolveSlugRedirect(
+    req.nextUrl.pathname,
+    slugHistory as Record<string, string>,
+    '/',
+  );
+  if (target) {
+    return NextResponse.redirect(new URL(target, req.url), 301);
+  }
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
+  ],
+};
diff --git a/templates/shadcn/public/favicon.svg b/templates/shadcn/public/favicon.svg
new file mode 100644
index 0000000..cc18237
--- /dev/null
+++ b/templates/shadcn/public/favicon.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" role="img" aria-label="shadcn favicon">
+  <rect width="32" height="32" rx="8" fill="#18181b"/>
+  <rect x="9" y="9" width="14" height="14" rx="3.5" fill="#fafafa"/>
+</svg>
diff --git a/templates/shadcn/public/hero.svg b/templates/shadcn/public/hero.svg
new file mode 100644
index 0000000..faddf13
--- /dev/null
+++ b/templates/shadcn/public/hero.svg
@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 360" fill="none" role="img" aria-label="shadcn documentation hero">
+  <rect width="800" height="360" rx="20" fill="#09090b"/>
+  <circle cx="130" cy="70" r="190" fill="#27272a"/>
+  <circle cx="670" cy="300" r="180" fill="#18181b"/>
+  <circle cx="650" cy="50" r="110" fill="#3f3f46"/>
+  <circle cx="110" cy="320" r="120" fill="#09090b"/>
+  <circle cx="400" cy="180" r="86" fill="#fafafa"/>
+  <path d="M394 220 Q391 178 400 140 Q409 178 406 220 Z" fill="#fafafa" transform="rotate(-55 400 220)"/>
+  <path d="M394 220 Q391 176 400 136 Q409 176 406 220 Z" fill="#fafafa" transform="rotate(-27 400 220)"/>
+  <path d="M394 220 Q391 174 400 132 Q409 174 406 220 Z" fill="#fafafa"/>
+  <path d="M394 220 Q391 176 400 136 Q409 176 406 220 Z" fill="#fafafa" transform="rotate(27 400 220)"/>
+  <path d="M394 220 Q391 178 400 140 Q409 178 406 220 Z" fill="#fafafa" transform="rotate(55 400 220)"/>
+</svg>
diff --git a/templates/shadcn/public/logo.svg b/templates/shadcn/public/logo.svg
new file mode 100644
index 0000000..8053d77
--- /dev/null
+++ b/templates/shadcn/public/logo.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 118 32" fill="none" role="img" aria-label="shadcn">
+  <!-- Monochrome nested-square mark — a generic "components" motif, not a
+       reproduction of shadcn/ui's actual logo. -->
+  <rect x="4" y="4" width="24" height="24" rx="6" fill="none" stroke="#18181b" stroke-width="2"/>
+  <rect x="10" y="10" width="12" height="12" rx="3" fill="#18181b"/>
+  <!-- Wordmark — lowercase, matching how the real project styles its own name. -->
+  <text x="36" y="21" font-family="ui-sans-serif, system-ui, -apple-system, sans-serif" font-size="15" font-weight="600" letter-spacing="-0.01em" fill="currentColor">shadcn</text>
+</svg>
diff --git a/templates/shadcn/tsconfig.json b/templates/shadcn/tsconfig.json
new file mode 100644
index 0000000..e7ff3a2
--- /dev/null
+++ b/templates/shadcn/tsconfig.json
@@ -0,0 +1,41 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
diff --git a/templates/shadcn/widgets/Counter.tsx b/templates/shadcn/widgets/Counter.tsx
new file mode 100644
index 0000000..d786325
--- /dev/null
+++ b/templates/shadcn/widgets/Counter.tsx
@@ -0,0 +1,13 @@
+'use client';
+
+import { useState } from 'react';
+
+/** Real test widget proving MDX/CMS content can render a user-registered component, not the Fallback placeholder. */
+export function Counter({ start = 0 }: { start?: number }) {
+  const [count, setCount] = useState(start);
+  return (
+    <button type="button" className="fw-widget-counter" onClick={() => setCount((c) => c + 1)}>
+      Widget count: {count}
+    </button>
+  );
+}
diff --git a/templates/shadcn/widgets/index.ts b/templates/shadcn/widgets/index.ts
new file mode 100644
index 0000000..a04190f
--- /dev/null
+++ b/templates/shadcn/widgets/index.ts
@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react';
+import { Counter } from './Counter';
+
+/**
+ * Custom widget registry. Put your component at widgets/<Name>.tsx, import
+ * it here, and add it to this map — the key becomes the JSX tag name your
+ * MDX/CMS content uses (<Name ... />). Framework docs: "Custom Widgets."
+ */
+const widgets: Record<string, ComponentType<any>> = {
+  Counter,
+};
+
+export default widgets;