forge-openclaw-plugin 0.3.15 → 0.3.17

package/dist/server/{server → apps/api}/src/app.js

@@ -45,6 +45,7 @@ import { getGamificationAssetStatus, installGamificationAssetStyle } from "./ser
 import { getInsightsPayload } from "./services/insights.js";
 import { buildLifeForcePayload, createFatigueSignal, listLifeForceTemplates, resolveLifeForceUser, updateLifeForceProfile, updateLifeForceTemplate } from "./services/life-force.js";
 import { createEntities, deleteEntities, deleteEntity, getSettingsBinPayload, restoreEntities, searchEntities, updateEntities } from "./services/entity-crud.js";
+import { artifactEnrichmentRequestSchema, artifactListQuerySchema, artifactMetadataPatchSchema, artifactTrustPatchSchema, artifactUploadSchema, createArtifactFromUpload, entityLinkInputSchema, enrichArtifactWithLlm, getArtifactById, listArtifactAuditEvents, listArtifactVersions, listArtifacts, patchArtifactTrust, readArtifactDownload, replaceArtifactEntityLinks, rescanArtifact, updateArtifactMetadata } from "./services/artifacts.js";
 import { getPsycheOverview } from "./services/psyche.js";
 import { getPsycheMetricsViewData, syncDevrageMetricHistoryIfNeeded } from "./services/devrage.js";
 import { exportPsycheObservationCalendar, getPsycheObservationCalendar } from "./services/psyche-observation-calendar.js";
