@rubytech/create-maxy-lite 0.1.4 → 0.1.6

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 })
+}

package/payload/skills/calendar-site/template/public/booking.css

@@ -0,0 +1,100 @@
+/* Public booking page (calendar-site skill). Clean single-column Calendly-style
+   layout. Self-contained — no shared tokens, since this ships to Cloudflare
+   Pages, not the admin shell. The skill may overlay brand colors. */
+:root {
+  --bk-bg: #f6f6f4;
+  --bk-card: #ffffff;
+  --bk-ink: #1d1d1f;
+  --bk-muted: #6b6b70;
+  --bk-line: #e3e3e0;
+  --bk-accent: #4b6358;
+  --bk-accent-ink: #ffffff;
+  --bk-radius: 12px;
+}
+
+* { box-sizing: border-box; }
+
+body {
+  margin: 0;
+  background: var(--bk-bg);
+  color: var(--bk-ink);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  display: flex;
+  justify-content: center;
+  padding: 32px 16px;
+}
+
+.bk-card {
+  width: 100%;
+  max-width: 520px;
+  background: var(--bk-card);
+  border: 1px solid var(--bk-line);
+  border-radius: var(--bk-radius);
+  padding: 28px;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.05);
+}
+
+.bk-title { margin: 0 0 4px; font-size: 1.6rem; }
+.bk-sub { margin: 0 0 20px; color: var(--bk-muted); }
+.bk-status { margin: 8px 0; color: var(--bk-muted); }
+
+.bk-day { margin-bottom: 20px; }
+.bk-day-title { font-size: 0.95rem; margin: 0 0 8px; color: var(--bk-ink); }
+.bk-day-slots { display: flex; flex-wrap: wrap; gap: 8px; }
+
+.bk-slot {
+  border: 1px solid var(--bk-accent);
+  background: transparent;
+  color: var(--bk-accent);
+  border-radius: 8px;
+  padding: 8px 14px;
+  font-size: 0.9rem;
+  cursor: pointer;
+}
+.bk-slot:hover { background: var(--bk-accent); color: var(--bk-accent-ink); }
+
+.bk-form { display: flex; flex-direction: column; gap: 14px; }
+.bk-chosen { font-weight: 600; margin: 0 0 4px; }
+.bk-label { display: flex; flex-direction: column; gap: 4px; font-size: 0.85rem; color: var(--bk-muted); }
+.bk-input {
+  border: 1px solid var(--bk-line);
+  border-radius: 8px;
+  padding: 10px 12px;
+  font-size: 1rem;
+  color: var(--bk-ink);
+  font-family: inherit;
+}
+.bk-input:focus { outline: 2px solid var(--bk-accent); border-color: var(--bk-accent); }
+
+/* honeypot — visually and from the layout removed, still in the DOM for bots */
+.bk-hp {
+  position: absolute;
+  left: -9999px;
+  width: 1px;
+  height: 1px;
+  opacity: 0;
+}
+
+.bk-actions { display: flex; justify-content: space-between; gap: 12px; margin-top: 4px; }
+.bk-back {
+  background: transparent;
+  border: 1px solid var(--bk-line);
+  border-radius: 8px;
+  padding: 10px 16px;
+  cursor: pointer;
+  color: var(--bk-muted);
+}
+.bk-submit {
+  background: var(--bk-accent);
+  color: var(--bk-accent-ink);
+  border: none;
+  border-radius: 8px;
+  padding: 10px 20px;
+  font-size: 1rem;
+  cursor: pointer;
+}
+.bk-submit:disabled { opacity: 0.6; cursor: default; }
+
+.bk-done { text-align: center; padding: 16px 0; }
+.bk-done-title { margin: 0 0 8px; font-size: 1.3rem; }
+.bk-done-msg { color: var(--bk-muted); margin: 0; }

package/payload/skills/calendar-site/template/public/booking.js

