docs: review and update guide pages (Fable) (tldraw#9091)

In order to keep the documentation guides accurate and readable, this PR
reviews all 104 guide pages under `apps/docs/content` (getting started,
learn tldraw, SDK features, starter kits, and community — not the
generated reference docs or release notes) against the current SDK
source, and updates pages where needed. Pages that were already accurate
and clean are untouched.

Every API symbol, code example, internal link, and example link on each
page was verified against the packages' source and API reports. Changes
fall into three groups:

### Accuracy fixes

- Removed or replaced stale APIs: `defineMigrations`, the
`CollaboratorCursor` component override (now
`CollaboratorCursorOverlayUtil`), `@tldraw/tldraw` package references,
deprecated `indicator`/`inputs.currentPagePoint`/`isDragging` accessors,
and a nonexistent `editor.getDocumentState()`.
- Fixed code examples that wouldn't work as written: missing imports and
declarations, `editor.canUndo` without parens, a non-reactive
preferences read, wrong argument order in a starter-kit example, invalid
wrangler TOML, an `updateAssets` pattern that dropped required props.
- Corrected behavior claims: license tracking for hobby licenses,
`locale` prop precedence, animation speed direction, camera x/y
semantics, image-export error handling, embed sandbox/fallback behavior,
edge-scrolling insets, handle angle snapping, and others.
- Fixed broken or moved example links (persistence had six), a duplicate
starter-kit `order` conflict, and a sentence-case/anchor mismatch.

### New content

Four SDK feature pages were TODO stubs and are now full guides written
from source: **arrow shape**, **eraser**, **grid**, and **pen mode**.
They keep `status: draft` — flip to `published` when you're happy with
them.

### Clarity and style

Sentence-cased headings and labels, direct openings, short paragraphs,
trailing-gerund and hollow-filler cleanup, redundant sections removed,
and consistent `[Symbol](?)` API-link usage per the repo writing guides.

### Verification

- `yarn check-links` passes (no broken links).
- `yarn refresh-content` passes against freshly built package API files:
all MDX parses and every `[Symbol](?)` API link resolves. (This required
rebuilding `packages/*/api/api.json` locally; one bad API link added
during review was caught and removed this way.)

### Policy update

tldraw has closed external contributions. The contributing page now
states that the source is available to read but contributions are not
accepted, the translations page no longer invites translation help (and
drops the inaccurate "Lokalise for open source" section), and the
community section description no longer calls tldraw an open source
project.

### Change type

- [x] `other`

### Release notes

- Update documentation guides for accuracy, clarity, and style; add full
guides for the arrow shape, eraser, grid, and pen mode pages.

Author: steveruizok

apps/docs/content/community/contributing.mdx

@@ -8,4 +8,4 @@ order: 1
 
 tldraw's source code is available on GitHub at [github.com/tldraw/tldraw](https://github.com/tldraw/tldraw). While you can read the code, we are not accepting external contributions.
 
-The best way to help improve tldraw is to share your feedback. To report a bug or request a feature, [open an issue](https://github.com/tldraw/tldraw/issues) on GitHub or let us know on [Discord](https://discord.tldraw.com/?utm_source=docs&utm_medium=organic&utm_campaign=sociallink). If a code example would help the discussion, fork the repository and link to your branch in the issue.
+The best way to help improve tldraw is to share your feedback. To report a bug or request a feature, [open an issue](https://github.com/tldraw/tldraw/issues) on GitHub or let us know on [Discord](https://discord.tldraw.com/?utm_source=docs&utm_medium=organic&utm_campaign=sociallink). If a code example would help the discussion, please fork the repository and link to your branch in the issue.

apps/docs/content/community/license.mdx

@@ -6,19 +6,17 @@ date: 9/13/2023
 order: 2
 ---
 
-This article is about the [tldraw license](/legal/tldraw-license). The tldraw SDK's source code and published packages are provided under the tldraw license.
+The tldraw SDK's source code and published packages are provided under the [tldraw license](/legal/tldraw-license).
 
 Under its default terms, the tldraw SDK license permits use **only in development**.
 
-To use the tldraw SDK **in production**, you need either a:
+To use the tldraw SDK **in production**, you need one of the following:
 
-- [trial license](#Trial-license) for evaluation;
-- [commercial license](#Commercial-license) for commercial projects; or a
-- [hobby license](#Hobby-license) for non-commercial projects.
+- a [trial license](#Trial-license) for evaluation
+- a [commercial license](#Commercial-license) for commercial projects
+- a [hobby license](#Hobby-license) for non-commercial projects
 
-The SDK enforces its license using [license keys](#License-keys).
-
-Trial, commercial, and hobby licenses each come with a license key. The SDK will work in production only when provided with a valid and active license key. See the [License Keys](#License-keys) section for more information about license keys.
+Trial, commercial, and hobby licenses each come with a license key. The SDK will work in production only when provided with a valid and active license key. See the [License keys](#License-keys) section for more information.
 
 ### Trial license
 
@@ -54,10 +52,10 @@ When using the tldraw SDK under a commercial or hobby license, no information is
 
 When using the tldraw SDK in production under a trial license, the tldraw SDK will ping tldraw's servers with a hash of the license key. This information is primarily for analytics purposes. No user data, canvas contents, or personally-identifiable information (PII) is sent or saved.
 
-## Notes on Open Source
+## Notes on open source
 
-While the tldraw SDK is [source available](https://github.com/tldraw/tldraw), it is not permissively licensed. Many of our examples and demos are available under an MIT licenses, and you should feel free to use this code as if it were your own; however any source code or packages licensed by the tldraw SDK would not be [Open Source](https://opensource.org/osd) by any definition.
+While the tldraw SDK is [source available](https://github.com/tldraw/tldraw), it is not permissively licensed. Many of our examples and demos are available under the MIT license, and you should feel free to use this code as if it were your own; however, any source code or packages covered by the tldraw SDK license would not be [Open Source](https://opensource.org/osd) by any definition.
 
-If you wish to include tldraw in an open source project, you may do so but the SDK itself must remain under its original license. This means that you and your down-stream users will require their own trial, commercial, or hobby license in order to use the SDK in production. In this case, please also see our [trademark guidelines](https://tldraw.dev/legal/trademark-guidelines) that limit the use of the tldraw name and branding.
+If you wish to include tldraw in an open source project, you may do so but the SDK itself must remain under its original license. This means that you and your downstream users will require their own trial, commercial, or hobby license in order to use the SDK in production. In this case, please also see our [trademark guidelines](https://tldraw.dev/legal/trademark-guidelines) that limit the use of the tldraw name and branding.
 
 The tldraw SDK is a product of a company. See [tldraw.dev](https://tldraw.dev/company) for more information about the company and the team.

apps/docs/content/community/translations.mdx

@@ -6,12 +6,8 @@ date: 11/7/2023
 order: 0
 ---
 
-The tldraw user interface (in [@tldraw/ui](/docs/user-interface)) is currently translated into over thirty different languages, with twenty languages at above 70% completion. Where a key's translation is missing in the user's current language language, the default (English) translation will be used instead.
+The tldraw [user interface](/docs/user-interface) is translated into more than forty languages. Where a key's translation is missing in the user's current language, the default (English) translation is used instead.
 
-## Contributing translations
+We manage our translations through [Lokalise](https://lokalise.com).
 
-We manage our translations through [Lokalise](https://www.lokalise.com), a long-time tldraw sponsor. If you would like to help by translating or reviewing translations, please let us know on [Discord](https://discord.tldraw.com/?utm_source=docs&utm_medium=organic&utm_campaign=sociallink) so that we can add you to the project.
-
-## Lokalise for open source
-
-tldraw is proud to partner with [Lokalise](https://lokalise.com) through their Innovation and Research Plan. This initiative provides our developers with industry-leading localization technology, empowering the next generation of language professionals to master modern, AI-driven workflows.
+To learn how the SDK detects and applies languages, see [Internationalization](/sdk-features/internationalization).

apps/docs/content/docs/ai.mdx

@@ -79,7 +79,7 @@ editor.createShape({
 For richer AI output, create a custom shape that renders generated content. This approach works well for live HTML previews, interactive prototypes, or any content that needs special rendering:
 
 ```tsx
-// Abbreviated example—a full ShapeUtil also requires getDefaultProps, getGeometry, and indicator
+// Abbreviated example—a full ShapeUtil also requires getDefaultProps, getGeometry, and getIndicatorPath
 class PreviewShapeUtil extends ShapeUtil<PreviewShape> {
 	static override type = 'preview' as const
 
@@ -149,7 +149,8 @@ The [Agent starter kit](/starter-kits/agent) provides a complete implementation.
 The agent exposes a simple API for triggering canvas operations:
 
 ```tsx
-const agent = useTldrawAgent(editor)
+// Inside a component wrapped by TldrawAgentAppProvider
+const agent = useAgent()
 
 // Simple prompt
 agent.prompt('Draw a flowchart showing user authentication')
@@ -178,8 +179,8 @@ This dual approach—visual screenshots plus structured data—gives the model b
 Agents perform operations through typed action schemas. Each action has a defined structure, and the agent system validates, sanitizes, and applies actions to the editor:
 
 ```tsx
-// Simplified illustration—the actual implementation converts through a SimpleShape
-// intermediate format. See CreateActionUtil in the agent starter kit for the full code.
+// Simplified illustration—the actual implementation converts through an intermediate
+// shape format. See CreateActionUtil in the agent starter kit for the full code.
 class CreateActionUtil extends AgentActionUtil<CreateAction> {
 	override applyAction(action: Streaming<CreateAction>, helpers: AgentHelpers) {
 		if (!action.complete) return
@@ -213,19 +214,17 @@ const { blob } = await editor.toImage(editor.getCurrentPageShapes(), { format: '
 
 ### Structured data
 
-Access shape data directly from the store for text extraction or structured analysis:
+Access shape data directly from the store for text extraction or structured analysis. Use [ShapeUtil#getText](?) to extract a shape's text content as a plain string:
 
 ```tsx
 const shapes = editor.getCurrentPageShapes()
 
-const textContent = shapes
-	.filter((s) => s.type === 'text' || s.type === 'note' || s.type === 'geo')
-	.map((s) => ({
-		id: s.id,
-		type: s.type,
-		text: s.props.text,
-		bounds: editor.getShapePageBounds(s),
-	}))
+const textContent = shapes.map((shape) => ({
+	id: shape.id,
+	type: shape.type,
+	text: editor.getShapeUtil(shape).getText(shape),
+	bounds: editor.getShapePageBounds(shape),
+}))
 ```
 
 ### Combining approaches

apps/docs/content/docs/collaboration.mdx

@@ -53,7 +53,7 @@ Collaboration involves three concerns:
 
 - **Synchronizing data** — Getting document changes in and out of the [store](/sdk-features/store). See [Persistence](/docs/persistence) for the basics, or [Collaboration](/sdk-features/collaboration) for building custom sync.
 - **User presence** — Sharing cursor positions, selections, and viewports with other users. See [Collaboration](/sdk-features/collaboration) for presence APIs and [Cursors](/sdk-features/cursors) for customizing how collaborator cursors appear.
-- **Collaboration UI** — The visual elements that show other users on the canvas. See [UI components](/sdk-features/ui-components) for overriding components like `CollaboratorCursor` and `SharePanel`. Collaborator brushes, scribbles, and hints are rendered via the [OverlayUtil](?) system.
+- **Collaboration UI** — The visual elements that show other users on the canvas. See [UI components](/sdk-features/ui-components) for overriding components like `SharePanel`. The [OverlayUtil](?) system renders collaborator cursors, brushes, scribbles, and selection indicators—see [Overlay utils](/sdk-features/overlay-utils).
 
 ## Related
 

apps/docs/content/docs/driver.mdx

@@ -43,7 +43,7 @@ Every input method returns `this`, so calls can be chained. Call `dispose` when
 
 ## Simulating input
 
-Pointer, keyboard, wheel, and pinch events all flow through `editor.dispatch`, so they go through the editor's normal tool state machines—a `pointerDown` → `pointerMove`... → `pointerUp` sequence against the draw tool produces real draw shapes, not an image overlay:
+Pointer, keyboard, wheel, and pinch events all flow through `editor.dispatch`, so they go through the editor's normal tool state machines. A `pointerDown` → `pointerMove` → `pointerUp` sequence with the draw tool active creates real draw shapes:
 
 ```ts
 editor.setCurrentTool('draw')
@@ -84,7 +84,7 @@ driver.paste({ x: 400, y: 400 })
 
 ## Queries
 
-The driver tracks shapes it has caused to be created via `editor.sideEffects`, making it easy to grab the most recent result of a scripted action:
+The driver uses `editor.sideEffects` to track the shapes it creates, so you can grab the most recent result of a scripted action:
 
 ```ts
 const shape = driver.getLastCreatedShape()

apps/docs/content/docs/handles.mdx

@@ -43,18 +43,18 @@ Handle coordinates are in the shape's local coordinate system, where `(0, 0)` is
 
 There are four handle types:
 
-| Type      | Description                                                                 |
-| --------- | --------------------------------------------------------------------------- |
-| `vertex`  | A primary control point that defines part of the shape's geometry           |
-| `virtual` | A secondary handle between vertices, often used for adding new points       |
-| `create`  | A handle for extending geometry, like adding a point to the end of a line   |
-| `clone`   | A handle for duplicating the shape, used by notes for quick adjacent copies |
+| Type      | Description                                                                   |
+| --------- | ----------------------------------------------------------------------------- |
+| `vertex`  | A primary control point that defines part of the shape's geometry             |
+| `virtual` | A secondary handle that isn't a vertex, like the arrow's midpoint bend handle |
+| `create`  | A handle for adding new geometry, like inserting a point into a line segment  |
+| `clone`   | A handle for duplicating the shape, used by notes for quick adjacent copies   |
 
-Most custom shapes use `vertex` handles. The `virtual` and `create` types are used by the line shape to let users add points to a path.
+Most custom shapes use `vertex` handles. The arrow shape uses a `virtual` handle for its midpoint, and the line shape uses `create` handles to let users add points between vertices.
 
 ## Responding to handle drags
 
-When a user drags a handle, tldraw calls `onHandleDrag` with the updated handle position. Return the new shape props:
+When a user drags a handle, tldraw calls `onHandleDrag` with the updated handle position. Return the updated shape:
 
 ```tsx
 import { ShapeUtil, TLHandleDragInfo } from 'tldraw'
@@ -111,7 +111,7 @@ The `snapType` options are:
 
 ### Angle snapping
 
-When the user holds Shift while dragging, handles snap to 15-degree angles. By default, this is relative to the shape's position. You can snap relative to another handle by setting `snapReferenceHandleId`:
+When the user holds Shift while dragging, handles snap to 15-degree angles. By default, the angle is measured relative to an adjacent vertex handle on the shape. You can use a different reference handle by setting `snapReferenceHandleId`:
 
 ```tsx
 {

apps/docs/content/docs/indicators.mdx

@@ -12,7 +12,7 @@ keywords:
   - custom shapes
 ---
 
-Indicators are the outlines that appear around shapes when they're selected or hovered. They provide visual feedback about which shapes are active. They also help users understand the bounds of each shape.
+Indicators are the outlines that appear around shapes when they're selected or hovered. They show which shapes are active and where each shape's bounds are.
 
 ## How indicators work
 
@@ -112,8 +112,8 @@ In multiplayer sessions, indicators show other users' selections. These appear w
 
 ## Related topics
 
-| Topic                                                   | Description                                |
-| ------------------------------------------------------- | ------------------------------------------ |
-| [Shapes](/docs/shapes)                                  | Creating custom shapes with ShapeUtil      |
-| [User interface](/docs/user-interface)                  | Customizing tldraw's UI components         |
-| [Custom indicators example](/examples/indicators-logic) | Working example of indicator customization |
+| Topic                                                      | Description                                |
+| ---------------------------------------------------------- | ------------------------------------------ |
+| [Shapes](/docs/shapes)                                     | Creating custom shapes with ShapeUtil      |
+| [User interface](/docs/user-interface)                     | Customizing tldraw's UI components         |
+| [Custom indicators example](/examples/ui/indicators-logic) | Working example of indicator customization |

apps/docs/content/docs/mermaid.mdx

@@ -58,8 +58,8 @@ For unsupported types (pie, gantt, class, ER, etc.) pass an `onUnsupportedDiagra
 
 ```tsx
 await createMermaidDiagram(editor, text, {
-	onUnsupportedDiagram(svgString) {
-		editor.putExternalContent({ type: 'svg-text', text: svgString })
+	async onUnsupportedDiagram(svgString) {
+		await editor.putExternalContent({ type: 'svg-text', text: svgString })
 	},
 })
 ```
@@ -135,7 +135,7 @@ The callback receives `diagramKind`, `nodeId`, `kind`, and the full [`MermaidBlu
 ## Examples
 
 - [Hundreds of mermaid diagrams](/examples/use-cases/hundred-mermaids) — A runnable demo rendering many diagram types at once
-- [Customizing mermaid diagrams](/examples/use-cases/custom-shape-mermaids) - Converting mermaid diagram nodes into custom shapes
+- [Customizing mermaid diagrams](/examples/use-cases/custom-shape-mermaids) — Converting mermaid diagram nodes into custom shapes
 
 ## Related
 

apps/docs/content/docs/shapes.mdx

@@ -34,6 +34,8 @@ You can create your own shapes by defining a shape type and a ShapeUtil class.
 Register your shape's props using TypeScript module augmentation:
 
 ```ts
+import { TLShape } from 'tldraw'
+
 const CARD_TYPE = 'card'
 
 declare module 'tldraw' {
@@ -47,7 +49,7 @@ type CardShape = TLShape<typeof CARD_TYPE>
 
 ### Creating a ShapeUtil
 
-Implement the required methods: `getDefaultProps`, `getGeometry`, `component`, and `indicator`:
+Implement the required methods: `getDefaultProps`, `getGeometry`, `component`, and `getIndicatorPath`:
 
 ```tsx
 import { HTMLContainer, Rectangle2d, ShapeUtil } from 'tldraw'