@robbeverhelst/do 1.403.0 → 1.405.0

package/dist/do.js

@@ -14420,7 +14420,7 @@ var configError = (message) => new CliError("config", message, EXIT.CONFIG);
 
 // src/meta.ts
 var CLI_NAME = "do";
-var VERSION = "1.403.0";
+var VERSION = "1.405.0";
 var API_PREFIX = "/api/v1";
 var DEFAULT_API_URL = "http://localhost:3001";
 
@@ -17926,7 +17926,8 @@ var habitEntrySource = pgEnum("habit_entry_source", [
   "ingest",
   "agent"
 ]);
-var habitEntryKind = pgEnum("habit_entry_kind", ["check_in", "skip"]);
+var habitEntryKind = pgEnum("habit_entry_kind", ["check_in", "skip", "not_needed"]);
+var habitAnswerType = pgEnum("habit_answer_type", ["yn", "count", "amount", "dur"]);
 var habitSource = pgEnum("habit_source", ["manual", "google_fit", "strava", "github"]);
 var recurrenceMode = pgEnum("recurrence_mode", ["rigid", "flexible"]);
 var recurrenceFreq = pgEnum("recurrence_freq", ["daily", "weekly", "monthly", "yearly"]);
@@ -18011,6 +18012,15 @@ var tasks = pgTable("tasks", {
   index("tasks_tenant_ready_idx").on(t.tenantId, t.readyAt).where(sql`${t.readyAt} IS NOT NULL`),
   check2("tasks_area_xor_project_chk", sql`${t.projectId} IS NULL OR ${t.areaId} IS NULL`)
 ]);
