@cleocode/contracts 2026.6.6 → 2026.6.8

package/src/__tests__/operation-def.test.ts

@@ -21,6 +21,8 @@ import { describe, expect, it } from 'vitest';
 import type { CanonicalDomain, Gateway, Tier } from '../dispatch/identity.js';
 import { CANONICAL_DOMAINS } from '../dispatch/identity.js';
 import type { OperationDef, Resolution } from '../dispatch/operation-def.js';
+import type { OperationInputContract } from '../operations/input-contract.js';
+import type { OperationOutputContract } from '../operations/output-contract.js';
 import type { ParamDef } from '../operations/params.js';
 
 // ─── Compile-time structural-equality helpers ───────────────────────
@@ -66,6 +68,9 @@ type _OperationDefShape = {
   requiredParams: string[];
   params?: ParamDef[];
   mcpExposed?: boolean;
+  // T11692 (DHQ-033 / DHQ-057) — optional schema-first input/output contracts.
+  inputSchema?: OperationInputContract<unknown>;
+  outputSchema?: OperationOutputContract;
 };
 
 type _AssertOperationDefPinned = AssertEquals1<Equals<OperationDef, _OperationDefShape>>;

package/src/db-recovery.ts

@@ -142,3 +142,68 @@ export interface BackupRecoverResult {
    */
   dryRun: boolean;
 }
+
+/**
+ * Per-role outcome of a `cleo doctor repair` pass (T11829 · DHQ-060).
+ *
+ * `doctor repair` first PROBES each role's live DB via `PRAGMA quick_check`
+ * (the same probe the recovery pipeline runs on snapshot candidates) and only
+ * invokes the {@link recoverMalformedDb} → quarantine → restore-from-snapshot →
+ * verify pipeline for roles that are actually malformed. This record captures
+ * what was observed and done for one role.
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairRoleResult {
+  /** Canonical role inspected. */
+  role: DbRole;
+  /** Absolute path to the role's live DB file (resolved from `DB_INVENTORY`). */
+  dbPath: string;
+  /** `true` when the live DB file exists on disk. */
+  present: boolean;
+  /**
+   * `true` when the live DB passed `PRAGMA quick_check` (or was absent) — i.e.
+   * NO repair was needed. `false` when corruption was detected.
+   */
+  healthy: boolean;
+  /**
+   * `'skipped'` — healthy or absent, nothing done;
+   * `'would-repair'` — `--dry-run`, corruption detected, repair NOT performed;
+   * `'repaired'` — corruption detected and snapshot restore succeeded;
+   * `'failed'` — corruption detected but recovery could not complete.
+   */
+  action: 'skipped' | 'would-repair' | 'repaired' | 'failed';
+  /** Absolute path to the snapshot restored (or that would be), when applicable. */
+  restoredFrom: string | null;
+  /** Absolute path to the quarantined corrupt DB, when a repair was performed. */
+  quarantinedTo: string | null;
+  /** Approximate data-loss window in hours, when a snapshot timestamp was parsed. */
+  dataLossWindowHours: number | null;
+  /** Human-readable detail (probe outcome, error reason, or restore summary). */
+  detail: string;
+}
+
+/**
+ * Aggregate result of a `cleo doctor repair` invocation across one or more roles
+ * (T11829 · DHQ-060).
+ *
+ * @task T11829
+ * @epic T11833
+ * @saga T11242
+ * @public
+ */
+export interface DoctorRepairResult {
+  /** `true` when the run was a `--dry-run` (no files mutated). */
+  dryRun: boolean;
+  /** Per-role outcomes. */
+  roles: DoctorRepairRoleResult[];
+  /** Count of roles found malformed (`!healthy`). */
+  malformedCount: number;
+  /** Count of roles actually repaired this run. */
+  repairedCount: number;
+  /** Count of roles where a needed repair FAILED. */
+  failedCount: number;
+}

package/src/dispatch/operation-def.ts

@@ -28,6 +28,8 @@
  * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
  */
 
+import type { OperationInputContract } from '../operations/input-contract.js';
+import type { OperationOutputContract } from '../operations/output-contract.js';
 import type { ParamDef } from '../operations/params.js';
 import type { CanonicalDomain, Gateway, Tier } from './identity.js';
 
