Docs infra and consistency pass from site audit

Chrome:
- Enable Expressive Code frames: copy button on every block, filename
  title bars from title= or a leading // path comment
- Add pitfall callout kind and a collapsible deep-dive directive
- Table of contents: left rail with active marker, indented normal-weight h3s

Consistency and factual fixes:
- Data: addToCart throws through markSafeError so the rendered message
  matches production behavior
- Reads page: state that Solid Router's query() declares GET for you
- One session shape: getSession() from Sessions; locals.userId everywhere
- Forms: server module moved out of src/routes (a .ts there is an API
  route); note inline vs exported action forms
- Debugging: EFFECT_RELAY_TEAR repair text matches the runtime message
- Quick start / Boundaries / Components: the hold on navigation is Solid's,
  not Loading's; Quick start uses the updater setter form
- App structure: three rendering modes; prerender snippet shows imports
- Nested routes: typed paths for the sign-in link, sign-in route added
- Setup: App snippet aligned with the other two (paths import, Loading)
- Data fetching: query lifetime described from source, not 'on navigation'
- Testing: unpinned install commands; template package.json is the record
- Remove version-history language from concept pages
- Middleware: document both exports of virtual:file-routes
- Closing sections normalized to '## Next steps'; added to five pages with
  reference links moved inline
- Link text normalized to page titles; concepts index reading order adds
  Stores and Rendering and SSR
- Frontmatter: drop dead mainNavExclude and titleTemplate, drop use_cases /
  tags from hand-written pages, add descriptions to 14 pages

WRITING.md: callout kinds and rules, Avoid/Prefer convention, first-use
gloss, Recap section, Next steps and Common problems headings, frontmatter
fields, no version pins, code-block filename convention.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

WRITING.md