@@ -0,0 +1,202 @@
+// Public booking page (calendar-site skill). Dependency-free.
+// 1. Fetch the static availability config shipped with the page.
+// 2. Compute open slots client-side: the weekly window minus a buffer, for the
+//    next two weeks. There is no live free/busy merge, so a slot can collide
+//    with an existing event; the device-side reconcile pass rejects a colliding
+//    booking when it pulls submissions into the vault.
+// 3. Let the visitor pick a slot, collect name/email/note, and POST to the
+//    same-origin Pages Function (/api/book -> D1).
+
+// Pure slot computation, exported for test and reused by the browser code below.
+// availability: { timezone, durationMins, bufferMins, weekly: { mon: [["09:00","17:00"]], ... } }
+// from: a Date marking "now". daysAhead: how many days forward to offer.
+// Returns [{ start, end }] as timezone-naive ISO strings (YYYY-MM-DDTHH:MM:00).
+function computeSlots(availability, from, daysAhead) {
+  var DAY_KEYS = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+  var durationMins = availability.durationMins;
+  var stepMins = availability.durationMins + availability.bufferMins;
+  var weekly = availability.weekly || {};
+  var out = [];
+
+  function pad(n) { return (n < 10 ? '0' : '') + n; }
+  function toMinutes(hhmm) {
+    var parts = hhmm.split(':');
+    return parseInt(parts[0], 10) * 60 + parseInt(parts[1], 10);
+  }
+  function naive(date, mins) {
+    var y = date.getFullYear();
+    var m = pad(date.getMonth() + 1);
+    var d = pad(date.getDate());
+    var hh = pad(Math.floor(mins / 60));
+    var mm = pad(mins % 60);
+    return y + '-' + m + '-' + d + 'T' + hh + ':' + mm + ':00';
+  }
+
+  for (var dayOffset = 0; dayOffset < daysAhead; dayOffset++) {
+    var day = new Date(from.getFullYear(), from.getMonth(), from.getDate() + dayOffset);
+    var windows = weekly[DAY_KEYS[day.getDay()]] || [];
+    for (var w = 0; w < windows.length; w++) {
+      var winStart = toMinutes(windows[w][0]);
+      var winEnd = toMinutes(windows[w][1]);
+      for (var t = winStart; t + durationMins <= winEnd; t += stepMins) {
+        var startStr = naive(day, t);
+        if (new Date(startStr) < from) continue; // drop past slots
+        out.push({ start: startStr, end: naive(day, t + durationMins) });
+      }
+    }
+  }
+  return out;
+}
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { computeSlots };
+}
+
+(function () {
+  'use strict';
+  if (typeof document === 'undefined') return; // running under Node for tests
+
+  var DAYS_AHEAD = 14;
+
+  var statusEl = document.getElementById('bk-status');
+  var slotsEl = document.getElementById('bk-slots');
+  var formEl = document.getElementById('bk-form');
+  var chosenEl = document.getElementById('bk-chosen');
+  var doneEl = document.getElementById('bk-done');
+  var doneMsg = document.getElementById('bk-done-msg');
+  var durationEl = document.getElementById('bk-duration');
+  var backBtn = document.getElementById('bk-back');
+
+  var chosenSlot = null;
+
+  function setStatus(msg) {
+    statusEl.textContent = msg || '';
+  }
+  function fmtDayHeading(d) {
+    return d.toLocaleDateString([], { weekday: 'long', month: 'long', day: 'numeric' });
+  }
+  function fmtTime(d) {
+    return d.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' });
+  }
+
+  function renderSlots(slots, durationMins) {
+    if (durationMins) {
+      durationEl.textContent = durationMins + ' minute meeting';
+    }
+    if (slots.length === 0) {
+      setStatus('No open times in the next two weeks. Please check back later.');
+      return;
+    }
+    setStatus('');
+
+    var byDay = {};
+    var order = [];
+    slots.forEach(function (s) {
+      var start = new Date(s.start);
+      var key = start.toDateString();
+      if (!byDay[key]) {
+        byDay[key] = [];
+        order.push(key);
+      }
+      byDay[key].push(s);
+    });
+
+    order.forEach(function (key) {
+      var group = document.createElement('div');
+      group.className = 'bk-day';
+      var h = document.createElement('h2');
+      h.className = 'bk-day-title';
+      h.textContent = fmtDayHeading(new Date(key));
+      group.appendChild(h);
+
+      var row = document.createElement('div');
+      row.className = 'bk-day-slots';
+      byDay[key].forEach(function (s) {
+        var btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = 'bk-slot';
+        btn.textContent = fmtTime(new Date(s.start));
+        btn.addEventListener('click', function () {
+          chooseSlot(s);
+        });
+        row.appendChild(btn);
+      });
+      group.appendChild(row);
+      slotsEl.appendChild(group);
+    });
+  }
+
+  function chooseSlot(slot) {
+    chosenSlot = slot;
+    var start = new Date(slot.start);
+    chosenEl.textContent = fmtDayHeading(start) + ' at ' + fmtTime(start);
+    slotsEl.hidden = true;
+    formEl.hidden = false;
+  }
+
+  backBtn.addEventListener('click', function () {
+    chosenSlot = null;
+    formEl.hidden = true;
+    slotsEl.hidden = false;
+  });
+
+  formEl.addEventListener('submit', function (e) {
+    e.preventDefault();
+    if (!chosenSlot) return;
+    var fd = new FormData(formEl);
+    var payload = {
+      slotStart: chosenSlot.start,
+      slotEnd: chosenSlot.end,
+      name: fd.get('name'),
+      email: fd.get('email'),
+      note: fd.get('note'),
+      company: fd.get('company'),
+    };
+    var submitBtn = formEl.querySelector('.bk-submit');
+    submitBtn.disabled = true;
+    submitBtn.textContent = 'Booking…';
+
+    fetch('/api/book', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    })
+      .then(function (res) {
+        return res.json().then(function (body) {
+          return { ok: res.ok, body: body };
+        });
+      })
+      .then(function (r) {
+        if (!r.ok || !r.body.ok) {
+          throw new Error((r.body && r.body.error) || 'Booking failed');
+        }
+        formEl.hidden = true;
+        doneEl.hidden = false;
+        var start = new Date(chosenSlot.start);
+        doneMsg.textContent = 'Confirmed for ' + fmtDayHeading(start) + ' at ' + fmtTime(start) + '. A confirmation will follow by email.';
+      })
+      .catch(function (err) {
+        submitBtn.disabled = false;
+        submitBtn.textContent = 'Confirm booking';
+        setStatus('Sorry, that did not go through: ' + err.message + '. Please try again.');
+      });
+  });
+
+  function load() {
+    setStatus('Loading available times…');
+    fetch('/availability.json')
+      .then(function (res) {
+        if (!res.ok) throw new Error('HTTP ' + res.status);
+        return res.json();
+      })
+      .then(function (availability) {
+        var slots = computeSlots(availability, new Date(), DAYS_AHEAD);
+        renderSlots(slots, availability.durationMins);
+      })
+      .catch(function () {
+        setStatus('Could not load available times right now. Please refresh in a moment.');
+      });
+  }
+
+  load();
+})();

