@rubytech/create-maxy-lite 0.1.5 → 0.1.6

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/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.

package/payload/skills/deep-research/references/research-modes.md

@@ -0,0 +1,22 @@
+# Research Modes
+
+Adjust behaviour based on query type. Select the appropriate mode after Phase 1 decomposition.
+
+## General Research / Fact-finding
+
+- 3–5 sources is usually sufficient
+- Prioritise recency and source authority
+- Lead with the direct answer, then supporting evidence
+
+## Competitive / Market Intelligence
+
+- Always cover: (a) the company's own claims, (b) independent analyst or press coverage, (c) user sentiment (G2, Reddit, Trustpilot where relevant)
+- Structure output as: Overview, Key differentiators, Weaknesses/risks, Pricing (if findable), Verdict
+- Flag if pricing is not publicly listed
+
+## Academic / Deep Literature Review
+
+- Prioritise peer-reviewed sources, preprints (arXiv, bioRxiv), and institutional reports
+- Note study size, methodology, and date for each source
+- Distinguish between consensus findings and contested/emerging claims
+- Use deep search depth. Do not stop at 3 sources for academic queries

package/payload/skills/deep-research/references/search-strategy.md

@@ -0,0 +1,24 @@
+# Search Strategy and Source Evaluation
+
+## Query Crafting (Phase 2)
+
+Map each sub-question to one or more targeted search queries:
+
+- Keep queries short (3–6 words). Specific nouns beat vague phrases.
+- Vary query framing: try the direct question, a "site:domain" form, and a comparison form where relevant.
+- For competitive intelligence: always search the target company directly AND search for independent reviews/comparisons.
+- For literature/academic queries: search for primary papers, then for secondary summaries.
+- For fast-changing topics (pricing, funding, personnel): append the current year to queries.
+- Never repeat the same query twice. If a search returns poor results, rephrase. Do not retry identical terms.
+
+## Source Fetching and Extraction (Phase 3)
+
+For each source returned:
+
+1. Fetch the full page content where possible, not just the snippet.
+2. Extract only what is relevant to the sub-question that drove this search.
+3. Note the publication date if visible.
+4. Flag sources older than 18 months as `[possibly outdated]`.
+5. Prefer: official docs, primary research, reputable press. Deprioritise: forums, SEO farms, undated pages.
+
+Do not quote large blocks verbatim. Paraphrase and extract the key claim or data point.

package/payload/skills/docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: docs
+description: >
+  Reference documentation for how maxy-lite works, loaded on demand. Use when the
+  owner asks how the assistant works, what it can do, where their files are, how
+  to get started, or for help. Trigger phrases: "how does this work", "what can
+  you do", "where are my files", "help", "getting started", "explain maxy",
+  "how is my data stored".
+---
+
+# docs
+
+A small set of reference documents describing how maxy-lite works. Do not load them all. Read the one that answers the owner's question with the `Read` tool, then answer from it.
+
+## References
+
+- **`references/getting-started.md`** Read this for a new owner, or for "how do I use this", "what can you do" at a high level, "help", or general orientation. Plain-language, owner-facing.
+- **`references/capability-map.md`** Read this for "what can you do" in detail, "what tools do you have", "can you do X", or to understand which capabilities exist and in what form.
+- **`references/vault-model.md`** Read this for "where is my data", "how is it stored", "what is the vault", anything about file layout, entity types, areas, links, or the validator. The technical model of the store.
+
+## Boundaries
+
+These references describe lite's own reality: a single assistant, a file-native vault, on one device. They are not the platform documentation for the larger graph-backed product. For the exact field-by-field schema, point to `schema/SCHEMA.md` rather than restating it.

package/payload/skills/docs/references/capability-map.md

