@honeydeck/honeydeck 0.1.0

package/docs/presenter-mode.md

@@ -0,0 +1,104 @@
+# Presenter Mode
+
+## Overview
+
+Presenter mode shows the presenter everything they need while the audience sees only the slides.
+
+## UI Layout
+
+```txt
+┌──────────────────────────────────────────┐
+│  ┌──────────────────┐  ┌──────────┐      │
+│  │                  │  │          │      │
+│  │     Current      │  │   Next   │      │
+│  │                  │  │          │      │
+│  └──────────────────┘  └──────────┘      │
+│                                          │
+│  Notes:                                  │
+│  - Remember to demo the sparkle button   │
+│  - Mention PDF export                    │
+│                                          │
+│  Slide 3/12 · Step 2/4    12:34  [Open]  │
+└──────────────────────────────────────────┘
+```
+
+Includes:
+- Current slide preview (larger)
+- Next timeline-state preview (smaller): the next step on the current slide when one exists, otherwise the next slide at step 0
+- Speaker notes for current slide
+- Slide number / step counter
+- Wall clock
+- Button to open audience view in a new tab/window
+- Navigation buttons that move through the timeline while staying in presenter mode
+
+## Speaker Notes
+
+Use the `Notes` component:
+
+```mdx
+import { Notes } from '@honeydeck/honeydeck'
+
+# My Slide
+
+Content here.
+
+<Notes>
+  # Demo cue
+
+  - Remember to demo the sparkle button
+  - Mention PDF export
+</Notes>
+```
+
+`Notes` content is:
+- Hidden from the normal audience slide view.
+- Excluded from PDF output.
+- Visible only in presenter mode.
+- Rendered as compact Markdown prose in the notes panel, including headings, lists, links, code, and quotes.
+
+## Opening Presenter Mode
+
+- Keyboard shortcut `p` from normal presentation → opens in a new window/tab.
+- Navigation controls button in normal presentation.
+- Direct URL: `/#/presenter/1/0`
+
+Pressing `p` opens presenter mode in a **new window** so the audience view stays on the projector.
+
+## Navigation
+
+Presenter mode uses the same timeline keyboard shortcuts as normal slide view:
+
+| Shortcut | Action |
+|----------|--------|
+| `→` / `d` | Next step; if no next step remains, next slide at step 0 |
+| `←` / `a` | Previous step; if at step 0, previous slide at final step |
+| `↓` / `s` | Next slide |
+| `↑` / `w` | Previous slide |
+
+Keyboard navigation and presenter navigation buttons keep the URL under `/#/presenter/...`. Presenter controls use `lucide-react` icons imported from suffixed `...Icon` exports.
+
+The `Next` preview shows the next timeline state, not just the next slide. Reveals and code step-through highlights therefore preview exactly what the audience will see after the next forward navigation.
+
+Reveal content from later timeline steps is also shown in the `Next` preview at reduced opacity, so the speaker can see what is still coming on that slide. Future steps remain hidden in audience view and in the presenter `Current` preview.
+
+When no next timeline state exists, the `Next` preview shows an end-of-deck placeholder instead of trying to render a missing slide.
+
+## Presenter/Audience Sync
+
+Presenter mode and audience view synchronize navigation via `BroadcastChannel` in the same browser/profile.
+
+- Presenter mode acts as the controller.
+- Audience view (opened from presenter mode) listens for navigation updates.
+- No server, internet, WebSocket, or device pairing required.
+- If `BroadcastChannel` is unavailable, both views function independently.
+
+This supports the common laptop/projector setup.
+
+## Mobile Presenter Mode
+
+On mobile, presenter mode shows:
+- Current slide
+- Notes
+- Navigation buttons
+
+No next slide preview (space constraint).

package/docs/slides.md

