@rubytech/create-maxy-code 0.1.230 → 0.1.233

package/dist/__tests__/rss-sampler-installer.test.js

@@ -0,0 +1,27 @@
+// Static-grep contracts for Task 600 installer additions:
+// swap provisioning and rss-sampler service registration.
+//
+// Why static-grep, not behaviour: the install branches spawn (sudo, systemctl,
+// dphys-swapfile), so end-to-end reproduction belongs to the manual smoke path.
+// The unit suite pins the branch points so a future refactor that removes them
+// fails loudly here.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+const here = dirname(fileURLToPath(import.meta.url));
+const INDEX_TS = resolve(here, "../../src/index.ts");
+const SRC = readFileSync(INDEX_TS, "utf-8");
+test("installSystemDeps Linux branch installs dphys-swapfile and writes CONF_SWAPSIZE=2048", () => {
+    assert.match(SRC, /apt-get.*install.*dphys-swapfile/s, "apt install dphys-swapfile must be present");
+    assert.match(SRC, /CONF_SWAPSIZE=2048/, "swap size must be 2048MB");
+    assert.match(SRC, /CONF_MAXSWAP=4096/, "swap max must be 4096MB");
+    assert.match(SRC, /dphys-swapfile.*restart|restart.*dphys-swapfile/s, "dphys-swapfile service must be restarted");
+});
+test("installService Linux branch writes rss-sampler user unit and enables it", () => {
+    assert.match(SRC, /rss-sampler\.service/, "rss-sampler.service unit must be written");
+    assert.match(SRC, /rss-sampler\.sh/, "rss-sampler.sh must appear in ExecStart");
+    assert.match(SRC, /rss-sampler.*enable|enable.*rss-sampler/s, "rss-sampler must be enabled");
+    assert.match(SRC, /rss-sampler installed/, "rss-sampler install must emit a logFile entry");
+});

package/dist/index.js

