@rubytech/create-maxy-lite 0.1.3 → 0.1.5

package/index.mjs

@@ -23,9 +23,9 @@ import { fileURLToPath } from 'node:url'
 
 import { makeLog } from './lib/log.mjs'
 import { readPins } from './lib/pins.mjs'
-import { PATHS, WEBCHAT_DIR, VALIDATOR_CLI, launcherPath, launcherScript, payloadLayCommand } from './lib/paths.mjs'
+import { PATHS, WEBCHAT_DIR, VALIDATOR_CLI, SKILLS_HOME, launcherPath, launcherScript, payloadLayCommand, ptyLoadCommand, skillsLinkCommand, vaultBindLogin, webchatRunEnv } from './lib/paths.mjs'
 import { orchestrate, STEP_NAMES } from './lib/orchestrate.mjs'
-import { claudeOk, validatorOk, vaultOk, webchatOk, healthcheck } from './lib/healthcheck.mjs'
+import { claudeOk, validatorOk, vaultOk, webchatOk, skillsOk, healthcheck } from './lib/healthcheck.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const PAYLOAD = path.join(HERE, 'payload')
@@ -107,14 +107,38 @@ const layPayload = () => {
   if (r.code !== 0) throw new Error(`payload lay failed: ${r.stderr.replace(/\s+/g, ' ').trim()}`)
 }
 
+/** Symlink the bundled skills into the guest's personal-skills source so `claude` discovers them. */
+// Runs guest-side (the paths are inside the rootfs); idempotent (`ln -sfn`).
+const linkSkills = () => {
+  const r = runIn(skillsLinkCommand())
+  if (r.code !== 0) throw new Error(`skills link failed: ${r.stderr.replace(/\s+/g, ' ').trim()}`)
+}
+
 /** Install the app deps (validator's js-yaml) and the webchat deps (node-pty, ws). */
 // Streamed: the webchat deps build node-pty natively, which is slow and verbose;
 // a failure carries the child's stderr so the cause is in the log.
+const PTY_NODE = `${WEBCHAT_DIR}/node_modules/node-pty/build/Release/pty.node`
 const installDeps = async () => {
   const app = await runInStream(`cd ${PATHS.appDir} && npm install --omit=dev`)
   if (app.code !== 0) throw new Error(`app deps install failed: ${app.stderr.replace(/\s+/g, ' ').trim()}`)
   const wc = await runInStream(`cd ${WEBCHAT_DIR} && npm install --omit=dev`)
   if (wc.code !== 0) throw new Error(`webchat deps install failed: ${wc.stderr.replace(/\s+/g, ' ').trim()}`)
+  // node-pty ships no linux-arm64 + Node 20 prebuild, so the install above can
+  // leave pty.node unbuilt when npm has ignore-scripts set. `npm rebuild` re-runs
+  // node-pty's node-gyp build; the env var forces scripts on regardless of ambient
+  // config, and --build-from-source keeps it a source compile should a future
+  // node-pty gain a prebuild fetcher. The toolchain step guarantees python3/make/g++.
+  const rb = await runInStream(
+    `cd ${WEBCHAT_DIR} && npm_config_ignore_scripts=false npm rebuild node-pty --build-from-source --foreground-scripts`,
+  )
+  if (rb.code !== 0) throw new Error(`node-pty native build failed: ${rb.stderr.replace(/\s+/g, ' ').trim()}`)
+  // Prove the built module actually loads under the guest's Node — this is exactly
+  // what the relay does at launch, so a pass here means no `Failed to load native
+  // module: pty.node` crash. A bare file-presence test would miss an unloadable
+  // binary. The same ptyLoadCommand backs the npm-app skip-guard, so the guard
+  // admits exactly what this asserts. Fail at install time, not at relay launch.
+  if (runIn(ptyLoadCommand()).code !== 0)
+    throw new Error(`node-pty native module did not load after build: ${PTY_NODE}`)
 }
 
 /** Write the `maxy-lite` launcher into the Termux bin dir. */
