forge-openclaw-plugin 0.2.13 → 0.2.18

package/dist/server/app.js

@@ -7,6 +7,7 @@ import { listActivityEvents, listActivityEventsForTask, removeActivityEvent } fr
 import { approveApprovalRequest, createAgentAction, createInsight, createInsightFeedback, deleteInsight, getInsightById, listAgentActions, listApprovalRequests, listInsights, rejectApprovalRequest, updateInsight } from "./repositories/collaboration.js";
 import { listEventLog } from "./repositories/event-log.js";
 import { createGoal, getGoalById, listGoals, updateGoal } from "./repositories/goals.js";
+import { createHabit, createHabitCheckIn, getHabitById, listHabits, updateHabit } from "./repositories/habits.js";
 import { listDomains } from "./repositories/domains.js";
 import { buildNotesSummaryByEntity, createNote, getNoteById, listNotes, updateNote } from "./repositories/notes.js";
 import { createBehavior, createBehaviorPattern, createBeliefEntry, createEmotionDefinition, createEventType, createModeGuideSession, createModeProfile, createPsycheValue, createTriggerReport, getBehaviorById, getBehaviorPatternById, getBeliefEntryById, getEmotionDefinitionById, getEventTypeById, getModeGuideSessionById, getModeProfileById, getPsycheValueById, getTriggerReportById, listBehaviors, listBehaviorPatterns, listBeliefEntries, listEmotionDefinitions, listEventTypes, listModeGuideSessions, listModeProfiles, listPsycheValues, listSchemaCatalog, listTriggerReports, updateBehavior, updateBehaviorPattern, updateBeliefEntry, updateEmotionDefinition, updateEventType, updateModeGuideSession, updateModeProfile, updatePsycheValue, updateTriggerReport } from "./repositories/psyche.js";
@@ -27,7 +28,7 @@ import { getWeeklyReviewPayload } from "./services/reviews.js";
 import { createTaskRunWatchdog } from "./services/task-run-watchdog.js";
 import { suggestTags } from "./services/tagging.js";
 import { PSYCHE_ENTITY_TYPES, createBehaviorSchema, createBeliefEntrySchema, createBehaviorPatternSchema, createEmotionDefinitionSchema, createEventTypeSchema, createModeGuideSessionSchema, createModeProfileSchema, createPsycheValueSchema, createTriggerReportSchema, updateBehaviorSchema, updateBeliefEntrySchema, updateBehaviorPatternSchema, updateEmotionDefinitionSchema, updateEventTypeSchema, updateModeGuideSessionSchema, updateModeProfileSchema, updatePsycheValueSchema, updateTriggerReportSchema } from "./psyche-types.js";