package/payload/skills/calendar-site/template/public/index.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Book a time</title>
+  <link rel="stylesheet" href="/booking.css" />
+</head>
+<body>
+  <main class="bk-card">
+    <h1 class="bk-title">Book a time</h1>
+    <p class="bk-sub" id="bk-duration"></p>
+
+    <div id="bk-status" class="bk-status" role="status"></div>
+
+    <section id="bk-slots" class="bk-slots" aria-label="Available times"></section>
+
+    <form id="bk-form" class="bk-form" hidden>
+      <p class="bk-chosen" id="bk-chosen"></p>
+      <label class="bk-label">Name
+        <input class="bk-input" type="text" name="name" required autocomplete="name" />
+      </label>
+      <label class="bk-label">Email
+        <input class="bk-input" type="email" name="email" required autocomplete="email" />
+      </label>
+      <label class="bk-label">Note (optional)
+        <textarea class="bk-input" name="note" rows="3"></textarea>
+      </label>
+      <!-- honeypot: hidden from people, tempting to bots -->
+      <input class="bk-hp" type="text" name="company" tabindex="-1" autocomplete="off" aria-hidden="true" />
+      <div class="bk-actions">
+        <button class="bk-back" type="button" id="bk-back">Back</button>
+        <button class="bk-submit" type="submit">Confirm booking</button>
+      </div>
+    </form>
+
+    <div id="bk-done" class="bk-done" hidden>
+      <h2 class="bk-done-title">You are booked</h2>
+      <p id="bk-done-msg" class="bk-done-msg"></p>
+    </div>
+  </main>
+  <script src="/booking.js"></script>
+</body>
+</html>

