@rubytech/create-maxy-code 0.1.497 → 0.1.498

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.497",
+  "version": "0.1.498",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:5db8891dfc1b60b2180597591dcad1b7ca9e89612f488314dd07e7dd73e5c119
+content-hash: sha256:99a8e6ca434399104da91bd275d70b2c95bb10b96f5d1b4666053d66de447468
 brand: maxy-code
 product-name: Maxy
 ---
@@ -1905,6 +1905,22 @@ A site capture becomes one of these too: an enquiry becomes a new contact routed
 
 Run a sweep a second time and it proposes nothing it already recorded on the first run, because those records are now in memory and it recognises them. A repeat sweep is quiet on purpose; that is the sign your graph is already up to date.
 
+## Automatic email→graph sweep (opt-in)
+
+The sweep above runs only when you ask, and it proposes rather than writes. There is a second, opt-in routine that runs on a schedule and writes on its own: the automatic email→graph sweep, set up through the `email-graph-sweep` skill. On each run it reads the new inbound mail on your mailbox, pulls out the organisations, people, and live jobs it finds, checks each against what Maxy already holds, saves the genuinely new ones, and then sends you a short report of what it read and saved.
+
+Turning it on needs two things, and Maxy tells you which is missing if either is absent:
+
+- **A connected mailbox.** The routine reads your mail, so a mail account (a standard IMAP mailbox, or a Microsoft 365 mailbox) must be connected. With no mailbox connected there is nothing to sweep, and Maxy says so instead of switching anything on.
+- **A place to send the report.** The routine reports over a persistent channel, so you name the WhatsApp number or Telegram chat that receives it, and that destination must already be registered as an admin or account-manager. If it is not registered, Maxy tells you that rather than falling back to a silent run.
+
+Two things to know before you switch it on:
+
+- **It messages you on every run.** It is a report you receive each time, not a silent background job. If you want a quiet, always-on tidy-up of the graph instead, that is a different routine.
+- **It is one-account, deliberate opt-in.** Maxy does not turn this on for you automatically, and it is held back from broad rollout for now while a safety fix for scheduled runs lands. Enable it for an account you are watching, not as a default.
+
+Turn it off with the same skill: ask to stop the automatic email sweep and Maxy cancels the schedule, so no further runs fire.
+
 ---
 # Slides
 Source: https://docs.getmaxy.com/slides.md
@@ -2994,6 +3010,35 @@ either is a regression.
 
 **Public visitor surface.** The public-host root (`GET /`), the `/:slug` agent routes, and the admin-host `/public` / `/public-chat` previews all serve one shell, `public.html` → [`app/public-entry.tsx`](../../../ui/app/public-entry.tsx) → `PublicChat`. `PublicChat` reuses `useSession` purely as the magic-link gatekeeper — it drives `AccessGate`, resolves the agent slug from the path, and handles `?token=` verification; once the grant is satisfied it mounts `ChatSurface variant="public"`, whose transcript reads the visitor-scoped, **delivered-only** stream `GET /api/public-reader/stream` ([`server/routes/public-reader.ts`](../../../ui/server/routes/public-reader.ts)) — the visitor sees the agent's delivered prose, never the tool/tool-result/directive bytes the legacy `/api/chat` SSE render exposed. The human visitor's branding is resolved client-side by `useSession`. For the head only, the server injects per-agent link-preview meta — `<title>`, `og:title`/`og:description`/`og:image`, `theme-color`, and a per-agent favicon, resolved from the same branding cache `useSession` reads — into the served shell, so a link-preview crawler (which never runs the client bundle) gets a branded card per agent instead of one generic shell; an agent with no branding cache gets the clean brand-default shell with no empty meta tags. There is exactly one public client surface and it is 1:1 visitor↔agent: the earlier `?surface=next` A/B handle is retired, group messaging is retired (not a supported product surface), and a former `/g/<slug>` group URL now serves the same 1:1 shell — a stale bookmark gets the 1:1 chat, never a broken render.
 
