@rubytech/create-maxy-lite 0.1.4 → 0.1.6

package/payload/skills/admin/upgrade/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: upgrade
+description: "Upgrade maxy-lite to the latest published version by re-running the lite installer when the owner asks."
+---
+
+# Upgrade
+
+The owner wants to upgrade maxy-lite. Re-run the lite installer; it is idempotent and brings the install to the latest published version.
+
+## Run the upgrade
+
+maxy-lite ships as one installer package (it has no brand variants), so the upgrade is a single command:
+
+```bash
+npx -y @rubytech/create-maxy-lite@latest
+```
+
+Stream the installer's stdout to the owner as it runs. The installer prints its own progress; pass it through, do not narrate around it.
+
+If the lite install records its own installer package name in a config file, read that field with `Read` and use it instead of the literal above. Never invent a different default.
+
+## After the upgrade
+
+The lite runtime is the `claude` process in the Termux session, not a brand systemd service. The upgrade applies to the files on disk; it takes effect on the next `claude` session. Tell the owner to start a fresh session to pick up the new version.
+
+## Surface failures verbatim
+
+- `npx` fetch from `registry.npmjs.org` fails (network, DNS, registry outage): show the error to the owner.
+- The installer exits non-zero: show the tail of stdout and stop.
+- `Permission denied` on `npx`: the Bash environment is misconfigured for this install; tell the owner.
+
+Never claim success on a failed run.

package/payload/skills/browser/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: browser
+description: >
+  Drive the device's Chromium for the things plain HTTP cannot do: render a
+  JavaScript-heavy page, turn an HTML file into a PDF, or capture a screenshot.
+  Use when url-get returns an empty page, when a deck or brochure or booking
+  page needs to become a PDF, or when the owner wants a picture of a page.
+  Trigger phrases: "this page is empty", "render it in a browser", "save it as
+  a PDF", "print to PDF", "take a screenshot of", "grab an image of this page".
+---
+
+# browser
+
+Three one-shot operations against the device Chromium over the Chrome DevTools Protocol: render, pdf, screenshot. Each call connects to the already-running Chromium, does one thing, and disconnects. Nothing stays open between calls.
+
+## When to use
+
+- **render**: a page came back empty or as a shell from `[[url-get]]`. It is client-rendered, so its content only exists after the browser runs its JavaScript. This script runs the page and returns the rendered text and HTML.
+- **pdf**: an HTML file (a deck, a brochure, a booking page) needs to become a PDF. Serve or open the HTML, then print it. This honours print CSS and prints backgrounds.
+- **screenshot**: the owner wants a picture of a page, or a section captured as an image.
+
+For static, server-rendered pages prefer `[[url-get]]`, which is lighter and returns verbatim markdown. Reach for `browser` only when the page needs a real browser.
+
+## How to run
+
+All three read the Chromium debug port from `CDP_PORT` (the lite runtime sets it). They attach to that browser and never launch their own.
+
+```bash
+# Render a JS page and read its rendered DOM
+node ~/.maxy-lite/skills/browser/scripts/render.mjs "https://app.example.com/dashboard"
+
+# Turn an HTML page into a PDF (add --landscape for landscape)
+node ~/.maxy-lite/skills/browser/scripts/pdf.mjs "http://localhost:8080/deck.html" /path/out.pdf
+
+# Capture a screenshot (optional --width/--height set the viewport first)
+node ~/.maxy-lite/skills/browser/scripts/screenshot.mjs "https://example.com" /path/out.png --width=1200 --height=800
+```
+
+`render` prints the visible text then the rendered HTML to stdout. `pdf` and `screenshot` write the file and print its path.
+
+## Reading the result
+
+- **Output on stdout, exit 0**: the operation succeeded.
+- **Non-zero exit**: an error on stderr as `[browser] error=<code>`:
+  - `cdp-port`: `CDP_PORT` is unset or invalid. The browser is not configured.
+  - `cdp-unreachable`: the Chromium debug port did not answer. The browser is not running.
+  - `render` / `pdf` / `screenshot`: the navigation or operation failed (a bad URL, a load timeout). The detail says which.
+
+Surface the error plainly. Do not invent the page contents or claim a file was written when it was not.
+
+## Form decision (recorded)
+
+Lite ships `browser` as a skill with per-call scripts, not as a persistent MCP server. The reason: lite's real browser needs are one-shot (render a page, print a PDF, take a screenshot), and a fresh script per call adds no long-lived process. This matches lite's zero-process default.
+
+Multi-call interactive automation (navigate, then click, then fill, then submit against one live page, with dialog arming and console buffering) genuinely needs a persistent listener and is not built here. If a real need for it appears, it is promoted to a lite browser MCP at that point.
+
+## Boundaries
+
+- One operation per call. There is no click, fill, type, or form-submit here. Those need a persistent page and are out of scope for the script form.
+- Attaches to the device Chromium; it does not start or manage the browser.

