@rubytech/create-maxy-lite 0.1.5 → 0.1.7

package/index.mjs

@@ -23,7 +23,7 @@ import { fileURLToPath } from 'node:url'
 
 import { makeLog } from './lib/log.mjs'
 import { readPins } from './lib/pins.mjs'
-import { PATHS, WEBCHAT_DIR, VALIDATOR_CLI, SKILLS_HOME, launcherPath, launcherScript, payloadLayCommand, ptyLoadCommand, skillsLinkCommand, vaultBindLogin, webchatRunEnv } from './lib/paths.mjs'
+import { PATHS, WEBCHAT_DIR, PTY_NODE, VALIDATOR_CLI, SKILLS_HOME, launcherPath, launcherScript, payloadLayCommand, ptyLoadCommand, ptyDirectLoadCommand, webchatInstallCommand, skillsLinkCommand, vaultBindLogin, webchatRunEnv } from './lib/paths.mjs'
 import { orchestrate, STEP_NAMES } from './lib/orchestrate.mjs'
 import { claudeOk, validatorOk, vaultOk, webchatOk, skillsOk, healthcheck } from './lib/healthcheck.mjs'
 
@@ -117,28 +117,29 @@ const linkSkills = () => {
 /** Install the app deps (validator's js-yaml) and the webchat deps (node-pty, ws). */
 // Streamed: the webchat deps build node-pty natively, which is slow and verbose;
 // a failure carries the child's stderr so the cause is in the log.
-const PTY_NODE = `${WEBCHAT_DIR}/node_modules/node-pty/build/Release/pty.node`
 const installDeps = async () => {
   const app = await runInStream(`cd ${PATHS.appDir} && npm install --omit=dev`)
   if (app.code !== 0) throw new Error(`app deps install failed: ${app.stderr.replace(/\s+/g, ' ').trim()}`)
-  const wc = await runInStream(`cd ${WEBCHAT_DIR} && npm install --omit=dev`)
+  // The webchat install runs with scripts enabled so node-pty's own install-time
+  // source build produces a pty.node that loads — the exact install the spike's Q2
+  // proved works in this proot layer. (Earlier this disabled scripts then forced an
+  // `npm rebuild --build-from-source`; that bespoke rebuild's artifact did not load.)
+  const wc = await runInStream(webchatInstallCommand())
   if (wc.code !== 0) throw new Error(`webchat deps install failed: ${wc.stderr.replace(/\s+/g, ' ').trim()}`)
-  // node-pty ships no linux-arm64 + Node 20 prebuild, so the install above can
-  // leave pty.node unbuilt when npm has ignore-scripts set. `npm rebuild` re-runs
-  // node-pty's node-gyp build; the env var forces scripts on regardless of ambient
-  // config, and --build-from-source keeps it a source compile should a future
-  // node-pty gain a prebuild fetcher. The toolchain step guarantees python3/make/g++.
-  const rb = await runInStream(
-    `cd ${WEBCHAT_DIR} && npm_config_ignore_scripts=false npm rebuild node-pty --build-from-source --foreground-scripts`,
-  )
-  if (rb.code !== 0) throw new Error(`node-pty native build failed: ${rb.stderr.replace(/\s+/g, ' ').trim()}`)
   // Prove the built module actually loads under the guest's Node — this is exactly
   // what the relay does at launch, so a pass here means no `Failed to load native
   // module: pty.node` crash. A bare file-presence test would miss an unloadable
   // binary. The same ptyLoadCommand backs the npm-app skip-guard, so the guard
   // admits exactly what this asserts. Fail at install time, not at relay launch.
-  if (runIn(ptyLoadCommand()).code !== 0)
-    throw new Error(`node-pty native module did not load after build: ${PTY_NODE}`)
+  // ptyLoadCommand goes through node-pty's loader, which masks the real cause (it
+  // reports only the last-tried prebuilds path's ENOENT). So on failure, require the
+  // built artifact directly to recover the actual dlopen error, and carry THAT into
+  // err= — the true reason (ABI/NODE_MODULE_VERSION/symbol/ELF), not the swallowed miss.
+  if (runIn(ptyLoadCommand()).code !== 0) {
+    const direct = runIn(ptyDirectLoadCommand())
+    const cause = direct.stderr.replace(/\s+/g, ' ').trim() || `no stderr; ${PTY_NODE}`
+    throw new Error(`node-pty native module did not load after build: ${cause}`)
+  }
 }
 
 /** Write the `maxy-lite` launcher into the Termux bin dir. */

package/lib/orchestrate.mjs

@@ -113,10 +113,10 @@ const STEPS = [
     // the launcher is written. The deps probe is `require("node-pty")`, not a
     // file-presence test: a present-but-unloadable `pty.node` (stale/wrong-ABI
     // from a prior build) would pass `test -f` yet crash the relay at launch, so
-    // the guard would skip the very rebuild that repairs it. The load-check is the
+    // the guard would skip the very install that repairs it. The load-check is the
     // same condition `installDeps` asserts post-build (shared ptyLoadCommand), so
     // the guard admits exactly what the build proves; a non-loadable module fails
-    // the guard and the step rebuilds.
+    // the guard and the step re-installs.
     done: (c) =>
       c.runIn(ptyLoadCommand()).code === 0 &&
       c.runIn('command -v claude').code === 0 &&

package/lib/paths.mjs

@@ -21,6 +21,11 @@ export const PATHS = {
 export const WEBCHAT_DIR = `${PATHS.appDir}/webchat`
 export const VALIDATOR_CLI = `${PATHS.appDir}/validator/cli.mjs`
 
+// The native artifact node-pty's source build emits. Absolute so it can be required
+// directly (see ptyDirectLoadCommand), and so the build-output path is asserted in
+// exactly one place.
+export const PTY_NODE = `${WEBCHAT_DIR}/node_modules/node-pty/build/Release/pty.node`
+
 /**
  * The guest-side command that proves node-pty's native module actually loads
  * under the guest's Node — `require("node-pty")` exits 0 only when `pty.node` is
@@ -34,6 +39,41 @@ export function ptyLoadCommand({ webchatDir = WEBCHAT_DIR } = {}) {
   return `cd ${webchatDir} && node -e 'require("node-pty")'`
 }
 
+/**
+ * The guest-side command that surfaces node-pty's *real* native-load error. It
+ * requires the built artifact (`build/Release/pty.node`) directly, so node-pty's
+ * `loadNativeModule` — which tries build/Release, build/Debug and prebuilds in turn
+ * and on total failure throws wrapping only the *last* path's ENOENT
+ * (`Cannot find module './prebuilds/<platform>-<arch>//pty.node'`), swallowing the
+ * build/Release dlopen error — is never on the path. A direct require of the
+ * artifact reports the actual cause (ABI/`NODE_MODULE_VERSION`/missing-symbol/ELF)
+ * on stderr. Diagnostic only: run when `ptyLoadCommand` (the relay's real load path,
+ * and the pass/fail gate) fails, to put the true reason into the step's `err=`.
+ */
+export function ptyDirectLoadCommand({ ptyNode = PTY_NODE } = {}) {
+  return `node -e 'require("${ptyNode}")'`
+}
+
+/**
+ * The webchat dependency install — the exact incantation the spike's Q2 proved
+ * builds *and loads* node-pty in this proot Ubuntu layer: a plain `npm install`
+ * with install scripts enabled. node-pty ships no linux-arm64 prebuild, so its
+ * own install script compiles `pty.node` from source against the guest's Node,
+ * and that artifact loads. `npm_config_ignore_scripts=false` forces scripts on
+ * regardless of any ambient ignore-scripts in the Ubuntu image. This deliberately
+ * replaces the earlier disable-scripts-then-force-`npm rebuild --build-from-source`
+ * workaround, whose rebuilt artifact did not load — the rebuild, not the version,
+ * was the divergence from Q2. The toolchain step guarantees python3/make/g++.
+ */
+export function webchatInstallCommand({ webchatDir = WEBCHAT_DIR } = {}) {
+  // Reproduce the spike's exact working command (`npm install node-pty` in the
+  // Ubuntu layer, scripts on) verbatim — that built a loadable pty.node. `npm
+  // install node-pty` also resolves the rest of package.json (ws), so it covers
+  // the webchat's deps too. The env prefix forces scripts on to match the spike's
+  // environment regardless of any ambient ignore-scripts in the Ubuntu image.
+  return `cd ${webchatDir} && npm_config_ignore_scripts=false npm install node-pty`
+}
+
 // The shipped skills, as bundled into the app dir, and the path the on-device
 // `claude` reads as its personal-skills source. `claude` runs with HOME=/root in
 // the proot Ubuntu layer, so `~/.claude/skills/*/SKILL.md` resolves under /root —

package/package.json

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

package/payload/package.json

@@ -3,6 +3,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.0",
+    "node-html-markdown": "^1.3.0"
   }
 }

package/payload/skills/README.md

@@ -0,0 +1,26 @@
+# maxy-lite skills
+
+The capability bundles maxy-lite carries beyond native vault file operations. Each bundle is a folder here; the lite runtime lays these into the assistant's skills directory at install time.
+
+## Layout
+
+A bundle is a folder with a `SKILL.md` (the instructions the assistant reads) and, where a capability needs to run something, a `scripts/` directory of small Node ESM scripts run via Bash. Skills are files, so they add no running process. Scripts depend on Node 22 or newer for native `fetch` and `WebSocket`. Some scripts read configuration (`REPLICATE_API_TOKEN`, `CDP_PORT`, `LITE_VAULT`, `LITE_SCRATCH`) from the environment, which the runtime supplies.
+
+## The bundles
+
+| Bundle | Form | What it does |
+|---|---|---|
+| `url-get` | skill + script | Fetch a web page faithfully as markdown. |
+| `deep-research` | skill | Research a topic over live web sources, save a cited Note to the vault. |
+| `replicate` | skill + script | Generate an image from a prompt via the Replicate API. |
+| `browser` | skill + scripts | Render a JavaScript page, turn HTML into a PDF, take a screenshot, over the device Chromium. |
+| `admin/datetime` | skill | Timezone queries and deterministic relative-date arithmetic. |
+| `admin/upgrade` | skill | Upgrade the install by re-running the lite installer. |
+| `admin/session-management` | skill | Start, resume, and recall native `claude` sessions. |
+| `docs` | skill | Reference documentation about how lite works, loaded on demand. |
+
+## Decisions recorded here
+
+**Browser form.** `browser` ships as a skill with per-call scripts, not a persistent MCP server, because lite's real browser needs are one-shot (render, print, screenshot). A fresh script per call adds no long-lived process, matching lite's zero-process default. Multi-call interactive automation (navigate, click, fill, submit against one live page) genuinely needs a persistent listener and is not built here; it is deferred to a follow-up task if a real need appears.
+
+**`update-knowledge` dropped.** The maxy-code `update-knowledge` admin skill refreshes a public agent's `KNOWLEDGE.md` from the graph. Lite has no graph and no public agents, so there is no analogue. It is intentionally not ported.

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

@@ -0,0 +1,147 @@
+---
+name: datetime
+description: >
+  Timezone queries (current time, conversion, UTC offset, DST) and
+  relative-date arithmetic (last Tuesday, two weeks ago, Q3 last year).
+  Trigger phrases: "what time is it in", "convert time", "timezone",
+  "time difference", "DST", "last X", "N days/weeks/months ago",
+  "this/next/previous X", "Qn YYYY", "Qn last year".
+---
+
+# Datetime & Timezone Queries
+
+Answer timezone-related questions and relative-date arithmetic using Node.js. Never freelance the math. Relative dates and quarter forms must go through the deterministic one-liner in this skill, which is the single source of truth for date arithmetic in lite. Computing dates by hand drifts on weekday offsets, leap days, and quarter-start months; the one-liner does not.
+
+## When to Activate
+
+- User asks for the current time in a named city or timezone
+- User asks to convert a time between timezones
+- User asks about UTC offset, time difference, or DST status for a location
+- User asks "what time is it?" with a location qualifier
+- User uses a relative date: "last Tuesday", "two weeks ago", "yesterday", "this Christmas", "Q3 last year", "Q1 2025"
+
+For simple "what time is it?" without a location, answer directly from the `<datetime>` block in the system prompt. No tool use needed.
+
+## Behaviour
+
+Use Bash to run a Node.js one-liner with `Intl.DateTimeFormat`. The IANA timezone database is built into Node.js, so no external packages are required.
+
+### Current time in a timezone
+
+```bash
+node -e "console.log(new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', second:'2-digit', timeZone:'IANA_TZ', timeZoneName:'longOffset' }).format(new Date()))"
+```
+
+Replace `IANA_TZ` with the target timezone identifier (e.g., `America/New_York`, `Asia/Tokyo`, `Europe/Berlin`).
+
+### Time conversion
+
+To convert a specific time from one zone to another, construct a `Date` object for the source time and format it in the target zone:
+
+```bash
+node -e "
+const d = new Date('ISO_DATETIME');
+const fmt = (tz) => new Intl.DateTimeFormat('en-GB', { weekday:'long', year:'numeric', month:'long', day:'numeric', hour:'2-digit', minute:'2-digit', timeZone:tz, timeZoneName:'short' }).format(d);
+console.log(fmt('SOURCE_TZ'));
+console.log(fmt('TARGET_TZ'));
+"
+```
+
+### DST and offset info
+
+```bash
+node -e "
+const now = new Date();
+const opts = { timeZone:'IANA_TZ', timeZoneName:'longOffset' };
+const parts = new Intl.DateTimeFormat('en-GB', opts).formatToParts(now);
+const offset = parts.find(p => p.type === 'timeZoneName')?.value ?? 'unknown';
+// Check DST by comparing Jan and Jul offsets
+const jan = new Date(now.getFullYear(), 0, 1);
+const jul = new Date(now.getFullYear(), 6, 1);
+const janOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jan).find(p => p.type === 'timeZoneName')?.value;
+const julOff = new Intl.DateTimeFormat('en-GB', opts).formatToParts(jul).find(p => p.type === 'timeZoneName')?.value;
+const dstActive = janOff !== julOff;
+const inDst = dstActive && offset !== janOff;
+console.log('Current offset:', offset);
+console.log('DST observed:', dstActive);
+console.log('Currently in DST:', inDst);
+"
+```
+
+## Common City-to-Timezone Mapping
+
+When the user names a city, map it to the IANA identifier:
+- London `Europe/London`
+- New York `America/New_York`
+- Los Angeles `America/Los_Angeles`
+- Tokyo `Asia/Tokyo`
+- Sydney `Australia/Sydney`
+- Dubai `Asia/Dubai`
+- Mumbai / Delhi `Asia/Kolkata`
+- Berlin / Paris `Europe/Berlin` / `Europe/Paris`
+- Singapore `Asia/Singapore`
+- Hong Kong `Asia/Hong_Kong`
+
+For less common cities, use Bash to search the IANA database:
+```bash
+node -e "console.log(Intl.supportedValuesOf('timeZone').filter(z => z.toLowerCase().includes('SEARCH_TERM'.toLowerCase())).join('\n'))"
+```
+
+## Relative date arithmetic
+
+When the owner references a relative date ("last Tuesday", "two weeks ago", "yesterday", "this Christmas", "Q3 2024", "Q1 last year"), never compute the result by hand. Use this deterministic one-liner. The reference timestamp defaults to now; pass an ISO string as the second argument to anchor against an earlier moment (e.g. when the owner's message timestamp matters).
+
+```bash
+node -e "
+const REF = process.argv[2] ? new Date(process.argv[2]) : new Date();
+const TXT = process.argv[1];
+const WEEKDAYS = {sun:0,sunday:0,mon:1,monday:1,tue:2,tues:2,tuesday:2,wed:3,weds:3,wednesday:3,thu:4,thur:4,thurs:4,thursday:4,fri:5,friday:5,sat:6,saturday:6};
+const NUMS = {one:1,two:2,three:3,four:4,five:5,six:6,seven:7,eight:8,nine:9,ten:10,eleven:11,twelve:12};
+const sod = d => { const o=new Date(d); o.setUTCHours(0,0,0,0); return o; };
+const addD = (d,n) => { const o=new Date(d); o.setUTCDate(o.getUTCDate()+n); return o; };
+const addM = (d,n) => { const o=new Date(d); o.setUTCMonth(o.getUTCMonth()+n); return o; };
+const addY = (d,n) => { const o=new Date(d); o.setUTCFullYear(o.getUTCFullYear()+n); return o; };
+const base = sod(REF);
+let m;
+if (/\\bevery(\\s+other)?\\s+/i.test(TXT)) { console.log('null (recurring)'); process.exit(0); }
+if (m = TXT.match(/\\b(yesterday|today|tomorrow)\\b/i)) {
+  const w = m[1].toLowerCase();
+  console.log((w==='yesterday'?addD(base,-1):w==='tomorrow'?addD(base,1):base).toISOString());
+} else if (m = TXT.match(/\\b(last|next|this)\\s+([A-Za-z]+)\\b/i)) {
+  const q = m[1].toLowerCase(), t = WEEKDAYS[m[2].toLowerCase()];
+  if (t === undefined) { console.log('null'); process.exit(0); }
+  const dow = base.getUTCDay();
+  let delta;
+  if (q==='last') { delta = t-dow; if (delta>=0) delta-=7; }
+  else if (q==='next') { delta = t-dow; if (delta<=0) delta+=7; }
+  else { const id = dow===0?7:dow, it = t===0?7:t; delta = it-id; }
+  console.log(addD(base, delta).toISOString());
+} else if (m = TXT.match(/\\b(a|an|\\d+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\\s+(day|week|month|year)s?\\s+ago\\b/i)) {
+  const w = m[1].toLowerCase();
+  const n = (w==='a'||w==='an')?1:(NUMS[w]??Number(w));
+  const u = m[2].toLowerCase();
+  const d = u==='day'?addD(base,-n):u==='week'?addD(base,-7*n):u==='month'?addM(base,-n):addY(base,-n);
+  console.log(d.toISOString());
+} else if (TXT.match(/\\b(?:this\\s+)?Christmas\\b/i)) {
+  console.log(new Date(Date.UTC(base.getUTCFullYear(),11,25)).toISOString());
+} else if (TXT.match(/\\b(?:this\\s+)?New\\s+Year(?:'s)?(?:\\s+Day)?\\b/i)) {
+  console.log(new Date(Date.UTC(base.getUTCFullYear(),0,1)).toISOString());
+} else if (m = TXT.match(/\\bQ([1-4])\\s+(\\d{2}|\\d{4})\\b/i)) {
+  let y = Number(m[2]); if (y<100) y+=2000;
+  console.log(new Date(Date.UTC(y,(Number(m[1])-1)*3,1)).toISOString());
+} else if (m = TXT.match(/\\bQ([1-4])\\s+(last|this|next)\\s+year\\b/i)) {
+  const refY = base.getUTCFullYear();
+  const y = m[2].toLowerCase()==='last'?refY-1:m[2].toLowerCase()==='next'?refY+1:refY;
+  console.log(new Date(Date.UTC(y,(Number(m[1])-1)*3,1)).toISOString());
+} else { console.log('null'); }
+" "PHRASE" "OPTIONAL_REF_ISO"
+```
+
+Replace `PHRASE` with the relative phrase ("last Tuesday", "Q3 2024") and optionally `OPTIONAL_REF_ISO` with the ISO reference timestamp. Recurring forms ("every other Friday") return `null` by design. Phrases that don't match return `null`.
+
+## Boundaries
+
+- Answers timezone questions and relative-date arithmetic only. Not scheduling, reminders, or alarms.
+- Uses the device system clock. If the clock is wrong, answers will be wrong.
+- Historical timezone data (e.g., "what time was it in Tokyo on 15 March 1990?") depends on the Node.js ICU dataset and may be inaccurate for dates before 1970.
+- The relative-date parser handles single-date phrases only; multi-date ranges ("from March through May") are out of scope.

package/payload/skills/admin/session-management/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: session-management
+description: "Start a new session, resume a previous one, or recall what a past session was about. Triggers when the owner says 'start a new session', 'continue the last session', 'pick up where we left off', 'what were we doing last time', or asks about a past conversation."
+---
+
+# Session management
+
+In maxy-lite a session is one run of the native `claude` CLI. There is no platform session machinery: no session-reset/list/resume tools, no injected previous-context block, no managed-context mode. This skill is the thin layer over what `claude` itself provides, for the moments the owner names a session intent directly.
+
+## What a lite session is
+
+Each `claude` run writes its transcript to a JSONL file under `~/.claude/projects/<project-dir>/<session-id>.jsonl`. That file is the durable record of the conversation. Resuming a session means starting `claude` against that file again.
+
+## Starting a new session
+
+When the owner wants to start fresh or clear the conversation: before they do, persist anything that should outlive the conversation to the vault. The new session starts with no memory of this one except what is written to files. Save open tasks as vault Task files, profile or decision changes as the relevant vault entity, then tell the owner what was saved and that they can start a new `claude` session.
+
+## Resuming a previous session
+
+`claude` resumes by session id:
+
+```bash
+claude --resume <session-id>
+```
+
+- **The most recent session.** List the transcripts newest-first and take the top one:
+  ```bash
+  ls -t ~/.claude/projects/*/*.jsonl | head -1
+  ```
+  The basename (without `.jsonl`) is the session id. Resume it.
+- **A specific past session by topic.** List several recent transcripts, read the start of each to find the one the owner means, then resume that id.
+
+## Recalling what a past session was about
+
+When the owner asks "what were we doing last time", do not guess. Read the most recent transcript (the newest `.jsonl` above) and summarise it from its actual contents. The transcript is the source of truth, not memory.
+
+## What this skill does not do
+
+It does not edit transcripts, delete past sessions, or compact context. Those are not lite features. If the owner asks for them, say plainly that lite keeps every session as a plain transcript file and does not manage them beyond new and resume.

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

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

package/payload/skills/browser/SKILL.md

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

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

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

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

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