forge-openclaw-plugin 0.2.24 → 0.2.26

package/dist/openclaw/session-bootstrap.d.ts

@@ -0,0 +1,78 @@
+import { type ForgePluginConfig } from "./api-client.js";
+import type { ForgePluginRegistrationApi } from "./plugin-sdk-types.js";
+type ForgeGoalRecord = {
+    id: string;
+    title: string;
+    description?: string | null;
+    status?: string;
+    horizon?: string | null;
+};
+type ForgeProjectRecord = {
+    id: string;
+    title: string;
+    description?: string | null;
+    status?: string;
+    goalId?: string | null;
+    goalTitle?: string | null;
+};
+type ForgeTaskRecord = {
+    id: string;
+    title: string;
+    description?: string | null;
+    status?: string;
+    priority?: string;
+    dueDate?: string | null;
+    projectId?: string | null;
+    projectTitle?: string | null;
+    goalId?: string | null;
+    goalTitle?: string | null;
+};
+type ForgeHabitRecord = {
+    id: string;
+    title: string;
+    description?: string | null;
+    polarity?: string;
+    frequency?: string | null;
+};
+type ForgeStrategyRecord = {
+    id: string;
+    title: string;
+    overview?: string | null;
+    status?: string | null;
+    isLocked?: boolean;
+};
+type ForgeWikiPageRecord = {
+    id: string;
+    slug: string;
+    title: string;
+    kind?: string;
+    parentSlug?: string | null;
+    summary?: string | null;
+    contentPlain?: string | null;
+};
+type ForgeOperatorContext = {
+    generatedAt?: string;
+    activeProjects?: ForgeProjectRecord[];
+    focusTasks?: ForgeTaskRecord[];
+    dueHabits?: ForgeHabitRecord[];
+    recommendedNextTask?: ForgeTaskRecord | null;
+};
+type ForgeOperatorOverview = {
+    generatedAt?: string;
+    warnings?: string[];
+    operator?: ForgeOperatorContext | null;
+};
+type ForgeSessionBootstrapPayload = {
+    overview: ForgeOperatorOverview | null;
+    goals: ForgeGoalRecord[];
+    projects: ForgeProjectRecord[];
+    tasks: ForgeTaskRecord[];
+    habits: ForgeHabitRecord[];
+    strategies: ForgeStrategyRecord[];
+    peoplePages: ForgeWikiPageRecord[];
+};
+export declare function listPeopleBranchPages(pages: ForgeWikiPageRecord[]): ForgeWikiPageRecord[];
+export declare function buildForgeSessionBootstrapContext(payload: ForgeSessionBootstrapPayload): string;
+export declare function buildLiveForgeSessionBootstrapContext(config: ForgePluginConfig): Promise<string>;
+export declare function registerForgeSessionBootstrapHook(api: ForgePluginRegistrationApi, config: ForgePluginConfig): void;
+export {};

package/dist/openclaw/session-bootstrap.js

