From e9128159650f810578902bc3b25f5938b89bb1d3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 14:00:16 +0000 Subject: [PATCH 1/5] docs(field): say that a title is single-heading rich text The title convention was only in the EXAMPLES of `field add rich-text --help`. An agent that reads `field add --help` and `field add text --help` never sees it, and adds a title as key text. The `text` router row and the `field add text` description now say that key text is for short plain strings, and give the command for a title. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YRv7FgAiL76NgBHywdGKPC --- src/commands/field-add-text.ts | 9 ++++++++- src/commands/field-add.ts | 3 ++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/src/commands/field-add-text.ts b/src/commands/field-add-text.ts index 7c946fc2..478be1de 100644 --- a/src/commands/field-add-text.ts +++ b/src/commands/field-add-text.ts @@ -8,7 +8,14 @@ import { addField } from "../lib/prismic/models"; const config = { name: "prismic field add text", - description: "Add a text field to a slice or custom type.", + description: ` + Add a key text field to a slice or custom type. + + Key text is a short plain string with no formatting. Titles and headings + are rich text limited to one heading block: + + prismic field add rich-text title --to-type blog_post --allow heading1 --single + `, positionals: { id: { description: "Field ID", required: true }, }, diff --git a/src/commands/field-add.ts b/src/commands/field-add.ts index d7742e25..0ae2f00c 100644 --- a/src/commands/field-add.ts +++ b/src/commands/field-add.ts @@ -89,7 +89,8 @@ export default createCommandRouter({ }, text: { handler: fieldAddText, - description: "Add a text field", + description: + "Add a key text field for short plain strings (not for titles or headings -- use rich-text --allow heading1 --single)", }, timestamp: { handler: fieldAddTimestamp, From f39bc1e844c59de6b7414569e72e36ba31284011 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 14:02:48 +0000 Subject: [PATCH 2/5] docs(field): soften the title guidance in `field add text --help` The text read like an instruction. It now reads as guidance, and it says what key text is good for before it points to rich text. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YRv7FgAiL76NgBHywdGKPC --- src/commands/field-add-text.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/commands/field-add-text.ts b/src/commands/field-add-text.ts index 478be1de..01ee1be6 100644 --- a/src/commands/field-add-text.ts +++ b/src/commands/field-add-text.ts @@ -11,8 +11,9 @@ const config = { description: ` Add a key text field to a slice or custom type. - Key text is a short plain string with no formatting. Titles and headings - are rich text limited to one heading block: + Key text is a short plain string with no formatting, which makes it a + good fit for names, usernames, and labels. For a title or a heading, + rich text limited to a single heading block is usually a better fit: prismic field add rich-text title --to-type blog_post --allow heading1 --single `, From 1ed89006e0a46716bc1d8ad68a12e132033f0582 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 14:03:41 +0000 Subject: [PATCH 3/5] docs(field): split the title guidance into its own paragraph Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YRv7FgAiL76NgBHywdGKPC --- src/commands/field-add-text.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/commands/field-add-text.ts b/src/commands/field-add-text.ts index 01ee1be6..d92dae37 100644 --- a/src/commands/field-add-text.ts +++ b/src/commands/field-add-text.ts @@ -12,8 +12,10 @@ const config = { Add a key text field to a slice or custom type. Key text is a short plain string with no formatting, which makes it a - good fit for names, usernames, and labels. For a title or a heading, - rich text limited to a single heading block is usually a better fit: + good fit for names, usernames, and labels. + + For a title or a heading, rich text limited to a single heading block + is usually a better fit: prismic field add rich-text title --to-type blog_post --allow heading1 --single `, From bb7acc892c2896c287c4dce3db4babadd2bee56d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 8 Sep 2026 14:33:02 +0000 Subject: [PATCH 4/5] docs(field): drop the key text examples The examples said key text is a good fit for names. An agent asked to model a blog author then adds the author as key text, but a link to an author type is better. The title guidance does not need the examples. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YRv7FgAiL76NgBHywdGKPC --- src/commands/field-add-text.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/commands/field-add-text.ts b/src/commands/field-add-text.ts index d92dae37..a5eeb0ed 100644 --- a/src/commands/field-add-text.ts +++ b/src/commands/field-add-text.ts @@ -11,8 +11,7 @@ const config = { description: ` Add a key text field to a slice or custom type. - Key text is a short plain string with no formatting, which makes it a - good fit for names, usernames, and labels. + Key text is a short plain string with no formatting. For a title or a heading, rich text limited to a single heading block is usually a better fit: From 822e5bfe01aa11788cafd462ed0820ff135d3975 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 9 Sep 2026 15:37:05 +0000 Subject: [PATCH 5/5] docs(field): call the field "text", not "key text" Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01YRv7FgAiL76NgBHywdGKPC --- src/commands/field-add-text.ts | 4 ++-- src/commands/field-add.ts | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/commands/field-add-text.ts b/src/commands/field-add-text.ts index a5eeb0ed..15bb983d 100644 --- a/src/commands/field-add-text.ts +++ b/src/commands/field-add-text.ts @@ -9,9 +9,9 @@ import { addField } from "../lib/prismic/models"; const config = { name: "prismic field add text", description: ` - Add a key text field to a slice or custom type. + Add a text field to a slice or custom type. - Key text is a short plain string with no formatting. + A text field holds a short plain string with no formatting. For a title or a heading, rich text limited to a single heading block is usually a better fit: diff --git a/src/commands/field-add.ts b/src/commands/field-add.ts index 0ae2f00c..c92ab3c9 100644 --- a/src/commands/field-add.ts +++ b/src/commands/field-add.ts @@ -90,7 +90,7 @@ export default createCommandRouter({ text: { handler: fieldAddText, description: - "Add a key text field for short plain strings (not for titles or headings -- use rich-text --allow heading1 --single)", + "Add a text field for short plain strings (not for titles or headings -- use rich-text --allow heading1 --single)", }, timestamp: { handler: fieldAddTimestamp,