@@ -140,24 +164,42 @@ const readVersions = () => ({
 const runHealthcheck = () =>
   healthcheck({
     checkClaude: () => claudeOk(() => runIn('claude --version')),
-    // Start the relay, poll its port for up to 10s, record whether it bound, kill it.
+    // Start the relay under the launcher's exact runtime condition — the vault
+    // bound in and the launcher env set — then poll its port for up to 10s, record
+    // whether it bound, and kill it. Run from bare Termux (`run`) because
+    // vaultBindLogin already enters the distro; `runIn` would nest a second login
+    // with no bind and test the wrong process. Return the full run result so a
+    // failed bind carries the relay's stderr (e.g. node-pty load crash) into err=.
     checkWebchat: () =>
       webchatOk(async () => {
-        const probe =
-          `cd ${WEBCHAT_DIR} && node server.mjs & SVPID=$!; ` +
+        const inner =
+          `cd ${WEBCHAT_DIR} && ${webchatRunEnv()} node server.mjs & SVPID=$!; ` +
           `for i in $(seq 1 10); do sleep 1; ` +
           `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort} && break; done; ` +
           `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort}; RC=$?; ` +
           `kill $SVPID 2>/dev/null; exit $RC`
-        return runIn(probe).code === 0
+        return run(vaultBindLogin(inner))
       }),
-    // Validator must exit 0 on an empty vault.
+    // Validator must exit 0 on an empty vault. Pass the full result so a non-zero
+    // exit carries the validator's stderr into err=.
     checkValidator: () => {
       const empty = `${PATHS.appDir}/.hc-empty-vault`
       runIn(`mkdir -p ${empty}`)
-      return validatorOk((vault) => runIn(`node ${VALIDATOR_CLI} ${vault}`).code, empty)
+      return validatorOk((vault) => runIn(`node ${VALIDATOR_CLI} ${vault}`), empty)
     },
-    checkVault: () => vaultOk(() => runIn(`test -d ${PATHS.vaultGuest}`).code === 0),
+    // The vault path only exists inside the distro when the login carries the
+    // launcher's `--bind`. Reproduce that bind, then check the guest path — exactly
+    // the launcher condition, not a session where the vault was never mounted. The
+    // full result carries the bind/login stderr into err= when the path is absent.
+    checkVault: () => vaultOk(() => run(vaultBindLogin(`test -d ${PATHS.vaultGuest}`))),
+    // The shipped skills are discoverable only when the personal-skills source
+    // carries their SKILL.md files. With nullglob off (the default here), a glob
+    // that matches nothing is passed to `ls` literally and `ls` exits non-zero
+    // because that path does not exist; a match lists real files and exits 0. So
+    // a 0 exit asserts at least one SKILL.md is linked (resolving through the
+    // symlinks) — a dangling or empty link dir fails. The full result carries the
+    // `ls` stderr into err= when nothing matched.
+    checkSkills: () => skillsOk(() => runIn(`ls ${SKILLS_HOME}/*/SKILL.md`)),
   })
 
 // ---- dry run ----------------------------------------------------------------
@@ -214,6 +256,7 @@ async function main() {
     interactive,
     ensureStorageGrant,
     layPayload,
+    linkSkills,
     installDeps,
     writeLauncher,
     readVersions,

package/lib/healthcheck.mjs

@@ -1,41 +1,82 @@
 // Post-install health check — the measured post-conditions, not "ran the step".
-// Each probe answers a binary question about the running system:
+// Each probe answers a binary question about the running system AND carries the
+// cause when it fails, so a red probe is diagnosable from the install log alone:
 //   claude    — does `claude --version` answer with a version?
-//   webchat   — does the relay port listen?
+//   webchat   — does the relay port listen? (its crash output is the relay stderr)
 //   validator — does the validator exit 0 on an empty vault?
 //   vault     — does the bind-mount path exist inside Ubuntu?
-// The probes take injected primitives so the decision rules are unit-testable;
-// index.mjs wires the real ones (run-in-Ubuntu, transient port probe, fs stat).
+//   skills    — does the personal-skills source carry the shipped SKILL.md files?
+// Each probe returns `{ ok, err }`: `ok` is the binary verdict, `err` is the tail
+// of the probe's stderr when it failed (empty when it passed). The probes take
+// injected primitives so the decision rules are unit-testable; index.mjs wires the
+// real ones (run-in-Ubuntu, transient port probe, fs stat), each yielding a
+// `{ code, stdout, stderr }` result so the cause survives into the log.
 
 const VERSION_RE = /\d+\.\d+\.\d+/
 
-/** True when `claude --version` exits 0 and prints a version. `runIn(cmd)` → {code, stdout}. */
+/**
+ * The diagnostic tail of a probe's output: the last few non-empty lines, with
+ * whitespace collapsed and length bounded. The actual failure (e.g. node-pty's
+ * `Failed to load native module`) is at the END of a crash's stderr, so the tail
+ * carries the cause; the cap keeps one `op=healthcheck` line readable.
+ */
+function tail(text, lines = 5, cap = 300) {
+  return String(text || '')
+    .split('\n')
+    .filter((l) => l.trim())
+    .slice(-lines)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, cap)
+}
+
+/** `{ ok, err }` from a `{ code, stdout, stderr }` result: err is the stderr tail on failure. */
+function verdict(ok, r) {
+  return { ok, err: ok ? '' : tail(r && (r.stderr || r.stdout)) }
+}
+
+/** True when `claude --version` exits 0 and prints a version. `runVersion()` → {code, stdout, stderr}. */
 export function claudeOk(runVersion) {
   const r = runVersion()
-  return r.code === 0 && VERSION_RE.test(r.stdout || '')
+  return verdict(r.code === 0 && VERSION_RE.test(r.stdout || ''), r)
 }
 
-/** True when the validator exits 0 on the given (empty) vault. `runValidator(vault)` → exit code. */
+/** True when the validator exits 0 on the given (empty) vault. `runValidator(vault)` → {code, stderr}. */
 export function validatorOk(runValidator, vaultPath) {
-  return runValidator(vaultPath) === 0
+  const r = runValidator(vaultPath)
+  return verdict(r.code === 0, r)
 }
 
-/** True when the bind-mount path exists. `exists()` → bool. */
-export function vaultOk(exists) {
-  return exists() === true
+/** True when the bind-mount path exists. `check()` → {code, stderr}. */
+export function vaultOk(check) {
+  const r = check()
+  return verdict(r.code === 0, r)
 }
 
-/** True when the relay port responded. `getStatus()` → Promise<bool>. */
+/** True when the relay port responded. `getStatus()` → Promise<{code, stderr}>. */
 export async function webchatOk(getStatus) {
-  return (await getStatus()) === true
+  const r = await getStatus()
+  return verdict(r.code === 0, r)
+}
+
+/** True when the shipped skills are present in the personal-skills source. `listSkills()` → {code, stderr} of an `ls` of the per-skill SKILL.md glob under SKILLS_HOME; err carries the ls stderr (e.g. "No such file") when nothing matched. */
+export function skillsOk(listSkills) {
+  const r = listSkills()
+  return verdict(r.code === 0, r)
 }
 
-/** Run all four probes and return `{ claude, webchat, validator, vault }`. */
-export async function healthcheck({ checkClaude, checkWebchat, checkValidator, checkVault }) {
+/**
+ * Run all five probes and return `{ claude, webchat, validator, vault, skills }`,
+ * each a `{ ok, err }` record. orchestrate flattens this into the `op=healthcheck`
+ * line: `<probe>=<ok>` for every probe, plus `<probe>Err=<cause>` for each failure.
+ */
+export async function healthcheck({ checkClaude, checkWebchat, checkValidator, checkVault, checkSkills }) {
   return {
-    claude: checkClaude() === true,
-    webchat: (await checkWebchat()) === true,
-    validator: checkValidator() === true,
-    vault: checkVault() === true,
+    claude: checkClaude(),
+    webchat: await checkWebchat(),
+    validator: checkValidator(),
+    vault: checkVault(),
+    skills: checkSkills(),
   }
 }

package/lib/orchestrate.mjs

@@ -15,7 +15,7 @@
 // All external effects go through injected ctx primitives so the sequence,
 // guards and idempotency are unit-testable; index.mjs wires the real ones.
 
-import { PATHS, WEBCHAT_DIR, launcherPath } from './paths.mjs'
+import { PATHS, launcherPath, ptyLoadCommand } from './paths.mjs'
 
 export const STEP_NAMES = ['termux-deps', 'proot', 'ubuntu', 'node', 'toolchain', 'vault-bind', 'npm-app']
 
@@ -109,11 +109,16 @@ const STEPS = [
   },
   {
     name: 'npm-app',
-    // Converged only when the deps are built, claude is present, AND the launcher
-    // is written — the launcher is the last mutation, so guarding on the first two
-    // alone would skip a half-finished install and report ok=true with no launcher.
+    // Converged only when node-pty's native module LOADS, claude is present, AND
+    // the launcher is written. The deps probe is `require("node-pty")`, not a
+    // file-presence test: a present-but-unloadable `pty.node` (stale/wrong-ABI
+    // from a prior build) would pass `test -f` yet crash the relay at launch, so
+    // the guard would skip the very rebuild that repairs it. The load-check is the
+    // same condition `installDeps` asserts post-build (shared ptyLoadCommand), so
+    // the guard admits exactly what the build proves; a non-loadable module fails
+    // the guard and the step rebuilds.
     done: (c) =>
-      c.runIn(`test -d ${WEBCHAT_DIR}/node_modules`).code === 0 &&
+      c.runIn(ptyLoadCommand()).code === 0 &&
       c.runIn('command -v claude').code === 0 &&
       c.existsHost(launcherPath()),
     run: async (c) => {
@@ -125,6 +130,9 @@ const STEPS = [
         ),
       )
       c.layPayload()
+      // The payload now carries the skills tree into the app dir; link each skill
+      // into the on-device personal-skills source so `claude` discovers them.
+      c.linkSkills()
       await c.installDeps()
       c.writeLauncher()
     },
@@ -166,10 +174,25 @@ async function runStep(step, ctx) {
   return { name: step.name, ok, skipped, ms }
 }
 
+/**
+ * Flatten the healthcheck record (`{ probe: { ok, err } }`) into one line's
+ * fields: `<probe>=<ok>` for every probe, in order, plus `<probe>Err=<cause>`
+ * immediately after any probe that failed. A healthy run carries no err fields.
+ */
+function healthcheckFields(hc) {
+  const fields = {}
+  for (const [name, p] of Object.entries(hc)) {
+    fields[name] = p.ok
+    if (!p.ok && p.err) fields[`${name}Err`] = p.err
+  }
+  return fields
+}
+
 /**
  * Run the full install. Stops at the first failed step (logs `done ok=false`,
- * no healthcheck). On success: emits the resolved versions, the four-probe
- * healthcheck, and `done ok=<all probes true>`.
+ * no healthcheck). On success: emits the resolved versions, the five-probe
+ * healthcheck (each probe's ok plus its captured err when false), and
+ * `done ok=<all probes true>`.
  */
 export async function orchestrate(ctx) {
   const t0 = ctx.now()
@@ -185,8 +208,8 @@ export async function orchestrate(ctx) {
   const v = ctx.readVersions()
   ctx.log('versions', { node: v.node, claude: v.claude, ttyd: v.ttyd })
   const hc = await ctx.runHealthcheck()
-  ctx.log('healthcheck', hc)
-  const ok = Object.values(hc).every(Boolean)
+  ctx.log('healthcheck', healthcheckFields(hc))
+  const ok = Object.values(hc).every((p) => p.ok)
   ctx.log('done', { ok, ranMs: ctx.now() - t0 })
   return { ok, results, healthcheck: hc }
 }

package/lib/paths.mjs

@@ -21,6 +21,44 @@ export const PATHS = {
 export const WEBCHAT_DIR = `${PATHS.appDir}/webchat`
 export const VALIDATOR_CLI = `${PATHS.appDir}/validator/cli.mjs`
 
+/**
+ * The guest-side command that proves node-pty's native module actually loads
+ * under the guest's Node — `require("node-pty")` exits 0 only when `pty.node` is
+ * both present and loadable (right ABI). This is the single construction of the
+ * load-check, shared by the `npm-app` skip-guard and `installDeps`' post-build
+ * assertion so the two can never drift: the guard admits exactly the modules the
+ * build asserts. A bare `test -f pty.node` would pass on a present-but-unloadable
+ * binary (stale/wrong-ABI from a prior build) and wrongly skip the rebuild.
+ */
+export function ptyLoadCommand({ webchatDir = WEBCHAT_DIR } = {}) {
+  return `cd ${webchatDir} && node -e 'require("node-pty")'`
+}
+
+// The shipped skills, as bundled into the app dir, and the path the on-device
+// `claude` reads as its personal-skills source. `claude` runs with HOME=/root in
+// the proot Ubuntu layer, so `~/.claude/skills/*/SKILL.md` resolves under /root —
+// discovered regardless of `claude`'s working directory (the vault). Skills are
+// shipped app content, so they live in the rootfs app dir, not in the shared
+// Obsidian vault; the install links them into SKILLS_HOME from this one source.
+export const SKILLS_SRC = `${PATHS.appDir}/skills`
+export const SKILLS_HOME = '/root/.claude/skills'
+
+/**
+ * The guest-side command that makes the bundled skills discoverable: ensure the
+ * personal-skills dir exists, then symlink each shipped skill dir into it. One
+ * source of truth (the app dir); `ln -sfn` is idempotent and leaves any sibling
+ * personal skills untouched. `shopt -s nullglob` makes an empty or absent skills
+ * source expand to zero iterations instead of bash's default unmatched-glob
+ * behaviour, which would otherwise pass the literal pattern through, create a
+ * dangling symlink named `*`, and still exit 0. So the empty case is a clean
+ * no-op that the `skills` health probe then reports false, rather than a silent
+ * false success. Run inside the distro (the paths are guest paths). `src` and
+ * `home` are pinned constants, never user input, so there is no injection surface.
+ */
+export function skillsLinkCommand({ src = SKILLS_SRC, home = SKILLS_HOME } = {}) {
+  return `shopt -s nullglob; mkdir -p ${home} && for d in ${src}/*/; do ln -sfn "$d" "${home}/$(basename "$d")"; done`
+}
+
 // Where the host payload is bind-mounted inside the guest while it is copied into
 // place. A throwaway path under the rootfs's own /tmp, distinct from the app dir.
 export const PAYLOAD_STAGE = '/tmp/maxy-lite-payload'
@@ -45,10 +83,37 @@ export function launcherPath(prefix = process.env.PREFIX || '/data/data/com.term
   return `${prefix}/bin/maxy-lite`
 }
 
+/**
+ * The env prefix the webchat relay needs to serve the bound vault on the pinned
+ * port. Shared by the launcher and the webchat health-check probe so the two
+ * cannot drift: the probe must start the relay with exactly the env production
+ * uses, or it tests a different process than the one the launcher runs.
+ */
+export function webchatRunEnv({ vaultGuest = PATHS.vaultGuest, port = PATHS.webchatPort } = {}) {
+  return `LITE_AGENT_HOME=${vaultGuest} LITE_PORT=${port}`
+}
+
+/**
+ * A proot-distro login into the distro with the shared-storage vault bound in,
+ * running `inner` under `bash -lc`. This is the single construction of the
+ * launcher's runtime condition (the `--bind` that makes `${vaultGuest}` exist);
+ * the launcher and the vault/webchat probes all build on it so a probe can never
+ * assert a post-condition under different conditions than production.
+ * Run from bare Termux (not nested inside another `proot-distro login`).
+ */
+export function vaultBindLogin(
+  inner,
+  { distro = PATHS.distro, vaultHost = PATHS.vaultHost, vaultGuest = PATHS.vaultGuest } = {},
+) {
+  return `proot-distro login ${distro} --bind ${vaultHost}:${vaultGuest} -- bash -lc '${inner}'`
+}
+
 /**
  * The `maxy-lite` launcher script (written into the Termux bin dir). Run from the
  * Termux shell, it enters Ubuntu with the vault bind-mount and starts the webchat
- * relay on localhost. Documented Termux:Boot opt-in re-runs this on boot.
+ * relay on localhost. Built from the shared bind + env helpers so the launcher
+ * and the health-check probes stay in lockstep. Documented Termux:Boot opt-in
+ * re-runs this on boot.
  */
 export function launcherScript({
   prefix = process.env.PREFIX || '/data/data/com.termux/files/usr',
@@ -58,12 +123,12 @@ export function launcherScript({
   port = PATHS.webchatPort,
   distro = PATHS.distro,
 } = {}) {
+  const inner = `cd ${webchatDir} && ${webchatRunEnv({ vaultGuest, port })} exec node server.mjs`
   return `#!${prefix}/bin/bash
 # maxy-lite launcher — starts the on-device web chat relay.
 # Enters the glibc Ubuntu layer with the shared-storage vault bound in, then runs
 # the relay on http://localhost:${port}. Open that URL in the phone browser.
 set -e
-exec proot-distro login ${distro} --bind ${vaultHost}:${vaultGuest} -- \\
-  bash -lc 'cd ${webchatDir} && LITE_AGENT_HOME=${vaultGuest} LITE_PORT=${port} exec node server.mjs'
+exec ${vaultBindLogin(inner, { distro, vaultHost, vaultGuest })}
 `
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-lite",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Install maxy-lite on an Android phone: orchestrates proot-distro Ubuntu, glibc Node, claude, the web-chat relay, the vault and its bind-mount — run via npx in bare Termux.",
   "type": "module",
   "engines": {

package/payload/skills/calendar-site/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: calendar-site
+description: Stand up a public "book time with me" page on a custom domain, and pull the bookings it captures into the vault as events. This is the skill behind "give me a booking link", "put up a Calendly-style page", "let people book a call with me", "deploy the booking site", and "reconcile new bookings". It writes a static availability config, assembles the booking page plus its D1 capture, deploys via the site-deploy skill, and on demand reads new submissions from D1 and writes each as a vault Event (then pushes it to Google Calendar). The vault Event is the source of truth.
+---
+
+# Stand up a booking site, and reconcile its bookings into the vault
+
+Two halves. The first deploys a public page that captures bookings to Cloudflare D1, so a booking is captured even while the phone is offline or asleep. The second is a pull-on-demand reconcile: when run, it reads new submissions from D1 and turns each into a vault Event. There is no always-on process. The vault is authoritative, so a captured row only becomes real once it is written as an Event and validated.
+
+The deploy mechanics (build, custom-domain attach, token discipline, the live done-gate) belong to the `site-deploy` skill. Read it before deploying. This skill adds the two things a booking site needs on top of a plain page: the static availability config the page reads to compute open slots, and the reconcile that brings captured rows into the vault.
+
+## The template
+
+The booking page ships in `template/`:
+
+- `availability.json` is the static slot source: `timezone`, `durationMins`, `bufferMins`, and a `weekly` window per day (`{ "mon": [["09:00","17:00"]], ..., "sat": [], "sun": [] }`, with an empty array for closed days).
+- `public/` is the page. It fetches `availability.json` and computes open slots client-side as the weekly window minus the buffer for the next two weeks. There is no live free/busy merge, so the page never reads any event detail.
+- `functions/api/book.ts` captures a submission to D1. `schema.sql` is the `bookings` table. `wrangler.toml` carries the Pages and D1 config with placeholders.
+
+## Deploy the page
+
+1. Collect the availability from the operator (timezone, meeting duration, buffer, weekly window) and write `availability.json`. Re-running with new numbers is how availability changes later; there is no separate editor.
+2. Assemble the template into the canonical Pages source path the `site-deploy` skill expects, and fill `wrangler.toml`'s `__PROJECT_NAME__`, `__D1_DATABASE_NAME__`, and `__D1_DATABASE_ID__`. Leave no `__...__` placeholder in the assembled tree.
+3. Provision the D1 `bookings` table by applying `schema.sql` to the remote database, using the Cloudflare token discipline the `site-deploy` skill and the Cloudflare connector own. Never write or echo a token.
+4. Hand the assembled tree to the `site-deploy` skill for the Pages deploy and custom-domain attach. Everything in its auth, domain, and DNS guidance applies unchanged.
+
+Done for this half is the `site-deploy` live gate plus a test submission that lands in D1:
+
+```bash
+curl -sS -X POST -H 'content-type: application/json' \
+  -d '{"slotStart":"2026-01-01T09:00:00","slotEnd":"2026-01-01T09:30:00","name":"verify","email":"verify@example.com"}' \
+  "https://<booking-domain>/api/book" -i | head -1
+```
+
+## Reconcile bookings into the vault
+
+This is the bridge from a captured D1 row to a vault Event. Run it when checking for new bookings (next session, or when the operator asks). It has no background process; nothing happens to a booking until this runs.
+
+1. Read the accepted, unswept rows:
+
+   ```bash
+   wrangler d1 execute <db-name> --remote --command \
+     "SELECT bookingId, slotStart, slotEnd, name, email, note FROM bookings WHERE status = 'accepted' AND swept = 0;"
+   ```
+
+2. For each row, before writing anything, run the **overlap guard**: scan `calendar/` for an existing Event whose time range overlaps `[slotStart, slotEnd)`. If one overlaps, do not write the Event and do not mark the row swept. Tell the operator there is a clash for that slot so they can decline or rebook it; leaving the row unswept lets a later run retry it once the clash is resolved. This guard is why a static page is safe: the page can offer a slot that filled after the page loaded, and the clash is caught here rather than silently double-booking.
+
+3. For a non-overlapping row, write the Event exactly as the `scheduling` skill prescribes: a `calendar/<summary>.md` file with `type: event`, `summary` (for example `Booking: <name>`), `start` = `slotStart`, `end` = `slotEnd`, and the booker's name, email, and note in the markdown body. Then run the validator to exit 0:
+
+   ```bash
+   maxy-lite-validate <vault>
+   ```
+
+   A non-zero exit means the Event drifted from the SCHEMA; fix the file before going on. Do not mark the row swept while its Event is non-conformant.
+
+4. Once the Event validates, push it to Google Calendar through the connector (the same step the `scheduling` skill uses), then mark the row swept so it is not reconciled again:
+
+   ```bash
+   wrangler d1 execute <db-name> --remote --command \
+     "UPDATE bookings SET swept = 1 WHERE bookingId = '<bookingId>';"
+   ```
+
+Done for this half is a test submission that, after a reconcile run, exists as a validator-passing vault Event.
+
+## Known limitation
+
+The page computes open slots from the static availability window with no live busy-merge, so it can offer a slot that has already filled. The reconcile overlap guard catches the clash when the booking is pulled into the vault, but there is a window where a visitor can submit a slot that turns out to be taken. That clash surfaces at reconcile time, not at booking time. Live busy-merge and two-way sync are not part of this skill; the static window plus the reconcile guard are the whole mechanism here.
+
+## Tool discipline
+
+The permitted surface is `wrangler`, `curl`, the Cloudflare API via the Cloudflare connector, and native vault file writes. Follow the Cloudflare references for token discipline: reuse one stable per-scope token, never mint one per deploy, never drive the dashboard with a browser, never write or echo a token. When a step fails, report the exact output with secrets redacted, name the failing URL or command, and stop.

package/payload/skills/calendar-site/template/availability.json

@@ -0,0 +1,14 @@
+{
+  "timezone": "Europe/London",
+  "durationMins": 30,
+  "bufferMins": 15,
+  "weekly": {
+    "mon": [["09:00", "17:00"]],
+    "tue": [["09:00", "17:00"]],
+    "wed": [["09:00", "17:00"]],
+    "thu": [["09:00", "17:00"]],
+    "fri": [["09:00", "17:00"]],
+    "sat": [],
+    "sun": []
+  }
+}

package/payload/skills/calendar-site/template/functions/api/book.ts

@@ -0,0 +1,112 @@
+// Booking capture Pages Function (calendar-site skill).
+//
+// Served at POST /api/book on the booking domain. Writes the submission
+// straight to D1 so capture survives while the device is offline or asleep —
+// the calendar-site reconcile pass turns accepted rows into vault Events later.
+// Emits the [calendar-booking] submit + d1-write lifeline (Cloudflare Pages
+// captures console output).
+//
+// The handler is split so its logic is verifiable without the Pages runtime:
+// processBooking takes an injected DB + logger and returns the HTTP shape.
+
+interface D1Result {
+  meta?: { changes?: number }
+}
+interface D1PreparedStatement {
+  bind: (...values: unknown[]) => D1PreparedStatement
+  run: () => Promise<D1Result>
+}
+interface D1Database {
+  prepare: (query: string) => D1PreparedStatement
+}
+interface BookingEnv {
+  DB: D1Database
+}
+
+interface BookingBody {
+  slotStart?: unknown
+  slotEnd?: unknown
+  name?: unknown
+  email?: unknown
+  note?: unknown
+  company?: unknown // honeypot — real users never fill this
+}
+
+type Logger = (line: string) => void
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.trim().length > 0
+}
+
+// Field caps so a malicious POST cannot store an unbounded blob in D1.
+const MAX = { name: 200, email: 320, note: 2000, slot: 40 }
+
+function isIsoTimestamp(v: unknown): v is string {
+  return typeof v === 'string' && v.length <= MAX.slot && !Number.isNaN(Date.parse(v))
+}
+
+export async function processBooking(
+  body: BookingBody,
+  env: BookingEnv,
+  log: Logger,
+  newId: () => string,
+): Promise<{ status: number; payload: Record<string, unknown> }> {
+  // Honeypot: a populated `company` field means a bot. Return ok (so the bot
+  // sees success) but write nothing.
+  if (isNonEmptyString(body.company)) {
+    return { status: 200, payload: { ok: true } }
+  }
+
+  if (
+    !isIsoTimestamp(body.slotStart) ||
+    !isIsoTimestamp(body.slotEnd) ||
+    !isNonEmptyString(body.name) ||
+    !isNonEmptyString(body.email)
+  ) {
+    return { status: 400, payload: { ok: false, error: 'name, email, and ISO slotStart/slotEnd are required' } }
+  }
+  if (body.name.length > MAX.name || body.email.length > MAX.email) {
+    return { status: 400, payload: { ok: false, error: 'name or email too long' } }
+  }
+
+  const bookingId = newId()
+  const note = isNonEmptyString(body.note) ? body.note.slice(0, MAX.note) : ''
+  const createdAt = new Date().toISOString()
+  log(`[calendar-booking] op=submit bookingId=${bookingId} slotStart=${body.slotStart} email=${body.email}`)
+
+  const result = await env.DB.prepare(
+    `INSERT INTO bookings (bookingId, slotStart, slotEnd, name, email, note, status, createdAt, swept)
+     VALUES (?, ?, ?, ?, ?, ?, 'accepted', ?, 0)`,
+  )
+    .bind(bookingId, body.slotStart, body.slotEnd, body.name, body.email, note, createdAt)
+    .run()
+
+  const rowsWritten = result.meta?.changes ?? 0
+  log(`[calendar-booking] op=d1-write bookingId=${bookingId} rowsWritten=${rowsWritten}`)
+
+  if (rowsWritten < 1) {
+    return { status: 500, payload: { ok: false, error: 'capture failed' } }
+  }
+  return { status: 200, payload: { ok: true, bookingId } }
+}
+
+interface PagesContext {
+  request: Request
+  env: BookingEnv
+}
+
+export async function onRequestPost(context: PagesContext): Promise<Response> {
+  let body: BookingBody
+  try {
+    body = (await context.request.json()) as BookingBody
+  } catch {
+    return Response.json({ ok: false, error: 'invalid JSON' }, { status: 400 })
+  }
+  const { status, payload } = await processBooking(
+    body,
+    context.env,
+    (line) => console.log(line),
+    () => crypto.randomUUID(),
+  )
+  return Response.json(payload, { status })
+}