@@ -0,0 +1,240 @@
+import path from "node:path";
+import { isAgentBootstrapEvent } from "openclaw/plugin-sdk/hook-runtime";
+import { callConfiguredForgeApi, expectForgeSuccess } from "./api-client.js";
+const FORGE_SESSION_BOOTSTRAP_PATH = ".forge/generated/FORGE_SESSION_BOOTSTRAP.md";
+const FORGE_SESSION_BOOTSTRAP_NAME = "forge-session-bootstrap";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function cleanInline(value) {
+    return (value ?? "").replace(/\s+/g, " ").trim();
+}
+function excerpt(value, maxLength) {
+    const normalized = cleanInline(value);
+    if (!normalized) {
+        return "";
+    }
+    if (normalized.length <= maxLength) {
+        return normalized;
+    }
+    return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+function formatMeta(parts) {
+    return parts
+        .map((value) => cleanInline(value))
+        .filter(Boolean)
+        .join(" | ");
+}
+function buildGoalIndex(goals) {
+    return new Map(goals.map((goal) => [goal.id, goal.title]));
+}
+function buildProjectIndex(projects) {
+    return new Map(projects.map((project) => [project.id, project.title]));
+}
+function formatGoal(goal) {
+    const meta = formatMeta([goal.status, goal.horizon]);
+    const summary = excerpt(goal.description, 140);
+    return `- ${goal.title}${meta ? ` [${meta}]` : ""}${summary ? ` — ${summary}` : ""}`;
+}
+function formatProject(project, goalTitles) {
+    const linkedGoal = cleanInline(project.goalTitle) ||
+        (project.goalId ? goalTitles.get(project.goalId) ?? project.goalId : "");
+    const meta = formatMeta([project.status, linkedGoal ? `goal: ${linkedGoal}` : ""]);
+    const summary = excerpt(project.description, 140);
+    return `- ${project.title}${meta ? ` [${meta}]` : ""}${summary ? ` — ${summary}` : ""}`;
+}
+function formatTask(task, projectTitles, goalTitles) {
+    const linkedProject = cleanInline(task.projectTitle) ||
+        (task.projectId ? projectTitles.get(task.projectId) ?? task.projectId : "");
+    const linkedGoal = cleanInline(task.goalTitle) ||
+        (task.goalId ? goalTitles.get(task.goalId) ?? task.goalId : "");
+    const meta = formatMeta([
+        task.status,
+        task.priority,
+        task.dueDate ? `due ${task.dueDate}` : "",
+        linkedProject ? `project: ${linkedProject}` : "",
+        !linkedProject && linkedGoal ? `goal: ${linkedGoal}` : ""
+    ]);
+    const summary = excerpt(task.description, 140);
+    return `- ${task.title}${meta ? ` [${meta}]` : ""}${summary ? ` — ${summary}` : ""}`;
+}
+function formatHabit(habit) {
+    const meta = formatMeta([habit.polarity, habit.frequency]);
+    const summary = excerpt(habit.description, 140);
+    return `- ${habit.title}${meta ? ` [${meta}]` : ""}${summary ? ` — ${summary}` : ""}`;
+}
+function formatStrategy(strategy) {
+    const meta = formatMeta([
+        strategy.status,
+        strategy.isLocked ? "locked" : "editable"
+    ]);
+    const summary = excerpt(strategy.overview, 140);
+    return `- ${strategy.title}${meta ? ` [${meta}]` : ""}${summary ? ` — ${summary}` : ""}`;
+}
+function hasPeopleAncestor(page, pagesBySlug) {
+    let parentSlug = page.parentSlug ?? null;
+    while (parentSlug) {
+        if (parentSlug === "people") {
+            return true;
+        }
+        parentSlug = pagesBySlug.get(parentSlug)?.parentSlug ?? null;
+    }
+    return false;
+}
+export function listPeopleBranchPages(pages) {
+    const pagesBySlug = new Map(pages.map((page) => [page.slug, page]));
+    return pages
+        .filter((page) => page.kind === "wiki")
+        .filter((page) => page.slug !== "people")
+        .filter((page) => hasPeopleAncestor(page, pagesBySlug))
+        .sort((left, right) => left.title.localeCompare(right.title));
+}
+export function buildForgeSessionBootstrapContext(payload) {
+    const goalTitles = buildGoalIndex(payload.goals);
+    const projectTitles = buildProjectIndex(payload.projects);
+    const overview = payload.overview?.operator ?? null;
+    const lines = [
+        "# Forge Session Bootstrap",
+        "",
+        "This block is generated from the live Forge runtime at session creation time. Treat it as a compact starting snapshot, not as the full source of truth.",
+        ""
+    ];
+    if (payload.overview?.generatedAt) {
+        lines.push(`Generated at: ${payload.overview.generatedAt}`, "");
+    }
+    if (overview) {
+        lines.push("## Current Forge Snapshot", "");
+        lines.push(`- Active projects in operator view: ${overview.activeProjects?.length ?? 0}`);
+        lines.push(`- Focus tasks in operator view: ${overview.focusTasks?.length ?? 0}`);
+        lines.push(`- Due habits in operator view: ${overview.dueHabits?.length ?? 0}`);
+        if (overview.recommendedNextTask) {
+            lines.push(`- Recommended next task: ${overview.recommendedNextTask.title}`);
+        }
+        if ((payload.overview?.warnings ?? []).length > 0) {
+            lines.push(`- Warnings: ${(payload.overview?.warnings ?? []).join(" | ")}`);
+        }
+        lines.push("");
+    }
+    lines.push(`## Goals (${payload.goals.length})`, "");
+    if (payload.goals.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.goals.map((goal) => formatGoal(goal)), "");
+    }
+    lines.push(`## Projects (${payload.projects.length})`, "");
+    if (payload.projects.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.projects.map((project) => formatProject(project, goalTitles)), "");
+    }
+    lines.push(`## Strategies (${payload.strategies.length})`, "");
+    if (payload.strategies.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.strategies.map((strategy) => formatStrategy(strategy)), "");
+    }
+    lines.push(`## Tasks (${payload.tasks.length})`, "");
+    if (payload.tasks.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.tasks.map((task) => formatTask(task, projectTitles, goalTitles)), "");
+    }
+    lines.push(`## Habits (${payload.habits.length})`, "");
+    if (payload.habits.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.habits.map((habit) => formatHabit(habit)), "");
+    }
+    lines.push(`## Wiki People Pages (${payload.peoplePages.length})`, "");
+    if (payload.peoplePages.length === 0) {
+        lines.push("- None.", "");
+    }
+    else {
+        lines.push(...payload.peoplePages.map((page) => {
+            const preview = excerpt(page.contentPlain ?? page.summary, 100);
+            return `- ${page.title}${preview ? ` — ${preview}` : ""}`;
+        }), "");
+    }
+    lines.push("## Use The Forge Skill", "");
+    lines.push("If you need more detail about any Forge entity, use the Forge skill/tools instead of guessing.");
+    lines.push("Relevant Forge entities include goals, projects, tasks, habits, strategies, notes, wiki pages, sleep sessions, workout sessions, psyche records, questionnaire records, preferences records, calendar events, work blocks, task timeboxes, and user ownership context.");
+    lines.push("If you need more detail about any listed person or relationship page, use the Forge skill to search the wiki and open the live page.");
+    lines.push("");
+    return lines.join("\n").trim();
+}
+async function readForgePayload(config, pathName) {
+    const result = await callConfiguredForgeApi(config, {
+        method: "GET",
+        path: pathName
+    });
+    return expectForgeSuccess(result);
+}
+async function loadForgeSessionBootstrapPayload(config) {
+    const [overviewResponse, goalsResponse, projectsResponse, tasksResponse, habitsResponse, strategiesResponse, wikiPagesResponse] = await Promise.all([
+        readForgePayload(config, "/api/v1/operator/overview"),
+        readForgePayload(config, "/api/v1/goals"),
+        readForgePayload(config, "/api/v1/projects"),
+        readForgePayload(config, "/api/v1/tasks"),
+        readForgePayload(config, "/api/v1/habits"),
+        readForgePayload(config, "/api/v1/strategies"),
+        readForgePayload(config, "/api/v1/wiki/pages")
+    ]);
+    const wikiPages = asArray(wikiPagesResponse.pages).filter((page) => isRecord(page) &&
+        typeof page.slug === "string" &&
+        typeof page.title === "string");
+    return {
+        overview: overviewResponse && isRecord(overviewResponse) && "overview" in overviewResponse
+            ? (overviewResponse.overview ?? null)
+            : null,
+        goals: asArray(goalsResponse.goals),
+        projects: asArray(projectsResponse.projects),
+        tasks: asArray(tasksResponse.tasks),
+        habits: asArray(habitsResponse.habits),
+        strategies: asArray(strategiesResponse.strategies),
+        peoplePages: listPeopleBranchPages(wikiPages)
+    };
+}
+export async function buildLiveForgeSessionBootstrapContext(config) {
+    return buildForgeSessionBootstrapContext(await loadForgeSessionBootstrapPayload(config));
+}
+export function registerForgeSessionBootstrapHook(api, config) {
+    if (!api.registerHook) {
+        return;
+    }
+    api.registerHook("agent:bootstrap", async (event) => {
+        if (!isAgentBootstrapEvent(event)) {
+            return;
+        }
+        try {
+            const content = await buildLiveForgeSessionBootstrapContext(config);
+            if (!content.trim()) {
+                return;
+            }
+            const generatedPath = path.join(event.context.workspaceDir, FORGE_SESSION_BOOTSTRAP_PATH);
+            const existingFiles = event.context.bootstrapFiles.filter((file) => file.path !== generatedPath);
+            event.context.bootstrapFiles = [
+                ...existingFiles,
+                {
+                    name: "BOOTSTRAP.md",
+                    path: generatedPath,
+                    content,
+                    missing: false
+                }
+            ];
+        }
+        catch (error) {
+            api.logger?.warn?.(`Forge session bootstrap hook could not load live Forge context: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }, {
+        name: FORGE_SESSION_BOOTSTRAP_NAME,
+        description: "Inject a live Forge workspace summary and People wiki snapshots into agent bootstrap context."
+    });
+}

package/dist/openclaw/tools.js

@@ -34,6 +34,11 @@ const scopedReadSchema = Type.Object({
 const optionalString = () => Type.Optional(Type.String());
 const optionalNullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
 const optionalDeleteMode = () => Type.Optional(Type.Union([Type.Literal("soft"), Type.Literal("hard")]));
+const optionalBoolean = () => Type.Optional(Type.Boolean());
+const optionalInteger = (minimum, maximum) => Type.Optional(Type.Integer({
+    ...(typeof minimum === "number" ? { minimum } : {}),
+    ...(typeof maximum === "number" ? { maximum } : {})
+}));
 const healthLinkInputSchema = () => Type.Object({
     entityType: Type.String({ minLength: 1 }),
     entityId: Type.String({ minLength: 1 }),
@@ -465,6 +470,277 @@ export function registerForgePluginTools(api, config) {
             }));
         }
     });
+    registerReadTool(api, config, {
+        name: "forge_get_preferences_workspace",
+        label: "Forge Preferences Workspace",
+        description: "Read Forge's current preference model for one user and domain, including the summary-first landing view, next comparison pair, concept libraries, map, table, and history.",
+        parameters: Type.Object({
+            userId: optionalString(),
+            domain: optionalString(),
+            contextId: optionalString()
+        }),
+        path: (params) => withQueryParams("/api/v1/preferences/workspace", params, [
+            "userId",
+            "domain",
+            "contextId"
+        ])
+    });
+    registerWriteTool(api, config, {
+        name: "forge_start_preferences_game",
+        label: "Forge Start Preferences Game",
+        description: "Start the Forge comparison game for one preference domain or context and return the next pair of items to compare.",
+        parameters: Type.Object({
+            userId: Type.String({ minLength: 1 }),
+            domain: Type.String({ minLength: 1 }),
+            contextId: optionalString()
+        }),
+        method: "POST",
+        path: "/api/v1/preferences/game/start"
+    });
+    registerWriteTool(api, config, {
+        name: "forge_merge_preferences_contexts",
+        label: "Forge Merge Preferences Contexts",
+        description: "Merge one or more preference contexts into a target context.",
+        parameters: Type.Object({
+            targetContextId: Type.String({ minLength: 1 }),
+            sourceContextIds: Type.Array(Type.String({ minLength: 1 }))
+        }),
+        method: "POST",
+        path: "/api/v1/preferences/contexts/merge"
+    });
+    registerWriteTool(api, config, {
+        name: "forge_enqueue_preferences_item_from_entity",
+        label: "Forge Enqueue Preferences Item From Entity",
+        description: "Queue an existing Forge entity into a preference domain so it can appear in the comparison game.",
+        parameters: Type.Object({
+            userId: Type.String({ minLength: 1 }),
+            domain: Type.String({ minLength: 1 }),
+            entityType: Type.String({ minLength: 1 }),
+            entityId: Type.String({ minLength: 1 })
+        }),
+        method: "POST",
+        path: "/api/v1/preferences/items/from-entity"
+    });
+    registerWriteTool(api, config, {
+        name: "forge_submit_preferences_judgment",
+        label: "Forge Submit Preferences Judgment",
+        description: "Record one pairwise preference outcome such as left, right, tie, or skip.",
+        parameters: Type.Object({
+            profileId: Type.String({ minLength: 1 }),
+            contextId: Type.String({ minLength: 1 }),
+            userId: Type.String({ minLength: 1 }),
+            leftItemId: Type.String({ minLength: 1 }),
+            rightItemId: Type.String({ minLength: 1 }),
+            outcome: Type.String({ minLength: 1 }),
+            strength: Type.Optional(Type.Number({ minimum: 0.5, maximum: 2 })),
+            responseTimeMs: Type.Optional(Type.Union([Type.Integer({ minimum: 0 }), Type.Null()])),
+            source: optionalString(),
+            reasonTags: Type.Optional(Type.Array(Type.String()))
+        }),
+        method: "POST",
+        path: "/api/v1/preferences/judgments"
+    });
+    registerWriteTool(api, config, {
+        name: "forge_submit_preferences_signal",
+        label: "Forge Submit Preferences Signal",
+        description: "Record a direct non-pairwise preference signal such as favorite, veto, must-have, bookmark, neutral, or compare-later.",
+        parameters: Type.Object({
+            profileId: Type.String({ minLength: 1 }),
+            contextId: Type.String({ minLength: 1 }),
+            userId: Type.String({ minLength: 1 }),
+            itemId: Type.String({ minLength: 1 }),
+            signalType: Type.String({ minLength: 1 }),
+            strength: Type.Optional(Type.Number({ minimum: 0.5, maximum: 2 })),
+            source: optionalString()
+        }),
+        method: "POST",
+        path: "/api/v1/preferences/signals"
+    });
+    api.registerTool({
+        name: "forge_update_preferences_score",
+        label: "Forge Update Preferences Score",
+        description: "Override or protect the inferred state of one preference item when the user wants explicit correction.",
+        parameters: Type.Object({
+            itemId: Type.String({ minLength: 1 }),
+            manualStatus: optionalNullableString(),
+            manualScore: Type.Optional(Type.Union([Type.Number(), Type.Null()])),
+            confidenceLock: Type.Optional(Type.Union([Type.Number({ minimum: 0, maximum: 1 }), Type.Null()])),
+            bookmarked: Type.Optional(Type.Boolean()),
+            compareLater: Type.Optional(Type.Boolean()),
+            frozen: Type.Optional(Type.Boolean())
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "PATCH",
+                path: `/api/v1/preferences/items/${typed.itemId}/score`,
+                body: {
+                    manualStatus: typed.manualStatus,
+                    manualScore: typed.manualScore,
+                    confidenceLock: typed.confidenceLock,
+                    bookmarked: typed.bookmarked,
+                    compareLater: typed.compareLater,
+                    frozen: typed.frozen
+                }
+            }));
+        }
+    });
+    registerReadTool(api, config, {
+        name: "forge_list_questionnaires",
+        label: "Forge List Questionnaires",
+        description: "List the Psyche questionnaire library across the selected user scope.",
+        parameters: scopedReadSchema,
+        path: (params) => withUserIds("/api/v1/psyche/questionnaires", params.userIds)
+    });
+    api.registerTool({
+        name: "forge_get_questionnaire",
+        label: "Forge Get Questionnaire",
+        description: "Read one Psyche questionnaire instrument with versions and scoring detail.",
+        parameters: Type.Object({
+            questionnaireId: Type.String({ minLength: 1 }),
+            userIds: Type.Optional(Type.Array(Type.String()))
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runRead(config, withQueryParams(`/api/v1/psyche/questionnaires/${typed.questionnaireId}`, typed, ["userIds"])));
+        }
+    });
+    api.registerTool({
+        name: "forge_clone_questionnaire",
+        label: "Forge Clone Questionnaire",
+        description: "Clone one Psyche questionnaire instrument into a new user-owned copy.",
+        parameters: Type.Object({
+            questionnaireId: Type.String({ minLength: 1 }),
+            userId: optionalNullableString()
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "POST",
+                path: `/api/v1/psyche/questionnaires/${typed.questionnaireId}/clone`,
+                body: { userId: typed.userId }
+            }));
+        }
+    });
+    api.registerTool({
+        name: "forge_ensure_questionnaire_draft",
+        label: "Forge Ensure Questionnaire Draft",
+        description: "Create or return the editable draft version for one questionnaire instrument.",
+        parameters: Type.Object({
+            questionnaireId: Type.String({ minLength: 1 })
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "POST",
+                path: `/api/v1/psyche/questionnaires/${typed.questionnaireId}/draft`
+            }));
+        }
+    });
+    api.registerTool({
+        name: "forge_publish_questionnaire_draft",
+        label: "Forge Publish Questionnaire Draft",
+        description: "Publish the current questionnaire draft as the live readable version.",
+        parameters: Type.Object({
+            questionnaireId: Type.String({ minLength: 1 }),
+            label: optionalString()
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "POST",
+                path: `/api/v1/psyche/questionnaires/${typed.questionnaireId}/publish`,
+                body: { label: typed.label }
+            }));
+        }
+    });
+    api.registerTool({
+        name: "forge_start_questionnaire_run",
+        label: "Forge Start Questionnaire Run",
+        description: "Start one questionnaire answer session for a specific user.",
+        parameters: Type.Object({
+            questionnaireId: Type.String({ minLength: 1 }),
+            userId: Type.String({ minLength: 1 }),
+            author: optionalString()
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "POST",
+                path: `/api/v1/psyche/questionnaires/${typed.questionnaireId}/runs`,
+                body: {
+                    userId: typed.userId,
+                    author: typed.author
+                }
+            }));
+        }
+    });
+    api.registerTool({
+        name: "forge_get_questionnaire_run",
+        label: "Forge Get Questionnaire Run",
+        description: "Read one questionnaire run with answers, scores, and completion state.",
+        parameters: Type.Object({
+            runId: Type.String({ minLength: 1 }),
+            userIds: Type.Optional(Type.Array(Type.String()))
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runRead(config, withQueryParams(`/api/v1/psyche/questionnaire-runs/${typed.runId}`, typed, ["userIds"])));
+        }
+    });
+    api.registerTool({
+        name: "forge_update_questionnaire_run",
+        label: "Forge Update Questionnaire Run",
+        description: "Patch one questionnaire run while the answers are still being filled.",
+        parameters: Type.Object({
+            runId: Type.String({ minLength: 1 }),
+            answers: Type.Optional(Type.Record(Type.String(), Type.Any())),
+            status: optionalString(),
+            notes: optionalString()
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "PATCH",
+                path: `/api/v1/psyche/questionnaire-runs/${typed.runId}`,
+                body: {
+                    answers: typed.answers,
+                    status: typed.status,
+                    notes: typed.notes
+                }
+            }));
+        }
+    });
+    api.registerTool({
+        name: "forge_complete_questionnaire_run",
+        label: "Forge Complete Questionnaire Run",
+        description: "Complete one questionnaire run and finalize its scoring pass.",
+        parameters: Type.Object({
+            runId: Type.String({ minLength: 1 })
+        }),
+        async execute(_toolCallId, params) {
+            const typed = params;
+            return jsonResult(await runWrite(config, {
+                method: "POST",
+                path: `/api/v1/psyche/questionnaire-runs/${typed.runId}/complete`
+            }));
+        }
+    });
+    registerReadTool(api, config, {
+        name: "forge_get_self_observation_calendar",
+        label: "Forge Self Observation Calendar",
+        description: "Read the Psyche self-observation calendar with note-backed observations, linked patterns, linked reports, and available tags.",
+        parameters: Type.Object({
+            from: optionalString(),
+            to: optionalString(),
+            userIds: Type.Optional(Type.Array(Type.String()))
+        }),
+        path: (params) => withQueryParams("/api/v1/psyche/self-observation/calendar", params, [
+            "from",
+            "to",
+            "userIds"
+        ])
+    });
     registerWriteTool(api, config, {
         name: "forge_search_entities",
         label: "Search Forge Entities",
@@ -491,7 +767,7 @@ export function registerForgePluginTools(api, config) {
     registerWriteTool(api, config, {
         name: "forge_create_entities",
         label: "Create Forge Entities",
-        description: "Create one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType` and full `data`. This is the preferred create path for planning, Psyche, and calendar records including calendar_event, work_block_template, and task_timebox.",
+        description: "Create one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType` and full `data`. This is the preferred create path for planning, Psyche, calendar, preferences basic CRUD, and questionnaire_instrument records.",
         parameters: Type.Object({
             atomic: Type.Optional(Type.Boolean()),
             operations: Type.Array(Type.Object({
@@ -506,7 +782,7 @@ export function registerForgePluginTools(api, config) {
     registerWriteTool(api, config, {
         name: "forge_update_entities",
         label: "Update Forge Entities",
-        description: "Update one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType`, `id`, and `patch`. This is the preferred update path for calendar_event, work_block_template, and task_timebox too; Forge runs calendar sync side effects downstream.",
+        description: "Update one or more Forge entities through the ordered batch workflow. Pass `operations` as an array. Each operation must include `entityType`, `id`, and `patch`. This is the preferred update path for calendar_event, work_block_template, task_timebox, preferences basic CRUD entities, and questionnaire_instrument too.",
         parameters: Type.Object({
             atomic: Type.Optional(Type.Boolean()),
             operations: Type.Array(Type.Object({
@@ -522,7 +798,7 @@ export function registerForgePluginTools(api, config) {
     registerWriteTool(api, config, {
         name: "forge_delete_entities",
         label: "Delete Forge Entities",
-        description: "Delete Forge entities in one batch request. Pass `operations` as an array with `entityType` and `id`. Delete defaults to soft mode unless hard is requested explicitly. Calendar-domain deletes still run their downstream removal logic, including remote calendar projection cleanup for calendar_event.",
+        description: "Delete Forge entities in one batch request. Pass `operations` as an array with `entityType` and `id`. Delete defaults to soft mode unless hard is requested explicitly. Some entities such as calendar-domain records, preference CRUD entities, and questionnaire_instrument delete immediately by design.",
         parameters: Type.Object({
             atomic: Type.Optional(Type.Boolean()),
             operations: Type.Array(Type.Object({
@@ -789,9 +1065,6 @@ export function registerForgePluginTools(api, config) {
             ]),
             label: Type.String({ minLength: 1 }),
             username: optionalString(),
-            clientId: optionalString(),
-            clientSecret: optionalString(),
-            refreshToken: optionalString(),
             password: optionalString(),
             serverUrl: optionalString(),
             authSessionId: optionalString(),