chore: remove 'review' namespace in document-api, docs improvements for format aliases, new sections

Author: harbournick

apps/cli/scripts/export-sdk-contract.ts

@@ -76,7 +76,7 @@ const INTENT_NAMES = {
   'doc.comments.list': 'list_comments',
   'doc.trackChanges.list': 'list_tracked_changes',
   'doc.trackChanges.get': 'get_tracked_change',
-  'doc.review.decide': 'review_decide',
+  'doc.trackChanges.decide': 'decide_tracked_change',
   'doc.query.match': 'query_match',
   'doc.mutations.preview': 'preview_mutations',
   'doc.mutations.apply': 'apply_mutations',

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -514,7 +514,7 @@ export const SUCCESS_SCENARIOS = {
         docPath,
         '--target-json',
         JSON.stringify(target),
-        '--marks-json',
+        '--inline-json',
         JSON.stringify({ bold: true }),
         '--out',
         harness.createOutputPath('doc-style-apply-output'),
@@ -537,21 +537,21 @@ export const SUCCESS_SCENARIOS = {
       args: ['track-changes', 'get', fixture.docPath, '--id', fixture.changeId],
     };
   },
-  'doc.review.decide': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
-    const stateDir = await harness.createStateDir('doc-review-decide-success');
-    const fixture = await harness.addTrackedChangeFixture(stateDir, 'doc-review-decide');
+  'doc.trackChanges.decide': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-trackChanges-decide-success');
+    const fixture = await harness.addTrackedChangeFixture(stateDir, 'doc-trackChanges-decide');
     return {
       stateDir,
       args: [
-        'review',
+        'track-changes',
         'decide',
         fixture.docPath,
         '--decision',
         'accept',
         '--target-json',
         JSON.stringify({ id: fixture.changeId }),
         '--out',
-        harness.createOutputPath('doc-review-decide-output'),
+        harness.createOutputPath('doc-trackChanges-decide-output'),
       ],
     };
   },

apps/cli/src/cli/__tests__/schema-ref-resolution.test.ts

@@ -32,7 +32,7 @@ const $defs: Record<string, Record<string, unknown>> = {
     required: ['kind', 'blockId', 'range'],
     additionalProperties: false,
   },
