@rubytech/create-maxy-lite 0.1.4 → 0.1.6

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>

package/payload/skills/memory/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: memory
+description: Remember and recall facts across sessions. Use when the user says to remember something, asks what you know about a person or topic, refers to something told to you earlier, or when you need to recover context at the start of a session. The vault is the memory; this skill is the convention for writing facts into it and reading them back.
+---
+
+# Memory
+
+There is no separate memory store. The vault is the memory: every fact you need to keep lives as frontmatter or body text in a vault file, and recall is reading those files back. This skill is thin on purpose. It codifies two things: where a fact goes when you learn it, and how to find a fact when you need it. The entity field lists are in [`SCHEMA.md`](../../schema/SCHEMA.md); the `contacts`, `work`, and `projects` skills own their respective writes.
+
+## Where a new fact goes
+
+A fact almost always belongs to something that already has a file. Put it there, not in a parallel store:
+
+- A fact **about a person or organization** (a preference, a relationship, a detail) goes in the body of that contact's file, or as a typed field if the SCHEMA has one for it (a new email goes in `emails`, a birthday in `birthday`). Edit the existing file.
+- A fact that **is** a thing the SCHEMA already models (a task to do, an event, a document) is created with the matching skill, not written as loose memory.
+- A standalone fact that belongs to **no existing entity** becomes a **Note**: a file in `activities/` with `type: note`, a `title`, and the fact in the markdown body. Link it to whatever it concerns with `about` so it is reachable by traversal.
+
+```yaml
+---
+type: note
+title: Jane wine preference
+about: "[[Jane Doe]]"
+area: personal
+---
+Jane prefers Rioja. Mentioned at the conference dinner.
+```
+
+Prefer enriching an existing file over creating a new note. A note is for a fact with no better home.
+
+## How to recall
+
+Recall is search over the vault, in this order:
+
+1. **Grep the frontmatter and body** for the term: `grep -rl "Rioja" .` finds every file mentioning it; `grep -rl "name: Jane" people/` finds the contact.
+2. **Read the matched file** for the full record.
+3. **Follow the links** to pull in connected context: a note's `about`, a person's `org`, a task's `project`. Traversal is following basenames between files.
+
+At the start of a session with no context, recall is the same move: Grep for the names or topics the user raises, read what comes back, and follow the links. Nothing is remembered that is not in a file, so if a fact is not found by Grep it was never written; write it.
+
+## After writing a fact, validate
+
+When a fact is written as a new note or by editing an entity file, run the deterministic validator over the vault:
+
+```sh
+maxy-lite-validate "$HOME/maxy"
+```
+
+It exits 0 only when every file conforms. If a line names the note you just wrote with `ok=false`, the bracketed error names the violation: `title:missing` (a note needs a title), `area:area` (an area outside the controlled vocabulary), `about:dangling` (the linked file does not exist). Fix the named field and re-run until that file is `ok=true`. A fact left in a failing file is a fact that will not be trusted on recall.

