drupal-mcp-connector 2.14.2 → 2.15.0

package/src/tools/nodes.js

@@ -14,7 +14,7 @@ import {
   assertReadAllowed, assertWriteAllowed, assertDeleteAllowed, assertPublishAllowed,
 } from "../lib/security.js";
 import { applySafeDraftDefault, hasExplicitModerationState } from "../lib/moderation-default.js";
-import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA } from "../lib/entity-response.js";
+import { shapeWriteResponse, flagUnrequestedStatusChange, RETURNING_SCHEMA, omitLiveComputedMetatag } from "../lib/entity-response.js";
 import { resolveErrRelationships, relationshipsWereSent } from "../lib/err-relationships.js";
 import { attachWrittenRevisionPair, readWrittenRevision } from "../lib/write-revision.js";
 import { prepareGuardedPatch, updateEntityGuarded } from "../lib/patch-preflight.js";
@@ -22,25 +22,11 @@ import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } f
 import { assertBodySummaryWritable, attachSummaryDeprecation } from "../lib/body-summary.js";
 import { buildRedirectAttributes, REDIRECT_ENTITY_TYPE } from "./redirects.js";
 import { applyAllowedFormatsToAttributes } from "../lib/field-definition.js";
+import { normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../lib/path-alias.js";
 
 /** Fallback language for an alias when the node exposes none. */
 const DEFAULT_ALIAS_LANGCODE = "en";
 
-/**
- * Normalize a URL-alias path for storage/comparison: trim, ensure a single
- * leading slash, drop a trailing slash (except root).
- * @param {*} value A raw alias.
- * @returns {?string} The normalized alias, or null when empty.
- */
-function normalizeAlias(value) {
-  if (value === undefined || value === null) return null;
-  let s = String(value).trim();
-  if (!s) return null;
-  if (!s.startsWith("/")) s = `/${s}`;
-  if (s.length > 1) s = s.replace(/\/+$/, "");
-  return s;
-}
-
 /**
  * Resolve the `path` attribute to send on an alias-aware node write so the alias
  * actually persists, and decide whether a rename redirect is needed.
@@ -58,6 +44,8 @@ function normalizeAlias(value) {
  *   run on create); `redirect` is `{ from, to, nid }` when a rename redirect is due.
  */
 async function resolvePathWrite({ backend, type, id, providedPath, isCreate }) {
+  // Always read the default revision + path_alias row. Aliases are not
+  // revisioned; a working-copy GET often omits pid on unpublished drafts (#274).
   const info = id
     ? await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}))
     : {};
@@ -133,6 +121,80 @@ async function createRenameRedirect(backend, sec, redirect) {
   }
 }
 