+### Routines
+
+The Routines surface (`/routines`) is the admin view of the account's
+automation `:Event` nodes — the device's scheduled agent turns and tool
+dispatches, which the Calendar surface deliberately excludes (`calendar.ts`
+unions only appointment events, `actionPlugin IS NULL`). It renders one card per
+routine (title, human-readable schedule, next run, channel/destination or tool,
+status); a card opens a detail modal modeled on the calendar `EventDetailModal`.
+The modal edits the prose instruction (`agentPrompt`, agent-dispatch routines
+only) and the schedule via a friendly builder (frequency daily/weekly/monthly,
+day-of-week, day-of-month, time) that falls back to a raw-cron field for patterns
+it cannot represent.
+
+The route (`server/routes/admin/routines.ts`) is account-scoped like `calendar.ts`
+(a foreign-account or non-automation `eventId` 404s):
+
+| Route | Behaviour |
+|-------|-----------|
+| `GET /api/admin/routines` | Lists automation Events: `recurrence IS NOT NULL OR agentChannel IS NOT NULL OR actionPlugin IS NOT NULL`. Keyed by the `eventId` property. |
+| `GET /api/admin/routines/:eventId` | One routine, same automation+account guard. |
+| `PATCH /api/admin/routines/:eventId` | Edits `agentPrompt` and/or `recurrence`. Cron validation and the timezone-aware `nextRun` recompute copy the scheduling plugin's `schedule-update` tool. An invalid cron is rejected 400 with no write. Only creation and deletion stay agent-only (`schedule-event`/`schedule-cancel`). |
+
+Observability rides `[admin:routines]`: `op=list accountId=<8> count=<n>`,
+`op=get id=<8> found=<bool>`, and `op=patch id=<8> fields=<…> outcome=ok|rejected
+reason=<invalid-cron|not-found> nextRun=<…> cron=<serialized>`. A `count=0` while
+routines exist for the account is the account-scope-miss signature; the logged
+`cron=` on `outcome=ok` confirms the persisted expression without opening the
+graph.
+
 ### Graph
 
 | Mount | Purpose |
@@ -3302,12 +3347,13 @@ authoritative. This section names the surfaces and what backs each.
 > owns all navigation; the full-width top header bar, the burger flyout, and the
 > "Powered by Claude Code" footer strip are retired. After the redesign:
 >
-> - **Nav rows** are Dashboard, Chat, Tasks, Calendar, Data, the brand container
->   row (Projects / Properties / Jobs, opening the graph filtered to the brand's
->   primary container), Graph (the unfiltered whole graph at `/graph`, waypoints
->   icon — active on plain `/graph`; the container row is active only when a
->   `label=` filter is present), Activity, and Browser. The active row carries an
->   accent left indicator. The older People / Agents / Artefacts entries in the
+> - **Nav rows** are Dashboard, Chat, Tasks, Calendar, Routines (the automation
+>   `:Event` nodes at `/routines`, `Zap` icon), Data, the brand container
+>   row (Projects / Properties / Jobs, `Folder` icon, opening the graph filtered
+>   to the brand's primary container), Graph (the unfiltered whole graph at
+>   `/graph`, waypoints icon — active on plain `/graph`; the container row is
+>   active only when a `label=` filter is present), Activity, and Browser. The
+>   active row carries an accent left indicator. The older People / Agents / Artefacts entries in the
 >   table below are pre-redesign.
 > - **Dashboard home** renders on `/` (a greeting, stat cards, a Live-now column,
 >   a Recent artefacts card, and a Channels column), consuming existing endpoints

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -89,6 +89,35 @@ either is a regression.
 
 **Public visitor surface.** The public-host root (`GET /`), the `/:slug` agent routes, and the admin-host `/public` / `/public-chat` previews all serve one shell, `public.html` → [`app/public-entry.tsx`](../../../ui/app/public-entry.tsx) → `PublicChat`. `PublicChat` reuses `useSession` purely as the magic-link gatekeeper — it drives `AccessGate`, resolves the agent slug from the path, and handles `?token=` verification; once the grant is satisfied it mounts `ChatSurface variant="public"`, whose transcript reads the visitor-scoped, **delivered-only** stream `GET /api/public-reader/stream` ([`server/routes/public-reader.ts`](../../../ui/server/routes/public-reader.ts)) — the visitor sees the agent's delivered prose, never the tool/tool-result/directive bytes the legacy `/api/chat` SSE render exposed. The human visitor's branding is resolved client-side by `useSession`. For the head only, the server injects per-agent link-preview meta — `<title>`, `og:title`/`og:description`/`og:image`, `theme-color`, and a per-agent favicon, resolved from the same branding cache `useSession` reads — into the served shell, so a link-preview crawler (which never runs the client bundle) gets a branded card per agent instead of one generic shell; an agent with no branding cache gets the clean brand-default shell with no empty meta tags. There is exactly one public client surface and it is 1:1 visitor↔agent: the earlier `?surface=next` A/B handle is retired, group messaging is retired (not a supported product surface), and a former `/g/<slug>` group URL now serves the same 1:1 shell — a stale bookmark gets the 1:1 chat, never a broken render.
 
