feat(update-doc-tool): add mention and column value blot support

[LinoyMargan]

Summary

• Add mention blot support (user, doc, board) to delta_format in update_doc_tool — both the create_doc_blocks path (mapDeltaFormat) and the update_doc_block path (mapDeltaFormatRaw)
• Add column_value blot support to embed column values inline in document blocks
• Use Number() for mention.id to match the docs-api expected ID type
• Omit attributes key when undefined (sending null is invalid per Quill Delta spec)
• Use @include directive to skip blocks query when include_blocks is not requested
• Bump version to 4.1.3

Monday Item

https://monday.monday.com/boards/18404309029/pulses/11549480166

Test Plan

• Create a doc block with a user mention in delta_format → mention appears correctly
• Create a doc block with a board/doc mention → mention appears correctly
• Create a doc block with a column_value blot → column value renders inline
• Update a doc block with mentions via update_doc_block → content saved correctly
• Plain text ops without attributes → attributes key omitted from JSON body

---

🤖 Generated with Claude Code

[RoniLandau]

`### Positive Aspects

1. Clean architecture: The dual-path handling (GraphQL BlotInput for create vs. raw JSON/macro format for update) is well-structured. The mapDeltaFormat and mapDeltaFormatRaw functions cleanly separate the two serialization formats.

2. Good schema design: The DeltaOperationSchema uses a z.union() discriminated on the shape of insert (text / mention / column_value), which is an idiomatic Zod pattern.

3. Solid test coverage: All 4 combinations are tested (mention x create, mention x update, column_value x create, column_value x update). The tests verify the exact payload shapes sent to the GraphQL API.

4. Helpful tool description: The updated system prompt in update-doc-tool.ts clearly documents how agents should use the new mention and column_value ops with concrete examples.

Issues & Concerns

1. Number() on mention id can silently produce NaN (Medium)

The schema accepts z.union([z.string(), z.number()]) for mention id, but the helper blindly calls Number(op.insert.mention.id). If an agent passes a non-numeric string (e.g., "abc"), this produces NaN which would be sent to the API as a silent failure. Consider adding validation:

const numericId = Number(op.insert.mention.id);
if (Number.isNaN(numericId)) {
  throw new Error(`Invalid mention id: ${op.insert.mention.id}`);
}

Or constrain the schema to only accept numeric strings via z.string().regex(/^\d+$/).

2. Inconsistent ID type coercion between paths (Low-Medium)

In mapDeltaFormat (create path), item_id is coerced with String(), but in mapDeltaFormatRaw (update path), it's coerced with Number(). This is presumably intentional (GraphQL ID type = string vs. raw JSON number), but a brief comment explaining why would help future maintainers:

// GraphQL ID scalar expects a string
item_id: String(op.insert.column_value.item_id)
 
// Raw JSON format expects a numeric itemId
itemId: Number(op.insert.column_value.item_id)

3. attributes: null still sent despite PR description claiming otherwise (Medium)

The PR description states "Omit attributes key when undefined (sending null is invalid per Quill Delta spec)", but looking at the test assertions for the raw path:

expect(content.deltaFormat[0]).toEqual({ insert: { text: 'Hey ' }, attributes: null });
expect(content.deltaFormat[2]).toEqual({ insert: { text: '\n' }, attributes: null });

attributes: null is still present in the output. If null is truly invalid per Quill Delta spec, then mapDeltaFormatRaw should filter out the key when the value is null/undefined:

const result: Record<string, unknown> = { insert: op.insert.text };
const attrs = mapAttributes(op.attributes);
if (attrs != null) result.attributes = attrs;
return result;

This seems like the stated fix wasn't actually implemented.`