package/payload/skills/projects/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: projects
+description: Create and track multi-step efforts in the vault and tie tasks, events, and documents to them. Use when the user describes something with several moving parts (a holiday, a house move, a renovation, a launch), asks to start a project, wants to see everything related to one, or wants to file a task or event under a project. Owns the Project entity of the maxy-lite SCHEMA.
+---
+
+# Projects
+
+A **Project** is a multi-step effort that ties together the tasks, events, and documents it involves. It is one file in `projects/`: YAML frontmatter plus a markdown body for the plan, status notes, and links. The authoritative field list is [`SCHEMA.md`](../../schema/SCHEMA.md) under *Projects*.
+
+## Project (`projects/<Name>.md`)
+
+Required: `type: project`, `name`, and `area` (one of the controlled areas in the SCHEMA). Optional: `status` (`active` / `done` / `someday`), `startDate`, `dueDate` (`YYYY-MM-DD`), `about` (a single link to anything the project centres on). `area` is required for a project, unlike for a contact or task, so always set it.
+
+```yaml
+---
+type: project
+name: House Move
+area: home
+status: active
+startDate: 2026-06-01
+dueDate: 2026-09-30
+---
+Moving from the London flat to the house in Bristol. Survey, mortgage, packers, schools.
+```
+
+## Tying tasks and events to a project
+
+A project does not list its members in its own frontmatter. Instead each Task or Event carries a `project` link back to the project. To file an item under a project, edit the item and set its `project` field to the project's basename in wikilink form, e.g. in a task file `project: "[[House Move]]"`. The project file must exist first. The `work` skill owns the Task fields; this skill owns the Project file.
+
+## Seeing everything in a project
+
+The links point inward, so Grep for the project's name across the activity and calendar folders:
+
+- tasks in a project: `grep -rl "\[\[House Move\]\]" activities/`
+- events in a project: `grep -rl "\[\[House Move\]\]" calendar/`
+
+Read the matched files for the detail. To close a project, edit its `status` to `done`; do not delete the file.
+
+## After every write, validate
+
+After creating or editing a project file (or after setting a `project` link on a task or event), run the deterministic validator over the vault:
+
+```sh
+maxy-lite-validate "$HOME/maxy"
+```
+
+It exits 0 only when every file conforms. If a line names the project you just wrote with `ok=false`, the bracketed error names the violation: `name:missing` or `area:missing` (a required field is absent), `area:area` (an area outside the controlled vocabulary), `about:dangling` (the linked file does not exist), `startDate:type` or `dueDate:type` (a malformed date). Fix the named field and re-run until that file is `ok=true`. Never leave a project you wrote in a failing state.

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

@@ -0,0 +1,21 @@
+---
+name: publish-site
+description: Put a built site or page online and hand back a live link. Use when the user says publish, host, put this online, make it live, or share a link to a deck or page. Routes to `site-deploy`, which deploys to Cloudflare Pages so the page stays up with the phone offline.
+---
+
+# Publish a site
+
+This is the intent router for "make it live". When the user wants a page online, you confirm what to publish and where the files are, then hand off to [`site-deploy`](../site-deploy/SKILL.md), which does the actual Cloudflare Pages deploy and returns the URL.
+
+## What you need before routing
+
+- A folder of static files ready to go: an [`slides`](../slides/SKILL.md) deck (the `.html` file plus its `media/` folder, if any), a landing page, or any HTML tree. If the site is not built yet, build it first; this skill does not generate content.
+- A project slug (lowercase, hyphenated). Offer one derived from the site's name and confirm it with the user, because the slug is the live address.
+
+## Where it gets hosted
+
+Cloudflare Pages is the lite default: the page is hosted on Cloudflare's edge and stays reachable when the phone is off. There is one hosting path in lite, so there is nothing to choose between; serving a page from the device itself is not part of lite. Hand the folder and the slug to `site-deploy` and relay the live URL it returns.
+
+## After it is live
+
+`site-deploy` gates "done" on a live `200` with the right content and gives back the URL. Surface that URL to the user as the result. If the deploy fails on authentication, the fix is `wrangler login`, per `site-deploy`.