package/payload/skills/browser/scripts/cdp.mjs

@@ -0,0 +1,134 @@
+// Minimal Chrome DevTools Protocol client for the lite browser scripts.
+//
+// Attaches to the device Chromium over CDP (CDP_PORT on 127.0.0.1) and never
+// launches its own browser. Each lite browser script connects, does one
+// operation against a fresh target, and disconnects. There is no persistent
+// session: the page lives only for the call. Ported in spirit from the
+// maxy-code browser plugin's cdp-session/cdp-render, trimmed to the one-shot
+// operations lite needs (render, pdf, screenshot).
+const HOST = "127.0.0.1";
+
+const fail = (code, msg) => {
+  console.error(`[browser] error=${code} detail=${JSON.stringify(msg)}`);
+  process.exit(1);
+};
+
+/** Resolve and validate CDP_PORT. Exits with error=cdp-port if unset/invalid. */
+export function cdpPort() {
+  const p = Number.parseInt(process.env.CDP_PORT ?? "", 10);
+  if (!p || Number.isNaN(p)) fail("cdp-port", "CDP_PORT not set or invalid");
+  return p;
+}
+
+/** Create a blank page target via the CDP HTTP surface. */
+export async function createTarget(port, timeoutMs = 15_000) {
+  let r;
+  try {
+    r = await fetch(`http://${HOST}:${port}/json/new`, { method: "PUT", signal: AbortSignal.timeout(timeoutMs) });
+  } catch (err) {
+    fail("cdp-unreachable", err instanceof Error ? err.message : String(err));
+  }
+  if (!r.ok) fail("cdp", `json/new returned ${r.status}`);
+  const t = await r.json();
+  if (!t.id || !t.webSocketDebuggerUrl) fail("cdp", "json/new response missing id/webSocketDebuggerUrl");
+  return t;
+}
+
+/** Best-effort target close. Failure is ignored. */
+export async function closeTarget(port, id) {
+  try {
+    await fetch(`http://${HOST}:${port}/json/close/${encodeURIComponent(id)}`, {
+      method: "PUT",
+      signal: AbortSignal.timeout(5_000),
+    });
+  } catch {
+    /* best effort */
+  }
+}
+
+/** A CDP command/event channel over one page websocket. */
+export class Cdp {
+  constructor(ws) {
+    this.ws = ws;
+    this.seq = 0;
+    this.pending = new Map();
+    this.events = new Map();
+    ws.addEventListener("message", (ev) => {
+      const raw = typeof ev.data === "string" ? ev.data : ev.data.toString();
+      const m = JSON.parse(raw);
+      if (m.id && this.pending.has(m.id)) {
+        const { resolve, reject } = this.pending.get(m.id);
+        this.pending.delete(m.id);
+        m.error ? reject(new Error(m.error.message)) : resolve(m.result);
+      } else if (m.method && this.events.has(m.method)) {
+        const fn = this.events.get(m.method);
+        this.events.delete(m.method);
+        fn();
+      }
+    });
+  }
+
+  cmd(method, params = {}, timeoutMs = 15_000) {
+    const id = ++this.seq;
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`command-timeout ${method}`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => {
+          clearTimeout(to);
+          resolve(v);
+        },
+        reject: (e) => {
+          clearTimeout(to);
+          reject(e);
+        },
+      });
+      this.ws.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  waitFor(event, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+      const to = setTimeout(() => {
+        this.events.delete(event);
+        reject(new Error(`load-timeout ${event}`));
+      }, timeoutMs);
+      this.events.set(event, () => {
+        clearTimeout(to);
+        resolve();
+      });
+    });
+  }
+}
+
+/** Open a websocket to a target and return a Cdp channel. On a connect failure
+ *  the half-open socket is closed before rethrowing, so a failed openSession
+ *  never leaves a dangling handle that would keep the process alive. */
+export async function openSession(target) {
+  if (typeof WebSocket === "undefined") fail("websocket-unavailable", "global WebSocket unavailable (Node < 22.4)");
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  try {
+    await new Promise((resolve, reject) => {
+      ws.addEventListener("open", () => resolve());
+      ws.addEventListener("error", (e) => reject(new Error(`websocket: ${String(e?.message ?? e)}`)));
+    });
+  } catch (err) {
+    try {
+      ws.close();
+    } catch {
+      /* already closed */
+    }
+    throw err;
+  }
+  return new Cdp(ws);
+}
+
+/** Shared navigate helper: enable Page, navigate, await load. */
+export async function navigate(session, url, loadTimeoutMs = 30_000) {
+  await session.cmd("Page.enable");
+  const load = session.waitFor("Page.loadEventFired", loadTimeoutMs);
+  await session.cmd("Page.navigate", { url });
+  await load;
+}

