Render help shortcuts with the reader's own modifier labels

src/lib/docs/editor.md

@@ -26,13 +26,13 @@ Right-click a scene in the sidebar and choose "Delete scene". A deleted scene go
 
 ## Formatting
 
-Write markdown and it styles in place: **bold** shows bold, # headings show large, > quotes show muted. The toolbar above the editor sets headings, bold, italic, quotes, and bullet lists on whatever is selected; Ctrl+B and Ctrl+I (Cmd on a Mac) do bold and italic from the keyboard.
+Write markdown and it styles in place: **bold** shows bold, # headings show large, > quotes show muted. The toolbar above the editor sets headings, bold, italic, quotes, and bullet lists on whatever is selected; Ctrl+B and Ctrl+I do bold and italic from the keyboard.
 
 The four alignment buttons set how the paragraphs under the selection sit on the page: left, centered, right, or justified. Alignment is written into the text as a small marker at the paragraph's start, like \center, so it travels with exports and shows correctly on reading pages, in EPUB, and in PDF. The marker dims in the editor; the left button removes it, so the paragraph follows the default alignment.
 
 Paragraphs without a marker use the default text alignment from your page setup (left unless you change it), set under Page setup on your account page or per story in its settings. The writing area's own font and line spacing are separate: set those under Editor on your account page, so you can write in one font on screen and export in another. The review screen's editor uses the same writing appearance.
 
-The two indent buttons beside them step the selected paragraphs in from the left and back out again (Ctrl+] and Ctrl+[, Cmd on a Mac). Like alignment, the indent is written as a marker (\indent) that rides with the text and shows everywhere, including exports.
+The two indent buttons beside them step the selected paragraphs in from the left and back out again (Ctrl+] and Ctrl+[). Like alignment, the indent is written as a marker (\indent) that rides with the text and shows everywhere, including exports.
 
 There are two ways to see your prose while you write, chosen under Editor behaviour on your account page (and per story in its settings):
 
@@ -66,7 +66,7 @@ For a clean read, select Preview. It is on the toolbar in both the single-scene
 
 ## Find and replace
 
-Press Ctrl+F (Cmd+F on a Mac) in the editor to search the open scene. The panel finds as you type; Enter jumps to the next match, and the replace field swaps one match or all of them. Press Escape to close it. To search across every scene, use Ctrl+K instead.
+Press Ctrl+F in the editor to search the open scene. The panel finds as you type; Enter jumps to the next match, and the replace field swaps one match or all of them. Press Escape to close it. To search across every scene, use Ctrl+K instead.
 
 The field at the top of the sidebar filters the chapter and scene list by name as you type, which is the quick way to find a scene in a long story.
 
@@ -124,7 +124,7 @@ When you come back to a story after time away, select "Catch me up" from the men
 
 Select "Update summaries" from the menu next to the send button to have the Assistant write a one or two line summary for each scene and chapter that does not have one yet, and refresh the ones it wrote earlier when you have changed the scene since. It works in the background and notifies you when it is done. A summary you wrote yourself is left untouched. These summaries feed the recap and help the Assistant keep track of your story.
 
-While you are writing, press Ctrl+J (Cmd+J on a Mac) to ask the Assistant to continue the passage from where your cursor is. The suggestion appears in grey after the cursor: press Tab to accept it, or Esc (or just keep typing) to dismiss it. Nothing is added until you accept.
+While you are writing, press Ctrl+J to ask the Assistant to continue the passage from where your cursor is. The suggestion appears in grey after the cursor: press Tab to accept it, or Esc (or just keep typing) to dismiss it. Nothing is added until you accept.
 
 To have the Assistant write a passage for you, select "Write" on the formatting toolbar. Tell it what you want in a sentence or two, and it drafts a passage that fits the scene and your world. The panel shows where you are in the prose - the text you had selected, or the passage leading up to your cursor - so a brief like "continue from here" picks up in the right place; select the x on that quote if you do not want it sent. On a new or nearly empty scene that follows another, it reads the end of the previous scene, so a brief like "continue from the previous scene" picks up the events and voice where they left off. You can edit the draft right there, then select "Insert at cursor" to drop it into the scene, ask for another try, or discard it. Nothing goes into your scene until you insert it.
 

src/lib/docs/getting-started.md

@@ -32,7 +32,7 @@ You can bring in a manuscript written elsewhere the same way. Pick a Word docume
 
 ## Jumping around
 
-Press Ctrl+K (Cmd+K on a Mac), or use the Search button in the top bar. Type to find any universe, story, scene, character, place, or lore entry you own, and press Enter to open it. The search also looks inside your prose: matches in scene text show a snippet, and opening one selects the match in the editor. The same box lists commands for where you are, such as creating a scene, switching focus mode on, or reading the whole story as one document.
+Press Ctrl+K, or use the Search button in the top bar. Type to find any universe, story, scene, character, place, or lore entry you own, and press Enter to open it. The search also looks inside your prose: matches in scene text show a snippet, and opening one selects the match in the editor. The same box lists commands for where you are, such as creating a scene, switching focus mode on, or reading the whole story as one document.
 
 Opening a story without picking a scene resumes the scene you edited last.
 

src/lib/docs/planning.md

