@rubytech/create-maxy-lite 0.1.4 → 0.1.6

package/index.mjs

@@ -23,9 +23,9 @@ import { fileURLToPath } from 'node:url'
 
 import { makeLog } from './lib/log.mjs'
 import { readPins } from './lib/pins.mjs'
-import { PATHS, WEBCHAT_DIR, VALIDATOR_CLI, launcherPath, launcherScript, payloadLayCommand, 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, healthcheck } from './lib/healthcheck.mjs'
+import { claudeOk, validatorOk, vaultOk, webchatOk, skillsOk, healthcheck } from './lib/healthcheck.mjs'
 
 const HERE = path.dirname(fileURLToPath(import.meta.url))
 const PAYLOAD = path.join(HERE, 'payload')
@@ -107,30 +107,39 @@ const layPayload = () => {
   if (r.code !== 0) throw new Error(`payload lay failed: ${r.stderr.replace(/\s+/g, ' ').trim()}`)
 }
 
+/** Symlink the bundled skills into the guest's personal-skills source so `claude` discovers them. */
+// Runs guest-side (the paths are inside the rootfs); idempotent (`ln -sfn`).
+const linkSkills = () => {
+  const r = runIn(skillsLinkCommand())
+  if (r.code !== 0) throw new Error(`skills link failed: ${r.stderr.replace(/\s+/g, ' ').trim()}`)
+}
+
 /** 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. Fail at install time, not at relay launch.
-  if (runIn(`cd ${WEBCHAT_DIR} && node -e 'require("node-pty")'`).code !== 0)
-    throw new Error(`node-pty native module did not load after build: ${PTY_NODE}`)
+  // 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.
+  // 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. */
@@ -160,7 +169,8 @@ const runHealthcheck = () =>
     // bound in and the launcher env set — then poll its port for up to 10s, record
     // whether it bound, and kill it. Run from bare Termux (`run`) because
     // vaultBindLogin already enters the distro; `runIn` would nest a second login
-    // with no bind and test the wrong process.
+    // with no bind and test the wrong process. Return the full run result so a
+    // failed bind carries the relay's stderr (e.g. node-pty load crash) into err=.
     checkWebchat: () =>
       webchatOk(async () => {
         const inner =
@@ -169,18 +179,28 @@ const runHealthcheck = () =>
           `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort} && break; done; ` +
           `curl -sf -o /dev/null http://localhost:${PATHS.webchatPort}; RC=$?; ` +
           `kill $SVPID 2>/dev/null; exit $RC`
-        return run(vaultBindLogin(inner)).code === 0
+        return run(vaultBindLogin(inner))
       }),
-    // Validator must exit 0 on an empty vault.
+    // Validator must exit 0 on an empty vault. Pass the full result so a non-zero
+    // exit carries the validator's stderr into err=.
     checkValidator: () => {
       const empty = `${PATHS.appDir}/.hc-empty-vault`
       runIn(`mkdir -p ${empty}`)
-      return validatorOk((vault) => runIn(`node ${VALIDATOR_CLI} ${vault}`).code, empty)
+      return validatorOk((vault) => runIn(`node ${VALIDATOR_CLI} ${vault}`), empty)
     },
     // The vault path only exists inside the distro when the login carries the
     // launcher's `--bind`. Reproduce that bind, then check the guest path — exactly
-    // the launcher condition, not a session where the vault was never mounted.
-    checkVault: () => vaultOk(() => run(vaultBindLogin(`test -d ${PATHS.vaultGuest}`)).code === 0),
+    // the launcher condition, not a session where the vault was never mounted. The
+    // full result carries the bind/login stderr into err= when the path is absent.
+    checkVault: () => vaultOk(() => run(vaultBindLogin(`test -d ${PATHS.vaultGuest}`))),
+    // The shipped skills are discoverable only when the personal-skills source
+    // carries their SKILL.md files. With nullglob off (the default here), a glob
+    // that matches nothing is passed to `ls` literally and `ls` exits non-zero
+    // because that path does not exist; a match lists real files and exits 0. So
+    // a 0 exit asserts at least one SKILL.md is linked (resolving through the
+    // symlinks) — a dangling or empty link dir fails. The full result carries the
+    // `ls` stderr into err= when nothing matched.
+    checkSkills: () => skillsOk(() => runIn(`ls ${SKILLS_HOME}/*/SKILL.md`)),
   })
 
 // ---- dry run ----------------------------------------------------------------