package/payload/skills/browser/scripts/pdf.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// browser pdf — render a page to a PDF file using Chromium's print pipeline
+// (honours @page/@media print CSS, prints backgrounds). One-shot: creates a
+// target, navigates, prints, closes. The on-device path for deck/brochure/
+// calendar-site HTML to PDF.
+import { writeFileSync } from "node:fs";
+import { cdpPort, createTarget, closeTarget, openSession, navigate } from "./cdp.mjs";
+
+const url = process.argv[2];
+const out = process.argv[3];
+const landscape = process.argv.includes("--landscape");
+if (!url || !out) {
+  console.error(`[browser] error=usage detail="usage: pdf.mjs <url> <out.pdf> [--landscape]"`);
+  process.exit(1);
+}
+
+const port = cdpPort();
+const target = await createTarget(port);
+let session;
+try {
+  session = await openSession(target);
+  await navigate(session, url);
+  const res = await session.cmd("Page.printToPDF", { landscape, printBackground: true });
+  const buf = Buffer.from(res.data, "base64");
+  writeFileSync(out, buf);
+  console.error(`[browser-pdf] url=${url} out=${out} bytes=${buf.length}`);
+  process.stdout.write(out + "\n");
+} catch (err) {
+  console.error(`[browser] error=pdf detail=${JSON.stringify(String(err?.message ?? err))}`);
+  process.exitCode = 1;
+} finally {
+  try {
+    session?.ws?.close();
+  } catch {
+    /* already closed */
+  }
+  await closeTarget(port, target.id);
+}

package/payload/skills/browser/scripts/render.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// browser render — render a JavaScript-heavy page in the device Chromium and
+// print its fully rendered DOM text and HTML. Use for pages url-get returns
+// empty. One-shot: creates a target, navigates, reads the DOM, closes.
+import { cdpPort, createTarget, closeTarget, openSession, navigate } from "./cdp.mjs";
+
+const url = process.argv[2];
+if (!url) {
+  console.error(`[browser] error=usage detail="usage: render.mjs <url>"`);
+  process.exit(1);
+}
+
+const port = cdpPort();
+const target = await createTarget(port);
+let session;
+try {
+  session = await openSession(target);
+  await navigate(session, url);
+  const htmlRes = await session.cmd("Runtime.evaluate", {
+    expression: "document.documentElement.outerHTML",
+    returnByValue: true,
+  });
+  const textRes = await session.cmd("Runtime.evaluate", {
+    expression: "document.body && document.body.innerText || ''",
+    returnByValue: true,
+  });
+  const html = typeof htmlRes?.result?.value === "string" ? htmlRes.result.value : "";
+  const text = typeof textRes?.result?.value === "string" ? textRes.result.value : "";
+  console.error(`[browser-render] url=${url} domBytes=${Buffer.byteLength(html)}`);
+  process.stdout.write(
+    `--- VISIBLE TEXT ---\n${text.slice(0, 200_000)}\n\n--- RENDERED HTML ---\n${html.slice(0, 800_000)}\n`,
+  );
+} catch (err) {
+  console.error(`[browser] error=render detail=${JSON.stringify(String(err?.message ?? err))}`);
+  process.exitCode = 1;
+} finally {
+  try {
+    session?.ws?.close();
+  } catch {
+    /* already closed */
+  }
+  await closeTarget(port, target.id);
+}