+### Routines
+
+The Routines surface (`/routines`) is the admin view of the account's
+automation `:Event` nodes — the device's scheduled agent turns and tool
+dispatches, which the Calendar surface deliberately excludes (`calendar.ts`
+unions only appointment events, `actionPlugin IS NULL`). It renders one card per
+routine (title, human-readable schedule, next run, channel/destination or tool,
+status); a card opens a detail modal modeled on the calendar `EventDetailModal`.
+The modal edits the prose instruction (`agentPrompt`, agent-dispatch routines
+only) and the schedule via a friendly builder (frequency daily/weekly/monthly,
+day-of-week, day-of-month, time) that falls back to a raw-cron field for patterns
+it cannot represent.
+
+The route (`server/routes/admin/routines.ts`) is account-scoped like `calendar.ts`
+(a foreign-account or non-automation `eventId` 404s):
+
+| Route | Behaviour |
+|-------|-----------|
+| `GET /api/admin/routines` | Lists automation Events: `recurrence IS NOT NULL OR agentChannel IS NOT NULL OR actionPlugin IS NOT NULL`. Keyed by the `eventId` property. |
+| `GET /api/admin/routines/:eventId` | One routine, same automation+account guard. |
+| `PATCH /api/admin/routines/:eventId` | Edits `agentPrompt` and/or `recurrence`. Cron validation and the timezone-aware `nextRun` recompute copy the scheduling plugin's `schedule-update` tool. An invalid cron is rejected 400 with no write. Only creation and deletion stay agent-only (`schedule-event`/`schedule-cancel`). |
+
+Observability rides `[admin:routines]`: `op=list accountId=<8> count=<n>`,
+`op=get id=<8> found=<bool>`, and `op=patch id=<8> fields=<…> outcome=ok|rejected
+reason=<invalid-cron|not-found> nextRun=<…> cron=<serialized>`. A `count=0` while
+routines exist for the account is the account-scope-miss signature; the logged
+`cron=` on `outcome=ok` confirms the persisted expression without opening the
+graph.
+
 ### Graph
 
 | Mount | Purpose |
@@ -397,12 +426,13 @@ authoritative. This section names the surfaces and what backs each.
 > owns all navigation; the full-width top header bar, the burger flyout, and the
 > "Powered by Claude Code" footer strip are retired. After the redesign:
 >
-> - **Nav rows** are Dashboard, Chat, Tasks, Calendar, Data, the brand container
->   row (Projects / Properties / Jobs, opening the graph filtered to the brand's
->   primary container), Graph (the unfiltered whole graph at `/graph`, waypoints
->   icon — active on plain `/graph`; the container row is active only when a
->   `label=` filter is present), Activity, and Browser. The active row carries an
->   accent left indicator. The older People / Agents / Artefacts entries in the
+> - **Nav rows** are Dashboard, Chat, Tasks, Calendar, Routines (the automation
+>   `:Event` nodes at `/routines`, `Zap` icon), Data, the brand container
+>   row (Projects / Properties / Jobs, `Folder` icon, opening the graph filtered
+>   to the brand's primary container), Graph (the unfiltered whole graph at
+>   `/graph`, waypoints icon — active on plain `/graph`; the container row is
+>   active only when a `label=` filter is present), Activity, and Browser. The
+>   active row carries an accent left indicator. The older People / Agents / Artefacts entries in the
 >   table below are pre-redesign.
 > - **Dashboard home** renders on `/` (a greeting, stat cards, a Live-now column,
 >   a Recent artefacts card, and a Channels column), consuming existing endpoints

