docs(ai-chat): unblock check-broken-links + address PR #3226 review feedback

- Replace `### chat.history {#chat-history}` and `## chat.defer() {#chat-defer}`
  with sentence-case headings ("Chat history", "Chat defer"). Mintlify's MDX
  parser couldn't parse the `{#...}` explicit-anchor syntax — `{...}` is JSX
  expression syntax in MDX, and `#chat-history` is not a valid expression. The
  sentence-case slug matches the existing cross-references on `/ai-chat/backend#chat-history`
  and `/ai-chat/features#chat-defer`.
- Fix the dead link to `/ai-chat/skills/overview` in patterns/skills.mdx by
  reframing as descriptive text instead.

Review feedback (CodeRabbit on PR #3226):

- backend.mdx persistence example: add a `<Warning>` callout reminding readers
  to scope every server action by the authenticated user (`where: { userId }`)
  before pasting into a real multi-user app. The example keeps auth out of the
  way to focus on the persistence shape; the warning makes the gap explicit.
- features.mdx `chat.local` example: `userContext.get().userId` was read later
  but `userId` wasn't part of the type or init — added it to both.
- features.mdx preload example: missing `import { useEffect } from "react";`.
- frontend.mdx restoring-on-page-load example: relabel `app/page.tsx` to
  `app/chat/[chatId]/ChatPage.tsx`. The exported `ChatPage` is a client
  component that takes `chatId` as a normal prop — not an App Router page,
  which would receive `params`. Added a comment showing the trivial server-
  component wrapper that awaits `params` and forwards `chatId` into it.

Internal "Phase 1/2/3" language stripped from skills.mdx and changelog.mdx —
roadmap-internal terminology that doesn't mean anything to readers.

Author: ericallam

docs/ai-chat/backend.mdx

@@ -619,6 +619,10 @@ To build a chat app that survives page refreshes, you need to persist two things
 
 #### Full persistence example
 
+<Warning>
+  The example below trusts raw `chatId` and returns rows without filtering by user. In a real multi-user app, **scope every query by the authenticated user** — read the user from your auth/session in each server action and add `where: { userId }` to all `db.chat.*` and `db.chatSession.*` queries. Without that, one client could read or delete another user's chat state, and `getAllSessions()` would leak other users' `publicAccessToken`s. The snippet keeps auth out of the way to focus on the persistence shape.
+</Warning>
+
 <CodeGroup>
 ```ts trigger/chat.ts
 import { chat } from "@trigger.dev/sdk/ai";
@@ -905,7 +909,7 @@ The action payload is validated against `actionSchema` on the backend — invali
   Actions always trigger `run()` — the LLM responds to the modified state. For silent state changes that don't need a response (e.g. injecting background context), use [`chat.inject()`](/ai-chat/background-injection) instead.
 </Note>
 
-### chat.history {#chat-history}
+### Chat history
 
 Imperative API for modifying the accumulated message history. Works from any hook (`onAction`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`) or from `run()` and AI SDK tools.
 

docs/ai-chat/changelog.mdx

@@ -44,7 +44,7 @@ See the [Sessions Upgrade Guide](/ai-chat/upgrade-guide) for the full step-by-st
 
 <Update label="April 19, 2026" description="0.0.0-chat-prerelease-20260419173457" tags={["SDK", "CLI"]}>
 
-## Agent Skills (Phase 1)
+## Agent Skills
 
 Ship reusable capabilities as folders — a `SKILL.md` plus optional scripts, references, and assets. The agent sees short descriptions in its system prompt, loads full instructions on demand via `loadSkill`, and invokes bundled scripts via `bash` — no manual wiring.
 

docs/ai-chat/features.mdx

