@honeydeck/honeydeck 0.5.0 → 0.6.0

package/AGENTS.md

@@ -1,13 +1,13 @@
 # Honeydeck package guide
 
-This package publishes the scoped public `@honeydeck/honeydeck` npm package. It owns the CLI, runtime, Vite plugin, layouts, themes, bundled skills, canonical package docs, and runtime reference pages.
+This package publishes the scoped public `@honeydeck/honeydeck` npm package. It owns the CLI, runtime, Vite plugin, layouts, themes, bundled skills, and runtime reference pages.
 
 ## Rules
 
 - Keep public import paths as `@honeydeck/honeydeck/...`.
-- `Readme.md` is the compact package README. `docs/getting-started.md` is the canonical first-run guide. Other canonical prose docs live in `docs/*.md`; keep links in MDX form unless referring to user/Slidev source files.
-- Built-in runtime reference pages cover project-specific theme tokens, active layouts, and built-in component docs. They do not render package Markdown docs in-deck.
-- Package docs, specs, `DEVELOPMENT.md`, and skills must remain included in npm package contents.
+- `Readme.md` is the compact package README and links to the public docs site. Reader-facing docs live in `packages/docs/content/docs`.
+- Built-in runtime reference pages cover project-specific theme tokens, active layouts, and built-in component docs. They do not render public docs in-deck.
+- Specs, `DEVELOPMENT.md`, and skills must remain included in npm package contents.
 - Use suffixed `lucide-react` icon exports.
 
 ## Commands

package/DEVELOPMENT.md

@@ -166,12 +166,12 @@ Important implications:
 - CLI bin points at `./src/cli/index.ts`.
 - Vite resolves Honeydeck runtime/layout/theme/component exports from source.
 - Local development and tests use `tsx` to execute TypeScript directly.
-- `package.json#files` must include all runtime, docs, spec, development, and skill files needed by installed users and AI agents.
+- `package.json#files` must include all runtime, spec, development, and skill files needed by installed users and AI agents.
 
 Published package contents must include:
 
 - `src/` for CLI, runtime, layouts, themes, Vite plugin, and assets
-- `Readme.md` as the compact package README, `docs/getting-started.md` as the first-run guide, and `docs/*.md` for package docs and marketing-site sync
+- `Readme.md` as the compact package README with links to the public docs site
 - Root `SPEC.md` plus colocated `SPEC.md` files so AI agents and maintainers can inspect expected behavior from an installed package
 - `DEVELOPMENT.md` so maintainers can inspect development workflow, internal architecture, testing, and release expectations from an installed package
 - `skills/` so `honeydeck skill`, `npx skills add <honeydeck-repo-url> --copy`, and explicit `npx skills add <honeydeck-repo-url> --copy --skill <skill-name>` can install Honeydeck agent skills
@@ -498,7 +498,6 @@ honeydeck/
     theme/                  Base, clean, and bee CSS theme layers and colocated theme tests
     defaults.ts             Shared defaults such as default deck entry
     assets.d.ts             Static asset type declarations
-  docs/                     Canonical Markdown docs synced into the marketing docs site
   skills/                   Bundled installable agent skills
   Readme.md                 Compact package README and documentation index
   SPEC.md                   Overview and navigation map for behavior specs

package/Readme.md

@@ -14,24 +14,24 @@ npm run dev
 
 Open the local URL printed by the dev server, edit `deck.mdx`, and your slides update instantly.
 