-import { activityListQuerySchema, activitySourceSchema, createAgentActionSchema, createAgentTokenSchema, batchCreateEntitiesSchema, batchDeleteEntitiesSchema, batchRestoreEntitiesSchema, batchSearchEntitiesSchema, batchUpdateEntitiesSchema, createGoalSchema, createInsightFeedbackSchema, createInsightSchema, createNoteSchema, createProjectSchema, createManualRewardGrantSchema, createSessionEventSchema, createTagSchema, notesListQuerySchema, updateTagSchema, createTaskSchema, eventsListQuerySchema, operatorLogWorkSchema, projectBoardPayloadSchema, projectListQuerySchema, entityDeleteQuerySchema, removeActivityEventSchema, resolveApprovalRequestSchema, rewardsLedgerQuerySchema, taskContextPayloadSchema, taskRunClaimSchema, taskRunFocusSchema, taskRunFinishSchema, taskRunHeartbeatSchema, taskRunListQuerySchema, taskListQuerySchema, tagSuggestionRequestSchema, uncompleteTaskSchema, updateSettingsSchema, updateGoalSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateRewardRuleSchema, updateTaskSchema } from "./types.js";
+import { activityListQuerySchema, activitySourceSchema, createAgentActionSchema, createAgentTokenSchema, batchCreateEntitiesSchema, batchDeleteEntitiesSchema, batchRestoreEntitiesSchema, batchSearchEntitiesSchema, batchUpdateEntitiesSchema, createGoalSchema, createInsightFeedbackSchema, createInsightSchema, createNoteSchema, createProjectSchema, createManualRewardGrantSchema, createHabitCheckInSchema, createHabitSchema, createSessionEventSchema, createTagSchema, notesListQuerySchema, updateTagSchema, createTaskSchema, eventsListQuerySchema, operatorLogWorkSchema, projectBoardPayloadSchema, projectListQuerySchema, entityDeleteQuerySchema, removeActivityEventSchema, resolveApprovalRequestSchema, rewardsLedgerQuerySchema, habitListQuerySchema, taskContextPayloadSchema, taskRunClaimSchema, taskRunFocusSchema, taskRunFinishSchema, taskRunHeartbeatSchema, taskRunListQuerySchema, taskListQuerySchema, tagSuggestionRequestSchema, uncompleteTaskSchema, updateSettingsSchema, updateGoalSchema, updateHabitSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateRewardRuleSchema, updateTaskSchema } from "./types.js";
 import { buildOpenApiDocument } from "./openapi.js";
 import { registerWebRoutes } from "./web.js";
 import { createManagerRuntime } from "./managers/runtime.js";
@@ -186,6 +187,39 @@ const AGENT_ONBOARDING_ENTITY_CATALOG = [
             { name: "notes", type: "Array<{ contentMarkdown, author?, links? }>", required: false, description: "Optional nested notes that will auto-link to the new task.", defaultValue: [] }
         ]
     },