-  MarkSet: {
+  InlineStylePatch: {
     type: 'object',
     properties: {
       bold: { type: 'boolean' },
@@ -71,10 +71,10 @@ describe('operation-params $ref resolution', () => {
       type: 'object',
       properties: {
         target: { $ref: '#/$defs/TextAddress' },
-        marks: { $ref: '#/$defs/MarkSet' },
+        inline: { $ref: '#/$defs/InlineStylePatch' },
         text: { type: 'string' },
       },
-      required: ['target', 'marks', 'text'],
+      required: ['target', 'inline', 'text'],
     };
     const result = jsonSchemaToTypeSpec(schema, $defs) as {
       type: string;
@@ -83,7 +83,7 @@ describe('operation-params $ref resolution', () => {
     };
     expect(result.type).toBe('object');
     expect((result.properties.target as { type: string }).type).toBe('object');
-    expect((result.properties.marks as { type: string }).type).toBe('object');
+    expect((result.properties.inline as { type: string }).type).toBe('object');
     expect((result.properties.text as { type: string }).type).toBe('string');
   });
 

apps/cli/src/cli/helper-commands.ts

@@ -4,7 +4,7 @@
  *
  * Helper commands are NOT derived from OPERATION_DEFINITIONS. They exist
  * only in the CLI and SDK layers, providing familiar shortcuts like
- * `superdoc format bold` that route to `format.apply` with marks pre-filled.
+ * `superdoc format bold` that route to `format.apply` with inline styles pre-filled.
  *
  * Each entry maps CLI tokens → canonical OperationId + default args to merge.
  * Helper commands route through the standard doc operation dispatch (read/mutation
@@ -34,7 +34,7 @@ export interface CliHelperCommand {
   inputTransform?: (input: Record<string, unknown>) => Record<string, unknown>;
 }
 
-/** Maps a flat `--id` flag to the `target: { id }` shape expected by review.decide. */
+/** Maps a flat `--id` flag to the `target: { id }` shape expected by trackChanges.decide. */
 function mapIdToTarget(input: Record<string, unknown>): Record<string, unknown> {
   if (typeof input.id === 'string' && input.target === undefined) {
     const { id, ...rest } = input;
@@ -44,7 +44,7 @@ function mapIdToTarget(input: Record<string, unknown>): Record<string, unknown>
 }
 
 /**
- * Format helper commands — map `format <mark>` to `format.apply` with pre-filled marks.
+ * Format helper commands — map `format <mark>` to `format.apply` with pre-filled inline styles.
  * These keep `superdoc format bold|italic|underline|strikethrough` as ergonomic
  * shortcuts over the canonical `format.apply` contract operation.
  */
@@ -53,7 +53,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   {
     tokens: ['format', 'bold'],
     canonicalOperationId: 'format.apply',
-    defaultInput: { marks: { bold: true } },
+    defaultInput: { inline: { bold: true } },
     description: 'Apply bold formatting to a text range.',
     category: 'format',
     mutates: true,
@@ -65,7 +65,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   {
     tokens: ['format', 'italic'],
     canonicalOperationId: 'format.apply',
-    defaultInput: { marks: { italic: true } },
+    defaultInput: { inline: { italic: true } },
     description: 'Apply italic formatting to a text range.',
     category: 'format',
     mutates: true,
@@ -74,7 +74,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   {
     tokens: ['format', 'underline'],
     canonicalOperationId: 'format.apply',
-    defaultInput: { marks: { underline: true } },
+    defaultInput: { inline: { underline: true } },
     description: 'Apply underline formatting to a text range.',
     category: 'format',
     mutates: true,
@@ -83,16 +83,16 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   {
     tokens: ['format', 'strikethrough'],
     canonicalOperationId: 'format.apply',
-    defaultInput: { marks: { strike: true } },
+    defaultInput: { inline: { strike: true } },
     description: 'Apply strikethrough formatting to a text range.',
     category: 'format',
     mutates: true,
     examples: ['superdoc format strikethrough --blockId p1 --start 0 --end 5'],
   },
-  // --- Track-changes review helpers (route to review.decide) ---
+  // --- Track-changes review helpers (route to trackChanges.decide) ---
   {
     tokens: ['track-changes', 'accept'],
-    canonicalOperationId: 'review.decide',
+    canonicalOperationId: 'trackChanges.decide',
     defaultInput: { decision: 'accept' },
     description: 'Accept a tracked change by ID.',
     category: 'trackChanges',
@@ -103,7 +103,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   },
   {
     tokens: ['track-changes', 'reject'],
-    canonicalOperationId: 'review.decide',
+    canonicalOperationId: 'trackChanges.decide',
     defaultInput: { decision: 'reject' },
     description: 'Reject a tracked change by ID.',
     category: 'trackChanges',
@@ -114,7 +114,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   },
   {
     tokens: ['track-changes', 'accept-all'],
-    canonicalOperationId: 'review.decide',
+    canonicalOperationId: 'trackChanges.decide',
     defaultInput: { decision: 'accept', target: { scope: 'all' } },
     description: 'Accept all tracked changes.',
     category: 'trackChanges',
@@ -123,7 +123,7 @@ export const CLI_HELPER_COMMANDS: readonly CliHelperCommand[] = [
   },
   {
     tokens: ['track-changes', 'reject-all'],
-    canonicalOperationId: 'review.decide',
+    canonicalOperationId: 'trackChanges.decide',
     defaultInput: { decision: 'reject', target: { scope: 'all' } },
     description: 'Reject all tracked changes.',
     category: 'trackChanges',

apps/cli/src/cli/operation-hints.ts

@@ -53,7 +53,7 @@ export const SUCCESS_VERB: Record<CliExposedOperationId, string> = {
   'comments.list': 'listed comments',
   'trackChanges.list': 'listed tracked changes',
   'trackChanges.get': 'resolved tracked change',
-  'review.decide': 'reviewed tracked change',
+  'trackChanges.decide': 'reviewed tracked change',
   'query.match': 'matched selectors',
   'mutations.preview': 'previewed mutations',
   'mutations.apply': 'applied mutations',
@@ -110,7 +110,7 @@ export const OUTPUT_FORMAT: Record<CliExposedOperationId, OutputFormat> = {
   'comments.list': 'commentList',
   'trackChanges.list': 'trackChangeList',
   'trackChanges.get': 'trackChangeInfo',
-  'review.decide': 'trackChangeMutationReceipt',
+  'trackChanges.decide': 'trackChangeMutationReceipt',
   'query.match': 'plain',
   'mutations.preview': 'plain',
   'mutations.apply': 'plain',
@@ -155,7 +155,7 @@ export const RESPONSE_ENVELOPE_KEY: Record<CliExposedOperationId, string | null>
   'comments.list': 'result',
   'trackChanges.list': 'result',
   'trackChanges.get': 'change',
-  'review.decide': 'receipt',
+  'trackChanges.decide': 'receipt',
   'query.match': 'result',
   'mutations.preview': 'result',
   'mutations.apply': 'result',
@@ -217,7 +217,7 @@ export const OPERATION_FAMILY: Record<CliExposedOperationId, OperationFamily> =
   'comments.list': 'comments',
   'trackChanges.list': 'trackChanges',
   'trackChanges.get': 'trackChanges',
-  'review.decide': 'trackChanges',
+  'trackChanges.decide': 'trackChanges',
   'query.match': 'query',
   'mutations.preview': 'general',
   'mutations.apply': 'general',

apps/cli/src/cli/operation-set.ts

@@ -94,9 +94,6 @@ function deriveCategoryFromDocApi(docApiId: OperationId): CliCategory {
     return COMMAND_CATALOG[docApiId].mutates ? 'mutation' : 'query';
   }
 
-  // Map 'review' reference group to 'trackChanges' CLI category
-  if (group === 'review') return 'trackChanges';
-
   return group as CliCategory;
 }
 

apps/cli/src/lib/operation-executor.ts

@@ -192,7 +192,7 @@ export async function executeOperation(request: ExecuteOperationRequest): Promis
         extraOptionSpecs: request.extraOptionSpecs,
       }),
     ) ?? {}) as Record<string, unknown>;
-    // Merge helper command defaults (e.g., marks: { bold: true } for `format bold`).
+    // Merge helper command defaults (e.g., inline: { bold: true } for `format bold`).
     // User-provided values take precedence over defaults.
     if (request.defaultInput) {
       input = { ...request.defaultInput, ...input };

apps/cli/src/lib/special-handlers.ts

@@ -144,7 +144,7 @@ const resolveTrackChangeId: PreInvokeHook = (input, context) => {
 };
 
 /**
- * review.decide needs stable-ID → raw-ID translation on target.id.
+ * trackChanges.decide needs stable-ID → raw-ID translation on target.id.
  */
 const resolveReviewDecideId: PreInvokeHook = (input, context) => {
   const record = asRecord(input);
@@ -230,8 +230,8 @@ const flattenTextMutationReceipt: PostInvokeHook = (result) => {
 export const PRE_INVOKE_HOOKS: Partial<Record<CliExposedOperationId, PreInvokeHook>> = {
   // Track-changes get needs stable-ID → raw-ID translation
   'trackChanges.get': resolveTrackChangeId,
-  // review.decide needs stable-ID → raw-ID translation on target.id
-  'review.decide': resolveReviewDecideId,
+  // trackChanges.decide needs stable-ID → raw-ID translation on target.id
+  'trackChanges.decide': resolveReviewDecideId,
 };
 
 /** Post-invoke: transform the raw invoke() result before envelope wrapping. */

apps/docs/CLAUDE.md

@@ -21,7 +21,7 @@ Document API docs have mixed manual/generated ownership. Treat these paths as au
 
 - `apps/docs/document-api/reference/*`: generated, committed to git (Mintlify deploys from git), do not hand-edit.
 - `packages/document-api/generated/*`: generated, **not in git**, do not hand-edit. Run `pnpm run generate:all` to produce.
-- `apps/docs/document-api/overview.mdx`: manual except for the block between:
+- `apps/docs/document-api/available-operations.mdx`: manual except for the block between:
   - `{/* DOC_API_OPERATIONS_START */}`
   - `{/* DOC_API_OPERATIONS_END */}`
 

apps/docs/docs.json

@@ -94,7 +94,15 @@
             "tag": "ALPHA",
             "pages": [
               "document-engine/overview",
-              "document-api/overview",
+              {
+                "group": "Document API",
+                "pages": [
+                  "document-api/overview",
+                  "document-api/reference/index",
+                  "document-api/common-workflows",
+                  "document-api/available-operations"
+                ]
+              },
               "document-engine/sdks",
               "document-engine/cli",
               "document-engine/mcp"