@@ -25,6 +25,7 @@ import { db } from "@/lib/db";
 
 // Declare at module level — each local needs a unique id
 const userContext = chat.local<{
+  userId: string;
   name: string;
   plan: "free" | "pro";
   messageCount: number;
@@ -39,6 +40,7 @@ export const myChat = chat.agent({
       where: { id: clientData.userId },
     });
     userContext.init({
+      userId: clientData.userId,
       name: user.name,
       plan: user.plan,
       messageCount: user.messageCount,
@@ -158,7 +160,7 @@ onTurnComplete: async ({ chatId }) => {
 
 ---
 
-## chat.defer() {#chat-defer}
+## Chat defer
 
 Use `chat.defer()` to run background work in parallel with streaming. The deferred promise runs alongside the LLM response and is awaited (with a 5s timeout) before `onTurnComplete` fires.
 
@@ -426,6 +428,7 @@ Preload eagerly triggers a run for a chat before the first message is sent. This
 Call `transport.preload(chatId)` to start a run early:
 
 ```tsx
+import { useEffect } from "react";
 import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
 import { useChat } from "@ai-sdk/react";
 

docs/ai-chat/frontend.mdx

@@ -125,7 +125,7 @@ On page load, fetch both the messages and the session state from your database,
 
 Because the underlying Session row outlives individual runs, a chat you were in yesterday resumes against the same chat — even if the original run has long since exited. The transport hydrates from the persisted state and uses `lastEventId` to resubscribe; if the client tries to send a new message and no run is alive, the server triggers a fresh continuation run on the same session before the message is appended.
 
-```tsx app/page.tsx
+```tsx app/chat/[chatId]/ChatPage.tsx
 "use client";
 
 import { useEffect, useState } from "react";
@@ -139,6 +139,13 @@ import {
   deleteSession,
 } from "@/app/actions";
 
+// Rendered from `app/chat/[chatId]/page.tsx`, which awaits `params`
+// and forwards `chatId` into this client component:
+//
+//   export default async function Page({ params }: { params: Promise<{ chatId: string }> }) {
+//     const { chatId } = await params;
+//     return <ChatPage chatId={chatId} />;
+//   }
 export default function ChatPage({ chatId }: { chatId: string }) {
   const [initialMessages, setInitialMessages] = useState([]);
   const [initialSession, setInitialSession] = useState(undefined);

docs/ai-chat/patterns/skills.mdx

@@ -17,7 +17,7 @@ Compared to regular AI SDK tools:
 
 PDFs are the canonical example: you don't want to ask the LLM to parse PDF bytes inline. You want it to `bash scripts/extract.py report.pdf` using a bundled `pdfplumber` wrapper. A skill ships the script, the instructions, and any reference notes together.
 
-Skills are also [dashboard-editable](/ai-chat/skills/overview) in Phase 2 — a platform team can tighten a skill's description or "when to use" text without a redeploy. Phase 1 (today) is SDK-only.
+Dashboard-editable `SKILL.md` is on the roadmap so a platform team can tighten a skill's description or "when to use" text without a redeploy. Today, skills are SDK-only — defined in your task code and shipped with each deploy.
 
 ## Trust model
 
@@ -197,11 +197,11 @@ If you're running `trigger dev`, the same layout appears in the local dev output
 - `bash` runs with `cwd` set to the skill's root. Inside the script, relative paths resolve against the skill directory.
 - Cross-skill access isn't provided — each skill is isolated by design. If two skills need to share data, either duplicate the shared file or consolidate the skills.
 
-## Limitations in Phase 1
+## Current limitations
 
-- `skill.resolve()` (backend-managed overrides) is not available yet. It throws a "not available in Phase 1, use `.local()`" error. Phase 2 ships dashboard-editable `SKILL.md` text.
+- `skill.resolve()` (backend-managed overrides) is not available yet — use `.local()` for now. Dashboard-editable `SKILL.md` is on the roadmap.
 - No per-skill metrics in the dashboard yet.
-- No Anthropic `/v1/skills` integration — use the portable path today; the Anthropic optimization comes in Phase 4.
+- No Anthropic `/v1/skills` integration — use the portable path today; we're tracking the Anthropic optimization separately.
 
 ## Full example