package/payload/skills/replicate/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: replicate
+description: >
+  Generate an image from a text prompt. Use when the owner wants a picture,
+  logo, illustration, diagram, icon, or any visual created from a description.
+  Trigger phrases: "generate an image", "make a picture of", "create a logo",
+  "draw me", "design an illustration", "I need a graphic of". Produces a real
+  image file in the vault.
+---
+
+# replicate
+
+Turn a text prompt into an image using the Replicate API. The script picks the model, calls the API, downloads the result into the vault, and prints the file path.
+
+## When to use
+
+The owner wants an image made from a description: a logo, an illustration, a concept sketch, a photoreal scene, a diagram, an icon. This produces an actual file, not a description of one.
+
+## Models
+
+Pick the model to match the job:
+
+- `nano-banana-pro` (default): photorealistic, data-driven visuals.
+- `recraft-v4`: design compositions and branded assets. The only model that can return `svg`.
+- `flux-schnell`: fast drafts and concept sketches.
+
+## How to run
+
+```bash
+node ~/.maxy-lite/skills/replicate/scripts/replicate-image.mjs \
+  --prompt="a calm mountain lake at dawn, soft light" \
+  --model=nano-banana-pro \
+  --aspect=16:9 \
+  --format=png
+```
+
+- `--prompt` (required): what to draw.
+- `--model` (optional, default `nano-banana-pro`): one of the three above.
+- `--aspect` (optional, default `1:1`): one of `1:1`, `4:3`, `3:2`, `16:9`, `21:9`, `9:16`.
+- `--format` (optional, default `png`): `png`, `jpg`, `webp`, or `svg` (svg only with `recraft-v4`).
+
+On success the file path prints to stdout and the image is saved under `$LITE_VAULT/Assets/generated/`. Show the owner the path.
+
+## Token
+
+The script reads `REPLICATE_API_TOKEN` from the environment, or falls back to `~/.replicate/api-token`. The lite runtime supplies the token from its secrets. If neither is set the script exits with `error=no-token`. Tell the owner a Replicate token is needed and stop.
+
+## Reading the result
+
+- **A file path on stdout, exit 0**: the image was generated and saved.
+- **Non-zero exit**: an error on stderr as `[replicate] error=<code>`:
+  - `no-token`: no token configured.
+  - `auth`: the token was rejected.
+  - `network`: the Replicate API was unreachable.
+  - `model`: an unknown model, a bad model option, or the generation failed.
+  - `download`: the image was generated but could not be fetched.
+  - `disk`: the image could not be written to the vault.
+
+Surface the error plainly. Never claim an image was made when the script failed.
+
+## Boundaries
+
+Generates one image per call. Does not edit existing images, run image-to-image, or upscale. Those need a different model and are not wired here.