@@ -92,6 +94,48 @@ export interface OperationDef {
    * @task T11448
    */
   mcpExposed?: boolean;
+
+  /**
+   * Schema-first INPUT contract for this operation (DHQ-033 / T11692).
+   *
+   * Declares the accepted request payload shape as a JSON Schema draft-07
+   * document with worked examples. When present, the dispatch/CLI layer
+   * validates the incoming payload against `inputSchema.schema` and rejects
+   * unknown keys LOUDLY (the schemas set `additionalProperties: false`), so a
+   * typo'd or unsupported field — e.g. passing `relates` to `tasks.add-batch`,
+   * which only accepts `depends` — fails fast with a typed {@link ValidationError}
+   * instead of being silently dropped.
+   *
+   * **Optional / incremental**: absent means "no declared input contract yet".
+   * The canonical SSoT registry of contracts is keyed by `<domain>.<operation>`
+   * (INPUT_CONTRACTS in core); this inline field lets a definition carry its
+   * own contract and is resolved by the SDK `describeOperation` when set.
+   *
+   * @see OperationInputContract
+   * @task T11692 — DHQ-033 input shape SSoT
+   */
+  inputSchema?: OperationInputContract<unknown>;
+
+  /**
+   * Schema-first OUTPUT contract for this operation (DHQ-057 / T11692).
+   *
+   * Declares the shape of the LAFS envelope's `data` payload as a JSON Schema
+   * draft-07 document, PLUS the curated list of valid `--field` JSON pointers.
+   * This is the SSoT that lets an agent predict the result shape instead of
+   * hand-sniffing it per verb — e.g. it encodes that `tasks.show` returns the
+   * task under `task`, so the correct pointer is `/data/task/title` and NOT
+   * `/data/title` (the latter is the exact `E_FIELD_NOT_FOUND` failure this
+   * field exists to prevent).
+   *
+   * **Optional / incremental**: absent means "no declared output contract yet".
+   * The canonical SSoT registry is keyed by `<domain>.<operation>`
+   * (OUTPUT_CONTRACTS in contracts); this inline field lets a definition carry
+   * its own contract and is resolved by the SDK `describeOperation` when set.
+   *
+   * @see OperationOutputContract
+   * @task T11692 — DHQ-057 output shape SSoT
+   */
+  outputSchema?: OperationOutputContract;
 }
 
 // ── Resolution ───────────────────────────────────────────────────────

package/src/dispatch/operations-registry.ts

@@ -7117,7 +7117,7 @@ export const OPERATIONS: OperationDef[] = [
     domain: 'docs',
     operation: 'add',
     description:
-      'docs.add (mutate) — attach a local file or URL to a CLEO owner entity (task, session, observation)',
+      'docs.add (mutate) — attach a local file, URL, or inline content to a CLEO owner entity (task, session, observation)',
     tier: 1,
     idempotent: false,
     sessionRequired: false,
@@ -7141,6 +7141,12 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Remote URL to attach',
       },
