drupal-mcp-connector 2.14.2 → 2.15.0

package/.agents/commands/drupal-create-translation.md

@@ -1,23 +1,25 @@
 ---
-description: "Create a translation as an unpublished non-default draft revision (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."
-argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [dryRun]"
+description: "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. 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."
+argument-hint: "<type> <id> <langcode> [site] [entityType] [attributes] [relationships] [revisionId] [dryRun]"
 ---
 
 Call the MCP tool `drupal_create_translation`.
 
-Create a translation as an unpublished non-default draft revision (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.
+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. 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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
 **Required:**
-- `type` (string): Bundle machine name, e.g. 'basic_page'
+- `type` (string): Bundle machine name, e.g. 'basic_page' or 'p_hero'
 - `id` (string): Entity UUID
 - `langcode` (string): Target language code, e.g. 'es', 'de', 'pt-br'
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
-- `entityType` (string): Entity type machine name. Default: 'node'.
+- `entityType` (string): Entity type machine name. Default: 'node'. Use 'paragraph' for paragraph field values.
 - `attributes` (object (pass as JSON)): Translated field values keyed by Drupal machine name
+- `relationships` (object (pass as JSON)): JSON:API relationships. Use for image alt (same file UUID, meta.alt).
+- `revisionId` (string): Paragraph revision id the host already pins. Required for Home-shaped non-default pins.
 - `dryRun` (boolean (true/false)): Validate without saving
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-entity-update.md

@@ -19,7 +19,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `langcode` (string): Target language for an unpublished working translation (nodes). Continues that translation via Sentinel.
 - `attributes` (object (pass as JSON))
 - `relationships` (object (pass as JSON))
-- `dryRun` (boolean (true/false)): 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.
+- `dryRun` (boolean (true/false)): 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` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-get-paragraph.md

@@ -1,11 +1,11 @@
 ---
-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."
-argument-hint: "<paragraphType> <id> [site]"
+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. 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."
+argument-hint: "<paragraphType> <id> [site] [langcode] [revisionId]"
 ---
 
 Call the MCP tool `drupal_get_paragraph`.
 
-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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -15,5 +15,7 @@ Parse the arguments supplied with this command into this tool's parameters:
 
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
+- `langcode` (string): Target language for the unpublished working translation (e.g. 'es').
+- `revisionId` (string): Paragraph revision id the host already pins.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-list-translations.md

@@ -1,11 +1,11 @@
 ---
-description: "List live and working translation langcodes for a Drupal node. 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."
+description: "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."
 argument-hint: "<type> <id> [site] [entityType]"
 ---
 
 Call the MCP tool `drupal_list_translations`.
 
-List live and working translation langcodes for a Drupal node. 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.
+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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 

package/.agents/commands/drupal-update-node.md

@@ -23,8 +23,8 @@ Parse the arguments supplied with this command into this tool's parameters:
 - `moderationState` (string): 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` (string): 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` (object (pass as JSON)): 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` (object (pass as JSON)): 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` (boolean (true/false)): 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` (object (pass as JSON)): 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` (boolean (true/false)): 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` (string): Response verbosity. "full" (default) returns the complete saved entity; "minimal" returns just identity + state (id, type, bundle, title, status, changed, url) — much smaller, recommended for bulk writes where the echoed body would dominate the response.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/.agents/commands/drupal-update-paragraph.md

@@ -1,11 +1,11 @@
 ---
-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."
-argument-hint: "<paragraphType> <id> [site] [attributes]"
+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. 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."
+argument-hint: "<paragraphType> <id> [site] [attributes] [langcode] [revisionId] [draftState]"
 ---
 
 Call the MCP tool `drupal_update_paragraph`.
 
-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.
 
 Parse the arguments supplied with this command into this tool's parameters:
 
@@ -16,5 +16,8 @@ Parse the arguments supplied with this command into this tool's parameters:
 **Optional:**
 - `site` (string): Named site from connector config. Omit only on reads: multi-site configs fall back to defaultSite (often local/dev, not production). Writes require an explicit site when more than one site is configured. Every response includes `_target` { name, baseUrl, source } (`hint` when you passed site, `default` when you did not).
 - `attributes` (object (pass as JSON)): Paragraph field values to change, keyed by Drupal machine name, e.g. { field_body: { value: '<p>..</p>', format: 'full_html' } }
+- `langcode` (string): Target language for an unpublished paragraph translation (e.g. 'es'). Continues Sentinel /mcp-draft; does not create a missing translation.
+- `revisionId` (string): Paragraph revision id the host already pins. Required when that pin is not the default revision.
+- `draftState` (string): Required with langcode. Opaque draftState from the previous paragraph draft read/create/update; prevents overwriting newer edits.
 
 If a required parameter is missing, ask before calling — do not invent values. Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the single tool call and summarize the result.

package/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-09-10
+
+### Fixed
+- Paragraph translation updates require the `draftState` returned by a previous draft read. Pass it unchanged to Sentinel for stale-write protection. Shared-status paragraphs remain pending for human editing (#280).
+- **Omit computed `metatag` on unpublished working-translation bodies (#283).**
+  JSON:API's computed `metatag` array is resolved from the live default
+  revision, so a Spanish draft response could still show English title and
+  description. The stored override (`field_metatags`) is unchanged. Draft
+  translation create/read now drop `fields.metatag` and set `_metatagOmitted`.
+
+- **`drupal_create_translation` sends live and working revision IDs when a draft exists (#282).**
+  Sentinel's translation POST 409s with "A working revision exists" if If-Match
+  is live-only. The connector now reads Sentinel's translation inventory for
+  the live/working pair (falling back to `rel:working-copy`) and sends
+  `If-Match: "live:working"`. The response includes `_revisions` so the caller
+  can see which revision the language landed on.
+
+- **`dryRun` fails when a published-node write would hit Sentinel's stale-copy check (#273).**
+  The id-mismatch PATCH probe never reaches entity validation / presave, so it
+  could not see MCP Sentinel's default-revision stale-version refusal. When
+  `rel:latest-version` and `rel:working-copy` share a vid and the default
+  revision's `changed` is later than `revision_timestamp` (`possiblyPatchBlocked`),
+  `drupal_update_node` / `drupal_entity_update` (including `dryRun`) now refuse
+  with a stable `STALE_COPY` error. The same message is rewritten if Sentinel
+  still returns it on the saving write. Governance is unchanged: the draft and
+  publish gates are not bypassed.
+- **Title-only node updates keep the existing URL alias; failed restorations error (#274).**
+  `getPathInfo` now fills `pid` / `aliasId` from the `path_alias` row when an
+  unpublished default or forward revision omits them on the computed `path`
+  field. After `drupal_update_node`, the connector re-reads the alias and, if
+  Pathauto still drifted it, PATCHes the existing `path_alias` entity. If the
+  alias still does not match, the tool throws instead of returning success or
+  creating a rename redirect. Title-only edits pin the live alias as before.
+
+### Added
+- **Codex skill target for `npm run install:commands` (#263).**
+  The installer writes `$HOME/.agents/skills/drupal-mcp/SKILL.md` (plus
+  `references/tools.md`) so Drupal MCP tools are discoverable in Codex. Custom
+  prompts under `~/.codex/prompts` are not written — OpenAI deprecated that
+  surface in favor of skills. Default clients are now `claude,grok,codex`.
+  Test with `--home` on an isolated directory.
+
+- **Unpublished paragraph field-value translation and image alt (#280).**
+  `drupal_create_translation` accepts `entityType: "paragraph"` and
+  `revisionId` (the host pin) and POSTs Sentinel's paragraph
+  `/mcp-draft/translations` surface. Continue with `drupal_update_paragraph`
+  + `langcode`; read with `drupal_get_paragraph` + `langcode`. Omitting
+  `langcode` on `drupal_update_paragraph` still uses canonical JSON:API.
+  Node translation writes forward image relationships so alt can change
+  while the file UUID stays the same. Replacing the file remains a
+  server refusal. Node-only translation create is unchanged.
+
 ## [2.14.2] - 2026-09-10
 
 ### Fixed

package/README.md

@@ -129,13 +129,15 @@ Clients that scan `.agents/commands/` (including Grok Build when this repo is
 the project) pick them up automatically.
 
 Clients that only scan a vendor home path (Claude Code `~/.claude/commands`,
-Grok `~/.grok/commands`) install from that tree into the **operator home**, so
-no consuming project has to commit `.claude/` or `.grok/`:
+Grok `~/.grok/commands`, Codex `$HOME/.agents/skills`) install from that tree
+into the **operator home**, so no consuming project has to commit `.claude/` or
+`.grok/`. Codex uses a **skill** (`drupal-mcp`), not deprecated custom prompts:
 
 ```bash
 npm run generate:commands    # refresh .agents/commands/ (from a clone)
-npm run install:commands     # copies into ~/.claude/commands and ~/.grok/commands
+npm run install:commands     # copies into ~/.claude/commands, ~/.grok/commands, and ~/.agents/skills/drupal-mcp/
 # npm run install:commands -- --clients claude
+# npm run install:commands -- --clients codex
 # npm run install:commands -- --home /path/to/fake-home   # tests / CI
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.14.2",
+  "version": "2.15.0",
   "description": "A secure, multi-site Model Context Protocol (MCP) connector for Drupal — dual-protocol JSON:API and GraphQL.",
   "type": "module",
   "main": "src/index.js",

package/scripts/generate-commands.js

@@ -8,14 +8,17 @@
  * Build, when this repo is the project) pick them up as `/drupal-<tool>`.
  *
  * Clients that only scan a vendor home directory (Claude Code `~/.claude/commands`,
- * Grok `~/.grok/commands`) get the same files via `npm run install:commands`.
+ * Grok `~/.grok/commands`, Codex `$HOME/.agents/skills`) get the same files via
+ * `npm run install:commands`. Codex receives one skill (`drupal-mcp`), not
+ * per-tool custom prompts.
  *
  * Driven from the same tool definitions as the server (src/tools/index.js), so the
  * command set never drifts from the tools. Run: `npm run generate:commands`.
  *
- * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`, `commandFileName`,
- * `COMMANDS_DIR`, and `generate` for tests; the file-writing side effect runs only
- * when executed directly.
+ * Exports `renderCommandMarkdown`, `renderClaudeCommandMarkdown`,
+ * `renderCodexSkillMarkdown`, `renderCodexToolsReference`, `CODEX_SKILL_NAME`,
+ * `commandFileName`, `COMMANDS_DIR`, and `generate` for tests; the file-writing
+ * side effect runs only when executed directly.
  */
 
 import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
@@ -113,6 +116,62 @@ export function renderClaudeCommandMarkdown(def) {
   });
 }
 
+/** Codex user-skill directory name under `$HOME/.agents/skills/`. */
+export const CODEX_SKILL_NAME = "drupal-mcp";
+
+/**
+ * Codex skill adapter (OpenAI Skills). Custom `~/.codex/prompts` slash
+ * commands are deprecated; Codex discovers `$HOME/.agents/skills/<name>/SKILL.md`.
+ * One skill covers the whole Drupal MCP tool surface so the skills list stays
+ * inside Codex's discovery budget.
+ *
+ * @param {Array<object>} [definitions]
+ * @returns {string} SKILL.md contents.
+ */
+export function renderCodexSkillMarkdown(definitions = allDefinitions) {
+  const count = definitions.length;
+  return [
+    "---",
+    `name: ${yamlString(CODEX_SKILL_NAME)}`,
+    `description: ${yamlString(
+      "Use Drupal MCP tools (drupal_*) via drupal-mcp-connector to read or write Drupal content, media, taxonomy, reports, and config. Trigger when the user asks to work with a Drupal site over MCP.",
+    )}`,
+    "---",
+    "",
+    "Call Drupal MCP tools by their protocol names (`drupal_list_nodes`, `drupal_update_node`, …).",
+    "The MCP server is configured separately (`codex mcp add drupal`); this skill does not replace that connection and does not use deprecated Codex custom prompts.",
+    "",
+    "Parse the user's request into the tool's parameters. If a required parameter is missing, ask before calling.",
+    "Coerce each value to its JSON type (booleans → true/false, numbers → numeric, object/array → parse JSON), then make the tool call and summarize the result.",
+    "",
+    "Destructive tools permanently change or delete data — confirm with the user before calling.",
+    "Do not invent REST paths, Drush commands, or Drupal admin URLs when an MCP tool exists.",
+    "",
+    `The connector currently exposes **${count}** tools. Full names and descriptions: [references/tools.md](references/tools.md).`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Progressive-disclosure catalog for the Codex Drupal skill.
+ * @param {Array<object>} [definitions]
+ * @returns {string} references/tools.md contents.
+ */
+export function renderCodexToolsReference(definitions = allDefinitions) {
+  const lines = [
+    "# Drupal MCP tools",
+    "",
+    "Protocol tool names for `drupal-mcp-connector`. Call these via MCP; do not invent REST paths.",
+    "",
+  ];
+  for (const def of definitions) {
+    const desc = String(def.description || "").replace(/\s+/g, " ").trim();
+    lines.push(`- \`${def.name}\`${desc ? ` — ${desc}` : ""}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
 /**
  * Write one command file per tool, pruning stale `drupal-*.md` first so removed
  * tools leave no orphans.

package/scripts/install-commands.js

@@ -9,11 +9,12 @@
  * copies so `/drupal-*` works in every project without committing a vendor
  * folder to this repo or to a consuming application.
  *
- * Default targets: `~/.claude/commands` (Claude adapter) and `~/.grok/commands`
- * (canonical files). Pass `--clients` to subset. Never writes into a project
- * tree.
+ * Default targets: `~/.claude/commands` (Claude adapter), `~/.grok/commands`
+ * (canonical files), and `$HOME/.agents/skills/drupal-mcp/` (Codex skill).
+ * Pass `--clients` to subset. Never writes into a project tree. Codex custom
+ * prompts (`~/.codex/prompts`) are not written — they are deprecated.
  *
- * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,agents]`
+ * Run: `npm run install:commands -- [--home DIR] [--clients claude,grok,codex,agents]`
  */
 
 import { mkdirSync, readdirSync, rmSync, writeFileSync, realpathSync } from "fs";
@@ -26,6 +27,9 @@ import {
   commandFileName,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
+  renderCodexSkillMarkdown,
+  renderCodexToolsReference,
+  CODEX_SKILL_NAME,
 } from "./generate-commands.js";
 
 /** Whitelisted install targets. `rel` is under `--home` (default: os.homedir()). */
@@ -42,9 +46,18 @@ export const CLIENTS = {
     rel: ".agents/commands",
     render: renderCommandMarkdown,
   },
+  // Codex discovers user skills at `$HOME/.agents/skills/<name>/SKILL.md`.
+  // One skill for the whole tool surface — not one skill per tool.
+  codex: {
+    rel: ".agents/skills",
+    kind: "skill",
+    skillName: CODEX_SKILL_NAME,
+    renderSkill: renderCodexSkillMarkdown,
+    renderReference: renderCodexToolsReference,
+  },
 };
 
-const DEFAULT_CLIENTS = ["claude", "grok"];
+const DEFAULT_CLIENTS = ["claude", "grok", "codex"];
 
 /**
  * Parse CLI flags. Unknown flags throw.
@@ -111,6 +124,15 @@ export function install(options = {}) {
     if (!client) {
       throw new Error(`Unknown client "${name}". Allowed: ${Object.keys(CLIENTS).join(", ")}`);
     }
+    if (client.kind === "skill") {
+      const dir = join(home, client.rel, client.skillName);
+      rmSync(dir, { recursive: true, force: true });
+      mkdirSync(join(dir, "references"), { recursive: true });
+      writeFileSync(join(dir, "SKILL.md"), client.renderSkill(definitions));
+      writeFileSync(join(dir, "references", "tools.md"), client.renderReference(definitions));
+      results.push({ client: name, dir, written: ["SKILL.md", "references/tools.md"] });
+      continue;
+    }
     const dir = join(home, client.rel);
     mkdirSync(dir, { recursive: true });
     for (const f of readdirSync(dir)) {
@@ -127,14 +149,15 @@ export function install(options = {}) {
   return results;
 }
 
-const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,agents]
+const HELP = `Usage: node scripts/install-commands.js [--home DIR] [--clients claude,grok,codex,agents]
 
-Copy generated /drupal-* command stubs into operator home directories.
-Does not write into a project tree.
+Copy generated /drupal-* command stubs (and the Codex skill) into operator
+home directories. Does not write into a project tree. Does not write
+deprecated Codex custom prompts (~/.codex/prompts).
 
   --home DIR       Install root (default: the current user's home)
-  --clients LIST   Comma-separated subset of: claude, grok, agents
-                   (default: claude,grok)
+  --clients LIST   Comma-separated subset of: claude, grok, codex, agents
+                   (default: claude,grok,codex)
 `;
 
 const invokedDirectly =

package/src/lib/backends/backend-interface.js

@@ -79,10 +79,12 @@ export class Backend {
    * for callers that must round-trip the alias `pid` on an in-place update (the
    * canonical entity only exposes `path.alias` as `url`). Optional capability:
    * the default returns nulls so read-only/path-less backends are safe. See the 1.5.1 alias fix.
-   * @param {{entityType: string, bundle: string, id: string}} _ref
-   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   * @param {{entityType: string, bundle: string, id: string, resourceVersion?: string}} _ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string), aliasId: ?string}>}
    */
-  async getPathInfo(_ref) { return { alias: null, pid: null, langcode: null, drupalId: null }; }
+  async getPathInfo(_ref) {
+    return { alias: null, pid: null, langcode: null, drupalId: null, aliasId: null };
+  }
 
   /**
    * Create an entity.

package/src/lib/backends/jsonapi.js

@@ -17,6 +17,7 @@ import {
   normalizeRelationship,
   BASE_ATTRIBUTE_FIELDS,
 } from "../canonical.js";
+import { isPositiveNid, normalizeAlias, PATH_ALIAS_ENTITY_TYPE } from "../path-alias.js";
 
 // Drupal exposes internal identifiers under drupal_internal__* attributes.
 // They are dropped from canonical `fields` except for the identifiers that
@@ -310,19 +311,88 @@ export class JsonApiBackend extends Backend {
    * (Drupal `PathItem::postSave` creates a duplicate alias when `pid` is absent)
    * — so this method exposes it. Returns nulls for entities/backends without a
    * path field. See the 1.5.1 alias fix.
-   * @param {{entityType: string, bundle: string, id: string}} ref
-   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string)}>}
+   *
+   * Unpublished default / forward revisions often omit `pid` on the computed
+   * `path` field even when a `path_alias` row exists. When the node numeric id
+   * is known, this method also looks up that row (aliases are not revisioned)
+   * so title-only edits can pin the live alias (#274).
+   * @param {{entityType: string, bundle: string, id: string, resourceVersion?: string}} ref
+   * @returns {Promise<{alias: ?string, pid: ?(number|string), langcode: ?string, drupalId: ?(number|string), aliasId: ?string}>}
    */
-  async getPathInfo({ entityType, bundle, id }) {
+  async getPathInfo({ entityType, bundle, id, resourceVersion }) {
     validateUuid(id);
-    const data = await drupalFetch(this.site, `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`);
+    let path = `${this.resourcePath(entityType, bundle)}/${encodeURIComponent(id)}`;
+    if (resourceVersion) {
+      path += `?resourceVersion=${encodeURIComponent(resourceVersion)}`;
+    }
+    const data = await drupalFetch(this.site, path);
     const attrs = data?.data?.attributes ?? {};
-    const path = attrs.path ?? null;
+    const nodePath = attrs.path ?? null;
+    const drupalId = attrs.drupal_internal__nid ?? attrs.drupal_internal__id ?? null;
+    const langcode = nodePath?.langcode ?? attrs.langcode ?? null;
+    let alias = nodePath?.alias ?? null;
+    let pid = nodePath?.pid ?? null;
+    let aliasId = null;
+
+    if (entityType === "node" && isPositiveNid(drupalId)) {
+      const row = await this.lookupPathAliasRow(`/node/${Number(drupalId)}`, {
+        langcode,
+        preferredAlias: alias,
+      });
+      if (row) {
+        aliasId = row.id;
+        if (pid === undefined || pid === null) pid = row.pid;
+        // Pathauto / unpublished computed fields can omit alias; the row is
+        // the router-visible value.
+        if (!alias) alias = row.alias;
+      }
+    }
+
+    return { alias, pid, langcode, drupalId, aliasId };
+  }
+
+  /**
+   * Load the path_alias row for a node source path. Best-effort: missing
+   * JSON:API exposure or an empty collection returns null.
+   * @param {string} sourcePath Drupal system path, e.g. `/node/44`.
+   * @param {{langcode?: ?string, preferredAlias?: ?string}} [opts]
+   * @returns {Promise<?{id: string, alias: ?string, pid: ?(number|string), langcode: ?string}>}
+   */
+  async lookupPathAliasRow(sourcePath, opts = {}) {
+    if (!/^\/node\/[1-9]\d*$/.test(sourcePath)) return null;
+    const params = new URLSearchParams();
+    params.set("filter[path]", sourcePath);
+    if (opts.langcode) params.set("filter[langcode]", String(opts.langcode));
+    let data;
+    try {
+      data = await drupalFetch(
+        this.site,
+        `${this.resourcePath(PATH_ALIAS_ENTITY_TYPE, PATH_ALIAS_ENTITY_TYPE)}?${params}`,
+      );
+    } catch {
+      return null;
+    }
+    const rows = Array.isArray(data?.data) ? data.data : [];
+    if (!rows.length) return null;
+    const preferred = normalizeAlias(opts.preferredAlias);
+    let picked = rows[0];
+    if (preferred) {
+      for (const row of rows) {
+        const attrs = row && typeof row === "object" ? row.attributes : null;
+        const rowAlias = attrs && typeof attrs === "object" ? attrs.alias : null;
+        if (normalizeAlias(rowAlias) === preferred) {
+          picked = row;
+          break;
+        }
+      }
+    }
+    if (!picked?.id) return null;
+    const a = picked.attributes && typeof picked.attributes === "object" ? picked.attributes : {};
     return {
-      alias: path?.alias ?? null,
-      pid: path?.pid ?? null,
-      langcode: path?.langcode ?? attrs.langcode ?? null,
-      drupalId: attrs.drupal_internal__nid ?? attrs.drupal_internal__id ?? null,
+      id: picked.id,
+      alias: a.alias ?? null,
+      pid: a.drupal_internal__id ?? a.pid ?? null,
+      langcode: a.langcode ?? null,
     };
   }