@@ -0,0 +1,25 @@
+# What maxy-lite can do
+
+maxy-lite is a single assistant that organises a person's files and helps with everyday tasks, all on their own device. Its capabilities take one of a few forms, chosen to keep the device light.
+
+## The forms
+
+- **Native file operations.** Reading, writing, and editing vault files directly. This covers all store work: contacts, notes, tasks, projects, events, and the filed documents and assets. No tool or process is involved.
+- **Skills with small scripts.** A skill is instructions the assistant reads; some come with a small script run on demand. This is the default for anything that fetches a page, calls a service, or runs a one-off job. Skills are files, so they add no running process.
+- **Official connectors.** Off-the-shelf remote services configured rather than built: Google (Gmail, Calendar, Drive) and Cloudflare.
+- **Channel servers.** The one kind of long-lived process: the messaging channels (Telegram, WhatsApp) that must listen for incoming messages.
+
+## What it can do today
+
+- **Store work** over the vault: keep contacts, notes, tasks, projects, a calendar, and filed documents, all as plain files.
+- **Fetch a web page** faithfully as markdown (the `url-get` skill).
+- **Research a topic** across live web sources and save a cited report to the vault (the `deep-research` skill).
+- **Generate an image** from a prompt (the `replicate` skill).
+- **Drive the browser** for the things plain HTTP cannot do: render a JavaScript page, turn HTML into a PDF, take a screenshot (the `browser` skill).
+- **Answer time and date questions** deterministically (the `datetime` skill).
+- **Manage sessions** start a new one, resume a past one, recall what a past one was about (the `session-management` skill).
+- **Upgrade itself** by re-running the installer (the `upgrade` skill).
+
+## What it deliberately does not have
+
+No graph database, no per-account separation, no specialist sub-agents, no public-facing agents. One assistant, one file tree, one device. Capabilities that exist only to serve those platform features are not part of lite.

package/payload/skills/docs/references/getting-started.md

@@ -0,0 +1,29 @@
+# Getting started with maxy-lite
+
+A short orientation for a new owner.
+
+## What it is
+
+maxy-lite is a personal assistant that runs entirely on your own device. It keeps your information as ordinary files and helps you with everyday tasks. One assistant does everything; there is nothing to log into and nothing leaves your phone unless you ask it to.
+
+## Where your files live
+
+Everything is stored as plain markdown files in your vault (by default `~/.maxy-lite/vault`). Each file is one thing: a contact, a note, a task, an event, a bill. You can open and edit the same files in Obsidian on your phone, so you are never locked out of your own data.
+
+## How to use it
+
+Just ask in plain language. The assistant picks the right tool for the job.
+
+- **Keep things organised:** "add Jane Smith to my contacts", "make a note about the boiler service", "remind me to renew the car insurance", "what's on my calendar next week".
+- **Research:** "what's the latest on X", "compare these two options", "look into this and save me a summary". It searches the web, reads the sources, and saves a cited note to your vault.
+- **Read a web page:** give it a link and ask what it says.
+- **Make an image:** "generate a logo for my side project", "make a picture of a mountain lake".
+- **Build a document or page:** ask for a deck, a brochure, or a simple website, and it turns the result into a PDF or publishes it.
+
+## Sessions
+
+Each conversation is one session, saved as a transcript file. You can start fresh any time, or ask the assistant to pick up where you left off. Before you clear a conversation, ask it to save anything important to the vault, since a new session only remembers what is written to files.
+
+## Keeping it current
+
+Ask the assistant to upgrade when you want the latest version. It re-runs the installer and the new version takes effect on your next session.

package/payload/skills/docs/references/vault-model.md

@@ -0,0 +1,40 @@
+# The vault model
+
+maxy-lite stores everything as plain markdown files in one folder tree, the vault. There is no database. Each file is one record: YAML frontmatter holds the structured fields, the markdown body holds the prose. This is the same substrate Obsidian reads, so the owner can browse and edit the same files on their phone.
+
+## Two organising dimensions
+
+- **`type`** (a frontmatter field) says what kind of record a file is. It drives which fields the validator checks. It does not depend on the folder.
+- **Area** says which part of life the record belongs to. It drives where the file is filed. The areas are a fixed list: `home`, `work`, `finance`, `health`, `vehicle`, `insurance`, `travel`, `education`, `family`, `legal`, `personal`.
+
+Every document, asset, and project must declare an `area`. Contacts, events, and activities may.
+
+## Layout
+
+- **Global folders** (cross-area): `people/`, `organizations/`, `calendar/`, `activities/`. These are the address book and calendar.
+- **Area folders** (the filing cabinet): one folder per area, holding typed documents and assets.
+- **`projects/`** holds projects.
+
+## Entity families
+
+- **Contacts and orgs:** Person (vCard fields), Organization.
+- **Time:** Event (iCalendar fields).
+- **Work:** Task, Project.
+- **Activity:** Note, Email, Call, Meeting. The long-form content (note body, email text, call notes) lives in the markdown body, not in a field.
+- **Assets:** Property, Vehicle, Account.
+- **Financial records:** Invoice, Expense, Bill, Statement, Payment.
+- **Life documents:** Policy, Contract, Warranty, TaxDocument, IdentityDocument.
+
+The full field-by-field declaration is `schema/SCHEMA.md`. Read that for the exact required and optional fields of each entity. Do not duplicate it here.
+
+## Links
+
+A field whose value is `"[[Target]]"` (or a bare filename) is an association to another file, resolved by basename. Keep filenames unique across folders so links resolve unambiguously.
+
+## The validator
+
+`validator/cli.mjs` checks a vault against `SCHEMA.md` with no model in the path. It flags missing required fields, wrong field types, bad area values, and links that resolve to no file or to the wrong entity type. A data skill writes vault files, then runs the validator and expects `invalid=0`, exit 0. A non-zero exit means a file violates the schema; fix it before claiming the data is saved.
+
+```bash
+node ~/.maxy-lite/validator/cli.mjs ~/.maxy-lite/vault
+```