+/**
+ * Update the existing path_alias row in place when a node PATCH did not stick
+ * the intended alias (Pathauto regenerating on title save, missing pid on
+ * unpublished drafts).
+ * @param {object} backend
+ * @param {object} sec
+ * @param {{aliasId?: ?string}} info
+ * @param {string} intendedAlias
+ * @returns {Promise<{repaired: boolean, reason?: string}>}
+ */
+async function repairAliasViaPathAlias(backend, sec, info, intendedAlias) {
+  if (!info?.aliasId) return { repaired: false, reason: "no path_alias id to update" };
+  try {
+    assertWriteAllowed(sec, "update", PATH_ALIAS_ENTITY_TYPE, PATH_ALIAS_ENTITY_TYPE);
+  } catch {
+    return { repaired: false, reason: "path_alias update not permitted by policy" };
+  }
+  try {
+    await backend.updateEntity({
+      entityType: PATH_ALIAS_ENTITY_TYPE,
+      bundle: PATH_ALIAS_ENTITY_TYPE,
+      id: info.aliasId,
+      attributes: { alias: intendedAlias },
+    });
+    return { repaired: true };
+  } catch (err) {
+    return { repaired: false, reason: err?.message || String(err) };
+  }
+}
+
+/**
+ * Confirm the intended alias is what canonical / working-copy reads return.
+ * If the node PATCH drifted (Pathauto), restore the path_alias row and
+ * re-read. Still-wrong reads throw — never report success for a failed
+ * restoration (#274).
+ * @param {object} args
+ * @returns {Promise<object>} The entity to return (possibly a post-repair re-read).
+ */
+async function assertAliasPersisted({
+  backend, sec, type, id, intendedAlias, resourceVersion, written,
+}) {
+  const shown = normalizeAlias(written?.url);
+  if (shown === intendedAlias) return written;
+
+  const info = await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}));
+  if (normalizeAlias(info.alias) === intendedAlias && shown === null) {
+    // Re-read omitted url but the alias row matches; treat as persisted.
+    return written;
+  }
+
+  const repair = await repairAliasViaPathAlias(backend, sec, info, intendedAlias);
+  const fresh = await backend.getEntity({
+    entityType: "node", bundle: type, id,
+    ...(resourceVersion ? { resourceVersion } : {}),
+  }).catch(() => null);
+  const afterInfo = await backend.getPathInfo({ entityType: "node", bundle: type, id }).catch(() => ({}));
+  const entityUrl = normalizeAlias(fresh?.url);
+  const aliasUrl = normalizeAlias(afterInfo.alias);
+  // The path_alias row is router-visible; the node's computed path field can
+  // lag. Persist if either re-read matches. Never return a drifted url.
+  if (entityUrl === intendedAlias || aliasUrl === intendedAlias) {
+    const entity = fresh ?? written;
+    if (normalizeAlias(entity?.url) === intendedAlias) return entity;
+    return { ...(entity && typeof entity === "object" ? entity : { id }), url: intendedAlias };
+  }
+  const reported = entityUrl || aliasUrl || shown || "(none)";
+  throw new Error(
+    `Alias restoration failed: requested "${intendedAlias}" but canonical ` +
+    `and working-copy reads still show "${reported}"` +
+    (repair.reason ? ` (${repair.reason})` : "") +
+    ". Update the path_alias entity directly. See connector #274."
+  );
+}
+
 /**
  * Build a Drupal body field descriptor from plain HTML + optional summary.
  *
@@ -191,7 +253,7 @@ async function getNode({ site: siteName, type, id, langcode, resourceVersion })
         entityType: "node", bundle: type, id, langcode: targetLang,
         draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
       });
-      return redactCanonicalEntity(entity, sec, "node");
+      return omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
     }
     const liveHas = (inventory.live?.translations ?? []).some((row) => row.langcode === targetLang);
     if (!liveHas) {
@@ -399,16 +461,24 @@ async function updateNode({ site: siteName, type, id, title, body, summary, form
     ...(patchTarget.resourceVersion ? { resourceVersion: patchTarget.resourceVersion } : {}),
     ...(patchTarget.draftRevision ? { draftRevision: patchTarget.draftRevision } : {}),
   });
-  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   // #169: when relationships were sent, the canonical re-read is the published
   // revision and is not proof an ERR field landed. Prefer rel:working-copy.
-  const fresh = await readWrittenRevision({
+  let fresh = await readWrittenRevision({
     backend, entityType: "node", bundle: type, id,
     relationshipsSent: relationshipsWereSent(resolvedRelationships),
     patchResult: patched,
     preferCanonical: true,
     resourceVersion: patchTarget.resourceVersion,
   });
+  const intendedAlias = pathAttr?.alias ? normalizeAlias(pathAttr.alias) : null;
+  if (intendedAlias) {
+    fresh = await assertAliasPersisted({
+      backend, sec, type, id, intendedAlias,
+      resourceVersion: patchTarget.resourceVersion, written: fresh,
+    });
+  }
+  // Redirect only after the new alias is what re-reads show (#274).
+  const redirectResult = redirect ? await createRenameRedirect(backend, sec, redirect) : null;
   const withRevs = await attachWrittenRevisionPair({
     backend, entityType: "node", bundle: type, id, entity: fresh, liveVid: patchTarget.liveVid,
   });
@@ -524,8 +594,8 @@ export const definitions = [
         moderationState: { type: "string", description: "Moderation state transition for content_moderation types, e.g. 'draft', 'published', 'archived'. Takes precedence over status. Required to keep or re-publish a live node — omitting it on a published moderated node defaults the write to 'draft'." },
         langcode: { type: "string", description: "Target language for an unpublished working translation (e.g. 'es'). Continues that translation via Sentinel; does not create a missing translation and does not PATCH canonical langcode." },
         fields:  { type: "object", description: "Scalar/attribute field values keyed by machine name. Formatted text: a string or { value, format?, summary? }. format must be in the field's allowed_formats; a single allowed format is used when omitted. Entity-reference fields go in `relationships`, not here." },
-        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot." },
-        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. Any refusal fails the dryRun." },
+        relationships: { type: "object", description: "Entity-reference fields as JSON:API relationships, keyed by field machine name. Single-value uses { data: { type, id } }; multi-value uses { data: [{ type, id }, …] }. Paragraph / ERR items must carry meta.target_revision_id — the connector injects it when missing, and fails the write if it cannot. Image alt on a translation uses the existing file UUID plus meta.alt; replacing the file is refused." },
+        dryRun:  { type: "boolean", default: false, description: "Validate, resolve ERR identifiers, and (on moderated targets) run the core PATCH-guard probe against Drupal, then return a preview without the real write. An existing node draft uses Sentinel's non-saving draft endpoint with the real payload and revision preconditions. Otherwise an id-mismatch core PATCH probes writability without saving. A published node with no distinct working copy whose changed timestamp is later than revision_timestamp (possiblyPatchBlocked) fails dryRun the same as the real write (#273). Any refusal fails the dryRun." },
         returning: RETURNING_SCHEMA,
       },
     },

package/src/tools/paragraphs.js

@@ -42,6 +42,11 @@ import {
 import {
   embedParagraphRef, paragraphRevisionId, resolveParagraphRevisionId, missingParagraphRevisionError,
 } from "../lib/err-relationships.js";
+import {
+  assertDraftLangcode,
+  readDraftTranslation,
+  writeDraft,
+} from "../lib/draft-write.js";
 
 /**
  * Build the resource-identifier ref used to embed a paragraph in a host ERR /
@@ -111,17 +116,32 @@ async function createParagraph({ site: siteName, paragraphType, attributes = {}
  * @throws {Error} If id is missing or the revision id cannot be read.
  * @throws {SecurityError} If updating paragraphs of this bundle is not permitted.
  */