@@ -0,0 +1,130 @@
+# Slides
+
+## Basics
+
+Slides are separated by `---` and may contain YAML frontmatter:
+
+```mdx
+---
+layout: Section
+---
+
+# Big Idea
+
+Content here.
+```
+
+Layout names are PascalCase. If no `layout:` is specified, `Default` is used.
+
+Layouts receive a `title` prop extracted from the first `# heading` in the slide, plus any additional frontmatter fields as props.
+
+## Multiple MDX Files
+
+The deck entry file defaults to `deck.mdx`, and `--deck <file.mdx>` can select another root document. Additional MDX files are included via standard ESM imports:
+
+```mdx
+import Intro from './slides/intro.mdx'
+import Demo from './slides/demo.mdx'
+
+<Intro />
+
+<Demo />
+```
+
+### How Honeydeck Distinguishes MDX from Components
+
+- Imports from `.mdx` files → **slide-structural** (creates slide boundaries).
+- Imports from `.tsx`/`.ts`/`.jsx`/`.js` or packages → **normal inline components**.
+
+```mdx
+import DemoSlides from './demo.mdx'   // slide group
+import Chart from './Chart'            // normal inline component
+```
+
+### Slide Expansion
+
+If an imported `.mdx` file contains `---` separators, those slides are expanded at the location where the component is rendered. Rendering an imported MDX component always creates slide boundaries around it.
+
+### Frontmatter in Imported Files
+
+- The first frontmatter block of the deck entry file defines **deck-level** settings and first-slide settings.
+- Frontmatter in imported MDX files is **slide-level only** — they cannot define deck settings.
+
+## Default Layouts
+
+Honeydeck's built-in defaults are clean and minimal. They provide:
+
+| Layout | Description |
+|--------|-------------|
+| `Blank` | Empty slide with only children |
+| `Default` | Title top-left, body flows below |
+| `Section` | Big centered heading for section breaks |
+| `Cover` | Opening/closing slide (title, body, author) |
+| `TwoCol` | Two equal columns |
+| `Image` | Prominent image with optional title and children |
+| `ImageLeft` | Prominent left image with title and body on the right |
+| `ImageRight` | Prominent right image with title and body on the left |
+
+### Two-Column Layout
+
+Uses explicit slot components:
+
+```mdx
+---
+layout: TwoCol
+---
+
+import { Left, Right } from '@honeydeck/honeydeck/layouts/TwoCol'
+
+<Left>
+## Pros
+- Fast
+- Simple
+</Left>
+
+<Right>
+## Cons
+- Limited
+</Right>
+```
+
+### Image Layout
+
+Displays a specified image prominently (not as background):
+
+```yaml
+---
+layout: Image
+image: /diagrams/architecture.png
+darkImage: /diagrams/architecture-dark.png
+---
+
+# System Architecture
+
+Caption below the image.
+```
+
+### Side Image Layouts
+
+Use `ImageLeft` or `ImageRight` when the image should sit beside the slide content:
+
+```yaml
+---
+layout: ImageLeft
+image: /photos/product.jpg
+darkImage: /photos/product-dark.jpg
+alt: Product detail
+---
+
+# Product Detail
+
+Short supporting copy beside the image.
+```
+
+## Assets
+
+Static files live in `/public`. Reference them with `/public/…`:
+
+```mdx
+<img src="/public/cover.jpg" />
+```

package/docs/slidev-migration.md