+      {
+        name: 'content',
+        type: 'string' as const,
+        required: false,
+        description: 'Inline document body (T10965); mutually exclusive with file/url',
+      },
       {
         name: 'desc',
         type: 'string' as const,

package/src/docs/provenance.ts

@@ -74,6 +74,7 @@ export const PROVENANCE_NODE_KINDS = [
  * - `related-task`    — child task is related (non-parent) to parent
  * - `linked-decision` — node references a BRAIN decision
  * - `derived-from`    — node was derived from a prior artifact
+ * - `shares-topic`    — two docs co-occur on a canonical topic slug (T11826)
  *
  * @task T10166
  */
@@ -83,7 +84,8 @@ export type ProvenanceEdgeRelation =
   | 'superseded-by'
   | 'related-task'
   | 'linked-decision'
-  | 'derived-from';
+  | 'derived-from'
+  | 'shares-topic';
 
 /**
  * Frozen const array backing {@link ProvenanceEdgeRelation} — used by the
@@ -98,6 +100,7 @@ export const PROVENANCE_EDGE_RELATIONS = [
   'related-task',
   'linked-decision',
   'derived-from',
+  'shares-topic',
 ] as const satisfies ReadonlyArray<ProvenanceEdgeRelation>;
 
 /**

package/src/docs/read.ts

@@ -0,0 +1,131 @@
+/**
+ * `docs.read` core-SDK contract — the envelope-typed surface an external
+ * consumer (the Obsidian plugin, `cleo docs view`) calls to render a single
+ * CLEO doc directly from `cleo.db`, the SOLE doc authority (saga T11778).
+ *
+ * The response carries the doc **body** plus its full provenance **frontmatter**
+ * (slug, version anchors, supersession pointers, related tasks, topics). Binary
+ * or non-UTF-8 bodies are surfaced as base64 (T11825 AC2) so a consumer can
+ * render images/PDFs/files stored as blobs without a second round-trip.
+ *
+ * Part of the T10400 core-SDK API standard — this is a typed contract, not an
+ * ad-hoc shape (T11825 AC3).
+ *
+ * @task T11825 (Epic T11781 / Saga T11778)
+ * @adr ADR-078 — Docs SSoT as provenance graph
+ */
+
+import { z } from 'zod';
+
+/**
+ * Provenance frontmatter for a doc, sourced from the `attachments` columns that
+ * back the docs SSoT. Mirrors what a published doc's YAML frontmatter would
+ * carry, but read live from the DB rather than a file.
+ *
+ * @task T11825
+ */
+export interface DocFrontmatter {
+  /** Stable human-readable slug (`attachments.slug`). */
+  readonly slug: string;
+  /** Doc-kind taxonomy tag (e.g. `adr`, `spec`), or null for untyped blobs. */
+  readonly kind: string | null;
+  /** Display title (falls back to slug). */
+  readonly title: string | null;
+  /** One-sentence human summary, distinct from the body. */
+  readonly summary: string | null;
+  /** Document workflow state (`draft | active | superseded | …`). */
+  readonly lifecycleStatus: string;
+  /** Sequential doc-version counter for this slug (`attachments.doc_version`). */
+  readonly docVersion: number;
+  /** CLEO release version that wrote this row (`attachments.owner_version`). */
+  readonly ownerVersion: string | null;
+  /** Slug of the doc this one supersedes, or null. */
+  readonly supersedes: string | null;
+  /** Slug of the doc that supersedes this one, or null. */
+  readonly supersededBy: string | null;
+  /** Canonical topic slugs this doc carries (`attachments.topics`). */
+  readonly topics: readonly string[];
+  /** `T####` task ids this doc relates to (`attachments.related_tasks`). */
+  readonly relatedTasks: readonly string[];
+  /** SHA-256 content address of the body. */
+  readonly sha256: string;
+  /** ISO-8601 creation instant. */
+  readonly createdAt: string;
+}
+
+/**
+ * The body payload of a doc read.
+ *
+ * Exactly one of {@link text} / {@link base64} is populated: UTF-8-decodable
+ * content is surfaced as `text` with `encoding: 'utf-8'`; binary content is
+ * surfaced as `base64` with `encoding: 'base64'`.
+ *
+ * @task T11825
+ */
+export interface DocBody {
+  /** How {@link DocReadResponse.body} content is encoded. */
+  readonly encoding: 'utf-8' | 'base64';
+  /** UTF-8 body text, present when `encoding === 'utf-8'`. */
+  readonly text?: string;
+  /** Base64-encoded body bytes, present when `encoding === 'base64'`. */
+  readonly base64?: string;
+  /** Decoded byte length of the body. */
+  readonly sizeBytes: number;
+  /** IANA MIME type, when known. */
+  readonly mimeType: string | null;
+}
+
+/**
+ * The full `docs.read` response envelope payload.
+ *
+ * @task T11825
+ */
+export interface DocReadResponse {
+  /** Provenance frontmatter. */
+  readonly frontmatter: DocFrontmatter;
+  /** Rendered body (text or base64). */
+  readonly body: DocBody;
+}
+
+/** Zod schema for {@link DocFrontmatter}. */
+export const docFrontmatterSchema = z.object({
+  slug: z.string(),
+  kind: z.string().nullable(),
+  title: z.string().nullable(),
+  summary: z.string().nullable(),
+  lifecycleStatus: z.string(),
+  docVersion: z.number().int(),
+  ownerVersion: z.string().nullable(),
+  supersedes: z.string().nullable(),
+  supersededBy: z.string().nullable(),
+  topics: z.array(z.string()).readonly(),
+  relatedTasks: z.array(z.string()).readonly(),
+  sha256: z.string(),
+  createdAt: z.string(),
+});
+
+/** Zod schema for {@link DocBody}. */
+export const docBodySchema = z.object({
+  encoding: z.enum(['utf-8', 'base64']),
+  text: z.string().optional(),
+  base64: z.string().optional(),
+  sizeBytes: z.number().int().nonnegative(),
+  mimeType: z.string().nullable(),
+});
+
+/** Zod schema for {@link DocReadResponse}. */
+export const docReadResponseSchema = z.object({
+  frontmatter: docFrontmatterSchema,
+  body: docBodySchema,
+});
+
+/**
+ * Type guard for {@link DocReadResponse}.
+ *
+ * @param value - Unknown value to validate.
+ * @returns True when `value` conforms to the `docs.read` response schema.
+ * @task T11825
+ */
+export function isDocReadResponse(value: unknown): value is DocReadResponse {
+  return docReadResponseSchema.safeParse(value).success;
+}

package/src/index.ts

@@ -346,6 +346,8 @@ export type {
   BackupRecoverResult,
   DbRecoveredRowCounts,
   DbRecoveryResult,
+  DoctorRepairResult,
+  DoctorRepairRoleResult,
 } from './db-recovery.js';
 // === Dependency Registry Contracts ===
 export type {
@@ -398,6 +400,14 @@ export {
   provenanceSessionNodeSchema,
   provenanceTaskNodeSchema,
 } from './docs/provenance.js';
+// === docs.read core-SDK Contract (T11825) ===
+export type { DocBody, DocFrontmatter, DocReadResponse } from './docs/read.js';
+export {
+  docBodySchema,
+  docFrontmatterSchema,
+  docReadResponseSchema,
+  isDocReadResponse,
+} from './docs/read.js';
 // === DocsAccessor Contracts (T9063) ===
 export type {
   DocExportFormat,
@@ -1318,6 +1328,15 @@ export type {
   OrchestrateReportGroup,
   OrchestrateReportParams,
 } from './operations/orchestrate.js';
+// === Operation Output Contracts (T11692 / DHQ-057 — per-op result shape SSoT) ===
+// OUTPUT-side mirror of the input contracts. Surfaces the LAFS envelope `data`
+// shape + valid --field JSON pointers so agents stop guessing (e.g. the real
+// pointer is /data/task/title, not /data/title).
+export type {
+  OperationOutputContract,
+  OperationOutputContractRegistry,
+} from './operations/output-contract.js';
+export { OUTPUT_CONTRACTS } from './operations/output-contracts-data.js';
 // ParamDef contract — re-exported at top level (SSoT for all operation param descriptors)
 export type {
   CittyArgDef,

package/src/llm/provider-profile.ts

@@ -14,6 +14,17 @@ import type { ModelTransport, StoredAuthTypeWire } from '../operations/llm.js';
 import type { TransportMessage, TransportTool } from './normalized-response.js';
 import type { ProviderOAuthConfig } from './oauth.js';
 
+/**
+ * Coarse provider capability tier used by the system-of-use router (E9).
+ *
+ * Ordered most→least capable: `frontier` (flagship reasoning), `standard`
+ * (general-purpose), `fast` (cheap/low-latency aux), `local` (on-device, e.g.
+ * Ollama). Sourced from the models.dev catalog (E8) when generated.
+ *
+ * @task T11756
+ */
+export type ProviderTier = 'frontier' | 'standard' | 'fast' | 'local';
+
 /**
  * Describes a single LLM provider — its auth capabilities, base URL,
  * default model, and optional live model-discovery hook.
@@ -54,9 +65,57 @@ export interface ProviderProfile {
    * Alternate names that resolve to this profile. Resolution is
    * case-insensitive. Alias conflicts with another profile's primary name
    * cause a `TypeError` at registration time.
+   *
+   * The canonical alias map (`codex`→`openai`, `google`→`gemini`, …) is declared
+   * here as DATA so the resolver never branches on provider name in code
+   * (T11756 AC2 · hermes `ProviderProfile.aliases` parity).
    */
   aliases?: ReadonlyArray<string>;
 
+  /**
+   * Coarse capability tier for system-of-use routing (E9). Sourced from the
+   * models.dev catalog capabilities when generated (E8 join), hand-set for
+   * builtins. Absent = unknown (the router treats it as `standard`).
+   *
+   * Hermes derives this from `model_metadata`; CLEO carries it as profile DATA
+   * so `resolveLLMForSystem` can pick the right tier without a code branch.
+   *
+   * @task T11756
+   */
+  readonly tier?: ProviderTier;
+
+  /**
+   * Cheap/fast auxiliary model for low-stakes calls (title generation, summaries,
+   * the warm/aux tier). Hermes `ProviderProfile.default_aux_model` parity. Absent
+   * (or empty) → fall back to {@link defaultModel}.
+   *
+   * @task T11756
+   */
+  readonly defaultAuxModel?: string;
+
+  /**
+   * Default `maxTokens` for this provider when the caller omits it. Hermes
+   * `ProviderProfile.default_max_tokens` parity. Absent → the transport's own
+   * default applies.
+   *
+   * @task T11756
+   */
+  readonly defaultMaxTokens?: number;
+
+  /**
+   * Temperature handling this provider REQUIRES. Hermes
+   * `ProviderProfile.fixed_temperature` parity:
+   *  - a `number` — the provider only accepts this exact temperature (e.g. the
+   *    OpenAI o-series require `1`); the transport MUST send it and ignore the
+   *    caller's override.
+   *  - `'omit'` — the provider rejects a `temperature` field entirely; the
+   *    transport MUST NOT send one.
+   *  - absent — the caller's temperature (or the transport default) applies.
+   *
+   * @task T11756
+   */
+  readonly fixedTemperature?: number | 'omit';
+
   /**
    * HTTP headers sent with every request to this provider.
    * Merged into the SDK client's `defaultHeaders`.

package/src/operations/__tests__/output-contracts.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for the per-operation OUTPUT contract SSoT (T11692 / DHQ-057).
+ *
+ * Pins the proof-set of OUTPUT contracts and — critically — encodes the exact
+ * shape fact that produced the bug: `tasks.show` returns the task under `task`,
+ * so the canonical pointer is `/data/task/title`, NOT `/data/title`.
+ *
+ * Also validates that mutation contracts reflect the MinimalMutateEnvelope
+ * shape (string[] ids, NOT object arrays) and that tasks.find uses the
+ * { results, total } wrapper (NOT a bare array).
+ *
+ * @task T11692
+ * @epic T11679
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { OperationOutputContract } from '../output-contract.js';
+import { OUTPUT_CONTRACTS } from '../output-contracts-data.js';
+
+describe('operations/output-contracts (T11692 · DHQ-057)', () => {
+  it('registers the high-traffic proof-set operations', () => {
+    for (const op of [
+      'tasks.show',
+      'tasks.list',
+      'tasks.find',
+      'tasks.add',
+      'tasks.add-batch',
+      'tasks.update',
+      'tasks.complete',
+    ]) {
+      expect(OUTPUT_CONTRACTS[op], `missing output contract for ${op}`).toBeDefined();
+    }
+  });
+
+  it('keys every entry by its own operation id', () => {
+    for (const [key, contract] of Object.entries(OUTPUT_CONTRACTS)) {
+      expect(contract.operation).toBe(key);
+    }
+  });
+
+  describe('tasks.show — the operation that bit us', () => {
+    const show = OUTPUT_CONTRACTS['tasks.show'] as OperationOutputContract;
+
+    it('encodes that the task is nested under `task` (data schema)', () => {
+      const schema = show.dataSchema as {
+        required?: string[];
+        properties?: Record<string, { properties?: Record<string, unknown> }>;
+      };
+      expect(schema.required).toContain('task');
+      // The title lives under task.properties.title — NOT at the data root.
+      expect(schema.properties?.task?.properties).toHaveProperty('title');
+      expect(schema.properties).not.toHaveProperty('title');
+    });
+
+    it('lists /data/task/title as a valid --field pointer and NOT /data/title', () => {
+      expect(show.fieldPointers).toContain('/data/task/title');
+      expect(show.fieldPointers).not.toContain('/data/title');
+    });
+
+    it('carries a shapeNote steering agents away from /data/<field>', () => {
+      expect(show.shapeNote).toBeTruthy();
+      expect(show.shapeNote).toContain('/data/task/');
+    });
+
+    it('notes that view may be null', () => {
+      expect(show.shapeNote).toContain('null');
+    });
+  });
+
+  describe('mutation envelopes — MinimalMutateEnvelope (string[] ids, T9931)', () => {
+    it('tasks.add surfaces the created task ID as a bare string at /data/created/0', () => {
+      const add = OUTPUT_CONTRACTS['tasks.add'] as OperationOutputContract;
+      // Correct: /data/created/0 → "T11692" (string), NOT /data/created/0/id
+      expect(add.fieldPointers).toContain('/data/created/0');
+      expect(add.fieldPointers).not.toContain('/data/created/0/id');
+      // Schema must reflect string[] items, not object[]
+      const schema = add.dataSchema as {
+        required?: string[];
+        properties?: Record<string, { items?: { type?: string } }>;
+      };
+      expect(schema.required).toEqual(
+        expect.arrayContaining(['count', 'created', 'updated', 'deleted']),
+      );
+      expect(schema.properties?.created?.items?.type).toBe('string');
+      expect(schema.properties?.updated?.items?.type).toBe('string');
+      expect(schema.properties?.deleted?.items?.type).toBe('string');
+    });
+
+    it('tasks.update / tasks.complete surface the changed task ID at /data/updated/0 (string)', () => {
+      for (const op of ['tasks.update', 'tasks.complete']) {
+        const c = OUTPUT_CONTRACTS[op] as OperationOutputContract;
+        // Correct: /data/updated/0 → "T11692" (string), NOT /data/updated/0/id
+        expect(c.fieldPointers).toContain('/data/updated/0');
+        expect(c.fieldPointers).not.toContain('/data/updated/0/id');
+        const schema = c.dataSchema as {
+          properties?: Record<string, { items?: { type?: string } }>;
+        };
+        expect(schema.properties?.updated?.items?.type).toBe('string');
+      }
+    });
+
+    it('tasks.add-batch dry-run pointers point to root /data/wouldCreate and /data/insertedCount', () => {
+      const batch = OUTPUT_CONTRACTS['tasks.add-batch'] as OperationOutputContract;
+      // Correct: root-level, NOT /data/dryRunSummary/wouldCreate
+      expect(batch.fieldPointers).toContain('/data/wouldCreate');
+      expect(batch.fieldPointers).toContain('/data/insertedCount');
+      expect(batch.fieldPointers).not.toContain('/data/dryRunSummary/wouldCreate');
+      expect(batch.fieldPointers).not.toContain('/data/dryRunSummary/insertedCount');
+      // shapeNote should clarify they are NOT under dryRunSummary
+      expect(batch.shapeNote).toContain('/data/wouldCreate');
+    });
+  });
+
+  it('tasks.find data is a wrapper object with /data/results (array) and /data/total', () => {
+    const find = OUTPUT_CONTRACTS['tasks.find'] as OperationOutputContract;
+    // Correct: wrapper object, NOT a bare array
+    expect((find.dataSchema as { type?: string }).type).toBe('object');
+    // Correct pointers
+    expect(find.fieldPointers).toContain('/data/results/0/id');
+    expect(find.fieldPointers).toContain('/data/total');
+    // Wrong pointers must NOT appear
+    expect(find.fieldPointers).not.toContain('/data/0/id');
+    expect(find.shapeNote).toContain('/data/results');
+  });
+});

package/src/operations/docs.ts

@@ -383,15 +383,25 @@ export interface DocsGenerateResult {
 /**
  * Parameters for `docs.add`.
  *
- * Exactly one of `file` or `url` must be provided.
+ * Exactly one of `file`, `url`, or `content` must be provided.
  */
 export interface DocsAddParams {
   /** Owner entity ID (task, session, observation, etc.) — required. */
   ownerId: string;
-  /** Local file path to attach (mutually exclusive with `url`). */
+  /** Local file path to attach (mutually exclusive with `url` and `content`). */
   file?: string;
-  /** URL to attach as reference (mutually exclusive with `file`). */
+  /** URL to attach as reference (mutually exclusive with `file` and `content`). */
   url?: string;
+  /**
+   * Inline document body authored directly on the command line or piped via
+   * stdin (`--content -`). Mutually exclusive with `file` and `url`. Stored
+   * as a `text/markdown` blob exactly as a file-sourced add would be —
+   * including the manifest.db mirror, slug reservation, memory observation,
+   * and audit trail — so a doc can be created without a pre-existing file.
+   *
+   * @task T10965
+   */
+  content?: string;
   /** Optional human-readable description. */
   desc?: string;
   /** Optional comma-separated labels for categorization. */