package/payload/skills/calendar-site/template/schema.sql

@@ -0,0 +1,19 @@
+-- D1 schema for the booking site (calendar-site skill).
+-- One row per public booking submission. Captured at the edge so a submission
+-- survives while the device is offline or asleep; the calendar-site reconcile
+-- pass later reads accepted, unswept rows and writes each into the vault as an
+-- Event (then marks the row swept).
+CREATE TABLE IF NOT EXISTS bookings (
+  id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  bookingId TEXT UNIQUE NOT NULL,
+  slotStart TEXT NOT NULL,
+  slotEnd   TEXT NOT NULL,
+  name      TEXT NOT NULL,
+  email     TEXT NOT NULL,
+  note      TEXT,
+  status    TEXT NOT NULL DEFAULT 'accepted',
+  createdAt TEXT NOT NULL,
+  swept     INTEGER NOT NULL DEFAULT 0
+);
+
+CREATE INDEX IF NOT EXISTS bookings_unswept ON bookings (status, swept);

package/payload/skills/calendar-site/template/wrangler.toml

@@ -0,0 +1,14 @@
+# Cloudflare Pages config for the booking site (calendar-site skill).
+# The skill fills the placeholders at assemble time:
+#   __PROJECT_NAME__     the Pages project name
+#   __D1_DATABASE_NAME__ the D1 database name
+#   __D1_DATABASE_ID__   the id printed by `wrangler d1 create`
+name = "__PROJECT_NAME__"
+pages_build_output_dir = "public"
+compatibility_date = "2024-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+[[d1_databases]]
+binding = "DB"
+database_name = "__D1_DATABASE_NAME__"
+database_id = "__D1_DATABASE_ID__"