+    {
+        entityType: "habit",
+        purpose: "A recurring commitment or recurring slip with explicit cadence, graph links, and XP consequences.",
+        minimumCreateFields: ["title"],
+        relationshipRules: [
+            "Habits can link directly to goals, projects, tasks, values, patterns, behaviors, beliefs, modes, and trigger reports.",
+            "Habits are recurring records, not task variants, and they participate in search, notes, delete/restore, and XP.",
+            "linkedBehaviorId remains a compatibility alias; linkedBehaviorIds is the canonical array form."
+        ],
+        searchHints: ["Search by title before creating a duplicate habit.", "Use linkedTo when the habit should already be attached to a goal, project, task, or Psyche entity."],
+        examples: ['{"title":"Morning training","frequency":"daily","polarity":"positive","linkedGoalIds":["goal_train_body"],"linkedValueIds":["value_steadiness"],"linkedBehaviorIds":["behavior_regulating_walk"]}'],
+        fieldGuide: [
+            { name: "title", type: "string", required: true, description: "Concrete recurring behavior label." },
+            { name: "description", type: "string", required: false, description: "What counts as success or failure for this habit.", defaultValue: "" },
+            { name: "status", type: "active|paused|archived", required: false, description: "Lifecycle state.", enumValues: ["active", "paused", "archived"], defaultValue: "active" },
+            { name: "polarity", type: "positive|negative", required: false, description: "Whether doing the behavior is aligned or misaligned.", enumValues: ["positive", "negative"], defaultValue: "positive" },
+            { name: "frequency", type: "daily|weekly", required: false, description: "Recurrence cadence.", enumValues: ["daily", "weekly"], defaultValue: "daily" },
+            { name: "targetCount", type: "integer", required: false, description: "How many repetitions define the cadence window.", defaultValue: 1 },
+            { name: "weekDays", type: "integer[]", required: false, description: "Weekday numbers for weekly habits where Monday is 1 and Sunday is 0.", defaultValue: [] },
+            { name: "linkedGoalIds", type: "string[]", required: false, description: "Linked goal ids.", defaultValue: [] },
+            { name: "linkedProjectIds", type: "string[]", required: false, description: "Linked project ids.", defaultValue: [] },
+            { name: "linkedTaskIds", type: "string[]", required: false, description: "Linked task ids.", defaultValue: [] },
+            { name: "linkedValueIds", type: "string[]", required: false, description: "Linked value ids.", defaultValue: [] },
+            { name: "linkedPatternIds", type: "string[]", required: false, description: "Linked pattern ids.", defaultValue: [] },
+            { name: "linkedBehaviorIds", type: "string[]", required: false, description: "Canonical linked behavior ids.", defaultValue: [] },
+            { name: "linkedBehaviorId", type: "string|null", required: false, description: "Compatibility alias for the first linked behavior id.", defaultValue: null, nullable: true },
+            { name: "linkedBeliefIds", type: "string[]", required: false, description: "Linked belief ids.", defaultValue: [] },
+            { name: "linkedModeIds", type: "string[]", required: false, description: "Linked mode ids.", defaultValue: [] },
+            { name: "linkedReportIds", type: "string[]", required: false, description: "Linked trigger report ids.", defaultValue: [] },
+            { name: "rewardXp", type: "integer", required: false, description: "XP granted on aligned check-ins.", defaultValue: 12 },
+            { name: "penaltyXp", type: "integer", required: false, description: "XP removed on misaligned check-ins.", defaultValue: 8 }
+        ]
+    },
     {
         entityType: "note",
         purpose: "A Markdown note that can link to one or many Forge entities.",
@@ -594,6 +628,15 @@ const AGENT_ONBOARDING_TOOL_INPUT_CATALOG = [
         notes: ["Restore only works for soft-deleted entities."],
         example: '{"operations":[{"entityType":"goal","id":"goal_123","clientRef":"goal-restore-1"}]}'
     },
+    {
+        toolName: "forge_grant_reward_bonus",
+        summary: "Grant an explicit manual XP bonus or penalty with clear provenance.",
+        whenToUse: "Use when the user or operator explicitly wants an auditable reward adjustment beyond the automatic task and habit reward paths.",
+        inputShape: "{ entityType: RewardableEntityType, entityId: string, deltaXp: integer, reasonTitle: string, reasonSummary?: string, metadata?: object }",
+        requiredFields: ["entityType", "entityId", "deltaXp", "reasonTitle"],
+        notes: ["Requires rewards.manage and write scopes.", "Use this for explicit operator judgement, not as a substitute for normal task_run or habit check-in rewards."],
+        example: '{"entityType":"habit","entityId":"habit_morning_training","deltaXp":18,"reasonTitle":"Operator bonus","reasonSummary":"Stayed with the habit through unusual travel friction.","metadata":{"manual":true,"source":"agent"}}'
+    },
     {
         toolName: "forge_post_insight",
         summary: "Store an agent-authored insight.",
@@ -736,6 +779,7 @@ function buildAgentOnboardingPayload(request) {
             "Goals are the top-level strategic layer.",
             "Projects belong to one goal through goalId.",
             "Tasks can belong to a goal, a project, both, or neither.",
+            "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.",
             "Psyche values can link to goals, projects, and tasks.",
@@ -771,6 +815,7 @@ function buildAgentOnboardingPayload(request) {
                 "forge_delete_entities",
                 "forge_restore_entities"
             ],
+            rewardWorkflow: ["forge_grant_reward_bonus"],
             workWorkflow: [
                 "forge_log_work",
                 "forge_start_task_run",
@@ -955,7 +1000,17 @@ function buildHealthPayload(taskRunWatchdog, extras = {}) {
         ...extras
     };
 }
+function shouldIncludeRuntimeProbe(headers) {
+    const probeHeader = headers["x-forge-runtime-probe"];
+    if (Array.isArray(probeHeader)) {
+        return probeHeader.some((value) => typeof value === "string" && value.trim() === "1");
+    }
+    return typeof probeHeader === "string" && probeHeader.trim() === "1";
+}
 function buildV1Context() {
+    const goals = listGoals();
+    const tasks = listTasks();
+    const habits = listHabits();
     return {
         meta: {
             apiVersion: "v1",
@@ -964,15 +1019,16 @@ function buildV1Context() {
             backend: "forge-node-runtime",
             mode: "transitional-node"
         },
-        metrics: buildGamificationProfile(listGoals(), listTasks()),
+        metrics: buildGamificationProfile(goals, tasks, habits),
         dashboard: getDashboard(),
         overview: getOverviewContext(),
         today: getTodayContext(),
         risk: getRiskContext(),
-        goals: listGoals(),
+        goals,
         projects: listProjectSummaries(),
         tags: listTags(),
-        tasks: listTasks(),
+        tasks,
+        habits,
         activeTaskRuns: listTaskRuns({ active: true, limit: 25 }),
         activity: listActivityEvents({ limit: 25 })
     };
@@ -980,8 +1036,9 @@ function buildV1Context() {
 function buildXpMetricsPayload() {
     const goals = listGoals();
     const tasks = listTasks();
+    const habits = listHabits();
     const rules = listRewardRules();
-    const gamificationOverview = buildGamificationOverview(goals, tasks);
+    const gamificationOverview = buildGamificationOverview(goals, tasks, habits);
     const dailyAmbientCap = rules
         .filter((rule) => rule.family === "ambient")
         .reduce((max, rule) => Math.max(max, Number(rule.config.dailyCap ?? 0)), 0) || 12;
@@ -989,7 +1046,7 @@ function buildXpMetricsPayload() {
         profile: gamificationOverview.profile,
         achievements: gamificationOverview.achievements,
         milestoneRewards: gamificationOverview.milestoneRewards,
-        momentumPulse: buildXpMomentumPulse(goals, tasks),
+        momentumPulse: buildXpMomentumPulse(goals, tasks, habits),
         recentLedger: listRewardLedger({ limit: 25 }),
         rules,
         dailyAmbientXp: getDailyAmbientXp(new Date().toISOString().slice(0, 10)),
@@ -998,6 +1055,7 @@ function buildXpMetricsPayload() {
 }
 function buildOperatorContext() {
     const tasks = listTasks();
+    const dueHabits = listHabits({ dueToday: true }).slice(0, 12);
     const activeProjects = listProjectSummaries({ status: "active" }).filter((project) => project.activeTaskCount > 0 || project.completedTaskCount > 0);
     const focusTasks = tasks.filter((task) => task.status === "focus" || task.status === "in_progress");
     const recommendedNextTask = focusTasks[0] ??
@@ -1008,6 +1066,7 @@ function buildOperatorContext() {
         generatedAt: new Date().toISOString(),
         activeProjects: activeProjects.slice(0, 8),
         focusTasks: focusTasks.slice(0, 12),
+        dueHabits,
         currentBoard: {
             backlog: tasks.filter((task) => task.status === "backlog").slice(0, 20),
             focus: tasks.filter((task) => task.status === "focus").slice(0, 20),
@@ -1231,9 +1290,18 @@ export async function buildServer(options = {}) {
         return context;
     };
     app.get("/api/health", async () => buildHealthPayload(taskRunWatchdog));
-    app.get("/api/v1/health", async () => buildHealthPayload(taskRunWatchdog, {
+    app.get("/api/v1/health", async (request) => buildHealthPayload(taskRunWatchdog, {
         apiVersion: "v1",
-        backend: "forge-node-runtime"
+        backend: "forge-node-runtime",
+        ...(shouldIncludeRuntimeProbe(request.headers)
+            ? {
+                runtime: {
+                    pid: process.pid,
+                    storageRoot: runtimeConfig.dataRoot ?? process.cwd(),
+                    basePath: runtimeConfig.basePath
+                }
+            }
+            : {})
     }));
     app.get("/api/v1/auth/operator-session", async (request, reply) => ({
         session: managers.session.ensureLocalOperatorSession(request.headers, reply)
@@ -1721,6 +1789,19 @@ export async function buildServer(options = {}) {
         const query = taskListQuerySchema.parse(request.query ?? {});
         return { tasks: listTasks(query) };
     });
+    app.get("/api/v1/habits", async (request) => {
+        const query = habitListQuerySchema.parse(request.query ?? {});
+        return { habits: listHabits(query) };
+    });
+    app.get("/api/v1/habits/:id", async (request, reply) => {
+        const { id } = request.params;
+        const habit = getHabitById(id);
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
     app.get("/api/v1/projects/:id", async (request, reply) => {
         const { id } = request.params;
         const project = listProjectSummaries().find((entry) => entry.id === id);
@@ -1764,7 +1845,7 @@ export async function buildServer(options = {}) {
         return { event };
     });
     app.get("/api/v1/metrics", async () => ({
-        metrics: buildGamificationOverview(listGoals(), listTasks())
+        metrics: buildGamificationOverview(listGoals(), listTasks(), listHabits())
     }));
     app.get("/api/v1/metrics/xp", async () => ({
         metrics: buildXpMetricsPayload()
@@ -1944,6 +2025,12 @@ export async function buildServer(options = {}) {
         reply.code(201);
         return { project };
     });
+    app.post("/api/v1/habits", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits" });
+        const habit = createHabit(createHabitSchema.parse(request.body ?? {}), toActivityContext(auth));
+        reply.code(201);
+        return { habit };
+    });
     app.patch("/api/v1/projects/:id", async (request, reply) => {
         const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/projects/:id" });
         const { id } = request.params;
@@ -1964,6 +2051,36 @@ export async function buildServer(options = {}) {
         }
         return { project };
     });
+    app.patch("/api/v1/habits/:id", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id" });
+        const { id } = request.params;
+        const habit = updateHabit(id, updateHabitSchema.parse(request.body ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
+    app.delete("/api/v1/habits/:id", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id" });
+        const { id } = request.params;
+        const habit = deleteEntity("habit", id, entityDeleteQuerySchema.parse(request.query ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit };
+    });
+    app.post("/api/v1/habits/:id/check-ins", async (request, reply) => {
+        const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/habits/:id/check-ins" });
+        const { id } = request.params;
+        const habit = createHabitCheckIn(id, createHabitCheckInSchema.parse(request.body ?? {}), toActivityContext(auth));
+        if (!habit) {
+            reply.code(404);
+            return { error: "Habit not found" };
+        }
+        return { habit, metrics: buildXpMetricsPayload() };
+    });
     app.patch("/api/v1/settings", async (request) => {
         const auth = requireScopedAccess(request.headers, ["write"], { route: "/api/v1/settings" });
         return {
@@ -2072,7 +2189,7 @@ export async function buildServer(options = {}) {
     app.get("/api/metrics", async (_request, reply) => {
         markCompatibilityRoute(reply);
         return {
-            metrics: buildGamificationProfile(listGoals(), listTasks())
+            metrics: buildGamificationProfile(listGoals(), listTasks(), listHabits())
         };
     });
     app.get("/api/task-runs", async (request, reply) => {
@@ -2102,7 +2219,7 @@ export async function buildServer(options = {}) {
         markCompatibilityRoute(reply);
         const query = taskListQuerySchema.parse(request.query ?? {});
         return {
-            metrics: buildGamificationProfile(listGoals(), listTasks()),
+            metrics: buildGamificationProfile(listGoals(), listTasks(), listHabits()),
             dashboard: getDashboard(),
             overview: getOverviewContext(),
             today: getTodayContext(),
@@ -2111,6 +2228,7 @@ export async function buildServer(options = {}) {
             projects: listProjectSummaries(),
             tags: listTags(),
             tasks: listTasks(query),
+            habits: listHabits(),
             activeTaskRuns: listTaskRuns({ active: true, limit: 25 }),
             activity: listActivityEvents({ limit: 25 })
         };

package/dist/server/openapi.js

@@ -242,6 +242,89 @@ export function buildOpenApiDocument() {
             isCurrent: { type: "boolean" }
         }
     };
+    const habitCheckIn = {
+        type: "object",
+        additionalProperties: false,
+        required: ["id", "habitId", "dateKey", "status", "note", "deltaXp", "createdAt", "updatedAt"],
+        properties: {
+            id: { type: "string" },
+            habitId: { type: "string" },
+            dateKey: { type: "string", format: "date" },
+            status: { type: "string", enum: ["done", "missed"] },
+            note: { type: "string" },
+            deltaXp: { type: "integer" },
+            createdAt: { type: "string", format: "date-time" },
+            updatedAt: { type: "string", format: "date-time" }
+        }
+    };
+    const habit = {
+        type: "object",
+        additionalProperties: false,
+        required: [
+            "id",
+            "title",
+            "description",
+            "status",
+            "polarity",
+            "frequency",
+            "targetCount",
+            "weekDays",
+            "linkedGoalIds",
+            "linkedProjectIds",
+            "linkedTaskIds",
+            "linkedValueIds",
+            "linkedPatternIds",
+            "linkedBehaviorIds",
+            "linkedBeliefIds",
+            "linkedModeIds",
+            "linkedReportIds",
+            "linkedBehaviorId",
+            "linkedBehaviorTitle",
+            "linkedBehaviorTitles",
+            "rewardXp",
+            "penaltyXp",
+            "createdAt",
+            "updatedAt",
+            "lastCheckInAt",
+            "lastCheckInStatus",
+            "streakCount",
+            "completionRate",
+            "dueToday",
+            "checkIns"
+        ],
+        properties: {
+            id: { type: "string" },
+            title: { type: "string" },
+            description: { type: "string" },
+            status: { type: "string", enum: ["active", "paused", "archived"] },
+            polarity: { type: "string", enum: ["positive", "negative"] },
+            frequency: { type: "string", enum: ["daily", "weekly"] },
+            targetCount: { type: "integer" },
+            weekDays: arrayOf({ type: "integer" }),
+            linkedGoalIds: arrayOf({ type: "string" }),
+            linkedProjectIds: arrayOf({ type: "string" }),
+            linkedTaskIds: arrayOf({ type: "string" }),
+            linkedValueIds: arrayOf({ type: "string" }),
+            linkedPatternIds: arrayOf({ type: "string" }),
+            linkedBehaviorIds: arrayOf({ type: "string" }),
+            linkedBeliefIds: arrayOf({ type: "string" }),
+            linkedModeIds: arrayOf({ type: "string" }),
+            linkedReportIds: arrayOf({ type: "string" }),
+            linkedBehaviorId: nullable({ type: "string" }),
+            linkedBehaviorTitle: nullable({ type: "string" }),
+            linkedBehaviorTitles: arrayOf({ type: "string" }),
+            rewardXp: { type: "integer" },
+            penaltyXp: { type: "integer" },
+            createdAt: { type: "string", format: "date-time" },
+            updatedAt: { type: "string", format: "date-time" },
+            lastCheckInAt: nullable({ type: "string", format: "date-time" }),
+            lastCheckInStatus: nullable({ type: "string", enum: ["done", "missed"] }),
+            streakCount: { type: "integer" },
+            completionRate: { type: "number" },
+            dueToday: { type: "boolean" },
+            checkIns: arrayOf({ $ref: "#/components/schemas/HabitCheckIn" })
+        }
+    };
     const activityEvent = {
         type: "object",
         additionalProperties: false,
@@ -252,6 +335,7 @@ export function buildOpenApiDocument() {
                 type: "string",
                 enum: [
                     "task",
+                    "habit",
                     "goal",
                     "project",
                     "domain",
@@ -378,7 +462,7 @@ export function buildOpenApiDocument() {
     const dashboardPayload = {
         type: "object",
         additionalProperties: false,
-        required: ["stats", "goals", "projects", "tasks", "tags", "suggestedTags", "owners", "executionBuckets", "gamification", "achievements", "milestoneRewards", "recentActivity", "notesSummaryByEntity"],
+        required: ["stats", "goals", "projects", "tasks", "habits", "tags", "suggestedTags", "owners", "executionBuckets", "gamification", "achievements", "milestoneRewards", "recentActivity", "notesSummaryByEntity"],
         properties: {
             stats: {
                 type: "object",
@@ -397,6 +481,7 @@ export function buildOpenApiDocument() {
             goals: arrayOf({ $ref: "#/components/schemas/DashboardGoal" }),
             projects: arrayOf({ $ref: "#/components/schemas/ProjectSummary" }),
             tasks: arrayOf({ $ref: "#/components/schemas/Task" }),
+            habits: arrayOf({ $ref: "#/components/schemas/Habit" }),
             tags: arrayOf({ $ref: "#/components/schemas/Tag" }),
             suggestedTags: arrayOf({ $ref: "#/components/schemas/Tag" }),
             owners: arrayOf({ type: "string" }),
@@ -422,7 +507,7 @@ export function buildOpenApiDocument() {
     const overviewContext = {
         type: "object",
         additionalProperties: false,
-        required: ["generatedAt", "strategicHeader", "projects", "activeGoals", "topTasks", "recentEvidence", "achievements", "domainBalance", "neglectedGoals"],
+        required: ["generatedAt", "strategicHeader", "projects", "activeGoals", "topTasks", "dueHabits", "recentEvidence", "achievements", "domainBalance", "neglectedGoals"],
         properties: {
             generatedAt: { type: "string", format: "date-time" },
             strategicHeader: {
@@ -443,6 +528,7 @@ export function buildOpenApiDocument() {
             projects: arrayOf({ $ref: "#/components/schemas/ProjectSummary" }),
             activeGoals: arrayOf({ $ref: "#/components/schemas/DashboardGoal" }),
             topTasks: arrayOf({ $ref: "#/components/schemas/Task" }),
+            dueHabits: arrayOf({ $ref: "#/components/schemas/Habit" }),
             recentEvidence: arrayOf({ $ref: "#/components/schemas/ActivityEvent" }),
             achievements: arrayOf({ $ref: "#/components/schemas/AchievementSignal" }),
             domainBalance: arrayOf({
@@ -475,7 +561,7 @@ export function buildOpenApiDocument() {
     const todayContext = {
         type: "object",
         additionalProperties: false,
-        required: ["generatedAt", "directive", "timeline", "dailyQuests", "milestoneRewards", "momentum"],
+        required: ["generatedAt", "directive", "timeline", "dueHabits", "dailyQuests", "milestoneRewards", "recentHabitRewards", "momentum"],
         properties: {
             generatedAt: { type: "string", format: "date-time" },
             directive: {
@@ -499,6 +585,7 @@ export function buildOpenApiDocument() {
                     tasks: arrayOf({ $ref: "#/components/schemas/Task" })
                 }
             }),
+            dueHabits: arrayOf({ $ref: "#/components/schemas/Habit" }),
             dailyQuests: arrayOf({
                 type: "object",
                 additionalProperties: false,
@@ -513,6 +600,7 @@ export function buildOpenApiDocument() {
                 }
             }),
             milestoneRewards: arrayOf({ $ref: "#/components/schemas/MilestoneReward" }),
+            recentHabitRewards: arrayOf({ $ref: "#/components/schemas/RewardLedgerEvent" }),
             momentum: {
                 type: "object",
                 additionalProperties: false,
@@ -550,7 +638,7 @@ export function buildOpenApiDocument() {
     const forgeSnapshot = {
         type: "object",
         additionalProperties: false,
-        required: ["meta", "metrics", "dashboard", "overview", "today", "risk", "goals", "projects", "tags", "tasks", "activeTaskRuns", "activity"],
+        required: ["meta", "metrics", "dashboard", "overview", "today", "risk", "goals", "projects", "tags", "tasks", "habits", "activeTaskRuns", "activity"],
         properties: {
             meta: {
                 type: "object",
@@ -573,6 +661,7 @@ export function buildOpenApiDocument() {
             projects: arrayOf({ $ref: "#/components/schemas/ProjectSummary" }),
             tags: arrayOf({ $ref: "#/components/schemas/Tag" }),
             tasks: arrayOf({ $ref: "#/components/schemas/Task" }),
+            habits: arrayOf({ $ref: "#/components/schemas/Habit" }),
             activeTaskRuns: arrayOf({ $ref: "#/components/schemas/TaskRun" }),
             activity: arrayOf({ $ref: "#/components/schemas/ActivityEvent" })
         }
@@ -1041,6 +1130,7 @@ export function buildOpenApiDocument() {
             "generatedAt",
             "activeProjects",
             "focusTasks",
+            "dueHabits",
             "currentBoard",
             "recentActivity",
             "recentTaskRuns",
@@ -1051,6 +1141,7 @@ export function buildOpenApiDocument() {
             generatedAt: { type: "string", format: "date-time" },
             activeProjects: arrayOf({ $ref: "#/components/schemas/ProjectSummary" }),
             focusTasks: arrayOf({ $ref: "#/components/schemas/Task" }),
+            dueHabits: arrayOf({ $ref: "#/components/schemas/Habit" }),
             currentBoard: {
                 type: "object",
                 additionalProperties: false,
@@ -1993,6 +2084,8 @@ export function buildOpenApiDocument() {
                 ProjectSummary: projectSummary,
                 Task: task,
                 TaskRun: taskRun,
+                HabitCheckIn: habitCheckIn,
+                Habit: habit,
                 ActivityEvent: activityEvent,
                 GamificationProfile: gamificationProfile,
                 AchievementSignal: achievementSignal,
@@ -2718,6 +2811,90 @@ export function buildOpenApiDocument() {
                     }
                 }
             },
+            "/api/v1/habits": {
+                get: {
+                    summary: "List habits with current streak and due-today state",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["habits"],
+                            properties: {
+                                habits: arrayOf({ $ref: "#/components/schemas/Habit" })
+                            }
+                        }, "Habit collection")
+                    }
+                },
+                post: {
+                    summary: "Create a habit",
+                    responses: {
+                        "201": jsonResponse({
+                            type: "object",
+                            required: ["habit"],
+                            properties: {
+                                habit: { $ref: "#/components/schemas/Habit" }
+                            }
+                        }, "Created habit"),
+                        default: { $ref: "#/components/responses/Error" }
+                    }
+                }
+            },
+            "/api/v1/habits/{id}": {
+                get: {
+                    summary: "Get a habit",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["habit"],
+                            properties: {
+                                habit: { $ref: "#/components/schemas/Habit" }
+                            }
+                        }, "Habit"),
+                        "404": { $ref: "#/components/responses/Error" }
+                    }
+                },
+                patch: {
+                    summary: "Update a habit",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["habit"],
+                            properties: {
+                                habit: { $ref: "#/components/schemas/Habit" }
+                            }
+                        }, "Updated habit"),
+                        "404": { $ref: "#/components/responses/Error" }
+                    }
+                },
+                delete: {
+                    summary: "Delete a habit",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["habit"],
+                            properties: {
+                                habit: { $ref: "#/components/schemas/Habit" }
+                            }
+                        }, "Deleted habit"),
+                        "404": { $ref: "#/components/responses/Error" }
+                    }
+                }
+            },
+            "/api/v1/habits/{id}/check-ins": {
+                post: {
+                    summary: "Record a habit outcome for one day",
+                    responses: {
+                        "200": jsonResponse({
+                            type: "object",
+                            required: ["habit", "metrics"],
+                            properties: {
+                                habit: { $ref: "#/components/schemas/Habit" },
+                                metrics: { $ref: "#/components/schemas/XpMetricsPayload" }
+                            }
+                        }, "Habit check-in result"),
+                        "404": { $ref: "#/components/responses/Error" }
+                    }
+                }
+            },
             "/api/v1/tags": {
                 get: {
                     summary: "List tags",