Slides

Client decks as single-file HTML, with a built-in co-design loop for humans and AI agents.

The idea: slides live in a git repo as plain HTML, get served through one entry point that injects feedback tooling into every page, and deploy as a login-protected space your team can review, annotate and comment on. No slide software, no design tool exports — a deck is a file you can diff, and every review comment arrives in a form an AI coding agent can act on directly.

What you get

• A deck template (template/deck-template.html) — fixed 16:9 stage (1280×720) scaled to the window, keyboard navigation, speaker notes drawer, and print output that is pixel-identical to the screen: Cmd+P gives one exact 16:9 page per slide. A restrained visual system (flat surfaces, one accent, no gradient-card slop) documented in template/README.md.
• An auto-generated index — deploy/stage.sh builds manifest.json (every deck, its title, its last git-commit date) and index.html renders it grouped by directory, sorted by recent activity with an A–Z toggle. Add a deck, it appears.
• Annotation for agents — every served page carries Agentation (the vanilla port, MIT): press A, click elements, write notes, press C, and paste structured markdown — element selectors included — into Claude Code, Cursor or a Slack thread.
• Comments as GitHub issues — a drawer on every deck lists open threads for that deck (issues labelled deck:<slug>), and posting/replying writes through a tiny server-side proxy. Threads outlive the session, show up in normal GitHub notifications, and agents can read them with gh issue list.
• One-button PDF — hover top-right, press ⎙.
• A deploy story — a zero-dependency Node server (deploy/server.js) serves the site and the comments API; instructions below put it on Azure App Service behind Entra ID login so the whole space is org-only.

Quickstart

git clone https://github.com/mattarderne/slides && cd slides
./deploy/serve.sh          # → http://localhost:4600

That script is the one way to run the site — it stages every page with the tooling injected, then serves. To enable comments, set GH_REPO to a repo your gh CLI can write issues to:

GH_REPO=you/your-slides ./deploy/serve.sh

Start a new deck by copying template/deck-template.html, then read template/README.md for the layout catalogue and style rules.

Working with an AI agent

CLAUDE.md / AGENTS.md tell the agent the rules: always serve via serve.sh (so the annotation toolbar is present when it shows you a deck), treat pasted Agentation selectors as ground truth, read and resolve comment issues before calling a deck done. The loop in practice:

1. Agent builds/edits a deck and serves it.
2. You annotate in the browser, copy markdown, paste to the agent.
3. Longer-lived decisions go in the comments drawer → GitHub issues.
4. Agent addresses annotations and issues, closes threads, redeploys.

Deploying (Azure App Service + Entra ID)

Any Node host works (the server is dependency-free). For an org-locked space on Azure:

az group create -n rg-slides -l westeurope
az appservice plan create -g rg-slides -n slides-plan --is-linux --sku F1
az webapp create -g rg-slides -p slides-plan -n <app-name> --runtime "NODE:22-lts"
az webapp config set -g rg-slides -n <app-name> --startup-file "node server.js"
az webapp config appsettings set -g rg-slides -n <app-name> \
  --settings GITHUB_TOKEN=<issues-token> GH_REPO=<owner/repo> SCM_DO_BUILD_DURING_DEPLOYMENT=false

# Entra ID login (Easy Auth), locked to your tenant:
az ad app create --display-name slides-auth --sign-in-audience AzureADMyOrg \
  --web-redirect-uris "https://<app-name>.azurewebsites.net/.auth/login/aad/callback" \
  --enable-id-token-issuance true
az ad app credential reset --id <appId> --years 2
az webapp config appsettings set -g rg-slides -n <app-name> \
  --settings MICROSOFT_PROVIDER_AUTHENTICATION_SECRET=<password>
az webapp auth config-version upgrade -g rg-slides -n <app-name>
az webapp auth microsoft update -g rg-slides -n <app-name> --client-id <appId> \
  --client-secret-setting-name MICROSOFT_PROVIDER_AUTHENTICATION_SECRET \
  --issuer "https://login.microsoftonline.com/<tenantId>/v2.0" --yes
az webapp auth update -g rg-slides -n <app-name> --enabled true \
  --action RedirectToLoginPage --redirect-provider azureactivedirectory

Then deploy: stage, zip server.js package.json site/ (where site/ is _site/), and az webapp deploy --type zip. The commenter identity on Azure comes from the Easy Auth header, so issues are attributed to whoever is logged in.

Layout

index.html            landing page (renders manifest.json)
template/             the deck template + style rules
example/              a sample deck
assets/               agentation-vanilla.js (MIT), slides-ui.js (print + comments UI)
deploy/               stage.sh · serve.sh · server.js · package.json

Credits

Agentation by Benji Taylor; vanilla port by mearnest-dev (MIT, vendored in assets/). Template and tooling released under MIT.