-async function updateParagraph({ site: siteName, paragraphType, id, attributes = {} }) {
+async function updateParagraph({ site: siteName, paragraphType, id, attributes = {}, langcode, revisionId, draftState }) {
   if (!id) throw new Error("A paragraph 'id' (UUID) is required to update an existing paragraph.");
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", "paragraph", paragraphType);
   const backend = await resolveBackend(site);
-  const paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+  let paragraph;
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const pinned = revisionId ?? paragraphRevisionId(
+      await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
+    );
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation update requires a paragraph revision ID (the host pin).");
+    }
+    paragraph = await writeDraft(backend, {
+      entityType: "paragraph", bundle: paragraphType, id, attributes, langcode: targetLang, draftState,
+      draftRevision: { revisionId: pinned },
+    });
+  } else {
+    paragraph = await backend.updateEntity({ entityType: "paragraph", bundle: paragraphType, id, attributes });
+  }
   const bundle = paragraph.bundle || paragraphType;
-  const revisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
-  if (revisionId === null) throw missingParagraphRevisionError(id, "Updated");
-  const ref = embedRef(bundle, paragraph.id, revisionId);
+  const resolvedRevisionId = await resolveParagraphRevisionId(backend, paragraph, paragraphType);
+  if (resolvedRevisionId === null) throw missingParagraphRevisionError(id, "Updated");
+  const ref = embedRef(bundle, paragraph.id, resolvedRevisionId);
   return { paragraph, ref, relationshipData: ref, note: EMBED_NOTE };
 }
 
@@ -134,16 +154,31 @@ async function updateParagraph({ site: siteName, paragraphType, id, attributes =
  *   The redacted paragraph with an embedding `ref`, or null if not found.
  * @throws {SecurityError} If reading paragraphs of this bundle is not permitted.
  */
-async function getParagraph({ site: siteName, paragraphType, id }) {
+async function getParagraph({ site: siteName, paragraphType, id, langcode, revisionId }) {
   const site = getSiteConfig(siteName);
   const sec = resolveSecurityConfig(site);
   assertReadAllowed(sec, "paragraph", paragraphType);
   const backend = await resolveBackend(site);
-  const entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
+  let entity;
+  if (langcode) {
+    const targetLang = assertDraftLangcode(langcode);
+    const pinned = revisionId ?? paragraphRevisionId(
+      await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id }),
+    );
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation read requires a paragraph revision ID (the host pin).");
+    }
+    entity = await readDraftTranslation(backend, {
+      entityType: "paragraph", bundle: paragraphType, id, langcode: targetLang,
+      draftRevision: { revisionId: pinned },
+    });
+  } else {
+    entity = await backend.getEntity({ entityType: "paragraph", bundle: paragraphType, id });
+  }
   if (!entity) return null;
   const redacted = redactCanonicalEntity(entity, sec, "paragraph");
-  const revisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted);
-  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, revisionId) };
+  const resolvedRevisionId = paragraphRevisionId(entity) ?? paragraphRevisionId(redacted) ?? revisionId;
+  return { ...redacted, ref: embedRef(redacted.bundle || paragraphType, redacted.id, resolvedRevisionId) };
 }
 
 // ---------------------------------------------------------------------------