@@ -0,0 +1,42 @@
+# 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.
+
+## Install the skill
+
+During a new project init, choose the agent skills installer:
+
+```bash
+npx @honeydeck/honeydeck init --name my-talk --install-skill
+```
+
+For an existing project, run:
+
+```bash
+honeydeck skill
+```
+
+Or install from the Honeydeck repository when the repository URL is finalized:
+
+```bash
+npx skills add <honeydeck-repo-url> --copy --skill slidev-migration
+```
+
+The same `skills` flow lets you choose project or global installation.
+
+## What it migrates
+
+The skill guides an agent through the common Slidev-to-Honeydeck mapping:
+
+| Slidev | Honeydeck |
+| --- | --- |
+| `slides.md` | `deck.mdx` |
+| `pages/*.md` with `src:` includes | imported `.mdx` slide groups |
+| `public/**` | `public/**` |
+| `components/*.vue` | React `components/*.tsx` |
+| `layouts/*.vue` or Slidev themes | Honeydeck layouts, layout maps, or kits |
+| `<v-click>` / `<v-clicks>` | `<Reveal>` / `<RevealGroup>` |
+| trailing note comments | `<Notes>` |
+| `slidev`, `slidev build`, `slidev export` | `honeydeck dev`, `honeydeck build`, `honeydeck pdf` |
+
+Advanced Slidev features such as Vue directives, `$clicks`, custom theme internals, Monaco/live-code blocks, and complex click positioning may need React-specific follow-up after the first migration pass.

package/docs/steps-and-reveals.md

@@ -0,0 +1,171 @@
+# Steps & Reveals
+
+Honeydeck has a first-class step concept. Each slide has a timeline built from `Reveal`/`RevealGroup` components, custom component step blocks, and code highlight ranges, counted in document order.
+
+## Timeline Model
+
+- Slides start at **step 0** — no reveals or custom component steps active.
+- Stepped code blocks show their first highlight group immediately whenever the block is visible.
+- Each `Reveal`, `RevealGroup` child, `TimelineSteps` block, or code highlight group after the first adds a step.
+- All step-producing elements share one slide-local timeline.
+- Nested step-producing elements are flattened into that same timeline. A parent
+  reveal target appears first; nested reveals, reveal groups, and code highlight
+  ranges appear after the parent and before the next sibling target.
+
+## Reveal
+
+```mdx
+import { Reveal } from '@honeydeck/honeydeck'
+
+# Why Honeydeck?
+
+<Reveal>Start with Markdown</Reveal>
+
+<Reveal>
+  Add <strong>interactive React</strong> when needed
+</Reveal>
+
+<Reveal>Export to PDF</Reveal>
+```
+
+### Behavior
+
+- **Cumulative** — once visible, content stays visible for the rest of the slide.
+- **Layout-stable** — hidden content reserves space (`opacity: 0` / `visibility: hidden`, not `display: none`).
+- **Default effect** — fade-in. Customize with `className` and Tailwind/CSS.
+
+## RevealGroup
+
+Reveals each direct child as its own step. If a direct child is a list, each
+list item is revealed as its own step:
+
+```mdx
+import { RevealGroup } from '@honeydeck/honeydeck'
+
+<RevealGroup>
+  - Markdown-first
+  - React-powered
+  - PDF-ready
+</RevealGroup>
+```
+
+To reveal multiple elements together, wrap them in a single `Reveal` instead.
+
+Nested reveals and code walkthroughs work inside group items:
+
+````mdx
+<RevealGroup>
+  <div>
+    Parent item
+    <Reveal>Nested detail</Reveal>
+  </div>
+  <div>
+    Code item
+    ```ts {1|2}
+    const a = 1
+    const b = 2
+    ```
+  </div>
+</RevealGroup>
+````
+
+Timeline:
+
+1. Parent item appears
+2. Nested detail appears
+3. Code item appears with line 1 highlighted
+4. Code highlights line 2
+
+## Custom Component Steps
+
+Use `TimelineSteps` when an imported React component should control part of
+the slide timeline, such as an accordion, tab set, or diagram walkthrough:
+
+```mdx
+import { Reveal, TimelineSteps } from '@honeydeck/honeydeck'
+import { AccordionDemo } from './AccordionDemo'
+
+<Reveal>Before the custom component</Reveal>
+
+<TimelineSteps steps={3}>
+  <AccordionDemo />
+</TimelineSteps>
+
+<Reveal>After the custom component</Reveal>
+```
+
+Inside the custom component:
+
+```tsx
+import { useTimelineSteps } from '@honeydeck/honeydeck'
+
+export function AccordionDemo() {
+  const { phase, stepIndex, stepCount, isPdfFinalRender } = useTimelineSteps()
+  // Open section stepIndex - 1 when phase is "active".
+  // Open all sections when isPdfFinalRender is true.
+}
+```
+
+`TimelineSteps` must be written in slide MDX with a literal positive integer
+`steps` value. Rendering it only inside an imported TSX component does not
+register steps, because Honeydeck counts the timeline at build time.
+
+When PDF export renders one final-state page per slide (`pdfSteps: final`),
+`useTimelineSteps()` exposes `isPdfFinalRender: true`. Step-driven custom
+components can use that to render a PDF-specific final composition, such as an
+accordion with every section open. In `pdfSteps: all`, the flag stays false
+because each step is captured as its own page.
+
+## Code Step-Through
+
+Code blocks support highlight ranges that participate in the same timeline:
+
+````mdx
+```ts {2-3|5|all}
+const a = 1
+const b = 2
+const c = 3
+console.log(a + b)
+console.log(c)
+```
+````
+
+- `{2-3|5|all}` — starts with lines 2-3 active, then steps to line 5, then all lines.
+- Index starts at 1.
+- The first group is the baseline highlight and adds 0 timeline steps; every later group adds 1 timeline step.
+
+### Code Step Behavior
+
+- **Baseline:** The first metadata group is active immediately, including at slide step 0 when the block is visible.
+- **Non-cumulative:** Only the lines specified for the active group are highlighted; previous highlights don't persist.
+- **Dim approach:** Non-highlighted lines are dimmed (controlled by `--honeydeck-code-line-dim-opacity: 0.4`).
+- **Shiki at build time:** No runtime JS cost for syntax highlighting.
+
+## Mixed Timeline Example
+
+````mdx
+# Demo
+
+```ts {2|4|all}
+const a = 1
+const b = 2
+console.log(a + b)
+```
+
+<Reveal>Now notice the output</Reveal>
+````
+
+Timeline:
+1. Slide starts with code line 2 highlighted
+2. Code highlights line 4
+3. Code highlights all lines
+4. Reveal appears
+
+## PDF Export of Steps
+
+Controlled by deck-level `pdfSteps` setting:
+
+| Value | Behavior |
+|-------|----------|
+| `final` (default) | Each slide appears once with all reveals visible, code at final highlight |
+| `all` | Each step state becomes a separate PDF page |