@@ -237,6 +257,7 @@ async function main() {
     interactive,
     ensureStorageGrant,
     layPayload,
+    linkSkills,
     installDeps,
     writeLauncher,
     readVersions,

package/lib/healthcheck.mjs

@@ -1,41 +1,82 @@
 // Post-install health check — the measured post-conditions, not "ran the step".
-// Each probe answers a binary question about the running system:
+// Each probe answers a binary question about the running system AND carries the
+// cause when it fails, so a red probe is diagnosable from the install log alone:
 //   claude    — does `claude --version` answer with a version?
-//   webchat   — does the relay port listen?
+//   webchat   — does the relay port listen? (its crash output is the relay stderr)
 //   validator — does the validator exit 0 on an empty vault?
 //   vault     — does the bind-mount path exist inside Ubuntu?
-// The probes take injected primitives so the decision rules are unit-testable;
-// index.mjs wires the real ones (run-in-Ubuntu, transient port probe, fs stat).
+//   skills    — does the personal-skills source carry the shipped SKILL.md files?
+// Each probe returns `{ ok, err }`: `ok` is the binary verdict, `err` is the tail
+// of the probe's stderr when it failed (empty when it passed). The probes take
+// injected primitives so the decision rules are unit-testable; index.mjs wires the
+// real ones (run-in-Ubuntu, transient port probe, fs stat), each yielding a
+// `{ code, stdout, stderr }` result so the cause survives into the log.
 
 const VERSION_RE = /\d+\.\d+\.\d+/
 
-/** True when `claude --version` exits 0 and prints a version. `runIn(cmd)` → {code, stdout}. */
+/**
+ * The diagnostic tail of a probe's output: the last few non-empty lines, with
+ * whitespace collapsed and length bounded. The actual failure (e.g. node-pty's
+ * `Failed to load native module`) is at the END of a crash's stderr, so the tail
+ * carries the cause; the cap keeps one `op=healthcheck` line readable.
+ */
+function tail(text, lines = 5, cap = 300) {
+  return String(text || '')
+    .split('\n')
+    .filter((l) => l.trim())
+    .slice(-lines)
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, cap)
+}
+
+/** `{ ok, err }` from a `{ code, stdout, stderr }` result: err is the stderr tail on failure. */
+function verdict(ok, r) {
+  return { ok, err: ok ? '' : tail(r && (r.stderr || r.stdout)) }
+}
+
+/** True when `claude --version` exits 0 and prints a version. `runVersion()` → {code, stdout, stderr}. */
 export function claudeOk(runVersion) {
   const r = runVersion()
-  return r.code === 0 && VERSION_RE.test(r.stdout || '')
+  return verdict(r.code === 0 && VERSION_RE.test(r.stdout || ''), r)
 }
 
-/** True when the validator exits 0 on the given (empty) vault. `runValidator(vault)` → exit code. */
+/** True when the validator exits 0 on the given (empty) vault. `runValidator(vault)` → {code, stderr}. */
 export function validatorOk(runValidator, vaultPath) {
-  return runValidator(vaultPath) === 0
+  const r = runValidator(vaultPath)
+  return verdict(r.code === 0, r)
 }
 
