feat: support append mode for Tana field updates

[jcfischer]

Summary

• expose Tana Local API mode: "append" for text/content field updates
• expose the same append mode for option-field updates on multi-value fields
• update CLI, MCP schemas/handlers, backend/client types, docs, and focused tests

OpenAPI Evidence

Observed locally on 2026-06-22 with:

rtk bun -e "const spec=await fetch('http://localhost:8262/openapi.json').then(r=>r.json()); ..."

The OpenAPI document reports:

• openapi: 3.1.1
• info.title: Tana Local API
• info.version: 1.0.0

Relevant request-body schemas:

{
  "path": "/nodes/{nodeId}/fields/{attributeId}/content",
  "properties": {
    "content": {
      "anyOf": [{ "type": "string" }, { "type": "null" }],
      "description": "The string value to set (null to clear the field)"
    },
    "mode": {
      "enum": ["replace", "append"],
      "default": "replace",
      "description": "Whether to replace the existing value or append to it (for multi-value fields)"
    }
  },
  "required": ["content"]
}

{
  "path": "/nodes/{nodeId}/fields/{attributeId}/option",
  "properties": {
    "optionId": {
      "type": "string",
      "description": "The node id of the option value to set"
    },
    "mode": {
      "enum": ["replace", "append"],
      "default": "replace",
      "description": "Whether to replace the existing value or append to it (for multi-value fields)"
    }
  },
  "required": ["optionId"]
}

The option endpoint schema is singular (optionId, not optionIds), so appending several option values means making one append call per option.

Verification

• rtk bunx tsc --noEmit
• rtk bun test tests/integration/local-api-integration.test.ts src/mcp/tools/__tests__/tool-schema.test.ts tests/unit/tool-mode.test.ts tests/unit/mcp-tool-mode-integration.test.ts

[jcfischer]

Sage code review — changes-requested

1 finding(s): 1 important.

HonestOracle

• [important] PR description:13 — Unverifiable append API claim
  The description claims, "The local Tana OpenAPI at http://localhost:8262/openapi.json documents mode: \"replace\" | \"append\" on both" and "Option append accepts one optionId per call; callers can append multiple options with repeated calls." The cited source is a localhost runtime URL with no captured schema excerpt, Tana version, or reproducible output, so reviewers cannot verify the option-append contract the docs and tooling now rely on.

---

Posted by Sage on Codex CLI substrate.

[jcfischer]

Sage code review — changes-requested

1 finding(s): 1 important.

Architecture

• [important] README.md:196 — Placeholder leaks into public CLI
  The public examples supertag set-field <nodeId> <attributeId> _ --option-id <optionId> and supertag set-field <nodeId> <attributeId> _ --option-id <optionId> --append cement a meaningless content placeholder into the option-field API surface. Fixing that later would be a breaking CLI shape change for option-field updates.
  Fix: Make <value> optional when --option-id is present, or expose an option-specific command before documenting append.

---

Posted by Sage on Codex CLI substrate.

[jcfischer]

Sage code review — approved

No findings. Sage approves.

---

Posted by Sage on Codex CLI substrate.

[jcfischer]

Sage code review — approved

No findings. Sage approves.

---

Posted by Sage on Codex CLI substrate.