@rubytech/create-maxy-code 0.1.230 → 0.1.232

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.230",
+  "version": "0.1.232",
   "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.