forge-openclaw-plugin 0.3.16 → 0.3.18

package/dist/server/apps/api/src/services/entity-crud.js

@@ -1,6 +1,7 @@
 import { z, ZodError } from "zod";
 import { getDatabase, runInTransaction } from "../db.js";
 import { createSleepSession, createSleepSessionSchema, createWorkoutSession, createWorkoutSessionSchema, deleteSleepSession, deleteWorkoutSession, getSleepSessionById, getWorkoutSessionById, listSleepSessions, listWorkoutSessions, updateSleepSession, updateSleepSessionSchema, updateWorkoutSession, updateWorkoutSessionSchema } from "../health.js";
+import { artifactMetadataCreateSchema, artifactMetadataPatchSchema, createArtifactMetadata, deleteArtifactMetadata, getArtifactById, listArtifacts, updateArtifactMetadata } from "./artifacts.js";
 import { createInsight, deleteInsight, getInsightById, listInsights, updateInsight } from "../repositories/collaboration.js";
 import { createCalendarEvent, createTaskTimebox, createWorkBlockTemplate, deleteCalendarEvent, deleteTaskTimebox, deleteWorkBlockTemplate, getCalendarEventById, getTaskTimeboxById, getWorkBlockTemplateById, listCalendarEvents, listTaskTimeboxes, listWorkBlockTemplates, updateCalendarEvent, updateTaskTimebox, updateWorkBlockTemplate } from "../repositories/calendar.js";
 import { createNote, deleteNote, getNoteById, listNotes, unlinkNotesForEntity, updateNote } from "../repositories/notes.js";
@@ -157,6 +158,17 @@ const CRUD_ENTITY_CAPABILITIES = {
         update: (id, patch) => updateTaskTimebox(id, patch),
         hardDelete: (id) => deleteTaskTimebox(id)
     },