package/payload/skills/email-composition/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: email-composition
+description: Draft and send email, and keep a record of what was sent in the vault. Use when the user asks to reply to a message, write a new email, follow up on a thread, or triage what is outstanding in the inbox (for example "reply to Sarah about the lease", "email Jane the quote", "what needs dealing with in my inbox"). Every send is approved by the user first, and every sent message is recorded as a vault Email associated to the person it went to.
+---
+
+# Email composition
+
+A conversational wrapper around the Gmail connector. Drafting, replying, follow-ups, triage, and recording the result. Human in the loop only: every send is approved by the user before it goes. There is no drip sequence, no scheduled send, no broadcast, and no automatic categorisation.
+
+Two things make this skill more than a thin wrapper: the user approves before anything leaves, and after a send the message is written back into the vault as an Email so the correspondence is part of the store, not lost in the provider. The Email entity is in [`SCHEMA.md`](../../schema/SCHEMA.md) under *Activities*.
+
+## Transport: the Gmail connector
+
+Outbound mail goes through the **Gmail connector** (the official Google remote MCP added on the device). Use whichever send, draft, and read tools that connector exposes; this skill names them by capability, not by a fixed tool name, because the connector is configured on the device and its tool surface belongs to the provider.
+
+If the Gmail connector is not connected yet, do the whole draft and approval flow, then tell the user the message is ready but the Gmail connector still needs connecting before it can be sent, and stop. Do not invent a send. Connecting the connector is the connectors setup, not this skill.
+
+## When to use
+
+- **Reply to a thread.** "Reply to Sarah's email about the lease."
+- **New outbound email.** "Email Jane the quote." "Send the team a note about Friday."
+- **Follow up.** "Follow up with everyone from yesterday."
+- **Triage.** "What's outstanding in my inbox?"
+
+Do not use it for listing or searching email as the end goal (a read tool answers that directly), or for any automated send loop. If the user asks for drip, scheduled, or broadcast sending, decline and say this skill is human in the loop only.
+
+## Who it is going to: resolve the person first
+
+The recorded Email links to the recipient with a `participants` link, and that link fails validation if the person's file does not exist. So settle the recipient before sending:
+
+- Find the contact by Grepping `people/` for the name or address, exactly as the `contacts` skill describes (`grep -rl "jane@acme.example" people/`).
+- If the recipient is not in the vault yet, create the Person file first (via the `contacts` skill) so the link will resolve when you record the send.
+
+## Flow: reply to a thread
+
+1. **Find the thread.** Use the connector's read or search tool to pull the message and its parents. If several threads match the user's description, show three to five candidates with sender, subject, and date, and ask which one. Never guess. If nothing matches, ask the user to refine rather than inventing a thread.
+2. **Read the context.** Reply to the actual question in the latest message, not a one line summary. If the thread has attachments the reply refers to, name them and ask whether to forward.
+3. **Skip the ones that should be skipped.** An out of office autoreply, an unsubscribe or list message: do not draft. Flag it to the user and move on. A hostile or grief toned message: draft carefully and say so in the presentation, so the user reviews it closely before sending.
+4. **Draft.** Keep it tight. Anchor to the specific question, and to any decision the user has already stated in this conversation. Default to a neutral, polite British business register unless the user has asked for another tone.
+5. **Present.** Show the draft with the recipient, the subject, the body, and any flags from step 3. Do not send at this point. The send is not approved yet.
+6. **Edit loop.** The user approves ("send it"), edits verbally ("make it shorter", "say yes to the price, not the timeline"), or abandons. Apply edits and re present until they approve or abandon.
+7. **Send, on explicit approval.** Call the connector's reply or send tool so the message threads correctly. If it errors, show the error as is and let the user decide whether to fix and retry or abandon. Do not retry silently.
+8. **Record the send.** See "Record every send" below. This is not optional.
+
+## Flow: new outbound email
+
+The same as a reply, with two differences: there is no thread to load, so ask the user for the recipient, the topic, and any constraints; and you send a fresh message rather than a reply. If the user names a group ("email the team") rather than one person, ask which addresses to include; list candidates you can resolve from `people/`, and do not invent recipients.
+
+## Flow: leave it in drafts
+
+When the user wants a reviewable, unsent message ("draft it", "leave it in drafts", "don't send yet"), run the same present and edit loop, but save the approved draft through the connector's draft tool instead of sending. Nothing is dispatched. A saved draft is not a send, so it is not recorded as a vault Email until it is actually sent.
+
+## Flow: triage
+
+When the user asks what is outstanding, read the last several unread messages and return a one line summary of each with a recommended action: reply, file, or ignore (autoreplies, newsletters, and list mail are ignore). Then wait. Triage never auto drafts; when the user picks one, drop into the reply flow for that message.
+
+## Record every send
+
+After the connector confirms a send, write the message into the vault as an Email so the correspondence is part of the store. Without this step the send leaves no trace in the vault, which is lost provenance and the main failure this skill exists to prevent.
+
+Write `activities/<subject>.md`:
+
+```yaml
+---
+type: email
+subject: Quote for the bathroom refit
+timestamp: 2026-06-21T14:00:00
+direction: outgoing
+participants:
+  - "[[Jane Doe]]"
+area: work
+---
+Hi Jane, here is the quote we discussed.
+```
+
+Required is `type: email` and `subject`. `timestamp` is the time of the send; `direction` is `outgoing` for a message you sent (use `incoming` if you are recording one that arrived). `participants` is a list of links to the people on the message, each of whom must already have a Person file. Optionally, `about` links the email to whatever it concerns (a project, a contact, anything), in which case that target file must already exist, and `area` files it under one life area. The body of the file is the email text. The field list is in [`SCHEMA.md`](../../schema/SCHEMA.md).
+
+Then validate:
+
+```sh
+maxy-lite-validate "$HOME/maxy"
+```
+
+It exits 0 only when every file conforms. If the Email you just wrote is `ok=false`, the bracketed error names the field: `subject:missing` (the required subject is absent), `participants:dangling` (a linked person has no file, so create it), `participants:target` (a link points at a non person file), `area:area` (an area outside the controlled vocabulary). Fix the named field and re run until it is `ok=true`. Never leave a sent message unrecorded or a recorded Email in a failing state.
+
+## Edge cases
+
+| Situation | What to do |
+|-----------|------------|
+| Several threads match the description | Show three to five candidates and ask. Never guess. |
+| Recipient not in the vault yet | Create the Person file first, then send and record, so the link resolves. |
+| Original thread has people in cc | Reply to the sender only by default. Ask before copying others. |
+| Inbound is an out of office or list message | Do not draft. Flag it and move on. |
+| Inbound is hostile or grief toned | Draft carefully and flag the tone. The user reviews before sending. |
+| The connector returns an error after approval | Show the error as is. The user decides whether to fix and retry or abandon. No silent retry. |
+| The Gmail connector is not connected | Draft and present, then say the connector needs connecting before the send. Do not fake a send. |
+
+## Out of scope
+
+Never offer these here, even if asked:
+
+- **Drip sequences** and any multi step automated send chain.
+- **Scheduled or delayed sends.** The user triggers the send when they approve.
+- **List broadcasts** to managed subscriber lists.
+- **Automatic inbox labelling or categorisation.** Triage is on demand only.
+- **New tools.** This skill orchestrates the Gmail connector and writes vault files. Nothing else.
+</content>