package/payload/skills/replicate/scripts/replicate-image.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// replicate-image — image generation via the Replicate HTTP API. Zero deps.
+//
+// Ported from the maxy-code replicate MCP tool to a single lite CLI script.
+// Uses native fetch against the Replicate predictions API (no replicate SDK, no
+// nanoid). Same three-model registry and aspect-ratio table. The generated image
+// is downloaded into the vault assets directory and its path printed to stdout.
+//
+// Token resolution (parity with maxy-code): REPLICATE_API_TOKEN env first, then
+// ~/.replicate/api-token. Errors go to stderr as [replicate] error=<code> and
+// exit non-zero. Codes: usage, no-token, model, auth, network, download, disk.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+
+const MODELS = {
+  "nano-banana-pro": { owner: "google", name: "nano-banana-pro" },
+  "recraft-v4": { owner: "recraft-ai", name: "recraft-v4", svg: "recraft-v4-svg" },
+  "flux-schnell": { owner: "black-forest-labs", name: "flux-schnell" },
+};
+
+const ASPECT = {
+  "1:1": { width: 1024, height: 1024 },
+  "4:3": { width: 1024, height: 768 },
+  "3:2": { width: 1024, height: 683 },
+  "16:9": { width: 1024, height: 576 },
+  "21:9": { width: 1344, height: 576 },
+  "9:16": { width: 576, height: 1024 },
+};
+
+const fail = (code, msg) => {
+  console.error(`[replicate] error=${code} detail=${JSON.stringify(msg)}`);
+  process.exit(1);
+};
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map((a) => {
+    const m = a.match(/^--([^=]+)=(.*)$/);
+    return m ? [m[1], m[2]] : [a, true];
+  }),
+);
+const prompt = args.prompt;
+const model = args.model || "nano-banana-pro";
+const aspectRatio = args.aspect || "1:1";
+const outputFormat = args.format || "png";
+if (!prompt || prompt === true) {
+  fail("usage", "usage: replicate-image.mjs --prompt=<text> [--model=] [--aspect=] [--format=]");
+}
+
+const token =
+  process.env.REPLICATE_API_TOKEN ||
+  (existsSync(join(homedir(), ".replicate", "api-token"))
+    ? readFileSync(join(homedir(), ".replicate", "api-token"), "utf-8").trim()
+    : "");
+if (!token) fail("no-token", "no Replicate token (set REPLICATE_API_TOKEN or ~/.replicate/api-token)");
+
+const entry = MODELS[model];
+if (!entry) fail("model", `unknown model: ${model} (use nano-banana-pro, recraft-v4, or flux-schnell)`);
+if (outputFormat === "svg" && model !== "recraft-v4") fail("model", "svg output is only available with recraft-v4");
+const name = outputFormat === "svg" && entry.svg ? entry.svg : entry.name;
+
+const dims = ASPECT[aspectRatio] ?? ASPECT["1:1"];
+const input =
+  model === "flux-schnell"
+    ? { prompt, aspect_ratio: aspectRatio, ...(outputFormat !== "svg" ? { output_format: outputFormat } : {}) }
+    : { prompt, width: dims.width, height: dims.height, ...(outputFormat !== "svg" ? { output_format: outputFormat } : {}) };
+
+// Create a prediction against the model. Prefer:wait blocks until the prediction
+// is terminal where the model supports it; otherwise we poll the get URL.
+const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Prefer: "wait" };
+let pred;
+try {
+  const r = await fetch(`https://api.replicate.com/v1/models/${entry.owner}/${name}/predictions`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ input }),
+  });
+  if (r.status === 401 || r.status === 403) fail("auth", "Replicate token rejected (invalid or revoked)");
+  if (!r.ok) fail("model", `Replicate API HTTP ${r.status}: ${(await r.text()).slice(0, 200)}`);
+  pred = await r.json();
+} catch (err) {
+  fail("network", err instanceof Error ? err.message : String(err));
+}
+
+while (pred.status && pred.status !== "succeeded" && pred.status !== "failed" && pred.status !== "canceled") {
+  if (!pred.urls?.get) fail("model", "prediction is not terminal but carries no poll URL");
+  await new Promise((r) => setTimeout(r, 1500));
+  try {
+    const r = await fetch(pred.urls.get, { headers: { Authorization: `Bearer ${token}` } });
+    pred = await r.json();
+  } catch (err) {
+    fail("network", err instanceof Error ? err.message : String(err));
+  }
+}
+if (pred.status !== "succeeded") {
+  fail("model", `generation ${pred.status}: ${JSON.stringify(pred.error ?? "").slice(0, 200)}`);
+}
+
+// Replicate output is a URL string or an array of URL strings, depending on model.
+const out = pred.output;
+const imageUrl = Array.isArray(out)
+  ? out.find((u) => typeof u === "string" && u.startsWith("http"))
+  : typeof out === "string" && out.startsWith("http")
+    ? out
+    : null;
+if (!imageUrl) fail("model", "generation returned unexpected output format");
+
+let buf;
+try {
+  const r = await fetch(imageUrl);
+  if (!r.ok) throw new Error(`HTTP ${r.status}`);
+  buf = Buffer.from(await r.arrayBuffer());
+} catch (err) {
+  fail("download", err instanceof Error ? err.message : String(err));
+}
+
+const ext = outputFormat === "svg" ? "svg" : outputFormat;
+const date = new Date().toISOString().slice(0, 10);
+const vault = process.env.LITE_VAULT || join(homedir(), ".maxy-lite", "vault");
+const genDir = resolve(vault, "Assets", "generated");
+const file = resolve(genDir, `${date}-${randomUUID().slice(0, 6)}.${ext}`);
+try {
+  mkdirSync(genDir, { recursive: true });
+  writeFileSync(file, buf);
+} catch (err) {
+  fail("disk", err instanceof Error ? err.message : String(err));
+}
+
+console.error(`[replicate] complete model=${model} format=${outputFormat} aspect=${aspectRatio} file=${file}`);
+process.stdout.write(file + "\n");