-/** True when the bind-mount path exists. `exists()` → bool. */
-export function vaultOk(exists) {
-  return exists() === true
+/** True when the bind-mount path exists. `check()` → {code, stderr}. */
+export function vaultOk(check) {
+  const r = check()
+  return verdict(r.code === 0, r)
 }
 
-/** True when the relay port responded. `getStatus()` → Promise<bool>. */
+/** True when the relay port responded. `getStatus()` → Promise<{code, stderr}>. */
 export async function webchatOk(getStatus) {
-  return (await getStatus()) === true
+  const r = await getStatus()
+  return verdict(r.code === 0, r)
+}
+
+/** True when the shipped skills are present in the personal-skills source. `listSkills()` → {code, stderr} of an `ls` of the per-skill SKILL.md glob under SKILLS_HOME; err carries the ls stderr (e.g. "No such file") when nothing matched. */
+export function skillsOk(listSkills) {
+  const r = listSkills()
+  return verdict(r.code === 0, r)
 }
 
-/** Run all four probes and return `{ claude, webchat, validator, vault }`. */
-export async function healthcheck({ checkClaude, checkWebchat, checkValidator, checkVault }) {
+/**
+ * Run all five probes and return `{ claude, webchat, validator, vault, skills }`,
+ * each a `{ ok, err }` record. orchestrate flattens this into the `op=healthcheck`
+ * line: `<probe>=<ok>` for every probe, plus `<probe>Err=<cause>` for each failure.
+ */
+export async function healthcheck({ checkClaude, checkWebchat, checkValidator, checkVault, checkSkills }) {
   return {
-    claude: checkClaude() === true,
-    webchat: (await checkWebchat()) === true,
-    validator: checkValidator() === true,
-    vault: checkVault() === true,
+    claude: checkClaude(),
+    webchat: await checkWebchat(),
+    validator: checkValidator(),
+    vault: checkVault(),
+    skills: checkSkills(),
   }
 }

package/lib/orchestrate.mjs

@@ -15,7 +15,7 @@
 // All external effects go through injected ctx primitives so the sequence,
 // guards and idempotency are unit-testable; index.mjs wires the real ones.
 
-import { PATHS, WEBCHAT_DIR, launcherPath } from './paths.mjs'
+import { PATHS, launcherPath, ptyLoadCommand } from './paths.mjs'
 
 export const STEP_NAMES = ['termux-deps', 'proot', 'ubuntu', 'node', 'toolchain', 'vault-bind', 'npm-app']
 
@@ -109,13 +109,16 @@ const STEPS = [
   },
   {
     name: 'npm-app',
-    // Converged only when node-pty's native module is built, claude is present,
-    // AND the launcher is written. The deps probe is the built `pty.node`, not the
-    // node_modules dir: node-pty ships no linux-arm64 prebuild, so a dir-present
-    // install can still lack the native module and crash the relay at launch.
-    // Guarding on pty.node makes a re-run rebuild it instead of skipping ok=true.
+    // Converged only when node-pty's native module LOADS, claude is present, AND
+    // 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 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 re-installs.
     done: (c) =>
-      c.runIn(`test -f ${WEBCHAT_DIR}/node_modules/node-pty/build/Release/pty.node`).code === 0 &&
+      c.runIn(ptyLoadCommand()).code === 0 &&
       c.runIn('command -v claude').code === 0 &&
       c.existsHost(launcherPath()),
     run: async (c) => {
@@ -127,6 +130,9 @@ const STEPS = [
         ),
       )
       c.layPayload()
+      // The payload now carries the skills tree into the app dir; link each skill
+      // into the on-device personal-skills source so `claude` discovers them.
+      c.linkSkills()
       await c.installDeps()
       c.writeLauncher()
     },
@@ -168,10 +174,25 @@ async function runStep(step, ctx) {
   return { name: step.name, ok, skipped, ms }
 }
 
+/**
+ * Flatten the healthcheck record (`{ probe: { ok, err } }`) into one line's
+ * fields: `<probe>=<ok>` for every probe, in order, plus `<probe>Err=<cause>`
+ * immediately after any probe that failed. A healthy run carries no err fields.
+ */
+function healthcheckFields(hc) {
+  const fields = {}
+  for (const [name, p] of Object.entries(hc)) {
+    fields[name] = p.ok
+    if (!p.ok && p.err) fields[`${name}Err`] = p.err
+  }
+  return fields
+}
+
 /**
  * Run the full install. Stops at the first failed step (logs `done ok=false`,
- * no healthcheck). On success: emits the resolved versions, the four-probe
- * healthcheck, and `done ok=<all probes true>`.
+ * no healthcheck). On success: emits the resolved versions, the five-probe
+ * healthcheck (each probe's ok plus its captured err when false), and
+ * `done ok=<all probes true>`.
  */
 export async function orchestrate(ctx) {
   const t0 = ctx.now()
@@ -187,8 +208,8 @@ export async function orchestrate(ctx) {
   const v = ctx.readVersions()
   ctx.log('versions', { node: v.node, claude: v.claude, ttyd: v.ttyd })
   const hc = await ctx.runHealthcheck()
-  ctx.log('healthcheck', hc)
-  const ok = Object.values(hc).every(Boolean)
+  ctx.log('healthcheck', healthcheckFields(hc))
+  const ok = Object.values(hc).every((p) => p.ok)
   ctx.log('done', { ok, ranMs: ctx.now() - t0 })
   return { ok, results, healthcheck: hc }
 }

package/lib/paths.mjs

@@ -21,6 +21,79 @@ 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
+ * both present and loadable (right ABI). This is the single construction of the
+ * load-check, shared by the `npm-app` skip-guard and `installDeps`' post-build
+ * assertion so the two can never drift: the guard admits exactly the modules the
+ * build asserts. A bare `test -f pty.node` would pass on a present-but-unloadable
+ * binary (stale/wrong-ABI from a prior build) and wrongly skip the rebuild.
+ */
+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 } = {}) {
+  return `cd ${webchatDir} && npm_config_ignore_scripts=false npm install --omit=dev`
+}
+
+// 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 —
+// discovered regardless of `claude`'s working directory (the vault). Skills are
+// shipped app content, so they live in the rootfs app dir, not in the shared
+// Obsidian vault; the install links them into SKILLS_HOME from this one source.
+export const SKILLS_SRC = `${PATHS.appDir}/skills`
+export const SKILLS_HOME = '/root/.claude/skills'
+
+/**
+ * The guest-side command that makes the bundled skills discoverable: ensure the
+ * personal-skills dir exists, then symlink each shipped skill dir into it. One
+ * source of truth (the app dir); `ln -sfn` is idempotent and leaves any sibling
+ * personal skills untouched. `shopt -s nullglob` makes an empty or absent skills
+ * source expand to zero iterations instead of bash's default unmatched-glob
+ * behaviour, which would otherwise pass the literal pattern through, create a
+ * dangling symlink named `*`, and still exit 0. So the empty case is a clean
+ * no-op that the `skills` health probe then reports false, rather than a silent
+ * false success. Run inside the distro (the paths are guest paths). `src` and
+ * `home` are pinned constants, never user input, so there is no injection surface.
+ */
+export function skillsLinkCommand({ src = SKILLS_SRC, home = SKILLS_HOME } = {}) {
+  return `shopt -s nullglob; mkdir -p ${home} && for d in ${src}/*/; do ln -sfn "$d" "${home}/$(basename "$d")"; done`
+}
+
 // Where the host payload is bind-mounted inside the guest while it is copied into
 // place. A throwaway path under the rootfs's own /tmp, distinct from the app dir.
 export const PAYLOAD_STAGE = '/tmp/maxy-lite-payload'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-lite",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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.