+    artifact: {
+        entityType: "artifact",
+        routeBase: "/api/v1/artifacts",
+        deleteMode: "soft_default",
+        inBin: true,
+        list: () => listArtifacts(),
+        get: (id) => getArtifactById(id),
+        create: () => createArtifactMetadata(),
+        update: (id, patch, context) => updateArtifactMetadata(id, patch, context),
+        hardDelete: (id, context) => deleteArtifactMetadata(id, context)
+    },
     sleep_session: {
         entityType: "sleep_session",
         routeBase: "/api/v1/health/sleep",
@@ -370,6 +382,7 @@ const CREATE_ENTITY_SCHEMAS = {
     calendar_event: createCalendarEventSchema,
     work_block_template: createWorkBlockTemplateSchema,
     task_timebox: createTaskTimeboxSchema,
+    artifact: artifactMetadataCreateSchema,
     sleep_session: createSleepSessionSchema,
     workout_session: createWorkoutSessionSchema,
     psyche_value: createPsycheValueSchema,
@@ -400,6 +413,7 @@ const UPDATE_ENTITY_SCHEMAS = {
     calendar_event: updateCalendarEventSchema,
     work_block_template: updateWorkBlockTemplateSchema,
     task_timebox: updateTaskTimeboxSchema,
+    artifact: artifactMetadataPatchSchema,
     sleep_session: updateSleepSessionSchema,
     workout_session: updateWorkoutSessionSchema,
     psyche_value: updatePsycheValueSchema,
@@ -702,6 +716,14 @@ function matchesLinkedTo(entityType, entity, linkedTo) {
         case "task_timebox":
             return ((linkedTo.entityType === "task" && entity.taskId === linkedTo.id) ||
                 (linkedTo.entityType === "project" && entity.projectId === linkedTo.id));
+        case "artifact":
+            return (Array.isArray(entity.links) &&
+                entity.links.some((link) => typeof link === "object" &&
+                    link !== null &&
+                    "entityType" in link &&
+                    "entityId" in link &&
+                    link.entityType === linkedTo.entityType &&
+                    link.entityId === linkedTo.id));
         case "psyche_value":
             return ((linkedTo.entityType === "goal" && Array.isArray(entity.linkedGoalIds) && entity.linkedGoalIds.includes(linkedTo.id)) ||
                 (linkedTo.entityType === "project" && Array.isArray(entity.linkedProjectIds) && entity.linkedProjectIds.includes(linkedTo.id)) ||

package/dist/server/apps/api/src/services/knowledge-graph.js

@@ -14,6 +14,7 @@ import { listProjectSummaries } from "./projects.js";
 import { listAiConnectors } from "../repositories/ai-connectors.js";
 import { buildKnowledgeGraphFacets, buildKnowledgeGraphFocusPayload, filterKnowledgeGraphData, selectKnowledgeGraphVisibleNodeIds } from "../../../web/src/lib/knowledge-graph.js";
 import { getEntityVisual } from "../../../web/src/lib/entity-visuals.js";
+import { listArtifacts } from "./artifacts.js";
 import { KNOWLEDGE_GRAPH_RELATION_FAMILY_MAP, buildKnowledgeGraphFocusHref, buildKnowledgeGraphNodeId, getKnowledgeGraphEntityHref } from "../../../web/src/lib/knowledge-graph-types.js";
 const GRAPH_RANGE = {
     from: "2000-01-01T00:00:00.000Z",
@@ -34,6 +35,7 @@ const BASE_NODE_SIZE = {
     calendar_event: 34,
     work_block: 32,
     timebox: 33,
+    artifact: 36,
     value: 38,
     pattern: 38,
     behavior: 38,
@@ -243,6 +245,13 @@ export function buildKnowledgeGraph(userIds, query = {}) {
     const calendarEvents = listCalendarEvents({ ...GRAPH_RANGE, userIds });
     const workBlocks = listWorkBlockTemplates({ userIds });
     const timeboxes = listTaskTimeboxes({ ...GRAPH_RANGE, userIds });
+    const artifacts = listArtifacts().filter((artifact) => {
+        if (selectedUserIds.size === 0) {
+            return true;
+        }
+        return Boolean((artifact.uploadedByUserId && selectedUserIds.has(artifact.uploadedByUserId)) ||
+            (artifact.actingForUserId && selectedUserIds.has(artifact.actingForUserId)));
+    });
     const eventTypes = filterOwnedEntities("event_type", listEventTypes(), userIds);
     const emotions = filterOwnedEntities("emotion_definition", listEmotionDefinitions(), userIds);
     const values = filterOwnedEntities("psyche_value", listPsycheValues(), userIds);
@@ -808,6 +817,42 @@ export function buildKnowledgeGraph(userIds, query = {}) {
             });
         }
     }
+    for (const artifact of artifacts) {
+        nodes.set(buildKnowledgeGraphNodeId("artifact", artifact.id), makeNode({
+            entityType: "artifact",
+            entityId: artifact.id,
+            entityKind: "artifact",
+            title: artifact.title,
+            subtitle: `${artifact.detectedExtension.toUpperCase()} · ${artifact.dangerLevel}`,
+            description: artifact.shortDescription || artifact.description,
+            searchText: JSON.stringify({
+                title: artifact.title,
+                shortDescription: artifact.shortDescription,
+                description: artifact.description,
+                originalFileName: artifact.originalFileName,
+                sourceLabel: artifact.sourceLabel,
+                metadata: artifact.metadata
+            }),
+            previewStats: [
+                { label: "Format", value: artifact.formatFamily },
+                { label: "Danger", value: `${artifact.dangerScore}/100` },
+                { label: "Links", value: artifact.links.length }
+            ],
+            href: getKnowledgeGraphEntityHref("artifact", artifact.id),
+            updatedAt: artifact.updatedAt
+        }));
+        for (const link of artifact.links) {
+            addEdge(edges, {
+                source: buildKnowledgeGraphNodeId("artifact", artifact.id),
+                target: buildKnowledgeGraphNodeId(link.targetEntityType, link.targetEntityId),
+                relationKind: "entity_link",
+                label: link.relationship || "Entity link",
+                strength: 0.7,
+                directional: true,
+                structural: false
+            });
+        }
+    }
     for (const eventType of eventTypes) {
         nodes.set(buildKnowledgeGraphNodeId("event_type", eventType.id), makeNode({
             entityType: "event_type",

package/dist/server/apps/api/src/services/psyche-observation-calendar.js

@@ -40,6 +40,7 @@ const ACTIVITY_ENTITY_LABELS = {
     work_block: "Work block",
     work_block_template: "Work block template",
     task_timebox: "Task timebox",
+    artifact: "Artifact",
     preference_catalog: "Preference catalog",
     preference_catalog_item: "Preference concept",
     preference_context: "Preference context",

package/dist/server/apps/api/src/types.js

@@ -172,6 +172,7 @@ export const activityEntityTypeSchema = z.enum([
     "work_block",
     "work_block_template",
     "task_timebox",
+    "artifact",
     "sleep_session",
     "workout_session"
 ]);
@@ -358,6 +359,7 @@ export const crudEntityTypeSchema = z.enum([
     "calendar_event",
     "work_block_template",
     "task_timebox",
+    "artifact",
     "psyche_value",
     "behavior_pattern",
     "behavior",

package/dist/server/apps/web/src/lib/api.js

@@ -890,6 +890,75 @@ export function createNote(input) {
         body: JSON.stringify(input)
     });
 }
+export async function listArtifacts(options = {}) {
+    const search = new URLSearchParams();
+    if (options.query?.trim()) {
+        search.set("query", options.query.trim());
+    }
+    if (options.artifactState) {
+        search.set("artifactState", options.artifactState);
+    }
+    if (options.dangerLevel) {
+        search.set("dangerLevel", options.dangerLevel);
+    }
+    if (options.formatFamily) {
+        search.set("formatFamily", options.formatFamily);
+    }
+    if (options.linkedEntityType?.trim() && options.linkedEntityId?.trim()) {
+        search.set("linkedEntityType", options.linkedEntityType.trim());
+        search.set("linkedEntityId", options.linkedEntityId.trim());
+    }
+    if (options.limit) {
+        search.set("limit", String(options.limit));
+    }
+    const suffix = search.size > 0 ? `?${search.toString()}` : "";
+    return request(`/api/v1/artifacts${suffix}`);
+}
+export function getArtifact(artifactId) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}`);
+}
+export function uploadArtifact(input) {
+    return request("/api/v1/artifacts", {
+        method: "POST",
+        body: JSON.stringify(input)
+    });
+}
+export function patchArtifact(artifactId, patch) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}`, {
+        method: "PATCH",
+        body: JSON.stringify(patch)
+    });
+}
+export function downloadArtifact(artifactId) {
+    return requestBlob(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/download`);
+}
+export function rescanArtifact(artifactId) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/scan`, { method: "POST" });
+}
+export function enrichArtifact(artifactId, input = {}) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/enrich`, {
+        method: "POST",
+        body: JSON.stringify(input)
+    });
+}
+export function replaceArtifactEntityLinks(artifactId, links) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/links`, {
+        method: "POST",
+        body: JSON.stringify({ links })
+    });
+}
+export function patchArtifactTrust(artifactId, input) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/trust`, {
+        method: "POST",
+        body: JSON.stringify(input)
+    });
+}
+export function listArtifactVersions(artifactId) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/versions`);
+}
+export function listArtifactAuditEvents(artifactId) {
+    return request(`/api/v1/artifacts/${encodeURIComponent(artifactId)}/audit`);
+}
 export function getNote(noteId) {
     return request(`/api/v1/notes/${noteId}`);
 }

package/dist/server/apps/web/src/lib/entity-visuals.js

@@ -1,4 +1,4 @@
-import { Bot, CalendarDays, Compass, FileText, FolderOpen, GitBranch, Heart, ListTodo, Network, NotebookPen, PanelTop, Quote, RefreshCw, Repeat, Route, Shapes, Sparkles, StickyNote, Target, Timer, Workflow } from "lucide-react";
+import { Archive, Bot, CalendarDays, Compass, FileText, FolderOpen, GitBranch, Heart, ListTodo, Network, NotebookPen, PanelTop, Quote, RefreshCw, Repeat, Route, Shapes, Sparkles, StickyNote, Target, Timer, Workflow } from "lucide-react";
 export const ENTITY_KINDS = [
     "goal",
     "project",
@@ -14,6 +14,7 @@ export const ENTITY_KINDS = [
     "calendar_event",
     "work_block",
     "timebox",
+    "artifact",
     "value",
     "pattern",
     "behavior",
@@ -127,6 +128,13 @@ const ENTITY_VISUAL_SEEDS = [
         iconName: "Timer",
         accentRgb: [244, 114, 182]
     },
+    {
+        kind: "artifact",
+        label: "Artifact",
+        icon: Archive,
+        iconName: "Archive",
+        accentRgb: [45, 212, 191]
+    },
     {
         kind: "value",
         label: "Value",
@@ -259,6 +267,7 @@ const CRUD_ENTITY_KIND_MAP = {
     calendar_event: "calendar_event",
     work_block_template: "work_block",
     task_timebox: "timebox",
+    artifact: "artifact",
     psyche_value: "value",
     behavior_pattern: "pattern",
     behavior: "behavior",

package/dist/server/apps/web/src/lib/knowledge-graph-types.js

@@ -39,6 +39,11 @@ export const KNOWLEDGE_GRAPH_HIERARCHY_LANES = [
         label: "Calendar",
         kinds: ["calendar_event", "work_block", "timebox"]
     },
+    {
+        id: "artifacts",
+        label: "Artifacts",
+        kinds: ["artifact"]
+    },
     {
         id: "values",
         label: "Values",
@@ -95,6 +100,7 @@ export const KNOWLEDGE_GRAPH_RELATION_LABELS = {
     strategy_step: "Strategy step",
     strategy_link: "Strategy context",
     habit_link: "Habit link",
+    entity_link: "Entity link",
     note_link: "Note link",
     wiki_parent: "Wiki parent",
     wiki_link: "Wiki link",
@@ -156,6 +162,7 @@ export const KNOWLEDGE_GRAPH_RELATION_FAMILY_MAP = {
     strategy_step: "structural",
     strategy_link: "contextual",
     habit_link: "contextual",
+    entity_link: "contextual",
     note_link: "contextual",
     wiki_parent: "structural",
     wiki_link: "contextual",
@@ -236,6 +243,8 @@ export function getKnowledgeGraphEntityHref(entityType, entityId, options) {
         case "work_block_template":
         case "task_timebox":
             return `/calendar`;
+        case "artifact":
+            return `/artifacts/${encodeURIComponent(entityId)}`;
         case "event_type":
         case "emotion_definition":
             return "/psyche/reports";

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "activation": {
     "onStartup": true,
     "onCapabilities": [
@@ -24,6 +24,7 @@
     "tools": [
       "forge_adjust_work_minutes",
       "forge_apply_doctor_fix",
+      "forge_call_artifact_route",
       "forge_call_life_force_route",
       "forge_call_movement_route",
       "forge_call_workbench_route",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",

package/server/migrations/072_artifact_store.sql

@@ -0,0 +1,106 @@
+CREATE TABLE IF NOT EXISTS artifact_blobs (
+  content_sha256 TEXT PRIMARY KEY,
+  storage_key TEXT NOT NULL UNIQUE,
+  byte_size INTEGER NOT NULL,
+  detected_mime_type TEXT NOT NULL DEFAULT '',
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS artifacts (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  short_description TEXT NOT NULL DEFAULT '',
+  description TEXT NOT NULL DEFAULT '',
+  original_file_name TEXT NOT NULL,
+  storage_key TEXT NOT NULL,
+  storage_path TEXT NOT NULL,
+  content_sha256 TEXT NOT NULL,
+  byte_size INTEGER NOT NULL,
+  detected_extension TEXT NOT NULL,
+  declared_mime_type TEXT NOT NULL DEFAULT '',
+  detected_mime_type TEXT NOT NULL DEFAULT '',
+  format_family TEXT NOT NULL,
+  source_kind TEXT NOT NULL DEFAULT 'upload',
+  source_label TEXT NOT NULL DEFAULT '',
+  uploaded_by_user_id TEXT,
+  uploaded_by_agent_id TEXT,
+  acting_for_user_id TEXT,
+  artifact_state TEXT NOT NULL DEFAULT 'active',
+  danger_score INTEGER NOT NULL DEFAULT 0,
+  danger_level TEXT NOT NULL DEFAULT 'low',
+  download_policy TEXT NOT NULL DEFAULT 'human_only',
+  scan_results_json TEXT NOT NULL DEFAULT '{}',
+  enrichment_results_json TEXT NOT NULL DEFAULT '{}',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY (content_sha256) REFERENCES artifact_blobs(content_sha256)
+);
+
+CREATE INDEX IF NOT EXISTS idx_artifacts_updated
+  ON artifacts (updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_artifacts_state_danger
+  ON artifacts (artifact_state, danger_level, updated_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_artifacts_sha
+  ON artifacts (content_sha256, updated_at DESC);
+
+CREATE TABLE IF NOT EXISTS artifact_versions (
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL,
+  version_number INTEGER NOT NULL,
+  content_sha256 TEXT NOT NULL,
+  storage_key TEXT NOT NULL,
+  byte_size INTEGER NOT NULL,
+  original_file_name TEXT NOT NULL,
+  scan_results_json TEXT NOT NULL DEFAULT '{}',
+  enrichment_results_json TEXT NOT NULL DEFAULT '{}',
+  created_by_actor TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (artifact_id) REFERENCES artifacts(id) ON DELETE CASCADE,
+  FOREIGN KEY (content_sha256) REFERENCES artifact_blobs(content_sha256),
+  UNIQUE (artifact_id, version_number)
+);
+
+CREATE INDEX IF NOT EXISTS idx_artifact_versions_artifact
+  ON artifact_versions (artifact_id, version_number DESC);
+
+CREATE TABLE IF NOT EXISTS entity_links (
+  source_entity_type TEXT NOT NULL,
+  source_entity_id TEXT NOT NULL,
+  target_entity_type TEXT NOT NULL,
+  target_entity_id TEXT NOT NULL,
+  anchor_key TEXT NOT NULL DEFAULT '',
+  relationship TEXT NOT NULL DEFAULT 'related',
+  created_by_actor TEXT,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (
+    source_entity_type,
+    source_entity_id,
+    target_entity_type,
+    target_entity_id,
+    anchor_key,
+    relationship
+  )
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_links_source
+  ON entity_links (source_entity_type, source_entity_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_entity_links_target
+  ON entity_links (target_entity_type, target_entity_id, created_at DESC);
+
+CREATE TABLE IF NOT EXISTS artifact_audit_events (
+  id TEXT PRIMARY KEY,
+  artifact_id TEXT NOT NULL,
+  event_type TEXT NOT NULL,
+  actor TEXT,
+  source TEXT NOT NULL,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  FOREIGN KEY (artifact_id) REFERENCES artifacts(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_artifact_audit_events_artifact
+  ON artifact_audit_events (artifact_id, created_at DESC);

package/server/migrations/073_artifact_entity_links_repair.sql

@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS entity_links (
+  source_entity_type TEXT NOT NULL,
+  source_entity_id TEXT NOT NULL,
+  target_entity_type TEXT NOT NULL,
+  target_entity_id TEXT NOT NULL,
+  anchor_key TEXT NOT NULL DEFAULT '',
+  relationship TEXT NOT NULL DEFAULT 'related',
+  created_by_actor TEXT,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY (
+    source_entity_type,
+    source_entity_id,
+    target_entity_type,
+    target_entity_id,
+    anchor_key,
+    relationship
+  )
+);
+
+CREATE INDEX IF NOT EXISTS idx_entity_links_source
+  ON entity_links (source_entity_type, source_entity_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_entity_links_target
+  ON entity_links (target_entity_type, target_entity_id, created_at DESC);

package/skills/forge-openclaw/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forge-openclaw-plugin
-description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, operator_overview, operator_context, calendar_overview, sleep_overview, sports_overview, training_load, weight_loss, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, flashcard, trigger_report, event_type, emotion_definition, sleep_session, or workout_session. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
+description: use when the user wants to save, search, update, review, start, stop, reward, explain, compare, or run Forge records, or when the conversation is clearly about a Forge entity or domain surface such as a goal, project, strategy, task, habit, note, wiki_page, artifact, calendar_event, calendar_connection, work_block_template, task_timebox, task_run, work_adjustment, insight, preference item, preference context, preference catalog, preference judgment, preference signal, questionnaire instrument, questionnaire run, self observation, operator_overview, operator_context, calendar_overview, sleep_overview, sports_overview, training_load, weight_loss, movement, life_force, workbench, psyche_value, behavior_pattern, behavior, belief_entry, mode_profile, mode_guide_session, flashcard, trigger_report, event_type, emotion_definition, sleep_session, or workout_session. identify the exact Forge object or specialized surface, keep the main conversation natural, guide psyche intake with active listening before storing it, and for psyche issues that need understanding first usually begin with one exploratory question before any formulation or save suggestion.
 ---
 
 Forge is the user's structured system for planning work, doing work, reflecting on patterns, and keeping a truthful record of what is happening. Use it when the user is clearly working inside that system, or when they are describing something that naturally belongs there and would benefit from being stored, updated, reviewed, or acted on in Forge. Keep the conversation natural first. Do not turn every message into intake. When a real Forge entity is clearly present, name the exact entity type plainly, help with the substance of the conversation, and then offer Forge once, lightly, if storing it would genuinely help.
@@ -59,7 +59,7 @@ PM surface rule:
   human/bot ownership filters.
 - Guided modal flows handle create, edit, move, link, and closeout actions.
 
-Forge has four major stored-entity surfaces, read-model surfaces, and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, the read-only training-load surface for cardiovascular load and HR zone review, the weight-loss and nutrition workflow, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, flashcards, trigger reports, event types, reusable emotion definitions, questionnaire instruments, questionnaire runs, and the note-backed self-observation calendar. Read-model surfaces include `operator_overview`, `operator_context`, `calendar_overview`, `sleep_overview`, `sports_overview`, `training_load`, `weight_loss`, and the self-observation calendar; ask what practical decision the read should support before adding write-shaped questions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
+Forge has four major stored-entity surfaces, read-model surfaces, specialized CRUD surfaces, and three specialized domain surfaces. The planning side covers goals, projects, strategies, tasks, habits, notes, calendar events, recurring work blocks, task timeboxes, live work sessions, and agent-authored insights. The Health side covers sleep sessions, sports and workout sessions, the read-only training-load surface for cardiovascular load and HR zone review, the weight-loss and nutrition workflow, companion pairing, and habit-generated workout records that should still stay linked to the broader Forge graph. The Preferences side covers contextual taste modeling, pairwise comparisons, direct signals, editable concept libraries, and preference items that can come from Forge entities or seeded concept domains such as food, activities, places, countries, fashion, people, media, and tools. The Psyche side covers values, patterns, behaviors, beliefs, modes, guided mode sessions, flashcards, trigger reports, event types, reusable emotion definitions, questionnaire instruments, questionnaire runs, and the note-backed self-observation calendar. Read-model surfaces include `operator_overview`, `operator_context`, `calendar_overview`, `sleep_overview`, `sports_overview`, `training_load`, `weight_loss`, and the self-observation calendar; ask what practical decision the read should support before adding write-shaped questions. The specialized domain surfaces are Movement, Life Force, and Workbench; agents must use their dedicated route families instead of forcing them through batch CRUD. Forge also has a SQLite-backed Wiki memory layer with explicit spaces, Markdown content in database rows, backlinks, optional embeddings, and structured links back to Forge entities. The Artifact Store is a specialized CRUD surface for trusted stored files such as spreadsheets, documents, PDFs, text, structured text, and images; artifact relationships use the general `entity_links` model, and agents must not download, open, execute, preview, or transform stored file bytes. Forge is also multi-user: every entity can belong to a typed `human` or `bot` user through `userId`, and read routes can scope to one or many users with `userId` or repeated `userIds`. The current access posture is configurable through a directional user graph, but the live default is still permissive: Forge can list users directly, every relationship edge starts open, and a user can read or affect another user's linked records when the route explicitly asks for them. Use `forge_get_user_directory` when owner identity or cross-user access matters. Strategies can also be locked into a contract with `isLocked`; once locked, do not mutate the graph or target structure unless the user explicitly wants the strategy unlocked first. The model should use the real entity names, not vague substitutes. Say `project`, not “initiative”. Say `behavior_pattern`, not “theme”. Say `trigger_report`, not “incident note”.
 Habits are a first-class recurring entity in the planning side.
 NEGATIVE HABIT CHECK-IN RULE: for a `negative` habit, the correct aligned/resisted outcome is `missed`. `missed` means the bad habit was resisted, the user stayed aligned, and the habit should award its XP bonus.
 
@@ -78,12 +78,40 @@ save confirmation. Report product actions such as "saved the belief", "corrected
 missing stay", "updated the weekday energy pattern", or "read the failed node" before
 any route-key or endpoint detail.
 
+Use the known-target fast path when the user already supplied the object, action, and
+likely lane. For normal entities, ask only for parent, owner, or duplicate-disambiguation that changes the write. For task hierarchy, ask only for the project,
+issue, or parent task that changes placement. For Movement, ask only for the missing
+interval, boundary, saved object, or confirmation. For Life Force, ask only for the
+weekday, profile field, signal intensity, or planning effect. For Workbench, ask only
+for the missing flow, run, node, input, output, or preservation choice. For direct
+Psyche saves, ask one accuracy or consent question instead of restarting exploration.
+
+Use the active-listening turn contract before deepening: reflect the specific stake,
+working shape, or product object in one sentence; decide internally whether the next
+answer would change wording, placement, timing, route scope, support action,
+verification read, preservation choice, or consent; then ask one question. For Psyche,
+name the felt stake, protection, prediction, payoff, cost, or value conflict, and when
+a functional loop or belief sentence is already visible, offer one tentative
+hypothesis plus one fit-or-correction question instead of another broad exploration.
+For logistical records, keep the reflection short and ask for the operational detail.
+
+Use the route execution handoff before any read, write, run, repair, or publish call:
+freeze the accepted user-facing target, choose exactly one lane, use batch CRUD only
+for catalog entities, use named tools or documented routes for specialized CRUD and
+action workflows, and for Movement, Life Force, Workbench, or Artifact Store verify `routeKey`,
+method, path, and `pathParams` from live onboarding `methodRoutes` before calling.
+Never hide placeholders in `query` or `body`, and never guess a nearby path.
+
 - Batch CRUD is the default for normal stored entities, including `goal`, `project`,
   `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`,
   `work_block_template`, `task_timebox`, all main Psyche records, basic Preferences
   CRUD records, `questionnaire_instrument`, `sleep_session`, and `workout_session`.
-- `wiki_page` and `calendar_connection` are specialized CRUD surfaces. Use the wiki
-  tools for wiki pages and the calendar connection tools for provider setup and sync.
+- `wiki_page`, `calendar_connection`, and `artifact` are specialized CRUD surfaces.
+  Use the wiki tools for wiki pages, the calendar connection tools for provider setup
+  and sync, and the Artifact Store route family for trusted file upload, metadata,
+  static scan, LLM metadata enrichment, generic entity links, trust state, versions,
+  and audit. Batch CRUD may search, update, delete, and restore artifact metadata, but
+  it must not create file artifacts or access file bytes.
 - `task_run`, `work_adjustment`, `questionnaire_run`, `preference_judgment`,
   `preference_signal`, and `self_observation` are action workflows. Use their
   dedicated tools or note-backed write model instead of generic entity create/update
@@ -97,6 +125,12 @@ any route-key or endpoint detail.
   exact `/api/v1/*` route or OpenClaw `/forge/v1/*` mirror published in onboarding.
   Life Force may be keyed as `lifeForce` and as the entity-style alias `life_force`;
   both point to the same `/api/v1/life-force/*` route family.
+- Artifact Store route keys live under
+  `forge_get_agent_onboarding.entityRouteModel.specializedCrudEntities.artifact`.
+  When the adapter exposes `forge_call_artifact_route`, use it for artifact list,
+  trusted upload, metadata update, static rescan, LLM enrichment, generic entity-link
+  replacement, trust state, versions, or audit. Do not expose or call the download
+  route from agent tools; downloads are human-operator-only.
 - The live onboarding `routeKeys` list, `methodRoutes` map, and specialized
   route-key tool schemas include the exact route-key to method/path map. Use
   `routeKeys` for the allowed names and `methodRoutes` as the
@@ -186,6 +220,16 @@ Concrete route-key examples for internal use:
   `{"routeKey":"runByPayload","body":{"flow":{"title":"One-off digest","nodes":[]},"input":{"topic":"question flow quality"}}}`
 - Workbench flow chat follow-up:
   `{"routeKey":"chatFlow","pathParams":{"id":"flow_research_digest"},"body":{"message":"Refine the summary around API route risks and keep the published output stable."}}`
+- Artifact metadata list:
+  `{"routeKey":"list","query":{"query":"thesis budget","formatFamily":"spreadsheet","limit":20}}`
+- Artifact trusted upload:
+  `{"routeKey":"createWithBytes","body":{"originalFileName":"budget.xlsx","contentBase64":"<base64>","title":"Thesis budget workbook","sourceLabel":"Uploaded by the operator from local files","useLlmEnrichment":true,"links":[{"entityType":"project","entityId":"project_thesis","relationship":"evidence"}]}}`
+- Artifact generic entity-link replacement:
+  `{"routeKey":"replaceGenericLinks","pathParams":{"id":"artifact_123"},"body":{"links":[{"entityType":"wiki_page","entityId":"note_thesis_budget","relationship":"embedded_reference"}]}}`
+- Artifact audit read:
+  `{"routeKey":"audit","pathParams":{"id":"artifact_123"}}`
+- Artifact forbidden agent action:
+  do not call `/api/v1/artifacts/:id/download`; hand the human to the Forge web app for download.
 
 Preferences rule:
 
@@ -289,6 +333,14 @@ Entity conversation rule:
   route lane, target object, correction, link, verification read, run/publish/preserve
   action, or consent. If the question would only add warmth, completeness, optional
   metadata, or form polish, skip it, summarize what is clear, and act or close.
+- Use the user-facing wording guard after openings, reads, writes, and confirmations:
+  do not say "that sounds important" unless you name the specific stake; do not ask
+  "what would you like to do with this?" when the user's verb or the read result
+  already makes one next action visible; replace endpoint, payload, mutation, batch
+  route, and route key language with product nouns such as missing stay, weekday
+  energy curve, saved flow, failed run, node output, belief sentence, pattern,
+  flashcard, wiki page, calendar connection, or task run; if no answer-changing
+  uncertainty remains, summarize the product result and stop.
 - Treat partial answers as progress. Before another follow-up, identify what is
   already usable: operation, entity or surface, target record or time span, working
   wording, owner or placement, route lane, and consent. Ask only for the first missing
@@ -915,6 +967,7 @@ When the user asks which Forge tools are available, list exactly these tools:
 `forge_call_movement_route`
 `forge_call_life_force_route`
 `forge_call_workbench_route`
+`forge_call_artifact_route`
 `forge_get_user_directory`
 `forge_get_ui_entrypoint`
 `forge_get_psyche_overview`