@@ -53,24 +53,61 @@ See below for an example of what this would look like in raw Markdown.
 |April | 4 |
 ```
 
-#### Asides
+#### Callouts and deep dives
 
-Asides serve as callout boxes in Solid's documentation.
-They represent a section of the document that is related to the content surrounding the aside, but not directly relevant to the page.
-They work well with explaining how Solid differs from other popular frameworks, referring to other points in the documentation, or serving as a tangential note.
-We ask that you use them sparingly.
+A page written as one unbroken column of prose and code reads as generated.
+Callouts change the register: they mark what the reader must not miss, what they can skip, and what will bite them.
+Aim for two or three per Learn page, placed where the content changes kind, not where a paragraph felt long.
 
-1. To use an aside, you must first import the correct component.
-2. Use the following command in your terminal. (Remember to be in the cloned Solid repo directory.)
+Write a callout as a container directive with an optional title in brackets:
 
-3. Once you have the Aside component imported, simply follow the below example for how to add one to your document.
+```
+:::pitfall[Title in the reader's words]
+The wrong version, what it does, and the fix.
+:::
+```
+
+The available kinds, and what each one is for:
+
+| Kind        | Use it for                                                                                                             |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `pitfall`   | A tempting approach that looks right and is not. Show the wrong code, name the consequence, quote the dev warning.     |
+| `caution`   | A constraint the reader must respect: an ordering rule, a limit, a case the runtime does not check.                    |
+| `danger`    | Data loss or a security exposure.                                                                                      |
+| `note`      | Context the paragraph needs but the flow does not: a difference from another framework, a scope statement.             |
+| `tip`       | A shortcut or a better default the reader may not know to look for.                                                    |
+| `advanced`  | Content for integrators and library authors that an app developer can skip.                                            |
+| `deep-dive` | Collapsed by default. How something works under the hood, or why a rule exists. Never the only place a rule is stated. |
+
+Rules:
+
+- A `pitfall` needs three things: the wrong code, the observed consequence, and the fix.
+  Where a development diagnostic fires, quote it and link its code to the Debugging reactivity guide.
+- A `deep-dive` must be skippable.
+  If the reader needs it to use the API, it belongs in the body.
+  Keep headings out of it so the page outline stays flat.
+- Do not put a callout inside a callout, and do not stack two in a row.
+- Callout titles are plain text; inline code in the bracket is dropped by the parser.
+- Do not use a callout to restate the paragraph above it.
+
+Tabs group alternatives the reader picks one of, such as package managers or validation libraries:
 
 ```
-:::note
-    content here
+::::tab-group[validation-library]
+
+:::tab[Valibot]
+...
+:::
+
+:::tab[Zod]
+...
 :::
+
+::::
 ```
 
+Tab groups that share a name select together across the site.
+
 ### Code examples
 
 Solid's documentation contains example code, like you've seen here in this guide.
@@ -97,6 +134,11 @@ npm install
 Code examples are vital to providing users with quick tips on how to use Solid.
 Knowing when to use inline code versus code blocks can further the understanding of the readers and users alike.
 
+When a block shows the contents of a file, name the file.
+A first-line comment such as `// src/router.ts` is lifted into the block's title bar, or set it on the fence with `title="src/router.ts"`.
+Fragments that are not a whole file get no filename.
+Every block has a copy button; do not add prose telling the reader to copy.
+
 ### Images
 
 Good documentation takes advantage of images, such as screenshots and graphics, to expand upon the written content.
@@ -123,6 +165,24 @@ Now that we've laid out how we'd like your contribution to look, we'd like to ta
 Please note that, for editing purposes, **each sentence gets its own line**.
 Paragraphs should have two lines between them.
 
+### Frontmatter
+
+Every hand-written page carries three fields:
+
+```yaml
+---
+title: "Sessions and auth"
+version: "2.0"
+description: "Build a signed cookie session on the request event, sign users in and out from server functions, and authorize every server entry point."
+---
+```
+
+`description` is one sentence, written for the search result and the `llms.txt` index: what the reader will be able to do after the page, not what the page "covers".
+Do not add `titleTemplate`; the browser title is built from `title` and the site name.
+`use_cases` and `tags` are emitted by the reference generator and are not used on hand-written pages.
+
+Do not pin package versions in prose or install commands; point at the template's `package.json` for the versions known to work together.
+
 ### Headings
 
 Headings act as the primary means of document organization.
@@ -224,15 +284,47 @@ Do not open with a definition ("A signal is a reactive primitive that...").
 Definitions belong after the reader knows why they need one.
 
 Where the page continues a sequence, say what the reader saw on the previous page and build on it.
-The Quick start counter, the cart on the Reactivity and Components pages, and the product page on the Async page are the recurring examples; reuse them before inventing a new domain.
+The recurring example across Learn is a storefront: the Quick start counter, then a product page, a cart, a checkout address form, an account area, and orders.
+Reuse those before inventing a new domain, and do not claim a page follows one example unless it does.
 
 ### Show what happens, then explain why
 
 Each section that introduces a behavior shows the code, states what the reader observes when it runs, and then explains the mechanism.
 "Click `+` and the subtotal changes; nothing else is touched" before "JSX expressions are tracking scopes."
+Every example gets that observation sentence; code followed directly by mechanism reads as a reference page.
 
 Where a tempting wrong approach exists, show it, show what it does (including the exact development warning where there is one), and show the fix.
 A section that only shows the right way leaves the reader unable to recognize the wrong way in their own code.
+Mark the pair so it can be scanned:
+
+```tsx
+// Avoid: the effect copies a value it could derive
+createEffect(
+	() => fullName(),
+	(name) => setDisplayName(name)
+);
+
+// Prefer: derive it where it is read
+const displayName = createMemo(() => fullName());
+```
+
+Then one sentence of what the `Avoid` version does when run, and the bracketed diagnostic code if one fires, linked to its section in Debugging reactivity.
+A `:::pitfall` callout is the right container when the wrong version is a common habit rather than a one-off.
+
+### Gloss a term the first time it appears
+
+Solid has vocabulary a new reader has not met: held update, settled, owner, tracking scope, projection, boundary.
+The first time a page uses one, say what it means in a clause and link the page that explains it.
+"the write is held (kept back until the data it needs has arrived; see Async reactivity)".
+After the first use, the bare term is fine.
+One new term per section; a paragraph that introduces three is a paragraph the reader will not finish.
+
+### Close with a recap
+
+Before the next-steps section, list the rules the page taught as five to eight one-line bullets under `## Recap`.
+Each line is a rule the reader can apply, not a heading restated: "Read signals inside JSX, a memo, or an effect's compute function" rather than "Reactivity basics".
+The recap is what gets screenshotted and quoted; write it as if it were the only part of the page someone reads.
+A page with fewer than four rules to recap does not need one.
 
 ### Test every example
 
@@ -250,18 +342,21 @@ Guides that choose between approaches need a section on what to weigh, not only
 
 ### End with the next page, not the reference
 
-The last section of a Learn page tells the reader where to go next and why, in terms of what they are trying to do.
+The last section of a Learn page is `## Next steps`: two to four links, each with a clause saying what the reader gets there in terms of what they are trying to do.
+Use that heading on every page so readers and tooling can find it.
 Link API references inline where the API is discussed.
 Do not end a section or a page with "See the reference for details"; the reference is where the reader goes when they already understand the idea.
 
+Troubleshooting goes under `## Common problems`, before Next steps, with each problem as an H3 in the reader's words so it appears in the page outline and can be linked.
+
 ### Vary the shape
 
 Do not write every page as introduction, one H2 per API, conclusion.
 Let the problem decide the sections: a troubleshooting section named after the symptom, a three-pass build-up, a decision list, a comparison of two versions of the same code.
 Section headings should be readable as the reader's question or situation where that helps ("A value renders once and never updates"), not only as the name of the mechanism.
 
-Do not add a closing paragraph that restates the page.
-If there is nothing to say after the last section but "where to go next", say only that.
+Do not add a closing paragraph that restates the page; the bulleted recap is the only summary.
+If there is nothing to say after the last section but "next steps", say only that.
 
 ### Use the reader's words for problems
 

osmium/src/mdx-components.tsx

@@ -19,19 +19,22 @@ import {
 
 import { clientOnly } from "@solidjs/start";
 import { Callout } from "./ui/callout";
+import { DeepDive } from "./ui/deep-dive";
 import { Tabs, TabList, TabPanel, Tab } from "./ui/tabs";
 
 export { Callout } from "./ui/callout";
+export { DeepDive } from "./ui/deep-dive";
 export { QuickLinks } from "./ui/quick-links";
 export { ImageLink } from "./ui/image-link";
 
 const EraserLinkImpl = clientOnly(() => import("./ui/eraser-link"));
 
-type CalloutType = "note" | "tip" | "advanced" | "caution" | "danger";
+type CalloutType =
+	"note" | "tip" | "advanced" | "caution" | "danger" | "pitfall";
 
 export const DirectiveContainer = (
 	props: {
-		type: "tab-group" | "tab" | CalloutType;
+		type: "tab-group" | "tab" | "deep-dive" | CalloutType;
 		title?: string;
 		codeGroup?: string;
 		tabNames?: string;
@@ -51,6 +54,9 @@ export const DirectiveContainer = (
 			}
 		>
 			<Match when={props.type === "tab"}>{_children}</Match>
+			<Match when={props.type === "deep-dive"}>
+				<DeepDive title={props.title} children={_children} />
+			</Match>
 			<Match when={props.type === "tab-group"}>
 				<TabGroup
 					syncKey={props.title}

osmium/src/ui/callout.tsx

@@ -6,6 +6,7 @@ import {
 	xCircle,
 	puzzlePiece,
 	bookOpen,
+	noSymbol,
 } from "solid-heroicons/solid";
 
 const styles = {
@@ -34,6 +35,13 @@ const styles = {
 			"bg-red-400/30 border-red-600 dark:border-red-400 dark:bg-red-400/20 dark:border-red-600",
 		title: "text-red-900 dark:text-red-400",
 	},
+	// A tempting approach that looks right and is not. Distinct from
+	// `caution` (a constraint to respect) and `danger` (data loss, security).
+	pitfall: {
+		container:
+			"bg-orange-400/25 border-orange-600 dark:border-orange-400 dark:bg-orange-400/15 dark:border-orange-600",
+		title: "text-orange-900 dark:text-orange-300",
+	},
 };
 
 const icons = {
@@ -72,6 +80,13 @@ const icons = {
 			class={`${props.class} fill-red-500 dark:fill-red-400`}
 		/>
 	),
+	pitfall: (props: { class?: string }) => (
+		<Icon
+			aria-hidden="true"
+			path={noSymbol}
+			class={`${props.class} fill-orange-600 dark:fill-orange-400`}
+		/>
+	),
 };
 
 type CalloutType = keyof typeof styles;

osmium/src/ui/deep-dive.tsx

@@ -0,0 +1,43 @@
+import { Icon } from "solid-heroicons";
+import { chevronRight, magnifyingGlassCircle } from "solid-heroicons/solid";
+import type { JSX } from "solid-js";
+
+export type DeepDiveProps = {
+	title?: string;
+	children: JSX.Element;
+};
+
+/**
+ * Collapsed by default. Holds material most readers can skip: how something
+ * works under the hood, why a rule exists, or an integrator-only detail.
+ * Keep headings out of the body so the page outline stays flat.
+ */
+export function DeepDive(props: DeepDiveProps) {
+	return (
+		<details class="group my-6 w-full rounded-3xl border border-slate-400/60 bg-slate-100/60 open:bg-slate-100 dark:border-slate-600 dark:bg-slate-800/40 dark:open:bg-slate-800/60">
+			<summary class="flex cursor-pointer list-none items-start gap-3 p-4 marker:content-none [&::-webkit-details-marker]:hidden">
+				<Icon
+					aria-hidden="true"
+					path={magnifyingGlassCircle}
+					class="mt-1 h-6 w-8 flex-none fill-slate-600 dark:fill-slate-300"
+				/>
+				<span class="flex w-full flex-col px-1">
+					<span class="text-xs font-semibold tracking-wide text-slate-600 uppercase dark:text-slate-400">
+						Deep dive
+					</span>
+					<span class="text-xl font-semibold text-slate-900 dark:text-white">
+						{props.title ?? "How this works"}
+					</span>
+				</span>
+				<Icon
+					aria-hidden="true"
+					path={chevronRight}
+					class="mt-2 h-5 w-5 flex-none fill-slate-500 transition-transform group-open:rotate-90 dark:fill-slate-400"
+				/>
+			</summary>
+			<div class="prose dark:prose-invert px-4 pb-4 pl-16 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0">
+				{props.children}
+			</div>
+		</details>
+	);
+}