@@ -709,6 +709,42 @@ function installSystemDeps() {
     // so deployPayload's writeChromiumBinaryPathFile and installService's
     // buildMaxyUnitFile both have a real absolute path to thread through.
     ensureNonSnapChromium();
+    // Task 600 — provision swap so the OOM-killer has a buffer to work in
+    // instead of silently freezing the box. dphys-swapfile is the standard
+    // Raspberry Pi OS swap manager. CONF_MAXSWAP raised to 4096 so the
+    // operator can manually grow the swap file without reinstalling.
+    // Best-effort: a failure here warns but does not abort the install.
+    try {
+        console.log("  [privileged] apt-get install dphys-swapfile");
+        shell("apt-get", ["install", "-y", "dphys-swapfile"], { sudo: true, bestEffort: true });
+        const desiredSwapConf = "CONF_SWAPSIZE=2048\nCONF_MAXSWAP=4096\n";
+        const swapConfPath = "/etc/dphys-swapfile";
+        let swapCurrent = "";
+        if (existsSync(swapConfPath)) {
+            try {
+                swapCurrent = readFileSync(swapConfPath, "utf-8");
+            }
+            catch {
+                swapCurrent = "";
+            }
+        }
+        if (swapCurrent === desiredSwapConf) {
+            logFile("  swap: already configured (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+        }
+        else {
+            const swapTmpPath = `/tmp/dphys-swapfile.${process.pid}`;
+            writeFileSync(swapTmpPath, desiredSwapConf);
+            console.log("  [privileged] install /etc/dphys-swapfile (CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096)");
+            shell("cp", [swapTmpPath, swapConfPath], { sudo: true });
+            spawnSync("rm", ["-f", swapTmpPath]);
+            console.log("  [privileged] systemctl restart dphys-swapfile");
+            shell("systemctl", ["restart", "dphys-swapfile"], { sudo: true, bestEffort: true });
+            logFile("  swap: configured CONF_SWAPSIZE=2048 CONF_MAXSWAP=4096 and restarted dphys-swapfile");
+        }
+    }
+    catch (err) {
+        console.error(`  WARNING: failed to provision swap: ${err instanceof Error ? err.message : String(err)}`);
+    }
     // Hostname resolution — four sources, in priority order:
     //   1. --hostname flag (unconditional — the caller is the authority)
     //   2. OS detection on same-brand upgrade (service exists → keep whatever is currently set)
@@ -3084,6 +3120,28 @@ function installService() {
     const claudePtysSliceName = "claude-ptys.slice";
     writeFileSync(join(serviceDir, claudePtysSliceName), buildClaudePtysSliceUnitFile());
     logFile(`  ${claudePtysSliceName}: Task 250 slice for claude-session-*.scope cohort`);
+    // Task 600 — per-brand RSS sampler: a long-running user service that
+    // periodically writes per-claude.exe RSS + aggregate RSS to disk.
+    // Named per-brand (BRAND.hostname prefix) so two brands on the same
+    // device each own their own sampler writing to their own log path.
+    const rssSamplerUnitName = `${BRAND.hostname}-rss-sampler.service`;
+    const rssSamplerScriptPath = resolve(INSTALL_DIR, "platform/scripts/rss-sampler.sh");
+    const rssSamplerLogPath = join(persistDir, "rss-sampler.log");
+    const rssSamplerUnit = `[Unit]
+Description=${BRAND.productName} RSS Sampler
+
+[Service]
+Type=simple
+ExecStart=/bin/bash ${rssSamplerScriptPath}
+Environment=LOG_PATH=${rssSamplerLogPath}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+    writeFileSync(join(serviceDir, rssSamplerUnitName), rssSamplerUnit);
+    logFile(`  rss-sampler installed: ${rssSamplerUnitName} LOG_PATH=${rssSamplerLogPath}`);
     // the edge service: always-on front door that owns the public
     // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
     // independent of the main brand service, so an in-place upgrade triggered
@@ -3294,11 +3352,14 @@ WantedBy=multi-user.target
     spawnSync("systemctl", ["--user", "enable", edgeUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", claudeSessionManagerUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "enable", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "enable", `${BRAND.hostname}-rss-sampler`], { stdio: "inherit" });
     // edge first: binds public port + starts VNC stack. Then claude-session-manager
     // (so the main brand unit's Requires= is satisfied). Then main brand service.
+    // rss-sampler is independent — start last, failure is non-blocking.
     spawnSync("systemctl", ["--user", "restart", edgeUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", claudeSessionManagerUnitShort], { stdio: "inherit" });
     spawnSync("systemctl", ["--user", "restart", unitName], { stdio: "inherit" });
+    spawnSync("systemctl", ["--user", "restart", `${BRAND.hostname}-rss-sampler`], { stdio: "inherit" });
     // Session manager runs in its own systemd user unit and can boot-fail silently
     // (e.g. mcp-block-missing). The web server below comes up regardless, so the
     // install terminal would otherwise report success while every API call 503s.

package/package.json

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

package/payload/platform/neo4j/schema.cypher

@@ -1566,6 +1566,13 @@ OPTIONS {
 //   mentioned | met | quoted | attended | transacted
 // Extractor refuses on ambiguity rather than collapsing to "other".
 //
+// `learnedAt` — datetime(), transaction-time: when this event was ingested.
+//   Distinct from `occurredAt` (valid-time: when the fact was true in the world).
+//   Enables bi-temporal queries: "events ingested on date X about something that
+//   happened in 1990". Backfilled from `createdAt` on pre-existing nodes; nodes
+//   without `createdAt` fall back to `datetime()` (safe approximation).
+//   Task 597.
+//
 // `compiledTruth` source:
 //   compiledTruthSource = "rewriter" (default) — compiled-truth-rewriter
 //     library wrote it.
@@ -1596,6 +1603,9 @@ FOR (t:TimelineEvent) ON (t.occurredAt);
 CREATE INDEX timeline_event_kind IF NOT EXISTS
 FOR (t:TimelineEvent) ON (t.kind);
 
+CREATE INDEX timeline_event_learned_at IF NOT EXISTS
+FOR (t:TimelineEvent) ON (t.learnedAt);
+
 CREATE VECTOR INDEX timeline_event_embedding IF NOT EXISTS
 FOR (t:TimelineEvent) ON (t.embedding)
 OPTIONS {
@@ -1605,6 +1615,16 @@ OPTIONS {
   }
 };
 
+// Task 597 migration — backfill learnedAt on :TimelineEvent nodes written
+// before transaction-time was tracked. Uses createdAt as the best available
+// proxy; nodes without createdAt get datetime() (safe: they predate the field).
+// CALL IN TRANSACTIONS avoids a single large write lock on installs with many nodes.
+CALL {
+  MATCH (t:TimelineEvent) WHERE t.learnedAt IS NULL
+  WITH t LIMIT 500
+  SET t.learnedAt = coalesce(t.createdAt, datetime())
+} IN TRANSACTIONS OF 500 ROWS;
+
 // `compiledTruthUpdatedAt` indices for stale-detection scans
 // (e.g. "find :Person with truth older than 7 days that has new events").
 CREATE INDEX person_compiled_truth_updated_at IF NOT EXISTS

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:7ccf57afeb67e23745bc86265d7a65790fd4fc6cba0a659a8fb6ee3f69027e6d
+content-hash: sha256:40fe99e94ab4ff0540965423bb0c7aa6016d438a5503f06aa3ab6608773c694e
 brand: maxy-code
 product-name: Maxy
 ---
@@ -1489,6 +1489,16 @@ Ask naturally:
 - "What did I last discuss about the Acme proposal?"
 - "Who have I met from the fintech conference?"
 
+## Thinking tools
+
+Three slash commands that apply analysis to what's already in your graph:
+
+**`/challenge <claim>`** — stress-tests an assertion. Maxy searches your graph for nodes that contradict or qualify the claim — nodes that assert the opposite, name exceptions, or add significant caveats — and presents the strongest counter-case it finds. If nothing in your graph challenges the claim, it says so rather than inventing one. Results cite node IDs and relevance scores so you can inspect the sources directly.
+
+**`/connect <topic-A> <topic-B>`** — finds the bridge. Maxy searches both topics, collects their immediate graph neighborhoods, and looks for nodes they share. If a direct bridge exists it names it in one sentence. If not, it surfaces the closest approach — the two nodes that are semantically nearest across the two sides — and proposes the connection you could draw.
+
+**`/emerge`** — names the unnamed clusters. Maxy retrieves your KnowledgeDocument and Section nodes that are not yet connected to a Concept node, groups them by shared theme, and proposes a Concept name for each cluster. You approve or skip each proposal one at a time; nothing is written without your confirmation. Clusters of fewer than three nodes are listed at the end as "too small to cluster."
+
 ## Listing and counting
 
 Maxy answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
@@ -1507,6 +1517,22 @@ The page reads only your own brand's Neo4j — a Maxy device and a Real Agent de
 
 **Typo-proof cypher.** When Maxy runs direct Cypher to answer a relational question, the query is checked against your Neo4j's live label and relationship-type taxonomy before it executes. Cypher that references an unknown name (an edge or label that does not exist in your graph) is rejected for writes and flagged with a warnings header for reads, so Maxy never silently acts on a query that targeted the wrong set of nodes. You should not see this — it runs invisibly — but it is the safety net that stops a fabricated edge name from producing "empty" results that are really just unreachable. Before acting on a bulk operation Maxy surfaces the result count and a sample; if it ever describes a cypher rejection, that means its first attempt was malformed and it corrected itself.
 
+## Bi-temporal timeline events
+
+Every factual statement Maxy extracts from your conversations is stored as a `:TimelineEvent` node. Each event carries two separate timestamps:
+
+- **`occurredAt`** (valid-time) — when the fact was true in the world. Set from the text itself; can reference a date in the past ("Alice joined in 1990" stores `occurredAt = 1990-01-01`).
+- **`learnedAt`** (transaction-time) — when the system ingested this event. Always the wall-clock time of the write; never back-dated.
+
+This distinction lets you ask two qualitatively different questions:
+
+- *"What happened to Alice in 1990?"* — query by `occurredAt`.
+- *"What did Maxy learn about Alice last Tuesday?"* — query by `learnedAt`.
+
+`memory-compiled-truth-history` returns both fields for every timeline event on an entity under the `timelineEvents` array, alongside the compiled-truth revision history in the `revisions` array.
+
+**Backfill:** Timeline events written before this feature was added have `learnedAt` set to their `createdAt` value by the schema migration. Events without `createdAt` (very old nodes) receive the migration run time as an approximation.
+
 ## Write doctrine
 
 Every new node in Maxy's graph is created with at least one connection to an existing node. A contact connects to the conversation or organisation it came from; a task connects to the session that raised it or the entities it will affect; a session summary connects to the conversation it summarises. A node with no connection is noise — it cannot be attributed, traversed, or explained — so the graph refuses to create one. If Maxy ever tries to record something without a link, the write is rejected and Maxy asks you to clarify where it belongs.
@@ -2572,6 +2598,18 @@ switch them off. Flipping it off again also drops them from any already-
 expanded neighbourhood so a click near a `ToolCall` does not re-introduce
 it.
 
+## Direct edge management
+
+`memory-edge` creates or deletes a typed directed edge between two nodes that already exist in the graph. Both nodes must belong to the same account — mismatched or foreign nodes are rejected with a structured error before any mutation runs.
+
+**Create:** MERGE is idempotent. First call returns `{created: true}`; a repeated call with the same endpoints and type returns `{created: false}`. Properties supplied on the call are stamped onto the relationship on CREATE only; a subsequent idempotent hit does not overwrite them.
+
+**Delete:** If the edge is present it is deleted and `{deleted: true}` is returned. If absent, the call is a no-op and returns `{deleted: false}`.
+
+`relationshipType` is uppercase-coerced. Types that start with an underscore (e.g. `_SOFT_DELETE`) are reserved for platform internals and are rejected.
+
+Typical flow: call `memory-search` for each endpoint to retrieve their `elementId` values, then call `memory-edge action=create relationshipType=RELATES_TO fromId=<id> toId=<id>`. The new edge appears when you hop-expand either endpoint on the `/graph` canvas.
+
 ---
 # Neo4j Edge Types
 Source: https://docs.getmaxy.com/neo4j.md

package/payload/platform/plugins/docs/references/graph.md

@@ -147,3 +147,15 @@ the 90% domain-navigation path stays clean without having to remember to
 switch them off. Flipping it off again also drops them from any already-
 expanded neighbourhood so a click near a `ToolCall` does not re-introduce
 it.
+
+## Direct edge management
+
+`memory-edge` creates or deletes a typed directed edge between two nodes that already exist in the graph. Both nodes must belong to the same account — mismatched or foreign nodes are rejected with a structured error before any mutation runs.
+
+**Create:** MERGE is idempotent. First call returns `{created: true}`; a repeated call with the same endpoints and type returns `{created: false}`. Properties supplied on the call are stamped onto the relationship on CREATE only; a subsequent idempotent hit does not overwrite them.
+
+**Delete:** If the edge is present it is deleted and `{deleted: true}` is returned. If absent, the call is a no-op and returns `{deleted: false}`.
+
+`relationshipType` is uppercase-coerced. Types that start with an underscore (e.g. `_SOFT_DELETE`) are reserved for platform internals and are rejected.
+
+Typical flow: call `memory-search` for each endpoint to retrieve their `elementId` values, then call `memory-edge action=create relationshipType=RELATES_TO fromId=<id> toId=<id>`. The new edge appears when you hop-expand either endpoint on the `/graph` canvas.

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

@@ -90,6 +90,16 @@ Ask naturally:
 - "What did I last discuss about the Acme proposal?"
 - "Who have I met from the fintech conference?"
 
+## Thinking tools
+
+Three slash commands that apply analysis to what's already in your graph:
+
+**`/challenge <claim>`** — stress-tests an assertion. {{productName}} searches your graph for nodes that contradict or qualify the claim — nodes that assert the opposite, name exceptions, or add significant caveats — and presents the strongest counter-case it finds. If nothing in your graph challenges the claim, it says so rather than inventing one. Results cite node IDs and relevance scores so you can inspect the sources directly.
+
+**`/connect <topic-A> <topic-B>`** — finds the bridge. {{productName}} searches both topics, collects their immediate graph neighborhoods, and looks for nodes they share. If a direct bridge exists it names it in one sentence. If not, it surfaces the closest approach — the two nodes that are semantically nearest across the two sides — and proposes the connection you could draw.
+
+**`/emerge`** — names the unnamed clusters. {{productName}} retrieves your KnowledgeDocument and Section nodes that are not yet connected to a Concept node, groups them by shared theme, and proposes a Concept name for each cluster. You approve or skip each proposal one at a time; nothing is written without your confirmation. Clusters of fewer than three nodes are listed at the end as "too small to cluster."
+
 ## Listing and counting
 
 {{productName}} answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
@@ -108,6 +118,22 @@ The page reads only your own brand's Neo4j — a Maxy device and a Real Agent de
 
 **Typo-proof cypher.** When {{productName}} runs direct Cypher to answer a relational question, the query is checked against your Neo4j's live label and relationship-type taxonomy before it executes. Cypher that references an unknown name (an edge or label that does not exist in your graph) is rejected for writes and flagged with a warnings header for reads, so {{productName}} never silently acts on a query that targeted the wrong set of nodes. You should not see this — it runs invisibly — but it is the safety net that stops a fabricated edge name from producing "empty" results that are really just unreachable. Before acting on a bulk operation {{productName}} surfaces the result count and a sample; if it ever describes a cypher rejection, that means its first attempt was malformed and it corrected itself.
 
+## Bi-temporal timeline events
+
+Every factual statement {{productName}} extracts from your conversations is stored as a `:TimelineEvent` node. Each event carries two separate timestamps:
+
+- **`occurredAt`** (valid-time) — when the fact was true in the world. Set from the text itself; can reference a date in the past ("Alice joined in 1990" stores `occurredAt = 1990-01-01`).
+- **`learnedAt`** (transaction-time) — when the system ingested this event. Always the wall-clock time of the write; never back-dated.
+
+This distinction lets you ask two qualitatively different questions:
+
+- *"What happened to Alice in 1990?"* — query by `occurredAt`.
+- *"What did {{productName}} learn about Alice last Tuesday?"* — query by `learnedAt`.
+
+`memory-compiled-truth-history` returns both fields for every timeline event on an entity under the `timelineEvents` array, alongside the compiled-truth revision history in the `revisions` array.
+
+**Backfill:** Timeline events written before this feature was added have `learnedAt` set to their `createdAt` value by the schema migration. Events without `createdAt` (very old nodes) receive the migration run time as an approximation.
+
 ## Write doctrine
 
 Every new node in {{productName}}'s graph is created with at least one connection to an existing node. A contact connects to the conversation or organisation it came from; a task connects to the session that raised it or the entities it will affect; a session summary connects to the conversation it summarises. A node with no connection is noise — it cannot be attributed, traversed, or explained — so the graph refuses to create one. If {{productName}} ever tries to record something without a link, the write is rejected and {{productName}} asks you to clarify where it belongs.