# Photo Portfolio: agent guide A photographer's portfolio site (package app) plus exports to manage it. The owner is usually not technical: do the work, show her the preview link, and confirm before anything destructive or public. Imports below use `@kentcdodds`. In a fork, use the fork's own scope (for example `kody:@janedoe/photo-portfolio/add-gallery`). ## Ground rules - **Her details live in package storage, never in agent memory.** Read them with `get-config`, change them with `update-config`. Do not save her name, email, phone, bio, or links to memory; read them fresh each time. - **Everything edits the draft.** Nothing is visible on the live site until `publish-changes`. After edits, send her the `previewUrl` from the result. - **Confirm before removing.** `remove-gallery` and `discard-changes` need `confirm: true`; call without it first and tell her what would change. - **Publish only when she says so** (or explicitly asked for it in one go). `publish-changes({ dryRun: true })` shows what will change. - Every mutating input is strict: unknown keys throw with the offending path. ## Start here ```ts import siteStatus from 'kody:@kentcdodds/photo-portfolio' const status = await siteStatus() // { // siteName: 'Your Name Photography', // liveUrl: 'https://jane.kody.run/packages/photo-portfolio', // previewUrl: 'https://jane.kody.run/packages/photo-portfolio/preview?token=…', // canonicalUrl: null, // usingSampleContent: true, // still showing the bundled sample galleries // galleries: 3, photos: 12, liveVersion: null, // pending: { hasChanges: false, configFields: [], galleriesAdded: [], … }, // inquiries: { total: 0, latestAt: null }, // } ``` `usingSampleContent: true` on a new fork means: offer to set her details and replace the samples. `liveUrl`/`previewUrl` are `null` (with a `setup` hint) until the app has been opened once: exports can't see the hosted URL, so the app records it in storage on its first request. Ask her to open the site from Kody once. ## Exports | Export | Example | | --- | --- | | default (`site-status`) | `await siteStatus()` | | `get-config` | `await getConfig({})` → `{ config, defaults, pendingConfigFields, liveUrl, previewUrl }` | | `update-config` | `await updateConfig({ tagline: 'Family & newborn photography', dryRun: true })` | | `add-gallery` | `await addGallery({ title: 'Smith Family', photos: [{ url, alt }] })` | | `add-photos` | `await addPhotos({ gallery: 'smith-family', photos: [{ base64, alt }] })` | | `update-gallery` | `await updateGallery({ gallery: 'smith-family', coverPhotoId: 'ph_…' })` | | `remove-photo` | `await removePhoto({ gallery: 'smith-family', photoId: 'ph_…' })` | | `remove-gallery` | `await removeGallery({ gallery: 'golden-hour', confirm: true })` | | `reorder-galleries` | `await reorderGalleries({ order: ['weddings', 'portraits'] })` | | `list-galleries` | `await listGalleries({ from: 'live' })` | | `get-preview-url` | `await getPreviewUrl({})` / `await getPreviewUrl({ rotate: true })` | | `publish-changes` | `await publishChanges({ note: 'Smith family gallery' })` | | `discard-changes` | `await discardChanges({ confirm: true })` | | `list-versions` | `await listVersions()` | | `rollback` | `await rollback({ version: 3 })` | | `list-inquiries` | `await listInquiries({ since: '2026-10-01', limit: 10 })` | Galleries are referenced by slug or id; photos by id (from `list-galleries`). ### Config fields (`update-config`) ```ts import updateConfig from 'kody:@kentcdodds/photo-portfolio/update-config' await updateConfig({ siteName: 'Jane Doe Photography', // header and page titles tagline: 'Family & newborn photography', // home page headline photographerName: 'Jane Doe', bio: "Hi, I'm **Jane**.\n\nI photograph families in Austin.\n\n[Book a session](contact)", headshot: { url: 'https://example.com/jane.jpg', alt: 'Jane smiling outdoors' }, // or { base64 }, or null to remove contactEmail: 'jane@example.com', // mailto link (inquiry emails go to her verified Kody address) phone: '(512) 555-0100', // null removes location: 'Austin, Texas', social: { instagram: 'https://instagram.com/janedoe', website: null }, bookingUrl: 'https://cal.com/janedoe/session', // shows a "Book a session" button bookingLabel: 'Book a session', accentColor: '#3a6ea5', // links and buttons theme: 'auto', // 'auto' follows the visitor's device; or 'light' / 'dark' seoDescription: 'Austin family and newborn photographer.', siteUrl: 'https://janedoephoto.com', // canonical origin, once a custom domain points here; null for the Kody URL notifyOnInquiry: true, // email her each contact-form message (30/day max) embedCopyright: true, // writes "© " into JPEG EXIF on new uploads showCameraDetails: false, // camera · lens · exposure under photos dryRun: true, // returns { changes } without saving }) ``` Defaults for a fresh fork are in `get-config` → `defaults`. Bio markdown: paragraphs, `#`–`###` headings, `-`/`1.` lists, `**bold**`, `*italic*`, `[links](https://…)`. Relative links like `(contact)` stay inside the site. ## Photo batches Each photo is decoded, rotated upright, resized to 480/960/1600/2400px (never upscaled), encoded as WebP and JPEG, stripped of GPS and other EXIF, and given a blur placeholder. That is CPU-heavy, so: - **At most 6 photos per call** (4 is a good batch). For a shoot of 30, create the gallery with the first 4, then `add-photos` in batches of 4. - Sources: `{ url }` (direct link to the image file, not a share page) or `{ base64 }` (data-URI prefix is fine). JPEG, PNG, or WebP; up to 30 MB and 12 megapixels. HEIC/AVIF fail with a message asking for JPEG. - **Alt text matters** (accessibility and search). Write a short description for each photo; it falls back to the caption, then "Photo from ". - A batch is all-or-nothing: if photo 3 of 4 fails, nothing is added and the error says `Photo 3 of 4: …`. ```ts import addGallery from 'kody:@kentcdodds/photo-portfolio/add-gallery' import addPhotos from 'kody:@kentcdodds/photo-portfolio/add-photos' const { gallery, previewUrl } = await addGallery({ title: 'Smith Family, Fall 2026', description: 'An evening at Zilker Park.', featured: true, // shown on the home page (default true) position: 'start', // newest first (default) cover: 0, // index into photos photos: [ { url: 'https://example.com/smith-01.jpg', alt: 'Family of four laughing on a park bench', caption: 'Golden hour' }, { url: 'https://example.com/smith-02.jpg', alt: 'Two kids running through fallen leaves' }, ], }) await addPhotos({ gallery: gallery.slug, photos: [{ url: 'https://example.com/smith-03.jpg', alt: 'Grandmother holding the baby' }], }) ``` `add-gallery({ …, draft: false })` adds and publishes in one call. It publishes **every** pending change, so only use it when she asked for that. ## Preview → publish → rollback ```ts import getPreviewUrl from 'kody:@kentcdodds/photo-portfolio/get-preview-url' import publishChanges from 'kody:@kentcdodds/photo-portfolio/publish-changes' import listVersions from 'kody:@kentcdodds/photo-portfolio/list-versions' import rollback from 'kody:@kentcdodds/photo-portfolio/rollback' const { previewUrl, pending } = await getPreviewUrl({}) // Opening previewUrl sets a 24h cookie: that browser sees the draft with a // "Preview" bar and an "Exit preview" link. Anyone with the link can see the // draft; rotate: true issues a new link and kills the old one. await publishChanges({ dryRun: true }) // { published: false, changes } await publishChanges({ note: 'Smith family' }) // { published: true, version: 4 } const { versions } = await listVersions() // newest first; versions[0] is live await rollback({ version: 3, dryRun: true }) // what would change, and whether unpublished draft edits would be lost await rollback({ version: 3 }) // { rolledBack: true, version: 5, restoredFrom: 3 } ``` - Versions snapshot content and settings (not the package code). The last 25 are kept; photos only used by older versions are deleted with them. - A rollback replaces the draft too (unpublished edits are discarded) and is itself a new version, so it can be undone. - `discard-changes({ confirm: true })` throws away the draft instead. ## Where things live | Storage key | Contents | | --- | --- | | `site/draft` | Config + gallery manifest being edited | | `site/live` | What visitors see (absent on a fresh fork: bundled defaults are live) | | `site/versions`, `site/version/` | Version index and snapshots | | `site/preview-token` | Current preview token | | `site/hosted-url` | Kody-hosted app URL, recorded by the app for export links | | `media/index`, `media/`, `media///` | Encoded photo files (base64, 512K chunks) | | `inquiries`, `inquiries/notification-budget` | Contact messages (newest 500) and the daily email budget | Sample galleries ship as files in `public/samples/` and are referenced by `source: 'bundled'` photos in `src/domain/defaults.ts`. ## Site routes `/`, `/galleries`, `/galleries/`, `/galleries//` (share URL and no-JS view), `/about`, `/contact`, `/sitemap.xml`, `/robots.txt`, `/preview?token=…&to=/path`, `/preview/exit`, `/media//.webp|jpg` (immutable, cached a year), `/health`. ## Gotchas - **Access today:** Kody package apps are served to the signed-in owner; the public can't open the site until Kody supports public package apps and custom domains. Check `liveUrl` in a private window before promising anything. - **Inquiry email** uses Kody's built-in email to the owner's verified address, with Reply-To set to the visitor. `contactEmail` is what visitors see. - `siteUrl` only changes canonical/OG/sitemap links. Set it after the custom domain actually serves the site. - Slugs change URLs. Renaming a gallery's slug breaks links already shared. - The draft and live site share stored photo files, so photos removed from the draft keep working live until the next publish. ## Development ```sh npm install npm test # node --test (config, manifest, versions/rollback, image pipeline) ``` Images are processed in pure JavaScript (`jpeg-js`, `@stacksjs/ts-webp`, `blurhash`, and a small PNG decoder on `DecompressionStream` in `src/images/png.ts`) because package bundles can't ship WebAssembly today. Avoid npm deps that pull in Node-only builds (e.g. `fflate`): the publish bundler resolves the `node` export condition, and Workers can't load `module`.