package/payload/platform/plugins/docs/references/sweep-guide.md

@@ -41,3 +41,19 @@ A site capture becomes one of these too: an enquiry becomes a new contact routed
 ## Running It Again
 
 Run a sweep a second time and it proposes nothing it already recorded on the first run, because those records are now in memory and it recognises them. A repeat sweep is quiet on purpose; that is the sign your graph is already up to date.
+
+## Automatic email→graph sweep (opt-in)
+
+The sweep above runs only when you ask, and it proposes rather than writes. There is a second, opt-in routine that runs on a schedule and writes on its own: the automatic email→graph sweep, set up through the `email-graph-sweep` skill. On each run it reads the new inbound mail on your mailbox, pulls out the organisations, people, and live jobs it finds, checks each against what {{productName}} already holds, saves the genuinely new ones, and then sends you a short report of what it read and saved.
+
+Turning it on needs two things, and {{productName}} tells you which is missing if either is absent:
+
+- **A connected mailbox.** The routine reads your mail, so a mail account (a standard IMAP mailbox, or a Microsoft 365 mailbox) must be connected. With no mailbox connected there is nothing to sweep, and {{productName}} says so instead of switching anything on.
+- **A place to send the report.** The routine reports over a persistent channel, so you name the WhatsApp number or Telegram chat that receives it, and that destination must already be registered as an admin or account-manager. If it is not registered, {{productName}} tells you that rather than falling back to a silent run.
+
+Two things to know before you switch it on:
+
+- **It messages you on every run.** It is a report you receive each time, not a silent background job. If you want a quiet, always-on tidy-up of the graph instead, that is a different routine.
+- **It is one-account, deliberate opt-in.** {{productName}} does not turn this on for you automatically, and it is held back from broad rollout for now while a safety fix for scheduled runs lands. Enable it for an account you are watching, not as a default.
+
+Turn it off with the same skill: ask to stop the automatic email sweep and {{productName}} cancels the schedule, so no further runs fire.

package/payload/platform/plugins/memory/PLUGIN.md

@@ -215,6 +215,8 @@ Graph hygiene is **agent-directed, case by case** — no autonomous rule engine,
 
 `memory-dream-run` is the operator-initiated graph-hygiene sweep — seven phases: orphan detection on `:Person`/`:Organization`/`:Concept`/`:Project`; stale compiled-truth scan on `compiledTruthUpdatedAt`; mark edges to `:Trashed` targets with `staleTarget: true`; LLM-bounded citation audit on `:TimelineEvent`; prune compiled-truth revisions to newest 20 per entity; materialise persistent `:BACKLINKS` edges derived from `:MENTIONS`/`:REFERENCES` (making reverse-link queries O(1)); normalise `tags[]` array properties on `:KnowledgeDocument` nodes and merge `:DefinedTerm {category:'obsidian-tag'}` variants. Each run writes a `:Report` (via `memory-report-write`) summarising counts; per-phase log lines `[dream-cycle] phase=<n>` join on the run id. Failure of any phase logs `[dream-cycle:phase-<n>:error]` and continues. Pass `phases: [4]` to run only the citation audit (e.g. after a bulk ingest); `maxEventsPerRun` defaults to 200 for phase 4, with a resume cursor stored as `:Report.lastEventCursor`. `memory-review-queue` is the read-only surface for `:OrphanCandidate` and `:CitationProposal` queues — counts plus a small sample per queue.
 
