# https://github.com/isatimur/presentation-md Project Manual

Generated at: 2026-07-30 23:05:01 UTC

## Table of Contents

- [Overview and Repository Architecture](#page-1)
- [Deck JSON Schema, Layouts, and Themes](#page-2)
- [Rendering, Export, and Import Pipeline](#page-3)
- [Agent Integration, MCP Tools, and Deck Design Judge](#page-4)

<a id='page-1'></a>

## Overview and Repository Architecture

### Related Pages

Related topics: [Deck JSON Schema, Layouts, and Themes](#page-2), [Rendering, Export, and Import Pipeline](#page-3), [Agent Integration, MCP Tools, and Deck Design Judge](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/isatimur/presentation-md/blob/main/README.md)
- [package.json](https://github.com/isatimur/presentation-md/blob/main/package.json)
- [pnpm-workspace.yaml](https://github.com/isatimur/presentation-md/blob/main/pnpm-workspace.yaml)
- [ATTRIBUTION.md](https://github.com/isatimur/presentation-md/blob/main/ATTRIBUTION.md)
- [CONTRIBUTING.md](https://github.com/isatimur/presentation-md/blob/main/CONTRIBUTING.md)
- [CHANGELOG.md](https://github.com/isatimur/presentation-md/blob/main/CHANGELOG.md)
</details>

# Overview and Repository Architecture

`presentation-md` is a Markdown-driven presentation toolchain packaged as a pnpm monorepo. It centers on authoring slides in Markdown and rendering them through a layered set of packages that progressively add export, rendering, and skill-pack distribution capabilities. The repository combines a renderer, an exporter, and a separate "skill pack" that integrates with Claude Code through a one-line installer. Source: [README.md:1-60]()

## Project Purpose and Scope

The project's purpose is to let authors write slide decks as Markdown while still producing presentation-ready output, including PPTX, with predictable visual behavior. The README documents the toolchain and its headline features, and explicitly advertises `deck-design-judge` as a carried skill so users can lint and improve slide design during authoring. Source: [README.md:1-60]()

Project governance, contribution flow, and licensing/attribution are split into dedicated documents so the README stays focused on usage. `ATTRIBUTION.md` records upstream credits, and `CONTRIBUTING.md` defines the workflow for outside contributors. Source: [ATTRIBUTION.md:1-20](), Source: [CONTRIBUTING.md:1-40]()

## Monorepo Structure

The repository is structured as a pnpm workspace. The root `package.json` defines top-level scripts and dev tooling, while `pnpm-workspace.yaml` enumerates the packages that live inside the workspace. Source: [package.json:1-60](), Source: [pnpm-workspace.yaml:1-20]()

Published packages visible in the release history include:

| Package | Role |
| --- | --- |
| `@presentation-md/render` | Slide rendering layer used to produce visual output |
| `@presentation-md/export` | Export pipeline, currently used to emit PPTX |
| `@presentation-skill-pack/install` | One-command installer entry point for Claude Code |
| `@presentation-skill-pack/core` | Carries `skill/` resources surfaced by the installer |

Source: [CHANGELOG.md:1-40]()

The renderer and exporter versions are coupled: a recent `@presentation-md/render@1.2.3` patch bumped its `@presentation-md/export` dependency to `1.3.1`, indicating that the two packages share an interface that is kept in lock-step. Source: [CHANGELOG.md:1-20]()

## Distribution and Skill Pack Pipeline

The distribution story has two tracks. The first is the standard npm release path governed by Changesets, recorded in `CHANGELOG.md` with patch, minor, and major sections per package. Source: [CHANGELOG.md:1-40]()

The second track is the skill-pack installer for Claude Code. The README documents the command `npx @presentation-skill-pack/install claude-code` as the way to bring the project into an agent environment. Source: [README.md:40-60]() Under the hood, this command resolves `@presentation-skill-pack/core/skill` and copies the files listed in that package's manifest into the agent's working directory. Source: [CHANGELOG.md:1-40]()

The renderer has been actively hardened for visual and security concerns. The `1.2.3` patch introduced local `file://` path prefetching for embedded PPTX assets, gated by an `allowedRoots` confinement, and raised AA contrast for neon, vapor, and loud comparison surfaces as well as the feature grid. Source: [CHANGELOG.md:1-20]()

## Known Architectural Gaps

Issue #9 highlights a documentation-versus-implementation gap surfaced during PR #7. The README now lists `deck-design-judge` as a skill carried by the repo, but the installer's `files` list in `@presentation-skill-pack/core/skill` does not yet include it. Source: [README.md:46](), Source: [CHANGELOG.md:1-40]()

The practical effect is that a user running the documented one-command install will not receive the `deck-design-judge` files locally, even though the README implies they are part of the skill bundle. Closing this gap requires either expanding the package's `files` manifest or pruning the README reference so the two stay aligned. Source: [README.md:46](), Source: [CHANGELOG.md:1-40]()

Contributors addressing this kind of gap are expected to follow the workflow described in `CONTRIBUTING.md` and to record user-visible changes through the Changesets pipeline so they appear in `CHANGELOG.md`. Source: [CONTRIBUTING.md:1-40](), Source: [CHANGELOG.md:1-40]()

---

<a id='page-2'></a>

## Deck JSON Schema, Layouts, and Themes

### Related Pages

Related topics: [Overview and Repository Architecture](#page-1), [Rendering, Export, and Import Pipeline](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/core/SKILL.md](https://github.com/isatimur/presentation-md/blob/main/packages/core/SKILL.md)
- [packages/core/deck.schema.json](https://github.com/isatimur/presentation-md/blob/main/packages/core/deck.schema.json)
- [packages/core/theme.schema.json](https://github.com/isatimur/presentation-md/blob/main/packages/core/theme.schema.json)
- [packages/core/src/validate-deck.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/validate-deck.ts)
- [packages/core/src/validate-theme.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/validate-theme.ts)
- [packages/core/src/theme-loader.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/theme-loader.ts)
</details>

# Deck JSON Schema, Layouts, and Themes

The `@presentation-md/core` package defines the canonical JSON contract for every deck produced in the system. A deck is a single document that combines structural metadata, an ordered list of slides, layout assignments per slide, and an optional theme reference. Two JSON Schema files (`deck.schema.json` and `theme.schema.json`) lock the shape of these documents, and two TypeScript validators (`validate-deck.ts`, `validate-theme.ts`) enforce them at build/load time before the renderer can consume the artifact. Source: [packages/core/SKILL.md](https://github.com/isatimur/presentation-md/blob/main/packages/core/SKILL.md) and [packages/core/deck.schema.json](https://github.com/isatimur/presentation-md/blob/main/packages/core/deck.schema.json).

## Deck Schema

A deck document is a top-level object that must validate against `deck.schema.json`. It typically carries identifying metadata (title, author, locale), a `theme` reference, and a `slides` array. Each slide element embeds a `layout` identifier plus arbitrary content blocks (titles, bullets, code, images, embeds, grids). The schema enforces required fields, slide ordering, and the union of allowed content block types so downstream tools — including the renderer and the `deck-design-judge` skill — can rely on a stable shape. Source: [packages/core/deck.schema.json](https://github.com/isatimur/presentation-md/blob/main/packages/core/deck.schema.json).

`validate-deck.ts` is the runtime gatekeeper: it compiles the schema with a JSON Schema validator, walks the document, and surfaces structured errors (path + reason) rather than throwing. This lets the CLI exit with a non-zero code while still printing a human-readable diagnostic, which is the contract used by CI and by the one-command installer pipeline. Source: [packages/core/src/validate-deck.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/validate-deck.ts).

## Layouts

Layouts are first-class named templates referenced from each slide via `slide.layout`. The renderer ships a small set of built-in layouts (e.g., `title`, `content`, `section`, `two-column`, `quote`, `blank`) and a deck may extend this set through its theme or through inline layout declarations. A layout definition describes the grid (rows/columns), slot names, default typography, and which content block types are accepted in each slot. Because layouts are referenced by string id rather than embedded inline, the same layout can be reused across slides and themes, and the `deck-design-judge` skill can reason about layout balance across an entire deck. Source: [packages/core/SKILL.md](https://github.com/isatimur/presentation-md/blob/main/packages/core/SKILL.md).

A slide-level layout override lets a single slide diverge from the deck's default layout while still inheriting theme tokens. This separation — layout (structure) vs. theme (style) — is what enables the same content to be re-skinned without rewriting slide bodies.

## Themes

A theme is a separate JSON document validated by `theme.schema.json`. It defines the visual surface: color tokens (background, foreground, accent, muted, semantic states), typography scales (font families, sizes, weights, line heights), spacing tokens, radii, shadows, and per-layout style overrides. Theme files are resolved relative to the deck via the loader in `theme-loader.ts`, which supports bundled themes, user-provided themes, and remote theme URLs. Source: [packages/core/theme.schema.json](https://github.com/isatimur/presentation-md/blob/main/packages/core/theme.schema.json) and [packages/core/src/theme-loader.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/theme-loader.ts).

`validate-theme.ts` runs the same compiled-schema pattern as the deck validator, but with stricter requirements on token completeness — a theme that omits a referenced token is rejected rather than silently falling back, which prevents visual drift between the local preview and the rendered output. Source: [packages/core/src/validate-theme.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/validate-theme.ts).

| Concern | Schema | Validator | Loader |
|---|---|---|---|
| Deck structure & slides | `deck.schema.json` | `validate-deck.ts` | n/a |
| Theme tokens & styles | `theme.schema.json` | `validate-theme.ts` | `theme-loader.ts` |
| Layout reuse | referenced from deck | enforced by deck schema | resolved by renderer |

## How They Fit Together

The validation pipeline runs in a fixed order: theme load → theme validate → deck validate → render. If any step fails, the artifact never reaches the renderer, and the `deck-design-judge` skill consumes the same validated document to score layout balance, contrast, and information density. This is why community issue #9 ("Wire deck-design-judge into the npx install pipeline") matters: the skill depends on the schema-stable shape produced by `validate-deck.ts`, and the installer must ship that file alongside the core skill so on-disk decks can be evaluated offline. Source: [packages/core/src/validate-deck.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/validate-deck.ts) and [packages/core/src/theme-loader.ts](https://github.com/isatimur/presentation-md/blob/main/packages/core/src/theme-loader.ts).

In short, the deck schema defines *what* a slide is, layouts define *how* it is arranged, and themes define *what it looks like*. Each layer has its own schema and validator, and the loader sits between the theme layer and the renderer so authors can swap visual identity without touching content.

---

<a id='page-3'></a>

## Rendering, Export, and Import Pipeline

### Related Pages

Related topics: [Deck JSON Schema, Layouts, and Themes](#page-2), [Agent Integration, MCP Tools, and Deck Design Judge](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/renderer-node/src/cli.ts](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-node/src/cli.ts)
- [packages/renderer-node/src/index.ts](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-node/src/index.ts)
- [packages/renderer-node/shared/document.html](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-node/shared/document.html)
- [packages/renderer-node/shared/base.css](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-node/shared/base.css)
- [packages/renderer-node/shared/theme-surfaces.json](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-node/shared/theme-surfaces.json)
- [packages/renderer-python/src/presentation_md_render/cli.py](https://github.com/isatimur/presentation-md/blob/main/packages/renderer-python/src/presentation_md_render/cli.py)
</details>

# Rendering, Export, and Import Pipeline

The presentation-md project ships two parallel renderer implementations — a Node.js package and a Python package — that share a common HTML/CSS/theme surface to convert Markdown slide sources into browser-ready presentation documents. Export and import flows (PPTX embed prefetch, theme catalogs, skill-pack wiring) are layered on top of these renderers through the `@presentation-md/render` and `@presentation-md/export` packages.

## Renderer Architecture

The pipeline is delivered as a monorepo with three coordinated layers:

| Layer | Package | Purpose |
|-------|---------|---------|
| Node entry | `@presentation-md/renderer-node` | CLI + programmatic API for rendering, exposes `cli.ts` and `index.ts` |
| Python entry | `@presentation-md/render` (Python) | `presentation_md_render` CLI mirroring the Node surface |
| Shared surface | `packages/renderer-node/shared/` | `document.html`, `base.css`, `theme-surfaces.json` consumed by both |

The Node CLI surface is defined in `cli.ts`, which wires commander-style argument parsing into the renderer exposed by `index.ts`. `Source: [packages/renderer-node/src/cli.ts:1-120]()`

The Python mirror lives at `packages/renderer-python/src/presentation_md_render/cli.py`, providing the same command-line ergonomics for environments where Node is unavailable. `Source: [packages/renderer-python/src/presentation_md_render/cli.py:1-120]()`

## Shared Document Surface

Both renderers emit a single HTML document using `document.html` as the template, styled by `base.css`, and themed via the structured catalog in `theme-surfaces.json`.

- `document.html` declares the slide shell, slide-list containers, and the script tags that hydrate runtime behavior such as keyboard navigation, fragment stepping, and embed rendering.
- `base.css` provides the design-token baseline: typography scale, layout grid, and the AA-contrast floor that the most recent patch raised for the `neon`, `vapor`, and `loud` themes plus the feature-grid component.
- `theme-surfaces.json` enumerates every theme (background palette, accent palette, surface treatments) the renderers can apply at build time.

`Source: [packages/renderer-node/shared/document.html:1-200]()`
`Source: [packages/renderer-node/shared/base.css:1-400]()`
`Source: [packages/renderer-node/shared/theme-surfaces.json:1-200]()`

## Export Flow (PPTX and Asset Embeds)

Export is handled by `@presentation-md/export`, which the renderer depends on at runtime. The current `@presentation-md/render@1.2.3` patch introduced an embed-prefetch pass:

- Local `file:///` PPTX embeds are prefetched before HTML emission so the embedded slide raster is bundled with the rendered output.
- Prefetch is confined to an `allowedRoots` allow-list, preventing the renderer from reading arbitrary local paths during export.
- The accompanying `base.css` revisions raise the AA contrast ratio for `neon`, `vapor`, `loud`, and the feature-grid component to keep embedded slides legible.

`Source: [packages/renderer-node/src/index.ts:1-200]()`
`Source: [packages/renderer-node/shared/base.css:1-400]()`

## Data Flow

```mermaid
flowchart LR
    MD[Markdown source] --> NodeCLI[renderer-node CLI]
    MD --> PyCLI[presentation_md_render CLI]
    NodeCLI --> Index[index.ts renderer]
    PyCLI --> Index
    Index --> Shared[shared/document.html + base.css + theme-surfaces.json]
    Shared --> Export[@presentation-md/export]
    Export --> Prefetch[file:// PPTX prefetch with allowedRoots]
    Prefetch --> Out[Rendered HTML / PPTX bundle]
    Installer[npx @presentation-skill-pack/install] -. gap .-> Judge[deck-design-judge]
```

## Import / Install Pipeline

The skill-pack installer (`npx @presentation-skill-pack/install claude-code`) is the canonical import path for Claude Code users. It currently resolves only `@presentation-skill-pack/core/skill`, whose `files` manifest does not include the `deck-design-judge` skill that the README documents.

This gap is tracked in community issue #9 ("Wire deck-design-judge into the npx install pipeline"), flagged by Codex on PR #7 against `README.md:46`. Until the `files` list in `@presentation-skill-pack/core/skill` is extended, users who want the design-judge skill must install it manually rather than through the one-command installer.

`Source: [packages/renderer-node/src/cli.ts:1-120]()`

## Known Limitations

- The one-command installer does not yet ship `deck-design-judge`; manual wiring is required (issue #9).
- Contrast and embed-prefetch behavior are tied to specific `@presentation-md/render` patch versions — older builds will not enforce `allowedRoots` confinement on local PPTX embeds, and will not include the raised AA-contrast floor for the affected themes.

---

<a id='page-4'></a>

## Agent Integration, MCP Tools, and Deck Design Judge

### Related Pages

Related topics: [Overview and Repository Architecture](#page-1), [Rendering, Export, and Import Pipeline](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/install/src/index.ts](https://github.com/isatimur/presentation-md/blob/main/packages/install/src/index.ts)
- [adapters/_common/install-judge-skill.sh](https://github.com/isatimur/presentation-md/blob/main/adapters/_common/install-judge-skill.sh)
- [adapters/claude-code/install.sh](https://github.com/isatimur/presentation-md/blob/main/adapters/claude-code/install.sh)
- [adapters/claude-code/install.ps1](https://github.com/isatimur/presentation-md/blob/main/adapters/claude-code/install.ps1)
- [adapters/claude-code/README.md](https://github.com/isatimur/presentation-md/blob/main/adapters/claude-code/README.md)
- [adapters/cursor/install.sh](https://github.com/isatimur/presentation-md/blob/main/adapters/cursor/install.sh)
</details>

# Agent Integration, MCP Tools, and Deck Design Judge

This page documents how `presentation-md` distributes its agent-side assets (skills, prompts, and tooling hooks) into AI coding agents such as Claude Code and Cursor, and how the **`deck-design-judge`** skill is currently split between the main installer and a secondary install script.

## 1. The `npx` Install Pipeline and `presentation-skill-pack`

The one-command installer advertised in the README is `npx @presentation-skill-pack/install claude-code` (or `…cursor`). The implementation lives in `packages/install/src/index.ts`, which resolves the package `@presentation-skill-pack/core/skill` and stages its `files` list into the target agent's configuration directory. The repo ships per-target adapter directories (`adapters/claude-code/`, `adapters/cursor/`) that wrap the same core payload and add agent-specific paths and hooks.

Source: [packages/install/src/index.ts]()

## 2. `deck-design-judge` — A Skill Outside the Core Payload

The README documents `deck-design-judge` as a skill this repo carries (`README.md:46`, per issue #9). However, the `@presentation-skill-pack/core/skill` `files` list does not currently include the judge skill, so calling `npx @presentation-skill-pack/install claude-code` alone will not place it on disk. A dedicated install script — `adapters/_common/install-judge-skill.sh` — exists to fill that gap and must be run separately (or wired into the main installer).

This separation is the root cause of the integration gap tracked in issue **#9 — "Wire deck-design-judge into the npx install pipeline"**, which Codex flagged on PR #7 during review.

Source: [adapters/_common/install-judge-skill.sh]()

## 3. Per-Agent Adapters

### 3.1 Claude Code
- Shell entry point: `adapters/claude-code/install.sh`
- Windows entry point: `adapters/claude-code/install.ps1`
- Documentation: `adapters/claude-code/README.md`

These scripts back the `claude-code` argument of the npm CLI and handle platform-specific staging (POSIX `cp`/`mkdir` vs. PowerShell `Copy-Item`/`New-Item`).

### 3.2 Cursor
- Shell entry point: `adapters/cursor/install.sh`

A parallel adapter targets Cursor's skill/config layout; other agents will follow the same pattern (adapter directory + adapter-specific install script + optional README).

| Adapter | Shell | PowerShell | README | Carries `deck-design-judge` |
|---|---|---|---|---|
| `claude-code` | ✓ | ✓ | ✓ | Only via `install-judge-skill.sh` |
| `cursor` | ✓ | — | — | Only via `install-judge-skill.sh` |

Source: [adapters/claude-code/README.md](), [adapters/cursor/install.sh]()

## 4. MCP Tools and Bridge to Renderers

`@presentation-md/render` v1.2.3 (released alongside `@presentation-md/export` 1.3.1) introduced `file:/` prefetching for PPTX embeds guarded by an `allowedRoots` confinement, plus raised contrast on the neon/vapor/loud comparison surfaces and the feature grid (`23e3a1f`). These changes give the agent side a safe primitive — fetching a local PPTX before handing its bytes to a downstream MCP tool — without leaking arbitrary filesystem paths. The install scripts are the on-ramp that makes those MCP-callable surfaces available inside Claude Code and Cursor environments.

Source: [@presentation-md/render changelog, change `23e3a1f`]()

## 5. Known Gap and Workaround

Until #9 is resolved, users must run **`bash adapters/_common/install-judge-skill.sh`** (or the equivalent PowerShell path once available) **after** the `npx` installer in order to obtain the `deck-design-judge` skill. Once the core `files` list is updated to include the judge skill, this manual step should disappear and the unified `npx @presentation-skill-pack/install <agent>` command will be sufficient.

Source: [issue #9 — "Wire deck-design-judge into the npx install pipeline"]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: isatimur/presentation-md

Summary: Found 9 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/isatimur/presentation-md/issues/9

## 2. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/isatimur/presentation-md

## 3. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/isatimur/presentation-md

## 4. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/isatimur/presentation-md

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/isatimur/presentation-md

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/isatimur/presentation-md/issues/8

## 8. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

## 9. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/isatimur/presentation-md

<!-- canonical_name: isatimur/presentation-md; human_manual_source: deepwiki_human_wiki -->