From 0d77f39443a248688f6c2ff8394ad617bea97a40 Mon Sep 17 00:00:00 2001
From: KnottyDyes <47539659+KnottyDyes@users.noreply.github.com>
Date: Sat, 10 Oct 2026 19:59:26 -0600
Subject: [PATCH] Docs: explain hyphenation defaults and image fitting modes to
 agents

Command descriptions left the new-text hyphenation default and image fitting outcomes implicit. State the default and each fitting mode's semantics, and add an MCP example that disables hyphenation. No behavior changes.
---
 crates/engine/src/cmd/object.rs |  2 +-
 crates/engine/src/cmd/text.rs   |  2 +-
 docs/mcp.md                     | 21 +++++++++++++++++++++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/crates/engine/src/cmd/object.rs b/crates/engine/src/cmd/object.rs
index 5e9ed391..7d7c7fae 100644
--- a/crates/engine/src/cmd/object.rs
+++ b/crates/engine/src/cmd/object.rs
@@ -586,7 +586,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Fitting",
             ["Object", "Fitting"],
             None,
-            "{mode: fillProportionally|fitProportionally|fitContentToFrame|centerContent|fitFrameToContent, ids?}",
+            "{mode: fillProportionally (preserves aspect ratio, covers frame, clips overflow)|fitProportionally (preserves aspect ratio, shows whole image, may leave empty space)|fitContentToFrame (stretches content to frame)|centerContent (keeps current size, positions at fitting alignment)|fitFrameToContent (resizes frame to content), ids?}",
             has_selection,
             fit
         ),
diff --git a/crates/engine/src/cmd/text.rs b/crates/engine/src/cmd/text.rs
index 0b87820f..6996a796 100644
--- a/crates/engine/src/cmd/text.rs
+++ b/crates/engine/src/cmd/text.rs
@@ -148,7 +148,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Paragraph Formatting",
             [],
             None,
-            "{attrs: {align?, leftIndent?, firstLineIndent?, spaceBefore?, spaceAfter?, dropCapLines?, dropCapChars?, dropCapStyle?, dropCapAlignLeft?, dropCapScaleDescenders?, hyphenate?, composer?, tabs?, ruleAbove?/ruleBelow?: {on?, weight?, color?, tint?, columnWidth?, offset?, leftIndent?, rightIndent?} (only the named rule fields change), …}}",
+            "{attrs: {align?, leftIndent?, firstLineIndent?, spaceBefore?, spaceAfter?, dropCapLines?, dropCapChars?, dropCapStyle?, dropCapAlignLeft?, dropCapScaleDescenders?, hyphenate?: bool (default true), composer?, tabs?, ruleAbove?/ruleBelow?: {on?, weight?, color?, tint?, columnWidth?, offset?, leftIndent?, rightIndent?} (only the named rule fields change), …}}",
             has_text_or_frames,
             |s, p| format_paras(s, p.get("attrs").unwrap_or(p))
         ),
diff --git a/docs/mcp.md b/docs/mcp.md
index f3558574..2eb03e1c 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -71,6 +71,27 @@ and `text.move` return, a story's `length` in `get_story` and `inspect_document`
 `get_story`. A character outside ASCII takes 2 to 4 bytes (é 2, — and は 3), so the story `はただ商店` has length 15
 and its second character starts at 3. An offset inside a character snaps back to the start of that character.
 
+## Text and image fitting
+
+Hyphenation is on by default for new text (`hyphenate: true`). To turn it off, select the text or a text frame,
+then call `execute`:
+
+```text
+execute          {"command": "type.para", "params": {"attrs": {"hyphenate": false}}}
+```
+
+With a text selection, this formats the selected paragraphs; with selected text frames, it formats their whole stories.
+
+Use `execute` with `object.fit` to fit a selected graphic frame (or pass `ids`):
+
+| `mode` | What it does |
+|---|---|
+| `fillProportionally` | Preserves aspect ratio, covers the frame and clips overflow. |
+| `fitProportionally` | Preserves aspect ratio, shows the whole image and may leave empty space. |
+| `fitContentToFrame` | Stretches the content to the frame's width and height. |
+| `centerContent` | Keeps the current size and positions content at the fitting alignment (center by default). |
+| `fitFrameToContent` | Resizes the frame to the content's bounds. |
+
 ## Tools
 
 | Tool | What it does |