package/payload/skills/browser/scripts/screenshot.mjs

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+// browser screenshot — capture a PNG of a page to a file. One-shot: creates a
+// target, navigates, captures, closes. Optional viewport width/height before
+// capture to control the rendered size.
+import { writeFileSync } from "node:fs";
+import { cdpPort, createTarget, closeTarget, openSession, navigate } from "./cdp.mjs";
+
+const url = process.argv[2];
+const out = process.argv[3];
+const args = Object.fromEntries(
+  process.argv.slice(4).map((a) => {
+    const m = a.match(/^--([^=]+)=(.*)$/);
+    return m ? [m[1], m[2]] : [a, true];
+  }),
+);
+if (!url || !out) {
+  console.error(`[browser] error=usage detail="usage: screenshot.mjs <url> <out.png> [--width=] [--height=]"`);
+  process.exit(1);
+}
+
+const port = cdpPort();
+const target = await createTarget(port);
+let session;
+try {
+  session = await openSession(target);
+  // Set the viewport before navigating so responsive layout and any
+  // viewport-dependent resources load at the requested size, not the default.
+  if (args.width && args.height) {
+    await session.cmd("Emulation.setDeviceMetricsOverride", {
+      width: Number(args.width),
+      height: Number(args.height),
+      deviceScaleFactor: 1,
+      mobile: false,
+    });
+  }
+  await navigate(session, url);
+  const res = await session.cmd("Page.captureScreenshot", { format: "png" });
+  const buf = Buffer.from(res.data, "base64");
+  writeFileSync(out, buf);
+  console.error(`[browser-screenshot] url=${url} out=${out} bytes=${buf.length}`);
+  process.stdout.write(out + "\n");
+} catch (err) {
+  console.error(`[browser] error=screenshot detail=${JSON.stringify(String(err?.message ?? err))}`);
+  process.exitCode = 1;
+} finally {
+  try {
+    session?.ws?.close();
+  } catch {
+    /* already closed */
+  }
+  await closeTarget(port, target.id);
+}