@@ -82,7 +82,7 @@ If you run a campaign, a note per sitting works well: keep the running log in a
 
 A note can also be attached to one scene. In the editor, open the Notes panel on the right and select "New note on this scene": the note is made, attached, and opened in the Notes view for you to write. From then on it shows at the top of the Notes panel whenever the scene is open, and in the story's note list like any other note.
 
-To jot something down without leaving the editor, press Ctrl+Alt+N (Cmd+Option+N on a Mac) or run "Quick note" from the command palette. A small card opens over the editor: write the thought, then Ctrl+Enter or "Save note" files it with the story's notes - attached to the open scene when there is one - and puts you back where you were. The first line becomes the note's title.
+To jot something down without leaving the editor, press Ctrl+Alt+N or run "Quick note" from the command palette. A small card opens over the editor: write the thought, then Ctrl+Enter or "Save note" files it with the story's notes - attached to the open scene when there is one - and puts you back where you were. The first line becomes the note's title.
 
 ## History
 

src/lib/docs/reviewing.md

@@ -39,7 +39,7 @@ Open the review window and pick what to review and what to check. You can open i
 
 - Right-click a scene or chapter in the sidebar, open the Assistant submenu, and choose **Review with the Assistant**.
 - In Review mode, open the **Assistant** tab on the right and use the **Review with the Assistant** button at the top.
-- From the command bar (Ctrl+K, or Cmd+K on a Mac), choose **Review with the Assistant**.
+- From the command bar (Ctrl+K), choose **Review with the Assistant**.
 - In the Assistant chat, type `/review`.
 
 The window has two choices. First, **what to review**: this scene, this chapter, or the whole story. Second, **what to check**:

src/lib/docs/shortcuts.md

@@ -1,7 +1,7 @@
 # Keyboard shortcuts
 
-Codex keeps to a small set of shortcuts. On a Mac, use Cmd where Ctrl is shown
-and Option where Alt is shown.
+Codex keeps to a small set of shortcuts, shown for your keyboard: Cmd and
+Option on a Mac, Ctrl and Alt everywhere else.
 
 ## Anywhere
 

src/lib/keys.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { isApplePlatform } from './keys';
+import { appleShortcutLabels, isApplePlatform } from './keys';
 
 describe('isApplePlatform', () => {
 	it('recognises Apple platform strings', () => {
@@ -16,3 +16,19 @@ describe('isApplePlatform', () => {
 		expect(isApplePlatform('')).toBe(false);
 	});
 });
+
+describe('appleShortcutLabels', () => {
+	it('rewrites combo labels and leaves bare key names alone', () => {
+		expect(appleShortcutLabels('press Ctrl+Alt+N, then Ctrl+Enter')).toBe(
+			'press Cmd+Option+N, then Cmd+Enter'
+		);
+		// Prose naming the keys without a combo stays as written, so the
+		// shortcuts article's own convention line survives the swap.
+		expect(appleShortcutLabels('Cmd and Option on a Mac, Ctrl and Alt everywhere else.')).toBe(
+			'Cmd and Option on a Mac, Ctrl and Alt everywhere else.'
+		);
+		expect(appleShortcutLabels('an image with alt+title text')).toBe(
+			'an image with alt+title text'
+		);
+	});
+});

src/lib/keys.ts

@@ -27,3 +27,10 @@ export function altLabel(): 'Option' | 'Alt' {
 	if (!browser) return 'Alt';
 	return isApplePlatform(currentPlatform()) ? 'Option' : 'Alt';
 }
+
+// Rewrites shortcut combos in help text for Apple keyboards: Ctrl+ becomes
+// Cmd+ and Alt+ becomes Option+. Only the combo forms are touched, so prose
+// that merely names the keys stays as written.
+export function appleShortcutLabels(text: string): string {
+	return text.replace(/\bCtrl\+/g, 'Cmd+').replace(/\bAlt\+/g, 'Option+');
+}

src/routes/docs/[topic]/+page.svelte

@@ -1,11 +1,20 @@
 <script lang="ts">
+	import { onMount } from 'svelte';
 	import { resolve } from '$app/paths';
 	import { renderMarkdown } from '$lib/markdown';
+	import { appleShortcutLabels, modLabel } from '$lib/keys';
 	import DocsShell from '$lib/components/DocsShell.svelte';
 	import type { PageData } from './$types';
 
 	let { data }: { data: PageData } = $props();
 
+	// The articles write shortcuts with the PC labels; an Apple reader sees
+	// Cmd and Option instead. The server cannot know the platform, so SSR
+	// serves the written form and the swap lands on mount.
+	let apple = $state(false);
+	onMount(() => (apple = modLabel() === 'Cmd'));
+	const body = $derived(apple ? appleShortcutLabels(data.article.body) : data.article.body);
+
 	// The next article in the registry order, so reading straight through works.
 	const next = $derived.by(() => {
 		const at = data.topics.findIndex((topic) => topic.slug === data.article.slug);
@@ -21,7 +30,7 @@
 	<div class="kicker">Help</div>
 	<!-- Trusted, committed markdown; renderMarkdown also escapes raw HTML. -->
 	<!-- eslint-disable-next-line svelte/no-at-html-tags -->
-	<article class="prose">{@html renderMarkdown(data.article.body)}</article>
+	<article class="prose">{@html renderMarkdown(body)}</article>
 
 	{#if next}
 		<nav class="more">