package/payload/skills/contacts/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: contacts
+description: Create, look up, and update people and organizations in the vault. Use when the user mentions a person or company to remember, asks who someone is, wants a contact's email or phone, links someone to where they work, or asks to update a contact's details. Owns the Person and Organization entities of the maxy-lite SCHEMA.
+---
+
+# Contacts
+
+The address book lives in the vault as one markdown file per contact. A **Person** is a file in `people/`; an **Organization** is a file in `organizations/`. Each file is YAML frontmatter (the typed fields) plus a markdown body for free notes about the contact. The authoritative field list is [`SCHEMA.md`](../../schema/SCHEMA.md) under *Contacts*. Read it before writing fields you are unsure of; the validator parses the same tables.
+
+## Person (`people/<Full Name>.md`)
+
+Required: `type: person` and `name` (the full display name). Optional, all from vCard: `firstName`, `lastName`, `nickname`, `emails` (a list), `tels` (a list), `title`, `role`, `address`, `birthday` (`YYYY-MM-DD`), `anniversary`, `urls` (a list), `categories` (a list), `area`. Set only the fields you actually know; do not invent values to fill a field.
+
+```yaml
+---
+type: person
+name: Jane Doe
+firstName: Jane
+lastName: Doe
+emails:
+  - jane@acme.example
+tels:
+  - "+44 7700 900000"
+org: "[[Acme Ltd]]"
+title: Head of Design
+area: work
+---
+Met at the London conference. Prefers email over phone.
+```
+
+## Organization (`organizations/<Name>.md`)
+
+Required: `type: organization` and `name`. Optional: `domain`, `website`, `industry`, `companyType`, `employees` (number), `revenue` (number), `phone`, `city`, `state`, `country`, `area`.
+
+## Linking a person to where they work
+
+A Person's `org` field is a single link to an Organization file; an Organization's `members` field is a list of links to Person files. A link is the target's basename in wikilink form, e.g. `org: "[[Acme Ltd]]"`. The Organization file must already exist, or the link dangles and fails. When you link a person to an organization that is not in the vault yet, create the Organization file first, then set `org`.
+
+## Looking someone up
+
+The vault is the index. To find a contact, Grep the frontmatter, not your memory:
+
+- by name: `grep -rl "name: Jane" people/`
+- by email: `grep -rl "jane@acme.example" people/`
+- everyone at a company: `grep -rl "\[\[Acme Ltd\]\]" people/` (people whose `org` points at it)
+
+Read the matched file for the full record, and follow its `org` link to the organization. Keep each filename unique: the validator resolves links by basename, so two `Jane Doe.md` files in different folders cannot be told apart.
+
+## After every write, validate
+
+The SCHEMA is enforced by a deterministic validator, not by convention. After creating or editing any contact file, run it over the vault:
+
+```sh
+maxy-lite-validate "$HOME/maxy"
+```
+
+It prints one `[lite-schema] op=validate ... ok=<bool>` line per file and exits 0 only when every file conforms. If a line names the file you just wrote with `ok=false`, the bracketed error names the violation: `name:missing` (a required field is absent), `field:type` (wrong value type), `area:area` (an area outside the controlled vocabulary), `org:dangling` (the linked organization file does not exist), `org:target` (the link points at a file of the wrong type). Fix the named field and re-run until that file is `ok=true`. Never leave a contact you wrote in a failing state.