package/payload/skills/business-assistant/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: business-assistant
+description: Handle a customer enquiry end to end for a small business: triage it, find or create the customer, book the appointment, send the confirmation, format a quote, and record every step in the vault. Use when a customer message comes in, when the user asks to book someone in, chase a quote, or see what is outstanding, or when running the day to day customer side of a small business. Composes the contacts, scheduling, and email skills; it adds no tools of its own.
+---
+
+# Business assistant
+
+You run the customer side of a small business so the owner can get on with the work: enquiries, bookings, quotes, and the admin around them. You are the owner's assistant, not the owner. Be professional and warm, keep messages short, and always be honest that you are an AI when asked. Never impersonate the owner, never pretend to be human, and never commit to a price without the owner's approval.
+
+This skill does not introduce new tools. It is a workflow over skills that already exist: `contacts` for the customer record, `scheduling` for the appointment, `email-composition` for correspondence, and `work`/`memory` for follow ups and context. Every record it writes is checked by the validator. The entity field lists are in [`SCHEMA.md`](../../schema/SCHEMA.md).
+
+## Read the vault first
+
+Before answering a customer, read what the vault already knows. Grep `people/` for the sender, read their Person file and any notes linked to them, and check `calendar/` for anything booked. Answer from what you find, not from assumption. After anything meaningful happens, write it back, so the next message starts from a fuller picture.
+
+## Triage
+
+Sort every incoming message into one of four levels and act accordingly.
+
+- **Red, urgent.** A safety risk or escalating damage (a leak, no heat for a vulnerable person in the cold). Give immediate safety advice and tell the owner now, in this conversation, before waiting on anything else.
+- **Amber, same or next day.** Something is broken but not dangerous. Gather the details needed to book or to quote, then handle it or surface it to the owner.
+- **Green, routine.** Planned work, a maintenance job, a quote request, a booking. Gather details and book the next suitable slot.
+- **Quick.** Confirming an appointment, chasing a quote, changing a booking, saying thanks. Answer straight away with minimal back and forth.
+
+## The enquiry workflow
+
+A new enquiry runs through five steps. Each one writes a vault record, and each write is validated before you move on.
+
+1. **Find or create the customer.** Look the sender up in `people/` (the `contacts` skill). If they are not there and this is a real enquiry, create the Person file first, with the name and whatever contact details you have. Everything else links to this file, so it has to exist before the links will resolve.
+2. **Record the enquiry.** Write a Note in `activities/` capturing what they want, linked to the customer with `about` and, if there is a job, to a Project with `project`. The Note body is the detail (what they asked for, when they are free, anything notable).
+3. **Book the slot.** When the enquiry needs an appointment, create the Event with the `scheduling` skill: an Event file in `calendar/` with the customer as an attendee. The vault Event is the source of truth; `scheduling` handles the calendar sync.
+4. **Send the confirmation.** Confirm the booking to the customer with the `email-composition` skill, or as a reply on whatever channel they used. The send is recorded as a vault Email linked to the customer, exactly as `email-composition` describes.
+5. **Leave a clean record.** After the steps above, the vault holds the customer, the enquiry Note, the booked Event, and the confirmation Email, all linked and all passing the validator. Run `maxy-lite-validate "$HOME/maxy"` and fix any named field until it exits 0. An enquiry that leaves no conformant record set is the failure this workflow exists to prevent.
+
+A worked example: the customer, the job, the enquiry, and the booked slot, the four files passing the validator together (the confirmation Email is the one the `email-composition` skill records). Every link resolves within the set, so the project links need the Project file present:
+
+```yaml
+# people/Jane Doe.md
+---
+type: person
+name: Jane Doe
+emails:
+  - jane@acme.example
+---
+
+# projects/Bathroom refit.md
+---
+type: project
+name: Bathroom refit
+area: work
+---
+
+# activities/Enquiry - Jane.md
+---
+type: note
+title: Enquiry - bathroom refit
+about: "[[Jane Doe]]"
+project: "[[Bathroom refit]]"
+area: work
+---
+Jane enquired about a full bathroom refit. Wants a survey then a quote. Mornings.
+
+# calendar/Bathroom survey - Jane.md
+---
+type: event
+summary: Bathroom survey - Jane Doe
+start: 2026-06-25T09:30:00
+end: 2026-06-25T10:00:00
+location: 42 Oak Lane, Stansted
+attendees:
+  - "[[Jane Doe]]"
+project: "[[Bathroom refit]]"
+status: CONFIRMED
+area: work
+---
+On-site survey ahead of quoting the refit.
+```
+
+## Quotes
+
+A quote is a number, and a number needs the owner's approval before it goes to a customer. Gather the scope, work out what you would quote, and put it to the owner. Once they approve, send the figure to the customer with the `email-composition` skill, and record what was quoted as a Note in `activities/`, linked to the customer with `about`, so the quote is part of the record. Do not generate an invoice or a signed document here; producing those is a separate skill.
+
+## Channels are reply only
+
+When a customer reaches you on a channel, reply on that channel; never send a cold first message to someone who has not contacted you. Cold outreach is not this skill's job and it puts the business's accounts at risk.
+
+## Escalating to the owner
+
+In a small business there is one owner, and that owner is the person you are talking to in this session. Escalating means surfacing the matter to them here, clearly and briefly, not routing it anywhere. There is no broadcast across channels.
+
+Always escalate, rather than deciding alone:
+
+- A price or any money decision the owner has not already approved.
+- A complaint or an unhappy customer.
+- A request outside the normal services, or a suspicious one.
+- An emergency that needs the owner's judgement.
+- A customer asking to speak to the owner directly. Never block that. Take their number and a good time, capture the context, and hand it over.
+
+Keep the escalation short. The owner is busy and reading on a phone.
+
+## Out of scope
+
+This skill stays inside the enquiry, booking, and quote workflow. It does not do:
+
+- **Sales pipeline objects** (deals, stages, a funnel). The store does not carry them yet; that is a separate, deferred part of the data model.
+- **Invoices, payments, and signed documents.** Invoice and payment records and document generation belong to other skills, not here.
+- **Industry specific scripts and overlays, voice or phone menus.** Out of scope.
+- **The public booking site and its captured leads.** Standing up a booking page and pulling its submissions into the vault is the `calendar-site` skill's job; this skill consumes the Events that land, it does not build the site.
+- **New tools.** Everything here is the contacts, scheduling, and email skills plus vault files.
+</content>

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": []
+  }
+}