package/package.json

@@ -0,0 +1,134 @@
+{
+	"name": "@honeydeck/honeydeck",
+	"version": "0.1.0",
+	"description": "MDX and React-based presentation framework for AI-friendly slide decks.",
+	"license": "MIT",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/honeydeck/honeydeck.git"
+	},
+	"homepage": "https://honeydeck.dev",
+	"bugs": {
+		"url": "https://github.com/honeydeck/honeydeck/issues"
+	},
+	"keywords": [
+		"presentations",
+		"slides",
+		"mdx",
+		"react",
+		"vite",
+		"tailwindcss"
+	],
+	"type": "module",
+	"bin": {
+		"honeydeck": "src/cli/bin.js"
+	},
+	"engines": {
+		"node": ">=22.18.0"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"!src/**/fixtures",
+		"!src/**/fixtures/**",
+		"docs",
+		"skills",
+		"Readme.md",
+		"SPEC.md",
+		"DEVELOPMENT.md",
+		"AGENTS.md"
+	],
+	"exports": {
+		".": "./src/runtime/index.ts",
+		"./types": "./src/runtime/types.ts",
+		"./layouts": "./src/layouts/index.ts",
+		"./layouts/ColorModeImage": "./src/layouts/ColorModeImage.tsx",
+		"./layouts/Blank": "./src/layouts/clean/Blank.tsx",
+		"./layouts/Default": "./src/layouts/clean/Default.tsx",
+		"./layouts/Cover": "./src/layouts/clean/Cover.tsx",
+		"./layouts/Section": "./src/layouts/clean/Section.tsx",
+		"./layouts/TwoCol": "./src/layouts/clean/TwoCol.tsx",
+		"./layouts/Image": "./src/layouts/clean/Image/Image.tsx",
+		"./layouts/ImageLeft": "./src/layouts/clean/ImageLeft.tsx",
+		"./layouts/ImageRight": "./src/layouts/clean/ImageRight.tsx",
+		"./layouts/placeholders": "./src/layouts/placeholders.ts",
+		"./layouts/bee": "./src/layouts/bee/index.ts",
+		"./layouts/bee/Blank": "./src/layouts/bee/Blank.tsx",
+		"./layouts/bee/Default": "./src/layouts/bee/Default.tsx",
+		"./layouts/bee/Cover": "./src/layouts/bee/Cover.tsx",
+		"./layouts/bee/Section": "./src/layouts/bee/Section.tsx",
+		"./layouts/bee/TwoCol": "./src/layouts/bee/TwoCol.tsx",
+		"./layouts/bee/Image": "./src/layouts/bee/Image/Image.tsx",
+		"./layouts/bee/ImageLeft": "./src/layouts/bee/ImageLeft.tsx",
+		"./layouts/bee/ImageRight": "./src/layouts/bee/ImageRight.tsx",
+		"./layouts/clean": "./src/layouts/clean/index.ts",
+		"./layouts/clean/Blank": "./src/layouts/clean/Blank.tsx",
+		"./layouts/clean/Default": "./src/layouts/clean/Default.tsx",
+		"./layouts/clean/Cover": "./src/layouts/clean/Cover.tsx",
+		"./layouts/clean/Section": "./src/layouts/clean/Section.tsx",
+		"./layouts/clean/TwoCol": "./src/layouts/clean/TwoCol.tsx",
+		"./layouts/clean/Image": "./src/layouts/clean/Image/Image.tsx",
+		"./layouts/clean/ImageLeft": "./src/layouts/clean/ImageLeft.tsx",
+		"./layouts/clean/ImageRight": "./src/layouts/clean/ImageRight.tsx",
+		"./theme.css": "./src/theme/base.css",
+		"./themes/base.css": "./src/theme/base.css",
+		"./themes/clean.css": "./src/theme/clean.css",
+		"./themes/bee.css": "./src/theme/bee.css",
+		"./components": "./src/runtime/components/index.ts",
+		"./components/code-block": "./src/runtime/components/CodeBlock.tsx",
+		"./remark/shiki-code-blocks": "./src/remark/shiki-code-blocks.ts"
+	},
+	"imports": {
+		"#cli/*": "./src/cli/*",
+		"#runtime/*": "./src/runtime/*",
+		"#remark/*": "./src/remark/*",
+		"#vite-plugin/*": "./src/vite-plugin/*"
+	},
+	"scripts": {
+		"build": "npm run typecheck",
+		"dev": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
+		"dev:init": "node --import tsx ./src/cli/index.ts dev --deck src/cli/templates/starter/deck.mdx",
+		"format": "biome check --write",
+		"lint": "biome check",
+		"pack:dry-run": "npm pack --dry-run",
+		"pack:smoke": "node ./scripts/packed-smoke.mjs",
+		"release:plan": "node ./scripts/release-plan.mjs",
+		"test": "node --test --import tsx \"src/**/*.test.ts\" \"src/**/*.test.tsx\"",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"@clack/prompts": "^1.3.0",
+		"@mdx-js/mdx": "^3.1.1",
+		"@mdx-js/rollup": "^3.1.1",
+		"@tailwindcss/vite": "^4.3.0",
+		"lucide-react": "^1.16.0",
+		"pdf-lib": "^1.17.1",
+		"playwright": "^1.59.1",
+		"remark-frontmatter": "^5.0.0",
+		"remark-gfm": "^4.0.1",
+		"shiki": "^4.0.2",
+		"tsx": "^4.21.0",
+		"typescript": "^6.0.3",
+		"unified": "^11.0.5",
+		"unist-util-visit": "^5.1.0",
+		"vite": "^8.0.11"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tailwindcss": "^4.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.15",
+		"@types/node": "^25.6.2",
+		"@types/react": "^19.2.14",
+		"@types/react-dom": "^19.2.3",
+		"react": "^19.2.6",
+		"react-dom": "^19.2.6",
+		"tailwindcss": "^4.3.0"
+	}
+}

