@wirecat/cli-base 0.70.0 → 0.72.0

package/CHANGELOG.md

@@ -8,6 +8,38 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.72.0 — 02.11.2026
+
+### Added
+
+- **A native list can say which fields it can leave out (`negatable`).** `queryFieldsOf(schema, { negatable: [...] })`
+  marks a field the source can also exclude with `-field:value` or `NOT field:value`; `commands --json` carries
+  `negatable: true` on it, and `fieldsHelp` adds a `Leave out:` line. Before, only the list's own code knew, so an
+  agent learned about `-event_type:birthday` from prose alone.
+- **`queryDescription(registry)`: a list's query in one sentence.** The terms it takes, which fields `-` can leave
+  out, and every field with its values: for an input that has no Fields section beside it, such as an MCP tool's
+  `query`.
+- **`meta.now`, `meta.now_local` and `clockMeta(now, zone)` (WC-TIME-7).** An answer an agent plans by can carry the
+  time it was made, in UTC and on the wall clock of the zone in use, beside `meta.timezone`. `metaSchema` accepts
+  both keys; `localTime` is the schema of the second.
+- **WC-CMD-17 and WC-MCP-4: a write that only an owner-only option asks for is a read over MCP.** `events export`
+  prints the `.ics` text, and writes a file only with `--output`, which MCP tools never offer; cli-core's
+  `writesFileOnlyWith` runs it through `read`, and the read-only lock refuses only a run that names a file.
+
+## 0.71.0 — 01.11.2026
+
+### Added
+
+- **A vocabulary flag can list the value names other domains give it (`otherValues`).** `--to` stays `<chat>` and also
+  takes `<address>` (mail); `--subject` stays `<ref>` and also takes `<text>`. `flag-two-meanings` accepts those and
+  reports any other value name. A CLI that declares `--to <address>` or `--subject <text>` needs no override.
+
+### Fixed
+
+- **0.70.0 made every messenger CLI fail `flag-two-meanings`.** It wrote `--to` as `<chat|address>` and `--subject`
+  as `<ref|text>`, and the lint compares the value name as written, so `--to <chat>` was reported. Both go back to
+  the original value name, and mail's names are listed beside them. Do not use 0.70.0.
+
 ## 0.70.0 — 01.11.2026
 
 ### Added

package/dist/commands/document.js