+var habitGroups = pgTable("habit_groups", {
+  id: text("id").primaryKey(),
+  tenantId: text("tenant_id").notNull().references(() => tenants.id),
+  name: text("name").notNull(),
+  icon: text("icon"),
+  position: integer2("position").notNull().default(0),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+}, (t) => [index("habit_groups_tenant_idx").on(t.tenantId, t.position)]);
 var habits = pgTable("habits", {
   ...leafColumns(),
   measurementType: habitMeasurementType("measurement_type").notNull(),
@@ -18034,10 +18044,22 @@ var habits = pgTable("habits", {
   eventOffset: text("event_offset"),
   durationMinutes: integer2("duration_minutes"),
   activeMonths: integer2("active_months").array(),
-  checklist: boolean4("checklist").notNull().default(false)
+  checklist: boolean4("checklist").notNull().default(false),
+  groupId: text("group_id").references(() => habitGroups.id, { onDelete: "set null" }),
+  answerType: habitAnswerType("answer_type"),
+  unitOne: text("unit_one"),
+  step: doublePrecision("step"),
+  decimals: integer2("decimals"),
+  quickPicks: doublePrecision("quick_picks").array().notNull().default(sql`'{}'::double precision[]`),
+  notNeededReasons: text("not_needed_reasons").array().notNull().default(sql`'{}'::text[]`),
+  skipReasons: text("skip_reasons").array().notNull().default(sql`'{}'::text[]`),
+  notNeededKeepsStreak: boolean4("not_needed_keeps_streak").notNull().default(true)
 }, (t) => [
   index("habits_tenant_idx").on(t.tenantId),
   index("habits_tenant_area_idx").on(t.tenantId, t.areaId),
+  index("habits_tenant_group_idx").on(t.tenantId, t.groupId),
+  check2("habits_decimals_chk", sql`${t.decimals} IS NULL OR ${t.decimals} BETWEEN 0 AND 3`),
+  check2("habits_step_chk", sql`${t.step} IS NULL OR ${t.step} > 0`),
   check2("habits_time_of_day_chk", sql`${t.timeOfDay} IS NULL OR ${t.timeOfDay} IN ('morning', 'midday', 'evening') OR ${t.timeOfDay} ~ '^([01][0-9]|2[0-3]):[0-5][0-9]$'`),
   check2("habits_duration_minutes_chk", sql`${t.durationMinutes} IS NULL OR ${t.durationMinutes} BETWEEN 1 AND 600`)
 ]);
@@ -18054,7 +18076,8 @@ var habitEntries = pgTable("habit_entries", {
   agentId: text("agent_id"),
   userId: text("user_id"),
   note: text("note"),
-  matchedName: text("matched_name")
+  matchedName: text("matched_name"),
+  reason: text("reason")
 }, (t) => [
   index("habit_entries_habit_occurred_idx").on(t.habitId, t.occurredAt),
   uniqueIndex("habit_entries_habit_external_uniq").on(t.habitId, t.externalId).where(sql`${t.externalId} IS NOT NULL`)
@@ -19110,6 +19133,7 @@ var habitMeasurementTypeSchema = _enum2(habitMeasurementType.enumValues);
 var habitPeriodSchema = _enum2(habitPeriod.enumValues);
 var habitEntrySourceSchema = _enum2(habitEntrySource.enumValues);
 var habitEntryKindSchema = _enum2(habitEntryKind.enumValues);
+var habitAnswerTypeSchema = _enum2(habitAnswerType.enumValues);
 var recurrenceModeSchema = _enum2(recurrenceMode.enumValues);
 var recurrenceFreqSchema = _enum2(recurrenceFreq.enumValues);
 var recurrenceUnitSchema = _enum2(recurrenceUnit.enumValues);
@@ -22479,7 +22503,16 @@ var habitSchema = createSelectSchema(habits, {
   eventOffset: string2().nullable().default(null),
   durationMinutes: number2().int().nullable().default(null),
   activeMonths: array(number2().int()).nullable().default(null),
-  checklist: boolean2().default(false)
+  checklist: boolean2().default(false),
+  groupId: string2().nullable().default(null),
+  answerType: habitAnswerTypeSchema.nullable().default(null),
+  unitOne: string2().nullable().default(null),
+  step: number2().nullable().default(null),
+  decimals: number2().int().nullable().default(null),
+  quickPicks: array(number2()).default([]),
+  notNeededReasons: array(string2()).default([]),
+  skipReasons: array(string2()).default([]),
+  notNeededKeepsStreak: boolean2().default(true)
 });
 var habitEntrySchema = createSelectSchema(habitEntries, {
   occurredAt: exports_coerce.date(),
@@ -22489,7 +22522,8 @@ var habitEntrySchema = createSelectSchema(habitEntries, {
   kind: habitEntryKindSchema.default("check_in"),
   agentId: string2().nullish(),
   note: string2().nullish(),
-  matchedName: string2().nullish()
+  matchedName: string2().nullish(),
+  reason: string2().nullish()
 }).extend({
   by: string2().nullish()
 });
@@ -22532,6 +22566,23 @@ var habitScheduleSchema = discriminatedUnion("kind", [
   })
 ]);
 var eventColumns = { eventSourceId: true, eventMatch: true, eventOffset: true };
+var HABIT_REASON_MAX = 40;
+var HABIT_CHOICES_MAX = 8;
+var habitReasonSchema = string2().trim().max(HABIT_REASON_MAX).transform((reason) => reason === "" ? null : reason);
+var habitReasonsSchema = array(string2().trim().min(1).max(HABIT_REASON_MAX)).max(HABIT_CHOICES_MAX).refine((list) => new Set(list.map((x) => x.toLowerCase())).size === list.length, {
+  message: "each reason once"
+});
+var habitAnswerFields = {
+  groupId: ulidSchema.nullish(),
+  answerType: habitAnswerTypeSchema.nullish(),
+  unitOne: string2().trim().min(1).max(30).nullish(),
+  step: number2().positive().max(1000).nullish(),
+  decimals: number2().int().min(0).max(3).nullish(),
+  quickPicks: array(number2().nonnegative()).max(HABIT_CHOICES_MAX).optional(),
+  notNeededReasons: habitReasonsSchema.optional(),
+  skipReasons: habitReasonsSchema.optional(),
+  notNeededKeepsStreak: boolean2().optional()
+};
 var createHabitInputSchema = createInsertSchema(habits, {
   id: ulidSchema,
   source: habitSourceSchema.optional(),
@@ -22548,7 +22599,8 @@ var createHabitInputSchema = createInsertSchema(habits, {
   remind: boolean2().optional(),
   durationMinutes: habitDurationMinutesSchema.nullish(),
   activeMonths: habitActiveMonthsSchema.optional(),
-  checklist: boolean2().optional()
+  checklist: boolean2().optional(),
+  ...habitAnswerFields
 }).omit({ tenantId: true, recurrenceRuleId: true, retiredAt: true, ...eventColumns }).extend({
   title: string2().min(1),
   schedule: habitScheduleSchema.optional(),
@@ -22568,7 +22620,8 @@ var updateHabitInputSchema = createUpdateSchema(habits, {
   dayTimes: weekdayTimesSchema.nullish(),
   remind: boolean2().optional(),
   durationMinutes: habitDurationMinutesSchema.nullish(),
-  activeMonths: habitActiveMonthsSchema.optional()
+  activeMonths: habitActiveMonthsSchema.optional(),
+  ...habitAnswerFields
 }).omit({
   id: true,
   tenantId: true,
@@ -22613,6 +22666,7 @@ var habitStreakSchema = object({
   graceBudget: number2().int().nonnegative(),
   graceRemaining: number2().int().nonnegative(),
   skippedToday: boolean2().default(false),
+  notNeededToday: boolean2().default(false),
   runSince: exports_iso.date().nullable().default(null)
 });
 var habitRoutineRefSchema = object({
@@ -22658,6 +22712,7 @@ var habitHeatmapCellSchema = object({
   value: number2(),
   satisfied: boolean2(),
   rest: boolean2().default(false),
+  notNeeded: boolean2().default(false),
   notes: array(string2()).optional()
 });
 var habitDetailSchema = habitSummarySchema.extend({
@@ -22749,6 +22804,12 @@ var habitCheckInByTitleResultSchema = habitSummarySchema.extend({
 var habitAliasInputSchema = object({ alias: habitAliasSchema }).strict();
 var habitSkipInputSchema = object({
   date: exports_iso.date().optional(),
+  note: habitEntryNoteSchema.nullish(),
+  reason: habitReasonSchema.nullish()
+}).strict();
+var habitNotNeededInputSchema = object({
+  date: exports_iso.date().optional(),
+  reason: habitReasonSchema.nullish(),
   note: habitEntryNoteSchema.nullish()
 }).strict();
 var habitPauseInputSchema = object({ until: exports_iso.date().nullish() }).strict();
@@ -30633,13 +30694,19 @@ var foodDayIntakeSchema = object({
   amount: string2().nullable(),
   note: string2().nullable()
 });
+var foodDayRefSchema = object({
+  id: string2(),
+  brand: string2().nullable(),
+  portions: record(string2(), number2())
+});
 var foodDayViewSchema = object({
   date: civilDate2,
   logs: array(mealLogViewSchema),
   total: foodDaySchema.nullable(),
   planned: array(plannedMealSchema),
   notes: array(foodDayMealNoteSchema),
-  intakes: array(foodDayIntakeSchema)
+  intakes: array(foodDayIntakeSchema),
+  refs: array(foodDayRefSchema).optional()
 });
 var MEAL_PLAN_STATUS_VALUES = ["as_planned", "swapped", "unplanned"];
 var MEAL_AFTER_KIND_VALUES = ["symptom", "episode", "dose", "sleep", "rating"];
@@ -32018,6 +32085,56 @@ var guestOperations = defineOperations({
   }
 });
 
+// ../../packages/schema/src/contracts/habit-groups.ts
+var HABIT_GROUP_NAME_MAX = 40;
+var habitGroupSchema = createSelectSchema(habitGroups, {
+  createdAt: exports_coerce.date(),
+  updatedAt: exports_coerce.date()
+});
+var name3 = string2().trim().min(1).max(HABIT_GROUP_NAME_MAX);
+var icon = string2().trim().regex(/^[a-z0-9-]{1,40}$/, "an icon name: lower-case letters, digits and dashes");
+var createHabitGroupInputSchema = object({
+  id: ulidSchema,
+  name: name3,
+  icon: icon.nullish(),
+  position: number2().int().nonnegative().optional()
+}).strict();
+var updateHabitGroupInputSchema = object({
+  name: name3.optional(),
+  icon: icon.nullable().optional(),
+  position: number2().int().nonnegative().optional()
+}).strict().refine((x) => Object.keys(x).length > 0, { message: "nothing to change" });
+
+// ../../packages/schema/src/operations/habit-groups.ts
+var crud3 = crudOperations({
+  segment: "habit-groups",
+  tag: "Habits",
+  noun: "habit group",
+  read: "habits:read",
+  write: "habits:write",
+  create: createHabitGroupInputSchema,
+  update: updateHabitGroupInputSchema,
+  listQuery: []
+});
+var habitGroupOperations = defineOperations({
+  ...crud3,
+  list: {
+    ...crud3.list,
+    description: "The Space's habit groups in their order (`position`, then oldest first): each `{ id, name, icon, position }`. A habit's `groupId` names its group."
+  },
+  create: {
+    ...crud3.create,
+    description: "A new group, `{ id, name, icon?, position? }`: the client mints the ULID; `icon` is an icon name (`sunrise`, `paw`); without a `position` it goes after the last group. A taken id is a 409.",
+    webhook: undefined
+  },
+  update: { ...crud3.update, webhook: undefined },
+  remove: {
+    ...crud3.remove,
+    description: "Delete a group. Its habits stay, ungrouped (their `groupId` becomes null).",
+    webhook: undefined
+  }
+});
+
 // ../../packages/schema/src/operations/habits.ts
 var item = { itemId: "The item's ULID." };
 var notChecklist = "A habit that isn't a checklist answers 409.";
@@ -32240,7 +32357,7 @@ var habitOperations = defineOperations({
     scopes: ["habits:write"],
     tag: "Habits",
     summary: "Skip a habit",
-    description: '"Skip gym today": a neutral rest day (a `skip` entry, value 0), never a miss. The streak treats the period as neutral and spends no grace. `date` (YYYY-MM-DD) defaults to today; an optional `note` says why ("Dentist"). Skipping a skipped day changes nothing but its note. Undo by deleting the skip entry like a check-in. Returns the refreshed habit; fires `habit.updated`.',
+    description: '"Skip gym today": a neutral rest day (a `skip` entry, value 0), never a miss. The streak treats the period as neutral and spends no grace. `date` (YYYY-MM-DD) defaults to today; an optional `reason` is its one-tap reason (one of the habit\'s `skipReasons`, "Away") and `note` says more ("Dentist"). It replaces a Not needed on that day; skipping a skipped day changes nothing but its reason and note. Undo by deleting the skip entry like a check-in. Returns the refreshed habit; fires `habit.updated`.',
     body: habitSkipInputSchema,
     status: 201,
     response: { description: "The refreshed habit." },
@@ -32250,6 +32367,23 @@ var habitOperations = defineOperations({
     },
     webhook: "habit.updated"
   },
+  notNeeded: {
+    method: "post",
+    path: "/habits/{id}/not-needed",
+    scopes: ["habits:write"],
+    tag: "Habits",
+    summary: "Answer a habit Not needed",
+    description: '"The scraps bucket was empty": checked, nothing to do (a `not_needed` entry, value 0). It adds a day to the streak while the habit\'s `notNeededKeepsStreak` is on (the default), and rests like a skip when it\'s off; `streak.notNeededToday` says so. `date` (YYYY-MM-DD) defaults to today; an optional `reason` is its one-tap reason (one of the habit\'s `notNeededReasons`, "Bucket empty") and `note` says more. It replaces a skip on that day; answering a day already not needed changes nothing but its reason and note. Undo by deleting the entry like a check-in. Returns the refreshed habit; fires `habit.updated`.',
+    body: habitNotNeededInputSchema,
+    status: 201,
+    response: { description: "The refreshed habit." },
+    errors: {
+      400: true,
+      404: true
+    },
+    webhook: "habit.updated",
+    operationId: "not_needed_habit"
+  },
   pause: {
     method: "post",
     path: "/habits/{id}/pause",
@@ -40830,18 +40964,18 @@ var runPlayStatusValues = [
   "dropped"
 ];
 var runPlayStatusSchema = _enum2(runPlayStatusValues);
-var name3 = string2().trim().min(1).max(200);
+var name4 = string2().trim().min(1).max(200);
 var text5 = string2().trim().max(2000);
 var shortText2 = string2().trim().max(300);
 var isoDate = string2().regex(/^\d{4}-\d{2}-\d{2}$/, "must be an ISO date (YYYY-MM-DD)");
 var ref = string2().trim().min(1).max(200);
 var runCharacterSchema = object({
-  name: name3,
+  name: name4,
   pronoun: _enum2(["he", "she", "they"]).nullish(),
   subtitle: shortText2.nullish(),
   level: number2().int().min(0).max(1e4).nullish(),
   build: shortText2.nullish(),
-  stats: array(object({ k: name3, v: union([number2(), shortText2]) }).strict()).max(40).optional(),
+  stats: array(object({ k: name4, v: union([number2(), shortText2]) }).strict()).max(40).optional(),
   traits: array(shortText2).max(20).optional(),
   backstory: text5.nullish(),
   rules: array(shortText2).max(30).optional(),
@@ -40850,12 +40984,12 @@ var runCharacterSchema = object({
 var runArcSchema = object({
   title: shortText2.nullish(),
   chapters: array(object({
-    key: name3,
-    name: name3,
+    key: name4,
+    name: name4,
     range: shortText2.nullish(),
     moral: text5.nullish()
   }).strict()).max(40),
-  current: name3.nullish()
+  current: name4.nullish()
 }).strict();
 var runStepStatusValues = ["done", "now", "todo", "skipped"];
 var runStepStatusSchema = _enum2(runStepStatusValues);
@@ -40868,7 +41002,7 @@ var runQuestStatusValues = ["active", "paused", "planned", "done", "failed"];
 var runQuestStatusSchema = _enum2(runQuestStatusValues);
 var runQuestSchema = object({
   ref: ref.nullish(),
-  name: name3,
+  name: name4,
   line: shortText2.nullish(),
   status: runQuestStatusSchema.default("active"),
   objective: text5.nullish(),
@@ -40883,7 +41017,7 @@ var runQuestSchema = object({
   }).strict()).max(40).optional(),
   pausedAt: shortText2.nullish(),
   why: text5.nullish(),
-  revisitAt: name3.nullish()
+  revisitAt: name4.nullish()
 }).strict();
 var runNextStepsSchema = object({
   items: array(shortText2.pipe(string2().min(1))).max(3),
@@ -40892,50 +41026,50 @@ var runNextStepsSchema = object({
 }).strict();
 var runChoiceSchema = object({
   ref: ref.nullish(),
-  title: name3,
+  title: name4,
   place: shortText2.nullish(),
   status: _enum2(["made", "planned"]).default("made"),
   options: array(shortText2).max(6).optional(),
   why: text5.nullish(),
   consequence: text5.nullish(),
-  revisitAt: name3.nullish(),
-  chapter: name3.nullish(),
+  revisitAt: name4.nullish(),
+  chapter: name4.nullish(),
   tone: _enum2(["good", "grey", "dark"]).nullish(),
   on: isoDate.nullish()
 }).strict();
 var runHomeSchema = object({
   ref: ref.nullish(),
-  name: name3,
+  name: name4,
   role: _enum2(["home", "collector", "storage", "planned", "later"]).default("home"),
   place: shortText2.nullish(),
-  upgrades: array(object({ name: name3, done: boolean2().default(false) }).strict()).max(40).optional(),
+  upgrades: array(object({ name: name4, done: boolean2().default(false) }).strict()).max(40).optional(),
   steward: shortText2.nullish(),
   note: text5.nullish()
 }).strict();
 var runPersonSchema = object({
   ref: ref.nullish(),
-  name: name3,
+  name: name4,
   role: _enum2(["child", "spouse", "steward", "follower", "pet", "rival", "other"]),
   status: _enum2(["with", "planned", "lost"]).default("with"),
   home: shortText2.nullish(),
   note: text5.nullish()
 }).strict();
 var runMountSchema = object({
-  name: name3,
+  name: name4,
   status: _enum2(["with", "planned", "lost"]).default("with"),
   note: text5.nullish()
 }).strict();
 var runUniqueSchema = object({
   ref: ref.nullish(),
-  name: name3,
+  name: name4,
   status: _enum2(["have", "now", "want"]).default("have"),
   source: shortText2.nullish(),
   displayAt: shortText2.nullish(),
-  set: name3.nullish()
+  set: name4.nullish()
 }).strict();
 var runChecklistSchema = object({
   key: string2().trim().min(1).max(60).regex(/^[a-z0-9][a-z0-9_-]*$/, "must be a lowercase slug"),
-  label: name3,
+  label: name4,
   total: number2().int().min(0).max(5000).nullish(),
   items: array(object({ id: ref, label: shortText2.nullish() }).strict()).max(5000).optional(),
   done: array(ref).max(5000),
@@ -40944,7 +41078,7 @@ var runChecklistSchema = object({
   legend: shortText2.nullish()
 }).strict();
 var runTeamMemberSchema = object({
-  species: name3,
+  species: name4,
   nick: shortText2.nullish(),
   level: number2().int().min(1).max(100).nullish(),
   nature: shortText2.nullish(),
@@ -40958,8 +41092,8 @@ var runAchievementsSchema = object({
   source: _enum2(["steam", "xbox", "psn", "manual"]).default("manual"),
   total: number2().int().min(0).max(5000).nullish(),
   enabled: boolean2().default(true),
-  unlocked: array(object({ name: name3, on: isoDate.nullish(), hint: shortText2.nullish(), key: ref.nullish() }).strict()).max(5000),
-  locked: array(object({ name: name3, hint: shortText2.nullish(), key: ref.nullish() }).strict()).max(5000).optional(),
+  unlocked: array(object({ name: name4, on: isoDate.nullish(), hint: shortText2.nullish(), key: ref.nullish() }).strict()).max(5000),
+  locked: array(object({ name: name4, hint: shortText2.nullish(), key: ref.nullish() }).strict()).max(5000).optional(),
   syncedAt: string2().datetime({ offset: true }).nullish()
 }).strict();
 var runRareFindsSchema = object({
@@ -40969,7 +41103,7 @@ var runRareFindsSchema = object({
 }).strict();
 var runInstallSchema = object({
   edition: shortText2.nullish(),
-  mods: array(object({ name: name3, url: string2().url().max(2000).nullish() }).strict()).max(200).default([]),
+  mods: array(object({ name: name4, url: string2().url().max(2000).nullish() }).strict()).max(200).default([]),
   savePath: string2().trim().max(500).nullish(),
   lastBackup: isoDate.nullish(),
   notes: text5.nullish()
@@ -40979,7 +41113,7 @@ var runSaveFields = {
   game: _enum2(["skyrim"]).default("skyrim"),
   fileName: shortText2.nullish(),
   saveNumber: number2().int().min(0).max(1e9),
-  playerName: name3,
+  playerName: name4,
   level: number2().int().min(0).max(1e4),
   location: shortText2,
   race: shortText2.nullish(),
@@ -41025,7 +41159,7 @@ var runFacetSchema = object({
   install: runInstallSchema.nullish(),
   save: runSaveSchema.nullish(),
   money: object({ goal: shortText2.nullish(), purpose: shortText2.nullish() }).strict().nullish(),
-  links: array(object({ label: name3, url: string2().url().max(2000) }).strict()).max(50).optional()
+  links: array(object({ label: name4, url: string2().url().max(2000) }).strict()).max(50).optional()
 }).strict();
 var runListSectionValues = [
   "orderOfPlay",
@@ -41179,12 +41313,12 @@ var runSaveHeaderResultSchema = object({
 var createRunInputSchema = object({
   id: ulidSchema,
   gameId: ulidSchema,
-  title: name3,
+  title: name4,
   status: runPlayStatusSchema.optional(),
   facet: runFacetSchema.optional()
 }).strict();
 var updateRunInputSchema = object({
-  title: name3.optional(),
+  title: name4.optional(),
   status: runPlayStatusSchema.optional(),
   facet: runFacetSchema.optional()
 }).strict();
@@ -46032,6 +46166,13 @@ var ENTITIES = [
     createInput: "CreateBlockTemplateInput",
     updateInput: "UpdateBlockTemplateInput"
   }),
+  entityFromOperations(habitGroupOperations, {
+    name: "habit-groups",
+    returns: "HabitGroup",
+    listFlags: [],
+    createInput: "CreateHabitGroupInput",
+    updateInput: "UpdateHabitGroupInput"
+  }),
   entityFromOperations({ list: webhookOperations.list, get: webhookOperations.get }, { name: "webhooks", returns: "WebhookSubscription", listFlags: [] })
 ];
 var entityByName = (name) => ENTITIES.find((e) => e.name === name);
@@ -51847,19 +51988,26 @@ var commands22 = [
           name: "note",
           type: "string",
           description: 'Why, if you like ("Dentist"); shows in the log.'
+        },
+        {
+          name: "reason",
+          type: "string",
+          description: `Its one-tap reason, usually one of the habit's skipReasons ("Away").`
         }
       ],
       scopes: [...habitOperations.skip.scopes],
       returns: "HabitSummary",
-      notes: `${routeOf(habitOperations.skip)}. The streak treats the period as neutral and spends no grace; the habit leaves Now for the day. Skipping a skipped day changes nothing. Undo: delete the skip entry (\`do habit check-ins <id>\` lists it with kind \`skip\`).`
+      notes: `${routeOf(habitOperations.skip)}. The streak treats the period as neutral and spends no grace; the habit leaves Now for the day. It replaces a Not needed on that day; skipping a skipped day changes nothing but its reason and note. Undo: delete the skip entry (\`do habit check-ins <id>\` lists it with kind \`skip\`).`
     },
     run: async ({ args, flags, requireClient }) => {
       const id = requireArg(args, 0, "habit id");
       const date = flagString(flags, "date");
       const note = flagString(flags, "note");
+      const reason = flagString(flags, "reason");
       const input = parseInput(habitSkipInputSchema, {
         ...date ? { date } : {},
-        ...note !== undefined ? { note } : {}
+        ...note !== undefined ? { note } : {},
+        ...reason !== undefined ? { reason } : {}
       });
       return {
         data: await requireClient().post(pathOf(habitOperations.skip, { id }), input),
@@ -51867,6 +52015,40 @@ var commands22 = [
       };
     }
   },
+  {
+    spec: {
+      path: ["habit", "not-needed"],
+      summary: 'Not needed: checked, nothing to do ("the scraps bucket was empty").',
+      args: [{ name: "id", required: true, description: "Habit ULID." }],
+      flags: [
+        { name: "date", type: "string", description: "The day (YYYY-MM-DD); defaults to today." },
+        {
+          name: "reason",
+          type: "string",
+          description: `Its one-tap reason, usually one of the habit's notNeededReasons ("Bucket empty").`
+        },
+        { name: "note", type: "string", description: "More, if you like; shows in the log." }
+      ],
+      scopes: [...habitOperations.notNeeded.scopes],
+      returns: "HabitSummary",
+      notes: `${routeOf(habitOperations.notNeeded)}. It adds a day to the streak while the habit's notNeededKeepsStreak is on (the default) and rests like a skip when it's off. It replaces a skip on that day; answering again changes nothing but its reason and note. Undo: delete the entry (\`do habit check-ins <id>\` lists it with kind \`not_needed\`).`
+    },
+    run: async ({ args, flags, requireClient }) => {
+      const id = requireArg(args, 0, "habit id");
+      const date = flagString(flags, "date");
+      const note = flagString(flags, "note");
+      const reason = flagString(flags, "reason");
+      const input = parseInput(habitNotNeededInputSchema, {
+        ...date ? { date } : {},
+        ...note !== undefined ? { note } : {},
+        ...reason !== undefined ? { reason } : {}
+      });
+      return {
+        data: await requireClient().post(pathOf(habitOperations.notNeeded, { id }), input),
+        render: renderHabit
+      };
+    }
+  },
   {
     spec: {
       path: ["routine", "done"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robbeverhelst/do",
-  "version": "1.403.0",
+  "version": "1.405.0",
   "private": false,
   "description": "do — the agent-drivable CLI over the public /api/v1 surface",
   "homepage": "https://github.com/robbeverhelst/do/tree/main/apps/cli",