-Decks are plain MDX files separated into slides with `---`; see the first deck example in [Getting started](docs/getting-started.md).
+Decks are plain MDX files separated into slides with `---`; see the first deck example in [Getting started](https://honeydeck.dev/docs/getting-started).
 
 ## Documentation
 
-- [Getting started](docs/getting-started.md) - first deck, first commands, and the shortest path to presenting
-- [Deeper dive](docs/deeper-dive.md) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
-- [Slides](docs/slides.md) - separators, multiple files, layouts, and assets
-- [Configuration](docs/configuration.md) - deck-level and slide-level frontmatter
-- [Steps and reveals](docs/steps-and-reveals.md) - timeline, reveal groups, code steps, Magic Code, and PDF behavior
-- [Components](docs/components.md) - core Honeydeck components such as `Reveal`, `RevealWith`, `BrowserFrame`, and `Keyboard`
-- [Customization](docs/customization.md) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
-- [Navigation](docs/navigation.md) - keyboard, touch, overview mode, and URL state
-- [Mobile and touch](docs/mobile.md) - mobile controls, touch gestures, and pinch zoom
-- [Presenter mode](docs/presenter-mode.md) - notes, presenter window, sync, and mobile behavior
-- [PDF export](docs/pdf-export.md) - options, color modes, and step handling
-- [Local development](docs/local-development.md) - running Honeydeck from this repository
-- [Skills](docs/skills.md) - optional agent skills for authoring, writing, and migration help
-- [Slidev migration](docs/slidev-migration.md) - moving from Slidev with the bundled agent skill
+- [Getting started](https://honeydeck.dev/docs/getting-started) - first deck, first commands, and the shortest path to presenting
+- [Deeper dive](https://honeydeck.dev/docs/deeper-dive) - CLI options, authoring patterns, imports, themes, architecture, and agent skills
+- [Slides](https://honeydeck.dev/docs/slides) - separators, multiple files, layouts, and assets
+- [Configuration](https://honeydeck.dev/docs/configuration) - deck-level and slide-level frontmatter
+- [Steps and reveals](https://honeydeck.dev/docs/steps-and-reveals) - timeline, reveal groups, code steps, Magic Code, and PDF behavior
+- [Components](https://honeydeck.dev/docs/components) - core Honeydeck components such as `Reveal`, `RevealWith`, `BrowserFrame`, and `Keyboard`
+- [Customization](https://honeydeck.dev/docs/customization) - themes, layout sets, Tailwind tokens, custom layouts, and layout demos
+- [Navigation](https://honeydeck.dev/docs/navigation) - keyboard, touch, overview mode, and URL state
+- [Mobile and touch](https://honeydeck.dev/docs/mobile) - mobile controls, touch gestures, and pinch zoom
+- [Presenter mode](https://honeydeck.dev/docs/presenter-mode) - notes, presenter window, sync, and mobile behavior
+- [PDF export](https://honeydeck.dev/docs/pdf-export) - options, color modes, and step handling
+- [Local development](https://honeydeck.dev/docs/local-development) - running Honeydeck from this repository
+- [Skills](https://honeydeck.dev/docs/skills) - optional agent skills for authoring, writing, and migration help
+- [Slidev migration](https://honeydeck.dev/docs/slidev-migration) - moving from Slidev with the bundled agent skill
 
 ## Common commands
 

package/SPEC.md

@@ -31,7 +31,7 @@ The Honeydeck specification is distributed:
 | Runtime | Node.js CLI binary from the scoped `@honeydeck/honeydeck` package | [`src/cli/SPEC.md`](src/cli/SPEC.md) |
 | Build setup | Honeydeck-managed dev/build setup; no user `vite.config.ts` required | [`src/runtime/SPEC.md`](src/runtime/SPEC.md), [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md) |
 | Styling | Explicit CSS imports, Tailwind-compatible utilities, and CSS custom properties | [`src/theme/SPEC.md`](src/theme/SPEC.md) |
-| Markdown | MDX with GitHub-flavored Markdown tables; canonical docs use `docs/*.md` | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md), [`src/remark/SPEC.md`](src/remark/SPEC.md) |
+| Markdown | MDX with GitHub-flavored Markdown tables; reader-facing docs are authored in `packages/docs/content/docs` and exported into package-local `docs/*.md` files during npm packaging | [`src/vite-plugin/SPEC.md`](src/vite-plugin/SPEC.md), [`src/remark/SPEC.md`](src/remark/SPEC.md) |
 | PDF | Rasterized slide pages matching browser rendering | [`src/cli/SPEC.md`](src/cli/SPEC.md) |
 | Syntax highlighting | Built-in code highlighting, runtime step dimming, and Magic Code transitions | [`src/remark/SPEC.md`](src/remark/SPEC.md) |
 | Icons | `lucide-react` suffixed `...Icon` component imports | [`src/SPEC.md`](src/SPEC.md) |
@@ -43,6 +43,7 @@ The Honeydeck specification is distributed:
 - Honeydeck wires the Tailwind Vite plugin internally, but Tailwind/theme CSS is only loaded when user-authored CSS imports it; generated projects install `tailwindcss` and import `./styles.css` from `deck.mdx`.
 - Generated projects use compatible semver ranges for React, Tailwind, TypeScript, and types.
 - Custom themes, layouts, and components are plain CSS/TypeScript modules; installed-package usage is handled by standard package metadata rather than by a Honeydeck-specific mechanism.
+- Published packages include generated package-local docs under `docs/*.md` plus `docs/index.json` so bundled agent skills can read version-aligned documentation from `node_modules/@honeydeck/honeydeck/docs`.
 - Icons come from `lucide-react` and must use suffixed `...Icon` component exports (for example `ChevronLeftIcon`), not inline SVG path helpers, emoji glyphs, or unsuffixed aliases.
 
 ---

package/docs/{components-browser-frame.md → browser-frame.md}

@@ -1,7 +1,11 @@
+<!-- Generated from packages/docs/content/docs/(components)/browser-frame.mdx. Do not edit by hand. -->
+
 # BrowserFrame
 
 Use `<BrowserFrame>` to show a live iframe inside a macOS-style browser window.
 
+<BrowserFramePlayground />
+
 ```mdx
 import { BrowserFrame } from '@honeydeck/honeydeck'
 

package/docs/components.md

@@ -1,22 +1,22 @@
+<!-- Generated from packages/docs/content/docs/(components)/components.mdx. Do not edit by hand. -->
+
 # Components
 
-Honeydeck core components are explicit imports from `@honeydeck/honeydeck`. They are also exported from `@honeydeck/honeydeck/components`.
+Honeydeck components are explicit MDX imports from `@honeydeck/honeydeck`. Use them when plain Markdown is not enough for timeline control, speaker notes, rich previews, or inline UI.
 
 ```mdx
 import { Reveal, RevealWith, RevealGroup, TimelineSteps, ListStyle, Keyboard, BrowserFrame, Notes } from '@honeydeck/honeydeck'
 ```
 
-Use these pages as the component reference:
-
 | Component | Use it for |
 | --- | --- |
-| [`Reveal`](components-reveal.md) | Show content at a specific slide timeline step. |
-| [`RevealWith`](components-reveal-with.md) | Show content with an existing reveal or numeric slide step without adding another step. |
-| [`RevealGroup`](components-reveal-group.md) | Reveal each direct child or list item one after another, with optional nested-list reveals. |
-| [`TimelineSteps`](components-timeline-steps.md) | Reserve timeline steps for an imported custom React component. |
-| [`ListStyle`](components-list-style.md) | Style Markdown, HTML, or JSX lists with no markers or custom markers. |
-| [`Keyboard`](components-keyboard.md) | Render semantic inline keyboard keys and shortcuts. |
-| [`BrowserFrame`](components-browser-frame.md) | Show a live iframe or fallback screenshot inside browser chrome. |
-| [`Notes`](components-notes.md) | Add formatted speaker notes for presenter mode. |
+| [`Reveal`](reveal.md) | Show content at a specific slide timeline step. |
+| [`RevealWith`](reveal-with.md) | Show content with an existing reveal or numeric slide step without adding another step. |
+| [`RevealGroup`](reveal-group.md) | Reveal each direct child or list item one after another, with optional nested-list reveals. |
+| [`TimelineSteps`](timeline-steps.md) | Reserve timeline steps for an imported custom React component. |
+| [`ListStyle`](list-style.md) | Style Markdown, HTML, or JSX lists with no markers or custom markers. |
+| [`Keyboard`](keyboard.md) | Render semantic inline keyboard keys and shortcuts. |
+| [`BrowserFrame`](browser-frame.md) | Show a live iframe or fallback screenshot inside browser chrome. |
+| [`Notes`](notes.md) | Add formatted speaker notes for presenter mode. |
 
-For broader timing concepts, see [Steps and reveals](steps-and-reveals.md). For custom components and layouts, see [Customization](customization.md).
+For timeline behavior in context, also see [Steps and reveals](steps-and-reveals.md).

package/docs/configuration.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/configuration.mdx. Do not edit by hand. -->
+
 # Configuration
 
 All settings live in YAML frontmatter — no separate config file.

package/docs/customization.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/customization.mdx. Do not edit by hand. -->
+
 # Customization
 
 Honeydeck starts with built-in layouts and a small base theme. Customize only what you need: CSS tokens, React components, or a layout map.

package/docs/deeper-dive.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(start)/deeper-dive.mdx. Do not edit by hand. -->
+
 # Diving deeper
 
 Use this guide after the quick start when you want to understand the main Honeydeck workflows without jumping straight into every reference page.

package/docs/getting-started.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(start)/getting-started.mdx. Do not edit by hand. -->
+
 # Getting started
 
 Honeydeck helps you create polished, interactive presentations using MDX. Write slides in Markdown, use different Layout, add React components when you need them, present using presenter mode, and export to PDF for easy sharing.

package/docs/index.json

@@ -0,0 +1,258 @@
+{
+  "generatedFrom": "packages/docs/content/docs",
+  "pages": [
+    {
+      "slug": "getting-started",
+      "title": "Getting started",
+      "description": "Getting started documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Start",
+        "Getting started"
+      ],
+      "file": "getting-started.md",
+      "sourcePath": "packages/docs/content/docs/(start)/getting-started.mdx"
+    },
+    {
+      "slug": "deeper-dive",
+      "title": "Deeper dive",
+      "description": "Deeper dive documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Start",
+        "Deeper dive"
+      ],
+      "file": "deeper-dive.md",
+      "sourcePath": "packages/docs/content/docs/(start)/deeper-dive.mdx"
+    },
+    {
+      "slug": "slides",
+      "title": "Slides",
+      "description": "Slides documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Slides"
+      ],
+      "file": "slides.md",
+      "sourcePath": "packages/docs/content/docs/(core)/slides.mdx"
+    },
+    {
+      "slug": "configuration",
+      "title": "Configuration",
+      "description": "Configuration documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Configuration"
+      ],
+      "file": "configuration.md",
+      "sourcePath": "packages/docs/content/docs/(core)/configuration.mdx"
+    },
+    {
+      "slug": "steps-and-reveals",
+      "title": "Steps and reveals",
+      "description": "Steps and reveals documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Steps and reveals"
+      ],
+      "file": "steps-and-reveals.md",
+      "sourcePath": "packages/docs/content/docs/(core)/steps-and-reveals.mdx"
+    },
+    {
+      "slug": "customization",
+      "title": "Customization",
+      "description": "Customization documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Customization"
+      ],
+      "file": "customization.md",
+      "sourcePath": "packages/docs/content/docs/(core)/customization.mdx"
+    },
+    {
+      "slug": "navigation",
+      "title": "Navigation",
+      "description": "Navigation documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Navigation"
+      ],
+      "file": "navigation.md",
+      "sourcePath": "packages/docs/content/docs/(core)/navigation.mdx"
+    },
+    {
+      "slug": "mobile",
+      "title": "Mobile and touch",
+      "description": "Mobile and touch documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Mobile and touch"
+      ],
+      "file": "mobile.md",
+      "sourcePath": "packages/docs/content/docs/(core)/mobile.mdx"
+    },
+    {
+      "slug": "presenter-mode",
+      "title": "Presenter mode",
+      "description": "Presenter mode documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "Presenter mode"
+      ],
+      "file": "presenter-mode.md",
+      "sourcePath": "packages/docs/content/docs/(core)/presenter-mode.mdx"
+    },
+    {
+      "slug": "pdf-export",
+      "title": "PDF export",
+      "description": "PDF export documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Core",
+        "PDF export"
+      ],
+      "file": "pdf-export.md",
+      "sourcePath": "packages/docs/content/docs/(core)/pdf-export.mdx"
+    },
+    {
+      "slug": "components",
+      "title": "Components",
+      "description": "Core Honeydeck components for timelines, presenter notes, browser frames, keyboard shortcuts, and styled lists.",
+      "breadcrumbs": [
+        "Components",
+        "Components"
+      ],
+      "file": "components.md",
+      "sourcePath": "packages/docs/content/docs/(components)/components.mdx"
+    },
+    {
+      "slug": "reveal",
+      "title": "Reveal",
+      "description": "Reveal documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "Reveal"
+      ],
+      "file": "reveal.md",
+      "sourcePath": "packages/docs/content/docs/(components)/reveal.mdx"
+    },
+    {
+      "slug": "reveal-with",
+      "title": "RevealWith",
+      "description": "RevealWith documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "RevealWith"
+      ],
+      "file": "reveal-with.md",
+      "sourcePath": "packages/docs/content/docs/(components)/reveal-with.mdx"
+    },
+    {
+      "slug": "reveal-group",
+      "title": "RevealGroup",
+      "description": "RevealGroup documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "RevealGroup"
+      ],
+      "file": "reveal-group.md",
+      "sourcePath": "packages/docs/content/docs/(components)/reveal-group.mdx"
+    },
+    {
+      "slug": "timeline-steps",
+      "title": "TimelineSteps",
+      "description": "TimelineSteps documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "TimelineSteps"
+      ],
+      "file": "timeline-steps.md",
+      "sourcePath": "packages/docs/content/docs/(components)/timeline-steps.mdx"
+    },
+    {
+      "slug": "list-style",
+      "title": "ListStyle",
+      "description": "ListStyle documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "ListStyle"
+      ],
+      "file": "list-style.md",
+      "sourcePath": "packages/docs/content/docs/(components)/list-style.mdx"
+    },
+    {
+      "slug": "keyboard",
+      "title": "Keyboard",
+      "description": "Keyboard documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "Keyboard"
+      ],
+      "file": "keyboard.md",
+      "sourcePath": "packages/docs/content/docs/(components)/keyboard.mdx"
+    },
+    {
+      "slug": "browser-frame",
+      "title": "BrowserFrame",
+      "description": "BrowserFrame documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "BrowserFrame"
+      ],
+      "file": "browser-frame.md",
+      "sourcePath": "packages/docs/content/docs/(components)/browser-frame.mdx"
+    },
+    {
+      "slug": "notes",
+      "title": "Notes",
+      "description": "Notes documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Components",
+        "Notes"
+      ],
+      "file": "notes.md",
+      "sourcePath": "packages/docs/content/docs/(components)/notes.mdx"
+    },
+    {
+      "slug": "local-development",
+      "title": "Local development",
+      "description": "Local development documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Develop",
+        "Local development"
+      ],
+      "file": "local-development.md",
+      "sourcePath": "packages/docs/content/docs/(develop)/local-development.mdx"
+    },
+    {
+      "slug": "skills",
+      "title": "Skills",
+      "description": "Skills documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Advanced",
+        "Skills"
+      ],
+      "file": "skills.md",
+      "sourcePath": "packages/docs/content/docs/(advanced)/skills.mdx"
+    },
+    {
+      "slug": "slidev-migration",
+      "title": "Slidev migration",
+      "description": "Slidev migration documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Advanced",
+        "Slidev migration"
+      ],
+      "file": "slidev-migration.md",
+      "sourcePath": "packages/docs/content/docs/(advanced)/slidev-migration.mdx"
+    },
+    {
+      "slug": "mermaid",
+      "title": "Mermaid",
+      "description": "Mermaid documentation for Honeydeck.",
+      "breadcrumbs": [
+        "Advanced",
+        "Mermaid"
+      ],
+      "file": "mermaid.md",
+      "sourcePath": "packages/docs/content/docs/(advanced)/mermaid.mdx"
+    }
+  ]
+}

package/docs/{components-keyboard.md → keyboard.md}

@@ -1,7 +1,11 @@
+<!-- Generated from packages/docs/content/docs/(components)/keyboard.mdx. Do not edit by hand. -->
+
 # Keyboard
 
 Use `<Keyboard>` to show one key or a shortcut in slide prose.
 
+<KeyboardPlayground />
+
 ```mdx
 import { Keyboard } from '@honeydeck/honeydeck'
 

package/docs/{components-list-style.md → list-style.md}

@@ -1,7 +1,11 @@
+<!-- Generated from packages/docs/content/docs/(components)/list-style.mdx. Do not edit by hand. -->
+
 # ListStyle
 
 Use `<ListStyle>` to style Markdown, HTML, or JSX lists inside a wrapper.
 
+<ListStylePlayground />
+
 By default it removes native markers:
 
 ```mdx

package/docs/local-development.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(develop)/local-development.mdx. Do not edit by hand. -->
+
 # Local development
 
 This guide explains how to test Honeydeck locally before it is published to npm.
@@ -19,7 +21,7 @@ npm install
 npm run dev
 ```
 
-Root `npm run dev` starts the private showcase deck package and the marketing/docs site together.
+Root `npm run dev` starts the private showcase deck package and the docs site together.
 
 To run only the showcase deck:
 

package/docs/mermaid.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(advanced)/mermaid.mdx. Do not edit by hand. -->
+
 # Mermaid
 
 Mermaid is not part of Honeydeck core. Use it as a normal project dependency and render diagrams through a local React component that you import from your deck.

package/docs/mobile.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/mobile.mdx. Do not edit by hand. -->
+
 # Mobile and Touch
 
 Honeydeck works on phones and tablets, but mobile presentation mode behaves differently from desktop so touch gestures stay reliable.

package/docs/navigation.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/navigation.mdx. Do not edit by hand. -->
+
 # Navigation
 
 ## Keyboard Shortcuts

package/docs/{components-notes.md → notes.md}

@@ -1,7 +1,11 @@
+<!-- Generated from packages/docs/content/docs/(components)/notes.mdx. Do not edit by hand. -->
+
 # Notes
 
 Use `<Notes>` to add presenter-only speaker notes to a slide.
 
+<NotesPlayground />
+
 ```mdx
 import { Notes } from '@honeydeck/honeydeck'
 

package/docs/pdf-export.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/pdf-export.mdx. Do not edit by hand. -->
+
 # PDF Export
 
 ## How It Works

package/docs/presenter-mode.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/presenter-mode.mdx. Do not edit by hand. -->
+
 # Presenter Mode
 
 ## Overview

package/docs/{components-reveal-group.md → reveal-group.md}

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(components)/reveal-group.mdx. Do not edit by hand. -->
+
 # RevealGroup
 
 Use `<RevealGroup>` when a short sequence should appear one item at a time.

package/docs/{components-reveal-with.md → reveal-with.md}

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(components)/reveal-with.mdx. Do not edit by hand. -->
+
 # RevealWith
 
 Use `<RevealWith>` when content should appear at the same timeline step as a named `<Reveal>` or any existing numeric slide step. It never adds a new step.

package/docs/{components-reveal.md → reveal.md}

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(components)/reveal.mdx. Do not edit by hand. -->
+
 # Reveal
 
 Use `<Reveal>` when content should appear at the next timeline step.
@@ -17,9 +19,9 @@ Reveals are cumulative: once visible, they stay visible while you advance throug
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `children` | `ReactNode` | — | Content to reveal. |
-| `name` | `string` | — | Optional slide-local target for [`RevealWith target="..."`](components-reveal-with.md). Must be a literal non-empty string. |
+| `name` | `string` | — | Optional slide-local target for [`RevealWith target="..."`](reveal-with.md). Must be a literal non-empty string. |
 | `className` | `string` | — | Custom class for styling or transitions. |
-| `at` | `number` | injected | Timeline step. Honeydeck injects this during compilation; author-authored values are build errors. Use [`RevealWith`](components-reveal-with.md) to sync with an existing step. |
+| `at` | `number` | injected | Timeline step. Honeydeck injects this during compilation; author-authored values are build errors. Use [`RevealWith`](reveal-with.md) to sync with an existing step. |
 | `as` | `"div" \| "span"` | injected | Wrapper element. Honeydeck injects this to keep valid MDX/HTML around block or inline content. |
 
 ## Behavior
@@ -28,6 +30,6 @@ Reveals are cumulative: once visible, they stay visible while you advance throug
 - Hidden content uses `visibility: hidden` plus `opacity: 0`, not `display: none`.
 - Nested reveals are supported.
 - Inline reveals inside paragraphs render inline wrappers.
-- Optional `name="..."` creates a slide-local target for [`RevealWith`](components-reveal-with.md).
+- Optional `name="..."` creates a slide-local target for [`RevealWith`](reveal-with.md).
 
 See [Steps and reveals](steps-and-reveals.md) for timeline ordering examples.

package/docs/skills.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(advanced)/skills.mdx. Do not edit by hand. -->
+
 # Skills
 
 Honeydeck ships optional agent skills that help AI coding agents work with presentations more reliably. They are plain skill files bundled with the `@honeydeck/honeydeck` package, so you can install them into a deck project or into your global agent setup.
@@ -31,7 +33,7 @@ npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
 
 | Skill | Use it for |
 | --- | --- |
-| `honeydeck` | Honeydeck-specific guidance for MDX decks, layouts, CSS imports, presenter notes, reveals, code steps, Magic Code, PDF export, and package docs. |
+| `honeydeck` | Honeydeck-specific guidance for MDX decks, layouts, CSS imports, presenter notes, reveals, code steps, Magic Code, PDF export, public docs, and package specs. |
 | `presentation-writing` | Framework-agnostic help with audience, storyline, slide headlines, speaker notes, timing, and review heuristics. |
 | `slidev-migration` | Migrating Slidev decks to Honeydeck, including rewriting Slidev `md magic-move` blocks to Honeydeck `md magic-code`, while preserving source files until you approve cleanup. |
 

package/docs/slides.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/slides.mdx. Do not edit by hand. -->
+
 # Slides
 
 ## Basics

package/docs/slidev-migration.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(advanced)/slidev-migration.mdx. Do not edit by hand. -->
+
 # Slidev migration
 
 Coming from [Slidev](https://sli.dev)? Honeydeck ships an optional `slidev-migration` agent skill that can help an AI coding agent initialize a Honeydeck project and migrate a Slidev deck.

package/docs/steps-and-reveals.md

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(core)/steps-and-reveals.mdx. Do not edit by hand. -->
+
 # Steps & Reveals
 
 Honeydeck has a first-class step concept. Each slide has a timeline built from `Reveal`/`RevealGroup`/`Fade`/`FadeGroup` components, `RevealWith`/`FadeWith` synchronized content, custom component step blocks, code highlight ranges, and Magic Code states, counted in document order.

package/docs/{components-timeline-steps.md → timeline-steps.md}

@@ -1,3 +1,5 @@
+<!-- Generated from packages/docs/content/docs/(components)/timeline-steps.mdx. Do not edit by hand. -->
+
 # TimelineSteps
 
 Use `<TimelineSteps>` when an imported React component should control part of a slide timeline.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@honeydeck/honeydeck",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
 	"license": "MIT",
 	"publishConfig": {
@@ -35,8 +35,8 @@
 		"!src/**/*.test.tsx",
 		"!src/**/fixtures",
 		"!src/**/fixtures/**",
-		"docs",
 		"skills",
+		"docs",
 		"Readme.md",
 		"SPEC.md",
 		"DEVELOPMENT.md",
@@ -95,6 +95,7 @@
 		"dev:init": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
 		"format": "biome check --write",
 		"lint": "biome check",
+		"prepack": "npm -w @honeydeck/docs run export:package-docs",
 		"pack:dry-run": "npm pack --dry-run",
 		"pack:smoke": "node ./scripts/packed-smoke.mjs",
 		"release:plan": "node ./scripts/release-plan.mjs",

package/skills/SPEC.md

@@ -6,17 +6,17 @@
 
 Honeydeck ships installable agent skills:
 
-- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, canonical package docs, and runtime reference pages.
+- `skills/honeydeck/SKILL.md` (`honeydeck`) helps AI agents use Honeydeck correctly: MDX entrypoint, deck frontmatter, exact `---` slide separators, slide frontmatter, built-in layouts, explicit theme/CSS imports, presenter notes, steps/reveals, code blocks, PDF export, custom React components, customization, public docs, specs, and runtime reference pages.
 - `skills/presentation-writing/SKILL.md` (`presentation-writing`) gives opinionated guidance for writing great slides and delivering good presentations: audience/goal/duration discovery, storyline, one idea per slide, strong headlines, sparse visuals, speaker notes, timing, narrative flow, progressive disclosure, and review heuristics.
 - `skills/slidev-migration/SKILL.md` (`slidev-migration`) helps AI agents migrate presentations from Slidev/sli.dev to Honeydeck: initialize a Honeydeck project when needed, convert `slides.md` to `deck.mdx`, map Slidev frontmatter/layouts/assets/notes/reveals/scripts/Magic Move code blocks to Honeydeck equivalents, and flag Vue/theme features that need manual React follow-up.
 
 Expected behavior:
 
 - All skills are discoverable by the `skills` CLI when users run `npx skills add <honeydeck-repo-url> --copy` or explicit `npx skills add <honeydeck-repo-url> --copy --skill honeydeck` / `--skill presentation-writing` / `--skill slidev-migration`.
-- The `honeydeck` skill instructs agents to use Honeydeck documentation (`Readme.md` for package overview, `docs/getting-started.md` for first-run guidance, package/root `SPEC.md`, linked colocated `SPEC.md` files, `docs/deeper-dive.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/customization.md`, `docs/configuration.md`, and related docs) as the source of truth when available.
-- The `honeydeck` skill documents a local docs discovery order: current project's `node_modules/@honeydeck/honeydeck`, monorepo checkout `packages/honeydeck`, package-root checkout docs, then the public docs URL.
+- The `honeydeck` skill instructs agents to use installed Honeydeck package documentation (`node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/docs/index.json`, `Readme.md`, package `SPEC.md`, linked colocated `SPEC.md` files, and the public docs site) as the source of truth when available.
+- The `honeydeck` skill documents a consumer-focused local docs discovery order: current project's `node_modules/@honeydeck/honeydeck/docs` package docs first, then installed package specs, then package-root checkout docs/specs, then the public docs URL. It must not require monorepo-only `packages/docs` paths for normal installed-package use.
 - The `presentation-writing` skill is framework-agnostic enough to help with presentation quality, while still working well alongside the Honeydeck skill.
 - The `slidev-migration` skill instructs agents to inspect existing Slidev projects, preserve source files until the user approves cleanup, initialize or merge Honeydeck starter files, migrate common Slidev syntax to Honeydeck MDX/React, rewrite `md magic-move` blocks to Honeydeck's canonical `md magic-code` syntax, and document unsupported or approximated features.
 - `honeydeck init` should offer to open the interactive skills installer for the generated project and make clear that accepting runs `npx skills add`.
 - `honeydeck init` and `honeydeck skill` should delegate bundled skill selection, scope selection, and agent selection to the same `npx skills add <honeydeck-package-source> --copy` flow.
-- `docs/skills.md` should document why and how to install the bundled skills, list the `honeydeck`, `presentation-writing`, and `slidev-migration` skills, and link to the Slidev migration guide for migration-specific details.
+- `packages/docs/content/docs/(advanced)/skills.mdx` should document why and how to install the bundled skills, list the `honeydeck`, `presentation-writing`, and `slidev-migration` skills, and link to the Slidev migration guide for migration-specific details.

package/skills/honeydeck/SKILL.md

@@ -9,28 +9,28 @@ You help the user work with Honeydeck presentations. Honeydeck decks are MDX fil
 
 ## Source of truth
 
-Before giving Honeydeck-specific syntax or changing a deck, prefer repository/package docs when available.
+Before giving Honeydeck-specific syntax or changing a deck, prefer the installed package docs and package specs when available. This skill is for consumers of the `@honeydeck/honeydeck` package, so do not depend on monorepo-only paths.
 
 Docs discovery order:
 
-1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and `node_modules/@honeydeck/honeydeck/docs/*.md`.
-2. Monorepo checkout docs: `packages/honeydeck/Readme.md`, `packages/honeydeck/SPEC.md`, and `packages/honeydeck/docs/*.md`.
-3. Fresh app or package-root docs: `Readme.md`, `SPEC.md`, and `docs/*.md`.
-4. Public docs URL when local docs are unavailable: `/docs` on the Honeydeck marketing site.
+1. Current project dependency docs: `node_modules/@honeydeck/honeydeck/docs/index.json`, `node_modules/@honeydeck/honeydeck/docs/*.md`, `node_modules/@honeydeck/honeydeck/Readme.md`, `node_modules/@honeydeck/honeydeck/SPEC.md`, and linked colocated `SPEC.md` files.
+2. Package-root checkout docs: `docs/index.json`, `docs/*.md`, `Readme.md`, `SPEC.md`, and linked colocated `SPEC.md` files.
+3. Public docs URL when local docs are unavailable: `https://honeydeck.dev/docs`.
 
 Important docs:
 
 - `Readme.md` for the compact package overview and documentation index
+- `docs/index.json` for the installed docs page list and order
 - `docs/getting-started.md` for quick start and first-run orientation
 - `docs/deeper-dive.md` for CLI details, feature overview, architecture, exports, and agent skills
-- root/package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
+- package `SPEC.md` and linked colocated `SPEC.md` files for expected behavior
 - `docs/slides.md` for deck structure, slide separators, and multi-file decks
 - `docs/steps-and-reveals.md` for step-by-step reveals, code steps, and Magic Code
 - `docs/customization.md` for themes, layouts, custom React components, layout maps, demos, and design tokens
 - `docs/configuration.md` for frontmatter options
 - `docs/navigation.md`, `docs/mobile.md`, `docs/presenter-mode.md`, and `docs/pdf-export.md` for presenting/exporting
 
-If the user is inside a generated Honeydeck project and package docs are not nearby, tell them they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
+If local package docs are unavailable, tell the user they can use the public docs site for prose docs and run `npx honeydeck dev` to open runtime reference pages for active theme tokens, layouts, and built-in components.
 
 ## Honeydeck basics to remember
 

package/skills/slidev-migration/SKILL.md

@@ -11,15 +11,15 @@ Start by reading all Honeydeck related skills available. Alternatively you can c
 
 ## Source of truth
 
-Before changing files, read the available project/package docs:
+Before changing files, read the available project docs and package specs:
 
-- `Readme.md`, `docs/getting-started.md`, root `SPEC.md`, linked colocated `SPEC.md` files, and `docs/slides.md` for Honeydeck deck structure
-- `docs/configuration.md` for Honeydeck frontmatter
-- `docs/steps-and-reveals.md` for Reveal/RevealGroup/code steps
-- `docs/customization.md` for layouts, themes, components, layout maps, and design tokens
+- `Readme.md`, public docs content under `packages/docs/content/docs` when in the monorepo, root `SPEC.md`, linked colocated `SPEC.md` files, and the Slides guide for Honeydeck deck structure
+- The Configuration guide for Honeydeck frontmatter
+- The Steps and reveals guide for Reveal/RevealGroup/code steps
+- The Customization guide for layouts, themes, components, layout maps, and design tokens
 - Existing Slidev files: `slides.md`, `pages/**/*.md`, `components/**/*.vue`, `layouts/**/*.vue`, `styles/**`, `public/**`, `package.json`, `vite.config.*`, and local theme/addon packages
 
-If Honeydeck docs are not nearby, package docs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
+If Honeydeck docs are not nearby, package specs may be in `node_modules/@honeydeck/honeydeck`, or the user can use the public docs site. A migrated deck's runtime reference pages cover active theme tokens, layouts, and built-in components.
 
 ## Migration goal
 

package/src/runtime/components/SPEC.md

@@ -14,7 +14,7 @@ Injected fenced code blocks render through `HoneydeckCodeBlock` from the direct
 
 ### Color Mode Controls
 
-`@honeydeck/honeydeck/components` exports the configured color mode type and color mode cycle button for public imports used by Honeydeck chrome surfaces and the marketing site.
+`@honeydeck/honeydeck/components` exports the configured color mode type and color mode cycle button for public imports used by Honeydeck chrome surfaces and the docs site.
 
 ```tsx
 import { ColorModeCycleButton, type ColorMode } from '@honeydeck/honeydeck/components'
@@ -30,7 +30,7 @@ Behavior:
 
 ### Button Controls
 
-`@honeydeck/honeydeck/components` exports generic Honeydeck-token-based button primitives and class recipes for runtime chrome, runtime reference pages, and marketing controls.
+`@honeydeck/honeydeck/components` exports generic Honeydeck-token-based button primitives and class recipes for runtime chrome, runtime reference pages, and docs controls.
 
 ```tsx
 import { Button, buttonPrimaryClass, iconButtonClass } from '@honeydeck/honeydeck/components'
@@ -41,7 +41,7 @@ Behavior:
 - `<Button>` renders a native `button` with `type="button"` by default.
 - `variant` selects one of `primary`, `secondary`, `icon`, `small`, or `quiet`.
 - `buttonClass(variant, className)` returns the matching token-based Tailwind class string and appends `className` when provided.
-- Exported class recipes use only shipped Honeydeck base-theme tokens for foreground, surface, border, primary, and transition behavior (`--honeydeck-primary`, `--honeydeck-primary-foreground`, `--honeydeck-surface`, `--honeydeck-surface-foreground`, `--honeydeck-border`, `--honeydeck-foreground`, `--honeydeck-background`) so public imports do not depend on marketing-only aliases at publish time.
+- Exported class recipes use only shipped Honeydeck base-theme tokens for foreground, surface, border, primary, and transition behavior (`--honeydeck-primary`, `--honeydeck-primary-foreground`, `--honeydeck-surface`, `--honeydeck-surface-foreground`, `--honeydeck-border`, `--honeydeck-foreground`, `--honeydeck-background`) so public imports do not depend on docs-site-only aliases at publish time.
 
 ### Runtime chrome buttons