@@ -33,6 +33,7 @@ const fieldInfoSchema = v.object({
     relation: v.optional(v.string()),
     native: v.optional(v.boolean()),
     placement: v.optional(v.literal("and")),
+    negatable: v.optional(v.boolean()),
 });
 const commandInfoSchema = v.object({
     path: v.array(v.string()),

package/dist/dev/lint.js

@@ -229,7 +229,10 @@ const CHECKS = {
         }));
     },
     "flag-two-meanings": (document, vocabulary) => {
-        const registered = new Map(vocabulary.flags.map((flag) => [flag.name, flag.value?.slice(1, -1).toLowerCase() ?? "switch"]));
+        const registered = new Map(vocabulary.flags.map((flag) => [
+            flag.name,
+            [flag.value?.slice(1, -1).toLowerCase() ?? "switch", ...(flag.otherValues ?? [])],
+        ]));
         const uses = new Map();
         const note = (option, where) => {
             const name = longName(option.flags);
@@ -246,8 +249,8 @@ const CHECKS = {
         const found = [];
         for (const [name, kinds] of [...uses].sort(([a], [b]) => byText(a, b))) {
             const expected = registered.get(name);
-            const off = expected === undefined ? [] : [...kinds.keys()].filter((kind) => kind !== expected);
-            if (kinds.size < 2 && off.length === 0)
+            const off = expected === undefined ? [] : [...kinds.keys()].filter((kind) => !expected.includes(kind));
+            if (expected === undefined ? kinds.size < 2 : off.length === 0)
                 continue;
             const described = [...kinds]
                 .map(([kind, where]) => `${kind === "switch" ? "a switch" : `<${kind}>`} in ${where.slice(0, 3).join(", ")}`)
@@ -256,7 +259,7 @@ const CHECKS = {
                 target: name,
                 message: expected === undefined
                     ? `${name} has ${kinds.size} meanings: ${described}`
-                    : `${name} is ${expected === "switch" ? "a switch" : `<${expected}>`} in the vocabulary, but: ${described}`,
+                    : `${name} is ${expected[0] === "switch" ? "a switch" : expected.map((kind) => `<${kind}>`).join(" or ")} in the vocabulary, but: ${described}`,
             });
         }
         return found;

package/dist/query/fields.d.ts

@@ -18,6 +18,8 @@ export interface FieldSpec {
     native?: boolean;
     /** `and`: only as a required term, never under OR or NOT — what a relation compiled to a sub-select needs. */
     placement?: "and";
+    /** On a native list, true when the source can also leave out what matches: `-field:value` or `NOT field:value`. */
+    negatable?: boolean;
     /** Checks only this field needs; throw with `queryError`. */
     validate?: (node: Predicate) => void;
 }
@@ -44,6 +46,8 @@ export interface FieldAnnotations {
     examples?: Readonly<Record<string, string>>;
     /** On a native list, the keys the source filters. */
     native?: readonly string[];
+    /** On a native list, the keys the source can also leave out: `-event_type:birthday`. */
+    negatable?: readonly string[];
     validate?: Readonly<Record<string, (node: Predicate) => void>>;
 }
 /**

package/dist/query/fields.js

@@ -54,11 +54,13 @@ export const queryFieldsOf = (schema, annotations = {}) => {
     const excluded = new Set(annotations.exclude ?? []);
     const words = new Set(annotations.text ?? []);
     const native = new Set(annotations.native ?? []);
+    const negatable = new Set(annotations.negatable ?? []);
     const finish = (field) => ({
         ...field,
         operators: OPERATORS_BY_TYPE[field.type],
         example: annotations.examples?.[field.name] ?? field.example ?? exampleOf(field.name, field.type, field.values),
         ...(native.has(field.name) ? { native: true } : {}),
+        ...(negatable.has(field.name) ? { negatable: true } : {}),
         ...(annotations.validate?.[field.name] ? { validate: annotations.validate[field.name] } : {}),
     });
     const own = Object.entries(entries).flatMap(([name, entry]) => {

package/dist/query/help.d.ts

@@ -2,3 +2,8 @@ import type { QueryRegistry } from "./fields.js";
 export declare const QUERY_SYNTAX = "field:value \u00B7 \"a phrase\" \u00B7 word* \u00B7 AND OR NOT \u00B7 ( ) \u00B7 [a TO b] \u00B7 > >= < <=";
 /** The Fields section of a list's help: one line per field it filters by, its defaults, the syntax and the guide. */
 export declare const fieldsHelp: (registry: Pick<QueryRegistry, "fields" | "defaults"> & Partial<Pick<QueryRegistry, "backend">>, guide?: string) => string;
+/**
+ * A list's query in one sentence, for an input with no help page beside it (an MCP tool's `query`): the terms the
+ * list takes, which fields may be left out with `-`, and every field it filters by.
+ */
+export declare const queryDescription: (registry: Pick<QueryRegistry, "fields"> & Partial<Pick<QueryRegistry, "backend" | "defaults">>) => string;

package/dist/query/help.js

@@ -1,8 +1,11 @@
 export const QUERY_SYNTAX = 'field:value · "a phrase" · word* · AND OR NOT · ( ) · [a TO b] · > >= < <=';
+const shownOf = (registry) => registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
+const leftOut = (fields) => fields.filter((field) => field.negatable).map((field) => field.name);
 const kindOf = (field) => field.values ? `${field.type}: ${field.values.join("|")}` : `${field.type}: ${field.operators.join(", ")}`;
 /** The Fields section of a list's help: one line per field it filters by, its defaults, the syntax and the guide. */
 export const fieldsHelp = (registry, guide) => {
-    const shown = registry.backend === "native" ? registry.fields.filter((field) => field.native) : registry.fields;
+    const shown = shownOf(registry);
+    const negatable = leftOut(shown);
     const rows = shown.map((field) => [field.name, kindOf(field), field.example]);
     const widths = [0, 1].map((at) => Math.max(...rows.map((row) => (row[at] ?? "").length)));
     return [
@@ -11,7 +14,28 @@ export const fieldsHelp = (registry, guide) => {
         ...(registry.defaults && registry.defaults.length > 0
             ? [`Defaults: ${registry.defaults.join(" ")} — name the field to change it`]
             : []),
+        ...(negatable.length > 0
+            ? [`Leave out: -${negatable[0]}:value or NOT ${negatable[0]}:value, for ${negatable.join(", ")}`]
+            : []),
         `Syntax: ${QUERY_SYNTAX}`,
         ...(guide ? [`Guide: ${guide}`] : []),
     ].join("\n");
 };
+/**
+ * A list's query in one sentence, for an input with no help page beside it (an MCP tool's `query`): the terms the
+ * list takes, which fields may be left out with `-`, and every field it filters by.
+ */
+export const queryDescription = (registry) => {
+    const shown = shownOf(registry);
+    if (shown.length === 0)
+        return "field:value terms; this list filters by none yet, so any term is refused";
+    const negatable = leftOut(shown);
+    const terms = registry.backend === "native"
+        ? `field:value terms joined by AND that narrow the list${negatable.length > 0
+            ? `; -field:value or NOT field:value leaves out what matches, for ${negatable.join(", ")} only`
+            : ""}`
+        : "field:value terms that narrow the list (Lucene: AND OR NOT, -field:value, [a TO b], > <)";
+    const fields = shown.map((field) => (field.values ? `${field.name} (${field.values.join("|")})` : field.name));
+    const defaults = registry.defaults?.length ? `; unless named: ${registry.defaults.join(" ")}` : "";
+    return `${terms}; fields: ${fields.join(", ")}; e.g. ${shown[0]?.example ?? ""}${defaults}`;
+};

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
 export { type DateRange, dateEndpoint, dateRange, dayBoundary, timezoneOf, wallTime, zonedMoment } from "./dates.js";
 export { type EvaluateOptions, evaluate } from "./evaluate.js";
 export { FIELD_TYPES, type FieldAnnotations, type FieldSpec, type FieldType, OPERATORS_BY_TYPE, QUERY_BACKENDS, type QueryBackend, type QueryRegistry, queryFieldsOf, } from "./fields.js";
-export { fieldsHelp, QUERY_SYNTAX } from "./help.js";
+export { fieldsHelp, QUERY_SYNTAX, queryDescription } from "./help.js";
 export { implicitTextTerms, type ParseOptions, parseLucene } from "./parser.js";
 export { defineQuery, describeQuery, exampleProblems, type FieldInfo, QUERY_REASONS, type QueryInfo, } from "./registry.js";
 export { type Occur, type Operator, type Predicate, QUERY_LIMITS, type QueryAst, type QueryContext, type QueryNode, queryAstSchema, queryError, queryNodeSchema, type Span, walkQuery, } from "./types.js";

package/dist/query/index.js

@@ -5,7 +5,7 @@
 export { dateEndpoint, dateRange, dayBoundary, timezoneOf, wallTime, zonedMoment } from "./dates.js";
 export { evaluate } from "./evaluate.js";
 export { FIELD_TYPES, OPERATORS_BY_TYPE, QUERY_BACKENDS, queryFieldsOf, } from "./fields.js";
-export { fieldsHelp, QUERY_SYNTAX } from "./help.js";
+export { fieldsHelp, QUERY_SYNTAX, queryDescription } from "./help.js";
 export { implicitTextTerms, parseLucene } from "./parser.js";
 export { defineQuery, describeQuery, exampleProblems, QUERY_REASONS, } from "./registry.js";
 export { QUERY_LIMITS, queryAstSchema, queryError, queryNodeSchema, walkQuery, } from "./types.js";

package/dist/standards/flags-what.js

@@ -444,10 +444,11 @@ export const WHAT_FLAGS = [
     { name: "--task", value: "<id>", role: "target", type: "id", meaning: "a task, by id" },
     {
         name: "--to",
-        value: "<chat|address>",
+        value: "<chat>",
         role: "target",
-        type: "string",
-        meaning: "who it goes to: a chat in a messenger, an e-mail address in mail; repeat it for more addresses",
+        type: "id",
+        otherValues: ["address"],
+        meaning: "who it goes to: a chat in a messenger (<chat>), an e-mail address in mail (<address>, repeated for more)",
     },
     {
         name: "--topic-name",
@@ -895,10 +896,11 @@ export const WHAT_FLAGS = [
     { name: "--sticker", value: "<id>", role: "value", type: "id", meaning: "send this sticker, alone" },
     {
         name: "--subject",
-        value: "<ref|text>",
+        value: "<ref>",
         role: "value",
         type: "string",
-        meaning: "what it is about: a reference in a note or task, the subject line in mail",
+        otherValues: ["text"],
+        meaning: "what it is about: a reference in a note or task (<ref>), the subject line in mail (<text>)",
         replaces: ["--about"],
     },
     {

package/dist/standards/index.d.ts

@@ -1,6 +1,6 @@
 export { EFFECT_LEVELS, type EffectLevel, type Effects, effectsSchema, writes } from "./effects.js";
 export { BASE_REASONS, COMMON_DETAILS, CRASH_CODE, CRASH_REASON, defineReasons, type ErrorObject, type ErrorReason, errorObjectSchema, } from "./errors.js";
 export { defineLogEvents, isContentKey, LOG_ATTRIBUTE_KEYS, LOG_EVENTS, LOG_SEVERITIES, type LogEvent, type LogRecord, type LogSeverity, logAttributesJsonSchema, logEventProblems, logRecordSchema, traceIdOf, } from "./log.js";
-export { type Issue, type ItemEnvelope, isoTime, issueSchema, itemEnvelopeSchema, jsonlEndSchema, jsonlItemSchema, jsonlOf, type ListEnvelope, listEnvelopeSchema, MAX_NEXT_STEPS, type Meta, type Missing, metaSchema, missingSchema, type NextStep, nextStepSchema, type Page, pageSchema, reference, type Total, totalSchema, } from "./output.js";
+export { clockMeta, type Issue, type ItemEnvelope, isoTime, issueSchema, itemEnvelopeSchema, jsonlEndSchema, jsonlItemSchema, jsonlOf, type ListEnvelope, listEnvelopeSchema, localTime, MAX_NEXT_STEPS, type Meta, type Missing, metaSchema, missingSchema, type NextStep, nextStepSchema, type Page, pageSchema, reference, type Total, totalSchema, } from "./output.js";
 export { fill, jsonSchemaOf, RegistryError } from "./registry.js";
 export { defineSteps, SAME_COMMAND, STEPS, type StepDefinition, type StepInput, type StepTarget, stepOf, } from "./steps.js";

package/dist/standards/index.js

@@ -1,6 +1,6 @@
 export { EFFECT_LEVELS, effectsSchema, writes } from "./effects.js";
 export { BASE_REASONS, COMMON_DETAILS, CRASH_CODE, CRASH_REASON, defineReasons, errorObjectSchema, } from "./errors.js";
 export { defineLogEvents, isContentKey, LOG_ATTRIBUTE_KEYS, LOG_EVENTS, LOG_SEVERITIES, logAttributesJsonSchema, logEventProblems, logRecordSchema, traceIdOf, } from "./log.js";
-export { isoTime, issueSchema, itemEnvelopeSchema, jsonlEndSchema, jsonlItemSchema, jsonlOf, listEnvelopeSchema, MAX_NEXT_STEPS, metaSchema, missingSchema, nextStepSchema, pageSchema, reference, totalSchema, } from "./output.js";
+export { clockMeta, isoTime, issueSchema, itemEnvelopeSchema, jsonlEndSchema, jsonlItemSchema, jsonlOf, listEnvelopeSchema, localTime, MAX_NEXT_STEPS, metaSchema, missingSchema, nextStepSchema, pageSchema, reference, totalSchema, } from "./output.js";
 export { fill, jsonSchemaOf, RegistryError } from "./registry.js";
 export { defineSteps, SAME_COMMAND, STEPS, stepOf, } from "./steps.js";

package/dist/standards/output.d.ts

@@ -2,6 +2,8 @@ import * as v from "valibot";
 /** At most two next steps per answer: the one to take, then one alternative. */
 export declare const MAX_NEXT_STEPS = 2;
 export declare const isoTime: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+/** The same moment on the wall clock of a zone, with its offset: `2026-11-02T16:03:00.000+01:00` (WC-TIME-2). */
+export declare const localTime: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>;
 /** The typed name of a stored thing, `msg:telegram/1/2/3` or `note:42`: what every other command takes. */
 export declare const reference: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
 export declare const nextStepSchema: v.VariantSchema<"kind", [v.StrictObjectSchema<{
@@ -83,11 +85,23 @@ export declare const metaSchema: v.StrictObjectSchema<{
     }, undefined>, undefined>, undefined>;
     readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
     readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+    /** When the command answered, for an agent that plans from "now" (WC-TIME-7); `timezone` names the zone of `now_local`. */
+    readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+    readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
     readonly window: v.OptionalSchema<v.StrictObjectSchema<{
         readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     }, undefined>, undefined>;
 }, undefined>;
+/**
+ * `meta.now`, `meta.now_local` and `meta.timezone` for an answer an agent plans by (WC-TIME-7): the moment in UTC, the
+ * same moment on the zone's wall clock, and the zone.
+ */
+export declare const clockMeta: (at: number, zone: string) => {
+    now: string;
+    now_local: string;
+    timezone: string;
+};
 export declare const listEnvelopeSchema: <T extends v.GenericSchema>(item: T) => v.StrictObjectSchema<{
     readonly items: v.ArraySchema<T, undefined>;
     readonly page: v.VariantSchema<"mode", [v.StrictObjectSchema<{
@@ -163,6 +177,9 @@ export declare const listEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        /** When the command answered, for an agent that plans from "now" (WC-TIME-7); `timezone` names the zone of `now_local`. */
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
@@ -225,6 +242,9 @@ export declare const itemEnvelopeSchema: <T extends v.GenericSchema>(item: T) =>
         }, undefined>, undefined>, undefined>;
         readonly truncated: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly timezone: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
+        /** When the command answered, for an agent that plans from "now" (WC-TIME-7); `timezone` names the zone of `now_local`. */
+        readonly now: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly now_local: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "an ISO 8601 time with its offset">]>, undefined>;
         readonly window: v.OptionalSchema<v.StrictObjectSchema<{
             readonly since: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
             readonly until: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;

package/dist/standards/output.js

@@ -4,6 +4,8 @@ import { dottedId, text } from "./registry.js";
 /** At most two next steps per answer: the one to take, then one alternative. */
 export const MAX_NEXT_STEPS = 2;
 export const isoTime = v.pipe(v.string(), v.isoTimestamp("an ISO 8601 time in UTC"), v.endsWith("Z", "an ISO 8601 time in UTC, ending in `Z`"));
+/** The same moment on the wall clock of a zone, with its offset: `2026-11-02T16:03:00.000+01:00` (WC-TIME-2). */
+export const localTime = v.pipe(v.string(), v.regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/, "an ISO 8601 time with its offset"));
 /** The typed name of a stored thing, `msg:telegram/1/2/3` or `note:42`: what every other command takes. */
 export const reference = v.pipe(v.string(), v.regex(/^[a-z]+:\S+$/, "a reference such as `note:42`"));
 export const nextStepSchema = v.variant("kind", [
@@ -81,8 +83,28 @@ export const metaSchema = v.strictObject({
     issues: v.optional(v.array(issueSchema)),
     truncated: v.optional(v.boolean()),
     timezone: v.optional(text),
+    /** When the command answered, for an agent that plans from "now" (WC-TIME-7); `timezone` names the zone of `now_local`. */
+    now: v.optional(isoTime),
+    now_local: v.optional(localTime),
     window: v.optional(v.strictObject({ since: v.optional(isoTime), until: v.optional(isoTime) })),
 });
+const offsetOf = (at, zone) => {
+    const name = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "longOffset" })
+        .formatToParts(at)
+        .find((part) => part.type === "timeZoneName")?.value ?? "GMT";
+    return name === "GMT" ? "+00:00" : name.slice(3);
+};
+/**
+ * `meta.now`, `meta.now_local` and `meta.timezone` for an answer an agent plans by (WC-TIME-7): the moment in UTC, the
+ * same moment on the zone's wall clock, and the zone.
+ */
+export const clockMeta = (at, zone) => {
+    const offset = offsetOf(at, zone);
+    const sign = offset.startsWith("-") ? -1 : 1;
+    const [hours = 0, minutes = 0] = offset.slice(1).split(":").map(Number);
+    const wall = new Date(at + sign * (hours * 60 + minutes) * 60_000).toISOString().slice(0, -1);
+    return { now: new Date(at).toISOString(), now_local: `${wall}${offset}`, timezone: zone };
+};
 const nextSteps = v.optional(v.pipe(v.array(nextStepSchema), v.maxLength(MAX_NEXT_STEPS)));
 export const listEnvelopeSchema = (item) => v.strictObject({
     items: v.array(item),

package/dist/standards/vocabulary.d.ts

@@ -43,6 +43,11 @@ export declare const vocabularySchema: v.StrictObjectSchema<{
         readonly type: v.PicklistSchema<readonly ["switch", "count", "number", "string", "id", "time", "duration", "choice", "list", "path", "cursor"], undefined>;
         readonly role: v.PicklistSchema<["action" | "budget" | "mode" | "output" | "paging" | "query" | "scope" | "sort" | "target" | "value", ...("action" | "budget" | "mode" | "output" | "paging" | "query" | "scope" | "sort" | "target" | "value")[]], undefined>;
         readonly meaning: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
+        /**
+         * Value names a domain other than the main one gives the flag, such as mail's `--to <address>` beside the
+         * messengers' `<chat>`. The meaning for each says which is which. `flag-two-meanings` accepts these and no others.
+         */
+        readonly otherValues: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a value name such as address">]>, undefined>, undefined>;
         readonly unit: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
         /** Other names for the same flag, which `flag-synonym` refuses. */
         readonly replaces: v.OptionalSchema<v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a long flag">]>, undefined>, undefined>;

package/dist/standards/vocabulary.js

@@ -49,6 +49,11 @@ const flagSchema = v.strictObject({
     type: v.picklist(FLAG_TYPES),
     role: v.picklist(Object.keys(FLAG_ROLES)),
     meaning: text,
+    /**
+     * Value names a domain other than the main one gives the flag, such as mail's `--to <address>` beside the
+     * messengers' `<chat>`. The meaning for each says which is which. `flag-two-meanings` accepts these and no others.
+     */
+    otherValues: v.optional(v.array(v.pipe(v.string(), v.regex(/^[a-z][a-z0-9-]*$/, "a value name such as address")))),
     unit: v.optional(text),
     /** Other names for the same flag, which `flag-synonym` refuses. */
     replaces: v.optional(v.array(v.pipe(v.string(), v.regex(/^--[a-z][a-z0-9]*(-[a-z0-9]+)*$/, "a long flag")))),

package/docs/standards/README.md

@@ -44,7 +44,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 | [Comparisons](comparisons.md) | `CMP` | 11 | Which tools a comparison page lists, rows as user tasks, agents and safety, where others are better, proof of marks |
 | [Releases](releases.md) | `REL` | 15 | `bin/release`, the release lock, versions, the owner's yes, trusted publishing |
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
-| [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |
+| [Time](time.md) | `TIME` | 7 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone, the time in answers agents plan by |
 | [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |
 | [New CLI](new-cli.md) | — | — | Starting a new CLI from the template: the command, the four manual steps, the checks |
 | [Kit surface](kit-surface.md) | — | — | The cli-base and cli-core exports the template is built on, and how a change to one reaches you |

package/docs/standards/commands.md

@@ -214,7 +214,10 @@ store or files without reading the service first (`remote: "none"`, `local: "wri
 - **Exceptions:** none. Without `effects`, the error handler never marks a failure safe to retry, and a next step
   that runs the command is never safe to run unasked. cli-base's `writes()` (`src/standards/effects.ts`) still
   counts every local write as a write; cli-core's MCP router adds its own `fetchesOnly` test (cli-core 0.468.0), so
-  `sync` and `calendars list` run through `read`.
+  `sync` and `calendars list` run through `read`. A command whose only local write is the file an owner-only option
+  names (`mcp: false`, such as `events export --output`) stays a write, and cli-core's `writesFileOnlyWith` marks it:
+  an MCP tool never offers the option, so it runs through `read`, and `<PREFIX>_READ_ONLY` refuses only a run that
+  gives the option.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0 (what counts as a read: cli-base 0.65.0). **Rulings:** the
   owner's ruling on what counts as a read over MCP (2026-10-27).
 

package/docs/standards/mcp.md

@@ -80,6 +80,8 @@ A command that reads the service and only saves what it read into the owner's lo
 - **Enforced by:** `cli-core: src/mcp/mcp.test.ts` · `cli-core: src/mcp/output-schema.test.ts`.
 - **Example:** `max_read { "command": "messages send", … }` is refused. `gcal_read { "command": "sync" }` runs:
   cli-core counts a command that only fetches into the local store as a read (`fetchesOnly`, cli-core 0.468.0).
+  `gcal_read { "command": "events export", … }` runs too: its one write is the file `--output` names, and MCP tools
+  never offer `--output` (cli-core's `writesFileOnlyWith`).
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0 (what counts as a read: cli-base 0.65.0). **Rulings:** the
   owner's ruling on what counts as a read over MCP (2026-10-27).

package/docs/standards/time.md

@@ -98,6 +98,22 @@ repository that stores times has a test that writes the same input under two zon
 - **Exceptions:** a repository that keeps no time skips the second test.
 - **Applies to:** all CLIs, cli-core and cli-base. **Since:** cli-base 0.48.0. **Rulings:** none.
 
+### WC-TIME-7 · Give the time and the zone in use where an agent plans from "now"
+
+An answer an agent reads to plan or schedule — a calendar's events, a meeting's preparation, a setup check — carries
+`meta.now` (the moment it answered, in UTC), `meta.now_local` (the same moment with the offset of the zone in use) and
+`meta.timezone`. cli-base's `clockMeta(now, zone)` builds the three from the command's clock.
+
+- **Why:** a model does not know the time, and guesses "today" and "next Monday" from its training. A widely used Google
+  Calendar MCP server gives its agents a `get-current-time` tool for the same reason; an answer that already carries
+  the time needs no extra call.
+- **Enforced by:** review only.
+- **Example:** `gcal personal events list --json` answers with `"meta": { "now": "2026-11-02T15:03:00.000Z",
+  "now_local": "2026-11-02T16:03:00.000+01:00", "timezone": "Europe/Madrid", … }`.
+- **Exceptions:** an answer about something other than the owner's time (a list of profiles, a tool catalogue)
+  leaves them out. The clock is the command's injected one, so a test pins it.
+- **Applies to:** all CLIs. **Since:** cli-base 0.72.0. **Rulings:** none.
+
 ## Sources
 
 - The owner's ruling of 21.10.2026: every time is stored and exchanged in UTC, in every repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",