package/payload/skills/deep-research/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: deep-research
+description: >
+  Use when the owner asks to research a topic, find current information, compare
+  options, review literature, fact-check a claim, or answer any question that
+  benefits from live web sources. Trigger phrases: "research", "find out",
+  "what's the latest on", "compare X and Y", "who is", "look into", "fact-check",
+  "deep dive", "what do we know about", "literature review", or any question
+  where stored knowledge may be stale or insufficient. Runs over native web
+  search and the url-get skill, and saves the result as a vault Note.
+---
+
+# deep-research
+
+Answer questions using live web sources. Search, read, extract, and cite. Do not guess. Synthesise across sources and present the result with full attribution, then save it to the vault.
+
+This runs over the native `WebSearch` and `WebFetch` tools and the `[[url-get]]` skill for full-page fetches. No external API key is needed.
+
+## Config
+
+```yaml
+citation_style: "inline"   # inline | footnotes | cards | minimal
+max_sources: 8             # sources to synthesise per query (4-12 recommended)
+search_depth: "standard"   # standard (3-5 searches) | deep (6-12 searches)
+show_confidence: true      # append a High / Medium / Low confidence note
+follow_up_questions: true  # suggest 3 follow-up questions
+```
+
+## Workflow
+
+**Phase 1, Decompose.** Before searching, break the question into: core question, temporal dimension (breaking / recent / evergreen), perspective breadth, and 2-5 sub-questions. State the decomposition in 1-3 lines, then proceed without asking permission. Read `references/research-modes.md` and select the research mode.
+
+**Phase 2, Search.** Map sub-questions to targeted search queries via `WebSearch`. Read `references/search-strategy.md` for query crafting and source evaluation.
+
+**Phase 3, Fetch and extract.** For each source, fetch the full page (`WebFetch`, or `[[url-get]]` for verbatim markdown), extract only what is relevant to the sub-question, and note publication dates. See `references/search-strategy.md` for the source-quality hierarchy and staleness rules.
+
+**Phase 4, Synthesise.** Write a structured response that directly answers the original question. Read `references/citation-styles.md` and apply the style from `config.citation_style`.
+
+**Phase 5, Confidence.** If `show_confidence: true`, append a confidence assessment. See `references/citation-styles.md` for the High / Medium / Low criteria.
+
+**Phase 6, Follow-ups.** If `follow_up_questions: true`, suggest 3 genuinely useful next questions. See `references/citation-styles.md`.
+
+**Phase 7, Persist.** Save the report to the vault as a Note so it is kept and searchable. Write one markdown file under the vault with frontmatter and the report in the body:
+
+```markdown
+---
+type: note
+title: <the research question>
+area: <an Areas value, if the topic fits one>
+---
+
+<the synthesised report, with citations inline>
+```
+
+`type` and `title` are required; `area` is optional and must be a value from the schema's Areas vocabulary. The report prose lives in the body, not in frontmatter. After writing, validate the vault and confirm it passes:
+
+```bash
+node ~/.maxy-lite/validator/cli.mjs ~/.maxy-lite/vault
+```
+
+Expect `invalid=0` and exit 0. If the Note fails validation, fix the frontmatter and re-run before telling the owner it is saved.
+
+## Hard rules
+
+1. **Never fabricate citations.** If you cannot find a source for a claim, say so explicitly.
+2. **Never quote more than 15 words verbatim** from any single source.
+3. **One direct quote per source maximum.** Paraphrase everything else.
+4. **Do not recite stored knowledge as search results.** If relying on prior knowledge, say "(from prior knowledge, not verified live)".
+5. **Stale is worse than honest.** If you cannot find current information, state the most recent date you found and invite the owner to check for updates.
+6. **No padding.** Every sentence must carry information. No filler, no generic caveats, no restated conclusions.

package/payload/skills/deep-research/references/citation-styles.md

@@ -0,0 +1,52 @@
+# Citation Styles, Confidence, and Follow-ups
+
+## Citation Styles (Phase 4)
+
+Apply the style set in `config.citation_style`:
+
+### inline (default)
+> The company raised $120M in Series B funding [1], led by Andreessen Horowitz [2].
+> Sources: [1] techcrunch.com/... [2] a16z.com/...
+
+### footnotes
+> Prose with no inline markers. Full source list at end:
+> ---
+> **Sources**
+> 1. Title. domain.com/path (Date if known)
+> 2. Title. domain.com/path
+
+### cards
+> Each source rendered as a mini card:
+> ┌─────────────────────────────────────────┐
+> │ [1] Title of article                    │
+> │ Source: domain.com · Date: YYYY-MM-DD   │
+> │ Relevant finding: one-line summary      │
+> └─────────────────────────────────────────┘
+
+### minimal
+> The company raised $120M (techcrunch.com/...), led by a16z (a16z.com/...).
+
+## Confidence Assessment (Phase 5)
+
+If `show_confidence: true`, append a brief confidence assessment after the main answer:
+
+**Confidence: High / Medium / Low**
+- High: multiple independent sources agree, sources are recent and authoritative
+- Medium: sources partially agree, or primary sources are thin
+- Low: limited sources, conflicting information, or significant recency gaps
+
+Always flag explicitly if:
+- A key sub-question could not be answered from available sources
+- Important information may exist behind paywalls or login walls
+- The topic is moving fast and this answer may be stale within days/weeks
+
+## Follow-up Questions (Phase 6)
+
+If `follow_up_questions: true`, end with:
+
+**You might also want to ask:**
+1. [Specific follow-up question 1]
+2. [Specific follow-up question 2]
+3. [Specific follow-up question 3]
+
+Make these genuinely useful: the next natural step in the research, not generic variations of the original question.