@@ -2219,6 +2220,9 @@ function classifyOnboardingEntity(entityType) {
     if (entityType === "wiki_page" || entityType === "calendar_connection") {
         return "specialized_crud_entity";
     }
+    if (entityType === "artifact") {
+        return "specialized_crud_entity";
+    }
     if (entityType === "movement" ||
         entityType === "life_force" ||
         entityType === "workbench") {
@@ -2243,6 +2247,8 @@ function buildPreferredMutationPath(entityType) {
             return "Use /api/v1/wiki/pages with POST or PATCH for page CRUD.";
         case "calendar_connection":
             return "Use /api/v1/calendar/discovery or /api/v1/calendar/macos-local/discovery before setup when needed; use /api/v1/calendar/connections with POST, PATCH, DELETE, rediscovery, and sync for connection lifecycle work.";
+        case "artifact":
+            return "Use POST /api/v1/artifacts for trusted file upload, GET/PATCH /api/v1/artifacts/:id for metadata, POST /api/v1/artifacts/:id/links for generic entity links, POST /api/v1/artifacts/:id/scan for static rescans, POST /api/v1/artifacts/:id/enrich for optional LLM metadata enrichment, POST /api/v1/artifacts/:id/trust for trusted state changes, GET /api/v1/artifacts/:id/versions and /audit for history, and GET /api/v1/artifacts/:id/download only for human operator downloads. Batch CRUD may search, patch metadata, soft-delete, restore, and hard-delete metadata only; it must not create file artifacts or download bytes.";
         case "task_run":
             return "Use the task-run action routes to start, heartbeat, focus, complete, or release live work.";
         case "questionnaire_run":
@@ -2288,6 +2294,8 @@ function buildPreferredMutationTool(entityType) {
             return "forge_upsert_wiki_page";
         case "calendar_connection":
             return "forge_connect_calendar_provider | forge_sync_calendar_connection | mirrored calendar connection routes";
+        case "artifact":
+            return "forge_call_artifact_route | forge_search_entities | forge_update_entities | forge_delete_entities | forge_restore_entities";
         case "task_run":
             return "forge_start_task_run | forge_heartbeat_task_run | forge_focus_task_run | forge_complete_task_run | forge_release_task_run";
         case "questionnaire_run":
@@ -2324,6 +2332,8 @@ function buildPreferredReadPath(entityType) {
             return "/api/v1/wiki/pages/:id";
         case "calendar_connection":
             return "/api/v1/calendar/connections";
+        case "artifact":
+            return "/api/v1/artifacts";
         case "task_run":
             return "/api/v1/operator/context";
         case "questionnaire_run":
@@ -2974,6 +2984,75 @@ const AGENT_ONBOARDING_ENTITY_CATALOG = [
             }
         ]
     }),
+    enrichOnboardingEntityGuide({
+        entityType: "artifact",
+        purpose: "A trusted stored file artifact with precise metadata, provenance, static safety scan results, optional LLM-assisted metadata enrichment, generic links to other Forge entities, version history, audit events, and human-only download access.",
+        minimumCreateFields: ["originalFileName", "contentBase64"],
+        relationshipRules: [
+            "Artifact file upload is not batch CRUD. Use POST /api/v1/artifacts so Forge can enforce trust, store bytes content-addressably, run static inspection, preserve provenance, and create the metadata record.",
+            "Artifact relationships use the general entity_links model and are exposed as artifact.links with sourceEntityType/sourceEntityId and targetEntityType/targetEntityId; do not invent artifact-specific link routes or relationship semantics.",
+            "Batch CRUD can search, patch metadata, soft-delete, restore, or hard-delete artifact metadata, but it must not create file artifacts or transfer bytes.",
+            "Only trusted human sessions or trusted/autonomous agent tokens with artifact.create and artifact.uploadBytes may upload bytes.",
+            "Agents must not download, open, execute, transform, parse with external programs, or autonomously run stored files. GET /api/v1/artifacts/:id/download is for human operator sessions only.",
+            "LLM enrichment may fill missing title, shortDescription, description, tags, and danger interpretation from safe metadata and static text samples; it must never lower the deterministic scanner danger score."
+        ],
+        searchHints: [
+            "Before uploading, ask only for missing decision-critical metadata: what the file is, why it should be preserved, where it came from, and which Forge records it should stay linked to.",
+            "If the user gave a file but no metadata, accept a concise title and provenance as enough; optional tags and links can be added later.",
+            "If the file may be sensitive or risky, confirm whether it should be stored at all and whether download should remain disabled or human-only.",
+            "For a review request, list or read artifact metadata and safety findings first; do not ask for upload details unless the user is adding a file."
+        ],
+        fieldGuide: [
+            {
+                name: "title",
+                type: "string",
+                required: false,
+                description: "Human-readable artifact title. LLM enrichment may fill it when missing."
+            },
+            {
+                name: "shortDescription",
+                type: "string",
+                required: false,
+                description: "Compact display summary. LLM enrichment may fill it when missing."
+            },
+            {
+                name: "description",
+                type: "string",
+                required: false,
+                description: "Longer purpose, provenance, and retrieval context."
+            },
+            {
+                name: "originalFileName",
+                type: "string",
+                required: true,
+                description: "Original user-facing filename; extension must be allowed."
+            },
+            {
+                name: "contentBase64",
+                type: "string",
+                required: true,
+                description: "Base64 bytes sent only through the dedicated artifact upload route."
+            },
+            {
+                name: "sourceLabel",
+                type: "string",
+                required: false,
+                description: "Provenance label such as source, project, export, or sender."
+            },
+            {
+                name: "links",
+                type: "Array<{ entityType, entityId, anchorKey?, relationship? }>",
+                required: false,
+                description: "Generic Forge entity links stored through entity_links."
+            },
+            {
+                name: "useLlmEnrichment",
+                type: "boolean",
+                required: false,
+                description: "When true and an LLM profile is configured, Forge fills missing metadata from safe scan context."
+            }
+        ]
+    }),
     enrichOnboardingEntityGuide({
         entityType: "movement",
         purpose: "The specialized Movement surface for day, month, all-time, timeline, trip, place, selection, settings, and manual overlay work.",
@@ -3105,6 +3184,7 @@ const AGENT_ONBOARDING_CONVERSATION_RULES = [
     "If the user already answered the normal opening question, do not repeat it. Move to the next missing clarification.",
     "Do not over-therapize logistical entities. For tasks, calendar events, work blocks, timeboxes, and task runs, one brief confirming sentence plus one question is usually enough.",
     "After each substantive answer, briefly say what is becoming clearer and ask only for the next thing that still changes the record shape or usefulness.",
+    "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.",
     "Before asking a follow-up, know what the user's answer would change: save, update, review, link, schedule, correct, run, publish, preserve, enrich, open the UI, or stop. If no possible answer would change the next action, summarize and act instead of asking.",
     "Use a minimum save-readiness checkpoint before asking another follow-up. For normal batch entities, act when you have accepted wording, meaningful body, and any ownership or placement that changes later use; do not ask for tags, links, priority, dates, assignees, or status just because optional fields exist. For operational records, act when the target action plus the time, object, or state that makes it truthful is clear. For read-model surfaces, read once the practical question and answer-changing scope are clear. For specialized Movement, Life Force, and Workbench writes, act once the lane plus target span/object/weekday/flow/run/node and intended correction or effect are clear.",
     "For strategic, reflective, or emotionally meaningful non-Psyche records, ask what feels important to keep true before you ask for labels, dates, or taxonomy.",
@@ -3122,6 +3202,8 @@ const AGENT_ONBOARDING_CONVERSATION_RULES = [
     "For read and overview requests, ask for human or bot user scope only when the answer would meaningfully differ across owners; otherwise keep the next question focused on the user's practical question.",
     "The opening question should help the user understand what they are actually trying to save, decide, review, or change, not make them perform the schema out loud.",
     "If the user already named the exact correction in usable language, confirm only the missing scope, timing, or route-selecting detail that still matters, then act.",
+    "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 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, or Workbench 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.",
     "Keep API and architecture nouns out of user-facing questions unless the user asks about implementation. Do not ask the user about surfaces, route families, CRUD, payloads, mutation paths, or read paths; ask about the human object such as a wiki page, note, trigger report, behavior pattern, belief, mode, movement timeline, energy model, weekday pattern, flow, run, or node result.",
     "Self-observation is not the default container for Psyche material. Use it only for a lightweight observed event note; prefer trigger_report for one emotionally meaningful episode, behavior_pattern for a recurring loop and functional analysis, behavior for one repeated move, belief_entry for a core sentence, mode_guide_session or mode_profile for an active part-state, flashcard for a brief rehearsable reminder to use during a trigger or urge, and wiki_page for durable memory.",
     "Do not bury schema work in self-observation. If the user is describing a schema theme, preserve it through a belief_entry, behavior_pattern, mode_profile, mode_guide_session, trigger_report, or wiki_page depending on whether it appears as a rule, loop, part-state, live exploration, one episode, or durable explanation.",
@@ -4298,6 +4380,20 @@ export const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         ],
         example: '{"sourceKind":"url","sourceUrl":"https://example.com/article","titleHint":"Research import","parseStrategy":"auto","entityProposalMode":"suggest"}'
     },
+    {
+        toolName: "forge_call_artifact_route",
+        summary: "Call one allowed Artifact Store route for trusted file upload, metadata, scans, enrichment, generic entity links, trust state, versions, or audit.",
+        whenToUse: "Use for artifact list/read/update/upload flows after the user wants a file preserved or reviewed as metadata. Use shared batch CRUD only for artifact metadata search/update/delete/restore. Do not use this tool to download, open, preview, execute, or transform file bytes.",
+        inputShape: '{ routeKey: "list"|"createWithBytes"|"readMetadata"|"updateMetadata"|"rescan"|"enrichWithLlm"|"replaceGenericLinks"|"trustState"|"versions"|"audit", pathParams?: { id?: string }, query?: object, body?: object }',
+        requiredFields: ["routeKey"],
+        notes: [
+            "The download route is intentionally absent from the agent tool surface; it is human-operator-only.",
+            "For createWithBytes, the body must include originalFileName and contentBase64, and the actor must be trusted and scoped for artifact byte upload.",
+            "For replaceGenericLinks, links are generic entity link inputs identifying target entityType, entityId, optional anchorKey, and relationship.",
+            "Optional LLM enrichment can fill missing metadata, but it must not lower the deterministic scanner danger score."
+        ],
+        example: '{"routeKey":"replaceGenericLinks","pathParams":{"id":"artifact_123"},"body":{"links":[{"entityType":"wiki_page","entityId":"note_budget_model","relationship":"embedded_reference","anchorKey":"budget-workbook"}]}}'
+    },
     {
         toolName: "forge_get_sleep_overview",
         summary: "Read the sleep surface with recent nights, scores, regularity, stage averages, and linked reflective context.",
@@ -4721,7 +4817,13 @@ function buildAgentOnboardingPayload(request) {
             "psyche.write",
             "psyche.note",
             "psyche.insight",
-            "psyche.mode"
+            "psyche.mode",
+            "artifact.readMetadata",
+            "artifact.create",
+            "artifact.uploadBytes",
+            "artifact.updateMetadata",
+            "artifact.link",
+            "artifact.enrichWithLlm"
         ],
         recommendedTrustLevel: "trusted",
         recommendedAutonomyMode: "approval_required",
@@ -4771,6 +4873,7 @@ function buildAgentOnboardingPayload(request) {
             taskRun: "A live work session attached to a task. Start, heartbeat, focus, complete, and release runs instead of faking work with status alone.",
             note: "A Markdown work note that can link to one or many entities. Use notes for progress evidence, context, and close-out summaries.",
             wiki: "KarpaWiki is the SQLite-backed memory layer: Markdown content in notes rows plus media, backlinks, optional embeddings, explicit spaces, and structured links back to Forge entities.",
+            artifact: "Artifacts are trusted stored files such as spreadsheets, documents, PDFs, text, structured text, or images. Forge stores bytes content-addressably, records provenance and metadata, runs static safety scans, exposes generic entity links, and serves downloads only to human operator sessions. Agents may upload only when trusted and scoped, and must not autonomously download, open, execute, or transform stored files.",
             sleepSession: "A sleep session is a first-class health record with timing, sleep and bed duration, stage breakdown, recovery metrics, annotations, and Forge links back to planning or Psyche context.",
             workoutSession: "A workout session is a first-class sports record imported from HealthKit or generated from a habit. It holds workout type, timing, energy or distance when available, subjective effort, narrative context, and Forge links.",
             preferences: "Forge Preferences is the explicit taste-modeling domain. It has workspaces, contexts, concept libraries, direct items, pairwise judgments, direct signals, and inferred scores.",
@@ -4820,6 +4923,7 @@ function buildAgentOnboardingPayload(request) {
             "Habits are recurring records that can connect directly to goals, projects, tasks, and durable Psyche entities.",
             "Task runs represent live work sessions on tasks and are separate from task status.",
             "Notes can link to one or many entities and are the canonical place for Markdown progress context or close-out evidence.",
+            "Artifacts are linkable stored entities backed by the general entity_links model; use generic entity links to attach a file to goals, projects, tasks, wiki-backed notes, Psyche records, calendar records, or other meaningful Forge context.",
             "Psyche values can link to goals, projects, and tasks.",
             "Behavior patterns, behaviors, beliefs, modes, flashcards, and trigger reports cross-link to describe one reflective model rather than isolated records.",
             "Insights can point at one entity, but they exist to capture interpretation or advice rather than raw work items."
@@ -4877,6 +4981,55 @@ function buildAgentOnboardingPayload(request) {
                     update: "/api/v1/calendar/connections/:id",
                     sync: "/api/v1/calendar/connections/:id/sync",
                     delete: "/api/v1/calendar/connections/:id"
+                },
+                artifact: {
+                    list: "/api/v1/artifacts",
+                    createWithBytes: "/api/v1/artifacts",
+                    readMetadata: "/api/v1/artifacts/:id",
+                    updateMetadata: "/api/v1/artifacts/:id",
+                    humanDownloadOnly: "/api/v1/artifacts/:id/download",
+                    rescan: "/api/v1/artifacts/:id/scan",
+                    enrichWithLlm: "/api/v1/artifacts/:id/enrich",
+                    replaceGenericLinks: "/api/v1/artifacts/:id/links",
+                    trustState: "/api/v1/artifacts/:id/trust",
+                    versions: "/api/v1/artifacts/:id/versions",
+                    audit: "/api/v1/artifacts/:id/audit",
+                    batchMetadata: {
+                        search: "/api/v1/entities/search",
+                        updateMetadata: "/api/v1/entities/update",
+                        deleteMetadata: "/api/v1/entities/delete",
+                        restoreMetadata: "/api/v1/entities/restore"
+                    },
+                    routeKeys: [
+                        "list",
+                        "createWithBytes",
+                        "readMetadata",
+                        "updateMetadata",
+                        "rescan",
+                        "enrichWithLlm",
+                        "replaceGenericLinks",
+                        "trustState",
+                        "versions",
+                        "audit"
+                    ],
+                    methodRoutes: {
+                        list: { method: "GET", path: "/api/v1/artifacts" },
+                        createWithBytes: { method: "POST", path: "/api/v1/artifacts" },
+                        readMetadata: { method: "GET", path: "/api/v1/artifacts/:id" },
+                        updateMetadata: { method: "PATCH", path: "/api/v1/artifacts/:id" },
+                        rescan: { method: "POST", path: "/api/v1/artifacts/:id/scan" },
+                        enrichWithLlm: { method: "POST", path: "/api/v1/artifacts/:id/enrich" },
+                        replaceGenericLinks: { method: "POST", path: "/api/v1/artifacts/:id/links" },
+                        trustState: { method: "POST", path: "/api/v1/artifacts/:id/trust" },
+                        versions: { method: "GET", path: "/api/v1/artifacts/:id/versions" },
+                        audit: { method: "GET", path: "/api/v1/artifacts/:id/audit" }
+                    },
+                    safetyRules: [
+                        "Do not expose the download route to agent tools. It is a human operator route only.",
+                        "Do not execute, preview, parse externally, or transform stored file bytes autonomously.",
+                        "Use general entity links for relationships; do not create artifact-specific link models.",
+                        "Use batch CRUD only for artifact metadata search/update/delete/restore, never for file-byte creation."
+                    ]
                 }
             },
             actionEntities: {
@@ -5268,7 +5421,7 @@ function buildAgentOnboardingPayload(request) {
                 ],
                 verifyCommands: [
                     `curl -s ${origin}/api/v1/health`,
-                    "openclaw plugins install --link --dangerously-force-unsafe-install ./projects/forge/openclaw-plugin",
+                    "openclaw plugins install --link --dangerously-force-unsafe-install ./projects/forge/plugins/openclaw",
                     "openclaw plugins inspect forge-openclaw-plugin --runtime",
                     "openclaw gateway restart",
                     "openclaw forge onboarding",
@@ -5381,6 +5534,15 @@ function buildAgentOnboardingPayload(request) {
             workbenchRunDetail: "/api/v1/workbench/flows/:id/runs/:runId",
             workbenchNodeResult: "/api/v1/workbench/flows/:id/runs/:runId/nodes/:nodeId",
             workbenchLatestNodeOutput: "/api/v1/workbench/flows/:id/nodes/:nodeId/output",
+            artifacts: "/api/v1/artifacts",
+            artifactDetail: "/api/v1/artifacts/:id",
+            artifactDownloadHumanOnly: "/api/v1/artifacts/:id/download",
+            artifactScan: "/api/v1/artifacts/:id/scan",
+            artifactEnrich: "/api/v1/artifacts/:id/enrich",
+            artifactEntityLinks: "/api/v1/artifacts/:id/links",
+            artifactTrust: "/api/v1/artifacts/:id/trust",
+            artifactVersions: "/api/v1/artifacts/:id/versions",
+            artifactAudit: "/api/v1/artifacts/:id/audit",
             wikiSettings: "/api/v1/wiki/settings",
             wikiSearch: "/api/v1/wiki/search",
             wikiHealth: "/api/v1/wiki/health",
@@ -5426,6 +5588,13 @@ function buildAgentOnboardingPayload(request) {
                 "forge_call_life_force_route",
                 "forge_call_workbench_route"
             ],
+            artifactWorkflow: [
+                "forge_call_artifact_route",
+                "forge_search_entities",
+                "forge_update_entities",
+                "forge_delete_entities",
+                "forge_restore_entities"
+            ],
             entityWorkflow: [
                 "forge_search_entities",
                 "forge_create_entities",
@@ -5492,9 +5661,10 @@ function buildAgentOnboardingPayload(request) {
             depthCalibrationRule: "Before deepening an intake, decide whether this is quick capture, guided formulation, review-first help, or action-first execution. Quick capture means the user already supplied usable wording and wants it saved, remembered, or logged; reflect the working shape once, ask only the one structural, accuracy, or consent detail that changes the write, and do not force full exploration. Guided formulation means the user asks to understand, name, map, decide, or work through unclear or charged material; use active listening, one lane at a time, and Psyche hypotheses when appropriate before saving. Review-first means read the relevant stored entity, overview, or specialized surface before asking write-shaped questions. Action-first means the target task run, work adjustment, preference signal or judgment, questionnaire run, Movement correction, Life Force signal or weekday template, or Workbench run or output is already clear, so act or ask only for the missing target, span, flow, run, node, weekday, correction, or consent. Do not downgrade psychologically meaningful material into quick capture when the user wants exploration, and do not expand a simple storage request into therapy or project planning.",
             operationLaneRule: "Keep the operation lane explicit before asking for lower-level details. Normal stored entities can be added, updated, reviewed or navigated, linked, or placed. Action workflows use verbs such as start, continue, complete, adjust, judge, signal, publish, sync, or observe. Specialized CRUD surfaces use lifecycle verbs such as create, read, update, sync, reconnect, delete, or browse. Read-model surfaces need a practical read question and scope before any write-shaped follow-up. Movement, Life Force, and Workbench use review, correct, repair, run, inspect, publish, or preserve lanes through their dedicated route keys. Psyche entities need a formulation lane before the storage lane when the user wants understanding; direct saves can move to one accuracy or consent question.",
             psycheExplorationRule: "When a Psyche entity needs understanding first, begin with one exploratory question before any working formulation, replacement belief, suggested title, or save pitch. Keep the opening reflection to one or two short sentences, stay in plain prose instead of bullets or numbered lists, keep that first reply short, do not mention Forge search or save structure yet, avoid colons or list-shaped phrasing, prefer what/when/how over why until the experience is grounded, wait for the user's answer before offering a fuller formulation, ask permission before moving from charged exploration into naming or challenge when needed, make the next question help the user feel more able to name the experience rather than more examined, do not widen into adjacent entities until the current one has a working sentence the user recognizes, and once the lived experience is coherent stop deepening and help the user name it cleanly. After one concrete example is clear and a hypothesis lands or is corrected, translate it into a saveable record shape such as a belief sentence, functional loop, behavior, mode, trigger report, value, event type, or emotion definition; do not leave the user with interpretation alone, name the primary Forge record it is becoming, and ask one accuracy or consent question instead of reopening broad exploration, then use the shared batch entity routes after the user accepts the wording or explicitly asks to save. When the user is updating a Psyche record because of one fresh episode, anchor in that episode before renaming the durable formulation, begin with the smallest part of the old wording that no longer fits, and do not reopen the full origin story unless the new understanding is truly structural. If the user accepts the wording, move toward the save instead of reopening deeper exploration.",
-            progressiveDisclosureRule: "Treat partial answers as progress, not as failed intake. Before asking another question, identify what is already usable: operation, entity or surface, target record or time span, working wording, owner or placement, route lane, and consent. Say the usable part back briefly, then ask only for the first missing detail that changes the action: duplicate disambiguation, hierarchy parent, time window, weekday, flow, run, node, correction, link, or save consent. For normal batch entities, do not ask for optional tags, priority, status, dates, color, links, or assignees when the accepted wording and meaningful body are already enough unless that metadata changes accountability, retrieval, or execution. For Movement, Life Force, and Workbench, if the user's wording already implies the dedicated lane, skip the broad route-family question and ask only for the target span, place, weekday, profile field, flow, run, node, output, correction, or consent that is still missing. For direct Psyche saves or updates, treat an offered belief sentence, functional loop, part voice, trigger episode, value phrase, event kind, emotion signature, or flashcard message as real data; ask one accuracy or consent question instead of reopening origin, evidence, or repair.",
+            progressiveDisclosureRule: "Treat partial answers as progress, not as failed intake. Before asking another question, identify what is already usable: operation, entity or surface, target record or time span, working wording, owner or placement, route lane, and consent. Say the usable part back briefly, then ask only for the first missing detail that changes the action: duplicate disambiguation, hierarchy parent, time window, weekday, flow, run, node, correction, link, or save consent. Use the known-target fast path when the user's wording already names the object and action: for normal entities ask only for parent, owner, or duplicate disambiguation; for task hierarchy ask only for the project, issue, or parent task; 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 normal batch entities, do not ask for optional tags, priority, status, dates, color, links, or assignees when the accepted wording and meaningful body are already enough unless that metadata changes accountability, retrieval, or execution. For Movement, Life Force, and Workbench, if the user's wording already implies the dedicated lane, skip the broad route-family question and ask only for the target span, place, weekday, profile field, flow, run, node, output, correction, or consent that is still missing. For direct Psyche saves or updates, treat an offered belief sentence, functional loop, part voice, trigger episode, value phrase, event kind, emotion signature, or flashcard message as real data; ask one accuracy or consent question instead of reopening origin, evidence, or repair.",
             writeConfirmationRule: "After create, update, delete, restore, run, read, or repair actions, confirm the user-facing record, action, and result in the user's language instead of reopening intake. For batch creates and updates, confirm the working title or accepted wording, container, and owner or placement only when those changed retrieval, accountability, or execution; if optional tags, priority, status, color, links, dates, or assignees were left provisional, say that plainly once instead of asking for all of them. For action workflows, confirm the real product action such as task run started or completed, work adjustment applied, preference judgment or signal submitted, questionnaire run updated or completed, calendar connection synced, or self-observation note written. For Psyche saves, confirm the accepted wording and whether it was saved as a first version, update, link, archive, or distinct version; do not reopen origin, evidence, repair, or adjacent entity mapping after the save unless that next object is already visible and materially useful. Ask a follow-up only if it changes the next action: correction, link, schedule, run, publish, enrichment, preservation choice, or UI handoff.",
             specializedSurfaceRule: "For Movement, Life Force, and Workbench, clarify the job first, then choose the dedicated route family internally and do not guess at a generic CRUD path. Use specializedDomainSurfaces.routeSelectionQuestions when they are present so the next follow-up selects the right route instead of asking generic questions. Before every dedicated call, run a route-contract handshake internally: select the product lane in plain language, verify the matching routeKey against live onboarding routeKeys and methodRoutes, fill any placeholders through pathParams, and ask the user only for the missing product noun that fills the placeholder. When available, use forge_call_movement_route, forge_call_life_force_route, or forge_call_workbench_route after the lane is clear. If a route-key tool is unavailable, stale, or missing the needed key, read live onboarding and use the exact specializedDomainSurfaces.methodRoutes entry for the selected lane; cross-check OpenAPI only to confirm the same method and path, do not fall back to generic batch CRUD, do not invent a nearby raw path, and treat schema disagreement as a Forge contract bug to fix. Before calling a specialized route, inspect its methodRoutes entry for placeholders such as :id, :weekday, :slug, :runId, :nodeId, or :pointId, then fill each one through pathParams with the same placeholder name; do not hide IDs in query, body, or routeKey. If the contract is missing a lane the product clearly supports, report a contract bug instead of silently using generic batch CRUD or a nearby route. In user-facing language, talk about timeline, overlay, weekday template, published output, run detail, or node result rather than surfaces, payloads, read paths, mutation paths, or CRUD. If the truth of the current state is still uncertain, read the relevant dedicated view before you mutate it. When the user already named a precise correction or review target, confirm only the route-selecting detail that is still missing. After a concrete Movement, Life Force, or Workbench correction, mutation, or result-producing run, read the relevant view back when the user is trying to understand the result rather than just store it: timeline or place/settings detail for Movement, the Life Force overview for energy-planning impact, and flow detail, run detail, node result, latest node output, published output, or run history for Workbench. After any dedicated read, translate the result into one next action: no change, Movement overlay/place/settings/link, Life Force workload/recovery/timebox/meeting/task-choice change, or Workbench rerun/node inspection/flow edit/publish/preserve/stop. Ask only for the missing span, place, weekday, flow, run, node, output, correction, preservation choice, or confirmation that would change that action. The canonical runtime routes stay under /api/v1/*, and the OpenClaw HTTP mirror exposes the same families under /forge/v1/movement, /forge/v1/life-force, and /forge/v1/workbench.",
+            artifactStoreRule: "For artifacts, ask only for the metadata that changes preservation and retrieval: what the file is, where it came from, why it should be kept, whether it should link to a Forge record, and whether optional LLM enrichment should fill missing title or description. Use dedicated Artifacts routes for upload, scan, enrichment, generic links, trust state, versions, and audit. Use batch CRUD only for artifact metadata search/update/delete/restore. Never download, open, run, execute, transform, or preview stored file bytes as an agent; downloads are human-operator-only.",
             reviewShortcutRule: "When the user is reviewing or correcting an existing record, ask what practical question they want the read or correction to answer, then narrow the saved object, timeframe, or route family first. Use the correct read posture before asking write-shaped questions: shared batch search or read hints for normal entities, wiki/calendar dedicated reads for specialized CRUD, read-model routes for overviews, and Movement, Life Force, or Workbench dedicated reads for those domain surfaces. After the read, answer the practical question before asking for any save, correction, link, run, enrichment, or publish detail, and state what the read rules in, rules out, or leaves uncertain. If several actions are possible, narrow to the one most directly supported by the read instead of handing the user a broad menu. Do not reopen the whole intake unless the user is actually redefining the record.",
             readModelWriteRule: "Self-observation is note-backed and should be written through observed notes with frontmatter.observedAt only when a lightweight episode observation is the right container. Do not use it as the default bucket for Psyche material: prefer trigger_report for one emotionally meaningful episode, behavior_pattern for functional analysis of a recurring loop, behavior for one repeated move, belief_entry for a core sentence, mode_guide_session or mode_profile for a central part-state, and wiki_page for durable memory such as books, articles, concepts, sources, or personal manuals. Sleep and workout sessions stay on batch CRUD by default; use the reflective review helpers only when enriching one already-known record after review.",
             psycheOpeningQuestionRule: "Prefer a concrete opening question tied to the entity: ask when the value mattered, what happened the last time the pattern appeared, what cue or body signal came first before the behavior, what the belief starts saying about self or outcome, what feels most at risk inside the mode, what the part is trying to get the user to do or stop doing, or where the shift began in the incident. Reflect briefly before the question, choose one follow-up lane at a time, say what is becoming clearer before the next deeper question, and if several Psyche entities are visible hold the adjacent ones lightly until the main container is clear.",
@@ -5523,7 +5693,7 @@ function buildAgentOnboardingPayload(request) {
             entityDeleteSummary: "Entity DELETE routes default to soft delete. Pass mode=hard only when permanent removal is intended. Immediate-delete entities skip the bin, and calendar-event deletes still remove remote projections downstream.",
             batchingRule: "forge_create_entities, forge_update_entities, forge_delete_entities, and forge_restore_entities all accept operations as arrays. Batch CRUD is the default for simple entities, so batch multiple related mutations together instead of reaching for a long list of entity-specific routes.",
             searchRule: "forge_search_entities accepts searches as an array. Search before create or update when duplicate risk exists.",
-            createRule: "Each create operation must include entityType and full data. entityType alone is not enough. This includes calendar_event, work_block_template, task_timebox, sleep_session, workout_session, preference CRUD entities, and questionnaire_instrument alongside the usual planning and Psyche entities.",
+            createRule: "Each create operation must include entityType and full data. entityType alone is not enough. This includes calendar_event, work_block_template, task_timebox, sleep_session, workout_session, preference CRUD entities, and questionnaire_instrument alongside the usual planning and Psyche entities. Artifact file-byte creation is the exception: use POST /api/v1/artifacts or forge_call_artifact_route createWithBytes, not batch create.",
             updateRule: "Each update operation must include entityType, id, and patch. For projects, lifecycle changes are status patches: active to restart, paused to suspend, completed to finish. Keep task and project scheduling rules on those same patch payloads. Official habit outcomes can also be logged through forge_update_entities by patching the habit with checkIn: { status, dateKey?, note?, description? } instead of route-hunting. Calendar-event updates still run downstream provider projection sync, and manual health-session field edits belong on the batch route by default rather than on the reflective review helpers.",
             specializedRouteToolRule: "forge_call_movement_route, forge_call_life_force_route, and forge_call_workbench_route expect { routeKey, pathParams?, query?, body? }. Choose routeKey from the tool schema or entityRouteModel.specializedDomainSurfaces, fill every methodRoutes placeholder with pathParams using names such as id, weekday, slug, runId, nodeId, or pointId, use query for read filters and userIds, and use body only for POST, PATCH, or PUT route keys. Do not put required IDs or weekdays inside routeKey, query, or body when the published path has a placeholder. The Life Force overview route key maps to GET /api/v1/life-force; do not invent /api/v1/life-force/overview. Normal stored entities still use the shared batch entity tools.",
             createExample: '{"operations":[{"entityType":"goal","data":{"title":"Create meaningfully"},"clientRef":"goal-create-1"},{"entityType":"goal","data":{"title":"Build a beautiful family"},"clientRef":"goal-create-2"}]}',
@@ -7469,6 +7639,197 @@ export async function buildServer(options = {}) {
         managers.authorization.requireAnyTokenScope(context, ["write", "insights"], detail);
         return context;
     };
+    const requireArtifactReadAccess = (headers, detail) => {
+        const context = authenticateRequest(headers);
+        managers.authorization.requireAuthenticatedActor(context, detail);
+        if (!context.session) {
+            managers.authorization.requireAnyTokenScope(context, ["artifact.readMetadata", "read"], detail);
+        }
+        return context;
+    };
+    const requireTrustedArtifactUploadAccess = (headers, detail) => {
+        const context = authenticateRequest(headers);
+        managers.authorization.requireAuthenticatedActor(context, detail);
+        if (!context.session) {
+            managers.authorization.requireAnyTokenScope(context, ["artifact.create"], detail);
+            managers.authorization.requireAnyTokenScope(context, ["artifact.uploadBytes"], detail);
+            if (context.token?.trustLevel !== "trusted" &&
+                context.token?.trustLevel !== "autonomous") {
+                throw new HttpError(403, "artifact_untrusted_agent", "Artifact uploads require a trusted agent identity.", {
+                    trustLevel: context.token?.trustLevel ?? null,
+                    requiredTrustLevels: ["trusted", "autonomous"],
+                    ...(detail ?? {})
+                });
+            }
+        }
+        return context;
+    };
+    const requireArtifactMetadataWriteAccess = (headers, detail) => {
+        const context = authenticateRequest(headers);
+        managers.authorization.requireAuthenticatedActor(context, detail);
+        if (!context.session) {
+            managers.authorization.requireAnyTokenScope(context, ["artifact.updateMetadata", "write"], detail);
+        }
+        return context;
+    };
+    const requireArtifactDownloadAccess = (headers, detail) => {
+        const context = authenticateRequest(headers);
+        managers.authorization.requireAuthenticatedOperator(context, detail);
+        return context;
+    };
+    const requireArtifactTrustAccess = (headers, detail) => {
+        const context = authenticateRequest(headers);
+        managers.authorization.requireAuthenticatedActor(context, detail);
+        if (!context.session) {
+            managers.authorization.requireAnyTokenScope(context, ["artifact.manageTrust", "artifact.overrideQuarantine"], detail);
+            if (context.token?.trustLevel !== "trusted" &&
+                context.token?.trustLevel !== "autonomous") {
+                throw new HttpError(403, "artifact_untrusted_agent", "Artifact trust overrides require a trusted agent identity.", {
+                    trustLevel: context.token?.trustLevel ?? null,
+                    requiredTrustLevels: ["trusted", "autonomous"],
+                    ...(detail ?? {})
+                });
+            }
+        }
+        return context;
+    };
+    app.get("/api/v1/artifacts", async (request) => {
+        requireArtifactReadAccess(request.headers, {
+            route: "/api/v1/artifacts"
+        });
+        return {
+            artifacts: listArtifacts(artifactListQuerySchema.parse(request.query ?? {}))
+        };
+    });
+    app.post("/api/v1/artifacts", { bodyLimit: 150 * 1024 * 1024 }, async (request, reply) => {
+        const auth = requireTrustedArtifactUploadAccess(request.headers, { route: "/api/v1/artifacts" });
+        const artifact = await createArtifactFromUpload(artifactUploadSchema.parse(request.body ?? {}), auth, { llm: managers.llm });
+        reply.code(201);
+        return { artifact };
+    });
+    app.get("/api/v1/artifacts/:id", async (request, reply) => {
+        requireArtifactReadAccess(request.headers, {
+            route: "/api/v1/artifacts/:id"
+        });
+        const { id } = request.params;
+        const artifact = getArtifactById(id);
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.patch("/api/v1/artifacts/:id", async (request, reply) => {
+        const auth = requireArtifactMetadataWriteAccess(request.headers, { route: "/api/v1/artifacts/:id" });
+        const { id } = request.params;
+        const artifact = updateArtifactMetadata(id, artifactMetadataPatchSchema.parse(request.body ?? {}), auth);
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.get("/api/v1/artifacts/:id/download", async (request, reply) => {
+        const auth = requireArtifactDownloadAccess(request.headers, { route: "/api/v1/artifacts/:id/download" });
+        const { id } = request.params;
+        const result = await readArtifactDownload(id);
+        if (!result) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        const fileName = result.artifact.originalFileName.replace(/["\\\r\n]/g, "_");
+        recordActivityEvent({
+            entityType: "artifact",
+            entityId: result.artifact.id,
+            eventType: "artifact.downloaded",
+            title: `Artifact downloaded: ${result.artifact.title}`,
+            description: "A human operator downloaded stored artifact bytes. Forge did not execute the file.",
+            actor: auth.actor ?? null,
+            source: auth.source,
+            metadata: {
+                contentSha256: result.artifact.contentSha256,
+                byteSize: result.artifact.byteSize
+            }
+        });
+        return reply
+            .header("content-type", result.artifact.detectedMimeType)
+            .header("content-length", String(result.bytes.byteLength))
+            .header("content-disposition", `attachment; filename="${fileName}"`)
+            .send(result.bytes);
+    });
+    app.post("/api/v1/artifacts/:id/scan", async (request, reply) => {
+        const auth = requireArtifactMetadataWriteAccess(request.headers, { route: "/api/v1/artifacts/:id/scan" });
+        const { id } = request.params;
+        const artifact = await rescanArtifact(id, auth);
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.post("/api/v1/artifacts/:id/enrich", async (request, reply) => {
+        const auth = requireArtifactMetadataWriteAccess(request.headers, { route: "/api/v1/artifacts/:id/enrich" });
+        if (!auth.session) {
+            managers.authorization.requireAnyTokenScope(auth, ["artifact.enrichWithLlm"], { route: "/api/v1/artifacts/:id/enrich" });
+        }
+        const { id } = request.params;
+        const artifact = await enrichArtifactWithLlm(id, artifactEnrichmentRequestSchema.parse(request.body ?? {}), auth, { llm: managers.llm });
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.post("/api/v1/artifacts/:id/links", async (request, reply) => {
+        const auth = requireArtifactMetadataWriteAccess(request.headers, { route: "/api/v1/artifacts/:id/links" });
+        if (!auth.session) {
+            managers.authorization.requireAnyTokenScope(auth, ["artifact.link"], {
+                route: "/api/v1/artifacts/:id/links"
+            });
+        }
+        const { id } = request.params;
+        const body = z
+            .object({ links: z.array(entityLinkInputSchema) })
+            .parse(request.body ?? {});
+        const artifact = replaceArtifactEntityLinks(id, body.links, auth);
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.post("/api/v1/artifacts/:id/trust", async (request, reply) => {
+        const auth = requireArtifactTrustAccess(request.headers, { route: "/api/v1/artifacts/:id/trust" });
+        const { id } = request.params;
+        const artifact = patchArtifactTrust(id, artifactTrustPatchSchema.parse(request.body ?? {}), auth);
+        if (!artifact) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { artifact };
+    });
+    app.get("/api/v1/artifacts/:id/versions", async (request, reply) => {
+        requireArtifactReadAccess(request.headers, {
+            route: "/api/v1/artifacts/:id/versions"
+        });
+        const { id } = request.params;
+        if (!getArtifactById(id)) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { versions: listArtifactVersions(id) };
+    });
+    app.get("/api/v1/artifacts/:id/audit", async (request, reply) => {
+        requireArtifactReadAccess(request.headers, {
+            route: "/api/v1/artifacts/:id/audit"
+        });
+        const { id } = request.params;
+        if (!getArtifactById(id)) {
+            reply.code(404);
+            return { error: "Artifact not found" };
+        }
+        return { events: listArtifactAuditEvents(id) };
+    });
     app.get("/api/health", async () => buildHealthPayload(taskRunWatchdog));
     app.get("/api/v1/health", async (request) => buildHealthPayload(taskRunWatchdog, {
         apiVersion: "v1",

package/dist/server/{server → apps/api}/src/connectors/box-registry.js

@@ -8,9 +8,9 @@ import { updateTask } from "../repositories/tasks.js";
 import { getOverviewContext } from "../services/context.js";
 import { searchEntities } from "../services/entity-crud.js";
 import { getWikiHealth, listWikiPages } from "../repositories/wiki-memory.js";
-import { executeCommonWorkbenchTool, mapWorkbenchTools } from "../../../src/lib/workbench/runtime.js";
-import { getWorkbenchNodeCatalog, getWorkbenchNodeDefinition } from "../../../src/lib/workbench/registry.js";
-import { normalizeWorkbenchPortDefinition } from "../../../src/lib/workbench/nodes.js";
+import { executeCommonWorkbenchTool, mapWorkbenchTools } from "../../../web/src/lib/workbench/runtime.js";
+import { getWorkbenchNodeCatalog, getWorkbenchNodeDefinition } from "../../../web/src/lib/workbench/registry.js";
+import { normalizeWorkbenchPortDefinition } from "../../../web/src/lib/workbench/nodes.js";
 function createSnapshotForConnectorOutput(boxId) {
     const outputId = boxId.replace(/^connector-output:/, "");
     const rows = getDatabase()

package/dist/server/{server → apps/api}/src/db.js

@@ -15,10 +15,29 @@ function dateOffsetIso(days) {
     date.setUTCDate(date.getUTCDate() + days);
     return date.toISOString().slice(0, 10);
 }
-const projectRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-const migrationsDir = path.join(projectRoot, "server", "migrations");
-const monorepoForgeDataRoot = path.resolve(projectRoot, "..", "..", "data", "forge");
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const apiRoot = path.resolve(moduleDir, "..");
+const migrationsDir = path.join(apiRoot, "migrations");
 const userSharedForgeDataRoot = path.join(os.homedir(), ".forge");
+function findSourceProjectRoot(startDir) {
+    let current = path.resolve(startDir);
+    while (true) {
+        if (existsSync(path.join(current, "package.json")) &&
+            existsSync(path.join(current, "apps", "api", "migrations")) &&
+            existsSync(path.join(current, "apps", "web", "src"))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+const sourceProjectRoot = findSourceProjectRoot(apiRoot);
+const monorepoForgeDataRoot = sourceProjectRoot
+    ? path.resolve(sourceProjectRoot, "..", "..", "data", "forge")
+    : null;
 function resolveCanonicalDataDir(root = dataRoot) {
     return path.resolve(root);
 }
@@ -72,7 +91,7 @@ export function resolveDefaultDataRoot(currentWorkingDir = process.cwd()) {
     // Inside the private monorepo, prefer the tracked shared Forge data root so
     // the local app, Hermes, OpenClaw, and repo-managed data all point at the
     // same state by default.
-    if (existsSync(monorepoForgeDataRoot)) {
+    if (monorepoForgeDataRoot && existsSync(monorepoForgeDataRoot)) {
         return monorepoForgeDataRoot;
     }
     return path.resolve(userSharedForgeDataRoot || currentWorkingDir);

package/dist/server/{server → apps/api}/src/health-weight-loss.js

@@ -4,7 +4,7 @@ import { getDatabase, runInTransaction } from "./db.js";
 import { getSettings } from "./repositories/settings.js";
 import { getDefaultUser, resolveUserForMutation } from "./repositories/users.js";
 import { readEncryptedSecret } from "./repositories/calendar.js";
-import { hallNiddkWeeklyRateKgToDailyEnergyAdjustment } from "../../src/lib/weight-loss-energy-model.js";
+import { hallNiddkWeeklyRateKgToDailyEnergyAdjustment } from "../../web/src/lib/weight-loss-energy-model.js";
 const ACTIVE_BASELINE_WINDOW_DAYS = 7;
 const optionalNumberSchema = z
     .union([z.coerce.number().finite(), z.null()])