package/skills/SPEC.md

@@ -0,0 +1,21 @@
+# Honeydeck Agent Skills Specification
+
+> Observable behavior for bundled installable agent skills.
+
+## Agent Skills
+
+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, kits, canonical package docs, 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 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/next-steps.md`, `docs/slides.md`, `docs/steps-and-reveals.md`, `docs/kits.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 `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, 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.

package/skills/honeydeck/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: honeydeck
+description: Help users create, edit, debug, and export Honeydeck MDX presentations. Use for Honeydeck syntax, deck.mdx structure, layouts, frontmatter, steps/reveals, presenter notes, code blocks, custom React components, kits/themes, CLI commands, dev preview, build, or PDF export.
+---
+
+# Honeydeck
+
+You help the user work with Honeydeck presentations. Honeydeck decks are MDX files powered by React, Vite, Tailwind v4, and Honeydeck layouts/components.
+
+## Source of truth
+
+Before giving Honeydeck-specific syntax or changing a deck, prefer repository/package docs when available.
+
+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.
+
+Important docs:
+
+- `Readme.md` for the compact package overview and documentation index
+- `docs/getting-started.md` for quick start and first-run orientation
+- `docs/next-steps.md` for CLI details, feature overview, architecture, exports, and agent skills
+- root/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 and code steps
+- `docs/kits.md` and `docs/kit-authoring.md` for themes, layouts, and reusable kits
+- `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.
+
+## Honeydeck basics to remember
+
+- The conventional entrypoint is `deck.mdx`.
+- The first `---` block is deck-level frontmatter.
+- Slides are separated by a line that is exactly `---`.
+- A slide can start with frontmatter to choose a layout, title, notes, or other options. Frontmatter is closed with another `---` block, and then content follows.
+- If frontmatter is invalid or incomplete, notify the user and provide correct syntax.
+- Frontmatter may provide additional properties for the selected layout. Check layout source or docs for available properties.
+- Built-in layouts include `Blank`, `Cover`, `Default`, `Section`, `TwoCol`, `Image`, `ImageLeft`, and `ImageRight`.
+- Built-in styling is explicit: generated decks import `./styles.css`, and that file imports Honeydeck/Tailwind theme CSS.
+- MDX can mix Markdown, JSX, imported React components, Honeydeck components, and code blocks.
+- Presenter notes belong in slide frontmatter when useful for narrative, timing, and delivery cues.
+- Use reveals/steps for progressive disclosure, not for every bullet by default.
+- PDF export is available with `npx honeydeck pdf`; use `--steps all` when revealed states matter.
+- Use sections to group related slides and provide visual breaks.
+
+## How to help
+
+1. Read existing deck imports, frontmatter, separators, and local style before editing.
+2. Preserve valid MDX and Honeydeck separators exactly.
+3. Prefer Honeydeck layouts and components over custom CSS when they fit.
+4. Keep examples small unless the user asks for a full deck.
+5. Explain Honeydeck-specific syntax briefly.
+6. Recommend `npx honeydeck dev` for preview and `npx honeydeck pdf` for export.
+7. If unsure about exact syntax, read the docs first instead of guessing.
+
+## Output style
+
+- When generating Honeydeck slides, output valid MDX that can be pasted into `deck.mdx`.
+- Include necessary imports and frontmatter.
+- Keep non-Honeydeck presentation advice brief unless the user also wants slide-writing guidance.