+**Scheduled sweep.** `memory-dream-run` is also driven automatically, per account, by the self-contained `mcp/dist/scripts/dream-cycle-sweep.js` binary. The always-running `platform/ui` server spawns it hourly (the same `registerLoop` pattern as `calendar-reconcile`), because the Pi has no other periodic surface. Per tick it enumerates every account (`account-enumeration`) and, for each, reads the most-recent dream-cycle `:Report`: an account swept within the last 24h is skipped (`op=skip reason=within-window`), an account with an empty graph is skipped (`op=skip reason=no-graph`), an account with no `:AdminUser` to parent a `:Report` is skipped (`op=skip reason=no-report-parent`, the provisioned-but-pre-PIN state), and any other account runs all seven phases via `memoryDreamRun` (`op=run … reportId=…`). The 24h cadence is enforced from that `:Report`, so the hourly tick is idempotent and needs no scheduler entry. The sweep is deterministic end to end — no LLM, no channel, no agent turn, no Claude credential — and is not a schedulable `:Event`, so the operator cannot cancel it. It PID-locks at `<configDir>/dream-cycle-sweep.lock` against overlap; a missing `dist` (dev tree) makes the server loop a silent no-op. Diagnostic: `logs-read --tail server 200 | grep '\[dream-cycle-sweep\]'`. The opt-in, mailbox-driven counterpart that extracts entities from inbound is a scheduled agent turn, not this deterministic path.
+
 ## Brain-capture diagnostic — `memory-brain-capture-recent`
 
 Read-only window into the extractive graph writes produced under this account. Returns recent `:MENTIONS` edges (`:Message-[:MENTIONS]->Entity`) and `:Idea` nodes interleaved by `observedAt`. Default window is 24 hours; pass `windowHours` (max 720) and `limit` (max 200) to scan a longer arc. Use this when the operator asks "what has the brain captured today?", "show me recent mentions of X", or "what ideas did I leave on the table this week?". Writes are produced by `database-operator` per-write briefs admin dispatches — either inline mid-turn, or as part of the on-demand `/insight` graph-completeness sweep (`platform/plugins/admin/skills/insight/SKILL.md`).

package/payload/platform/plugins/memory/mcp/dist/index.js

@@ -547,7 +547,7 @@ process.stderr.write("[memory-mcp] registered tool=conversation-archive-list-chu
 // MERGE-key (chunkElementId, kind, contentHash) baked into each mergeCypher.
 // ---------------------------------------------------------------------------
 const claimSchema = z.object({
-    kind: z.enum([...PROPOSAL_KINDS]).describe("One of: mention, task, preference, observed-relationship."),
+    kind: z.enum([...PROPOSAL_KINDS]).describe("One of: mention, task, preference, note, observed-relationship."),
     evidenceSnippet: z
         .string()
         .describe("Near-verbatim quote from the chunk body (≤80 chars enforced server-side)."),
@@ -566,7 +566,7 @@ const claimSchema = z.object({
         .optional()
         .describe("Kind-specific structured fields (taskTitle/taskDueHint for task; preferenceCategory/preferenceKey/preferenceValue for preference; relationshipType for observed-relationship)."),
 });
-lifelineTool(server, "conversation-archive-derive-insights", "Convert one chunk's agent-produced claims into operator-facing claim proposals (mention, task, preference, observed-relationship). The conversation-archive-enrich skill reads chunk bodies via `conversation-archive-list-chunks`, drives the dispatched specialist to emit claims in-turn, and passes them here for per-kind cypher emission. Applies the durable rejection sidecar so already-triaged claims do not re-surface. Read-only: the per-row operator gate runs in the skill, this tool never writes.", {
+lifelineTool(server, "conversation-archive-derive-insights", "Convert one chunk's agent-produced claims into operator-facing claim proposals (mention, task, preference, note, observed-relationship). The conversation-archive-enrich skill reads chunk bodies via `conversation-archive-list-chunks`, drives the dispatched specialist to emit claims in-turn, and passes them here for per-kind cypher emission. Applies the durable rejection sidecar so already-triaged claims do not re-surface. Read-only: the per-row operator gate runs in the skill, this tool never writes.", {
     archiveElementId: z
         .string()
         .describe("elementId of the :ConversationArchive parent (Task 397 — keyed on conversationIdentity) the operator named (required)."),