@@ -167,7 +202,7 @@ export const definitions = [
   {
     name: "drupal_update_paragraph",
     description:
-      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
+      "Update an existing Paragraph entity's field values by paragraph type (bundle) and UUID. Only the attributes you pass are changed (partial update); the host entity's reference to the paragraph is unchanged (same UUID), so this maintains a component paragraph in place without re-embedding. Pass langcode to continue an unpublished paragraph translation via Sentinel (the host pin, not a live English mutation). Omitting langcode still uses canonical JSON:API and remains gated on published-host children. Returns relationshipData including meta.target_revision_id for a later host attach. Use drupal_get_entity_schema (entityType 'paragraph', the bundle) to discover fields. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
@@ -175,19 +210,24 @@ export const definitions = [
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name, e.g. 'text', 'image', 'cta'" },
         id:            { type: "string", description: "Paragraph UUID" },
         attributes:    { type: "object", description: "Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }" },
+        langcode:      { type: "string", description: "Target language for an unpublished paragraph translation (e.g. 'es'). Continues Sentinel /mcp-draft; does not create a missing translation." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required when that pin is not the default revision." },
+        draftState:    { type: "string", pattern: "^[a-f0-9]{64}$", description: "Required with langcode. Opaque draftState from the previous paragraph draft read/create/update; prevents overwriting newer edits." },
       },
     },
   },
   {
     name: "drupal_get_paragraph",
     description:
-      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
+      "Fetch a single Paragraph entity by paragraph type (bundle) and UUID. Returns the redacted paragraph (fields include drupal_internal__revision_id) plus a `ref` ({ type: 'paragraph--<bundle>', id, meta: { target_revision_id } }) you can use to embed it in a host entity's paragraph / ERR field. Pass langcode to read an unpublished working translation via Sentinel. Paragraphs are referenced from a host field rather than queried standalone in production. Governed by the site security policy.",
     inputSchema: {
       type: "object", required: ["paragraphType", "id"],
       properties: {
         site:          { type: "string" },
         paragraphType: { type: "string", description: "Paragraph type / bundle machine name" },
         id:            { type: "string", description: "Paragraph UUID" },
+        langcode:      { type: "string", description: "Target language for the unpublished working translation (e.g. 'es')." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins." },
       },
     },
   },

package/src/tools/revisions.js

@@ -24,6 +24,7 @@ import {
   resolveSecurityConfig, assertReadAllowed, assertWriteAllowed, redactCanonicalEntity,
 } from "../lib/security.js";
 import { assertDraftLangcode, readDraftTranslation, readTranslationInventory } from "../lib/draft-write.js";
+import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 
 // Attributes that describe the entity's identity / revision bookkeeping / paths.
 // These are read-only or server-managed and must NOT be replayed on a revert.
@@ -223,7 +224,7 @@ async function getRevision({ site: siteName, type, id, version, langcode }) {
       entityType: "node", bundle: type, id, langcode: targetLang,
       draftRevision: { liveVid: inventory.live.vid, workingVid: inventory.working.vid },
     });
-    const redacted = redactCanonicalEntity(entity, sec, "node");
+    const redacted = omitLiveComputedMetatag(redactCanonicalEntity(entity, sec, "node"));
     return {
       entityType: "node",
       bundle: type,

package/src/tools/translations.js

@@ -12,8 +12,9 @@
  * with `langcode`. Reads of that draft are drupal_get_node / drupal_get_revision
  * with `langcode`.
  *
- * Paragraph field-value translation is not supported on this path. Shared
- * structure (references, files, aliases) stays on the source language.
+ * Paragraph field-value translation uses the same surface with
+ * entityType "paragraph" and the pinned paragraph revision. Image alt is a
+ * node relationship (`meta.alt`) with the shared file target unchanged.
  */
 
 import { getSiteConfig } from "../lib/config.js";
@@ -24,12 +25,14 @@ import {
 } from "../lib/security.js";
 import { validateUuid, validateMachineName } from "../lib/validate.js";
 import { applySafeDraftDefault } from "../lib/moderation-default.js";
-import { loadWorkingCopy } from "../lib/patch-preflight.js";
+import { omitLiveComputedMetatag } from "../lib/entity-response.js";
 import { entityRevisionId } from "../lib/write-revision.js";
+import { paragraphRevisionId } from "../lib/err-relationships.js";
 import {
   assertDraftLangcode,
   createTranslationDraft,
   readTranslationInventory,
+  resolveNodeTranslationPair,
 } from "../lib/draft-write.js";
 
 const LIST_NOTE =
@@ -58,7 +61,7 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
   assertReadAllowed(sec, entityType, type);
 
   const backend = await resolveBackend(site);
-  if (entityType === "node" && typeof backend.rawQuery === "function") {
+  if ((entityType === "node" || entityType === "paragraph") && typeof backend.rawQuery === "function") {
     try {
       const meta = await readTranslationInventory(backend, { entityType, bundle: type, id });
       const liveLangs = (meta.live?.translations ?? []).map((row) => row.langcode);
@@ -117,7 +120,8 @@ async function listTranslations({ site: siteName, entityType = "node", type, id
  * @returns {Promise<object>} The created translation, redacted.
  */
 async function createTranslation({
-  site: siteName, entityType = "node", type, id, langcode, attributes = {}, dryRun = false,
+  site: siteName, entityType = "node", type, id, langcode, attributes = {},
+  relationships, revisionId, dryRun = false,
 }) {
   validateMachineName(entityType, "entityType");
   validateMachineName(type, "type");
@@ -128,8 +132,8 @@ async function createTranslation({
   const sec = resolveSecurityConfig(site);
   assertWriteAllowed(sec, "update", entityType, type);
 
-  if (entityType !== "node") {
-    throw new Error("Governed translation create is implemented for nodes. Other entity types are not addressed by the draft-translation contract.");
+  if (entityType !== "node" && entityType !== "paragraph") {
+    throw new Error("Governed translation create is implemented for nodes and paragraphs.");
   }
 
   const backend = await resolveBackend(site);
@@ -137,46 +141,64 @@ async function createTranslation({
   if (!existing) {
     throw new Error("The entity was not found.");
   }
-  const liveVid = entityRevisionId(existing);
-  const workingCopy = await loadWorkingCopy(backend, { entityType, bundle: type, id });
-  const workingVid = entityRevisionId(workingCopy);
-  const sameWorking = workingVid !== null && liveVid !== null && String(workingVid) === String(liveVid);
-  const draftRevision = {
-    liveVid,
-    workingVid: workingCopy && !sameWorking ? workingVid : undefined,
-  };
 
-  const safeAttributes = { ...attributes };
-  delete safeAttributes.langcode;
-  if (safeAttributes.status === undefined && safeAttributes.moderation_state === undefined) {
-    safeAttributes.moderation_state = "draft";
+  let draftRevision;
+  let drafted = { ...attributes };
+  delete drafted.langcode;
+  if (entityType === "paragraph") {
+    const pinned = revisionId ?? paragraphRevisionId(existing);
+    if (pinned === null || pinned === undefined || pinned === "") {
+      throw new Error("Paragraph translation create requires a paragraph revision ID (the host pin).");
+    }
+    draftRevision = { revisionId: pinned };
+    assertPublishAllowed(sec, drafted);
+  } else {
+    draftRevision = await resolveNodeTranslationPair(backend, {
+      entityType, bundle: type, id, existing,
+    });
+    if (drafted.status === undefined && drafted.moderation_state === undefined) {
+      drafted.moderation_state = "draft";
+    }
+    drafted = await applySafeDraftDefault({
+      backend, entityType, bundle: type, id, attributes: drafted, existingEntity: existing,
+    });
+    assertPublishAllowed(sec, drafted);
   }
-  const drafted = await applySafeDraftDefault({
-    backend, entityType, bundle: type, id, attributes: safeAttributes, existingEntity: existing,
-  });
-  assertPublishAllowed(sec, drafted);
 
   if (dryRun) {
     await createTranslationDraft(backend, {
-      entityType, bundle: type, id, langcode: targetLang, attributes: drafted, draftRevision,
+      entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
     }, true);
     return {
       dryRun: true, operation: "create_translation", entityType, bundle: type, id,
-      langcode: targetLang, attributes: drafted,
+      langcode: targetLang, attributes: drafted, ...(relationships ? { relationships } : {}),
     };
   }
 
   const created = await createTranslationDraft(backend, {
-    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, draftRevision,
+    entityType, bundle: type, id, langcode: targetLang, attributes: drafted, relationships, draftRevision,
   });
-  return redactCanonicalEntity(created, sec, entityType);
+  const redacted = omitLiveComputedMetatag(redactCanonicalEntity(created, sec, entityType));
+  if (entityType !== "node") return redacted;
+  const workingVid = entityRevisionId(created) ?? draftRevision.workingVid;
+  const liveVid = draftRevision.liveVid;
+  if (liveVid === undefined || liveVid === null) {
+    if (workingVid === undefined || workingVid === null) return redacted;
+  }
+  return {
+    ...redacted,
+    _revisions: {
+      ...(liveVid !== undefined && liveVid !== null ? { live: liveVid } : {}),
+      ...(workingVid !== undefined && workingVid !== null ? { working: workingVid } : {}),
+    },
+  };
 }
 
 export const definitions = [
   {
     name: "drupal_list_translations",
     description:
-      "List live and working translation langcodes for a Drupal node. Uses Sentinel's " +
+      "List live and working translation langcodes for a Drupal node or paragraph. Uses Sentinel's " +
       "translation inventory when available (live default revision vs unpublished working " +
       "draft). Core JSON:API alone serves one language and cannot prove others are absent. " +
       "Defaults to node.",
@@ -193,23 +215,30 @@ export const definitions = [
   {
     name: "drupal_create_translation",
     description:
-      "Create a translation as an unpublished non-default draft revision (governed write). " +
+      "Create a translation as an unpublished non-default draft (governed write). " +
       "Adds the target language beside the default language; it does not PATCH langcode on " +
-      "the canonical entity. English live title, body, status, alias, and default revision " +
-      "stay unchanged. An existing translation is a conflict, not an overwrite. Continue the " +
-      "draft with drupal_update_node and langcode. Requires Sentinel's draft-translation " +
-      "endpoint and a translatable bundle. Paragraph field values are not translated on this " +
-      "path. Defaults to node. Publication stays denied for content-tier callers.",
+      "the canonical entity. When an English working draft already exists, both live and " +
+      "working revision IDs are sent (If-Match) so Sentinel will add the language on that " +
+      "draft (#282). English live title, body, status, alias, default revision, and " +
+      "paragraph ERR pins stay unchanged. An existing translation is a conflict, not an overwrite. " +
+      "The response includes `_revisions.live` / `_revisions.working` when known. " +
+      "Computed `metatag` is omitted on the draft body because JSON:API resolves it from the live default (#283); use field_metatags. " +
+      "Continue a node draft with drupal_update_node and langcode; continue a paragraph with " +
+      "drupal_update_paragraph and langcode. Image alt is a relationship (same file UUID, " +
+      "meta.alt). For paragraphs pass revisionId as the host pin. Requires Sentinel's " +
+      "draft-translation endpoint. Publication stays denied for content-tier callers.",
     inputSchema: {
       type: "object", required: ["type", "id", "langcode"],
       properties: {
-        site:       { type: "string" },
-        entityType: { type: "string", description: "Entity type machine name. Default: 'node'." },
-        type:       { type: "string", description: "Bundle machine name, e.g. 'basic_page'" },
-        id:         { type: "string", description: "Entity UUID" },
-        langcode:   { type: "string", description: "Target language code, e.g. 'es', 'de', 'pt-br'" },
-        attributes: { type: "object", description: "Translated field values keyed by Drupal machine name" },
-        dryRun:     { type: "boolean", description: "Validate without saving" },
+        site:          { type: "string" },
+        entityType:    { type: "string", description: "Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values." },
+        type:          { type: "string", description: "Bundle machine name, e.g. 'basic_page' or 'p_hero'" },
+        id:            { type: "string", description: "Entity UUID" },
+        langcode:      { type: "string", description: "Target language code, e.g. 'es', 'de', 'pt-br'" },
+        attributes:    { type: "object", description: "Translated field values keyed by Drupal machine name" },
+        relationships: { type: "object", description: "JSON:API relationships. Use for image alt (same file UUID, meta.alt)." },
+        revisionId:    { type: "string", description: "Paragraph revision id the host already pins. Required for Home-shaped non-default pins." },
+        dryRun:        { type: "boolean", description: "Validate without saving" },
       },
     },
   },