diff --git a/README.md b/README.md
index afb38a3..1fc9833 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,22 @@ Each push to `main` triggers a new deployment. PRs get preview URLs automaticall
 - `VERCEL_TOKEN` - create at [vercel.com/account/tokens](https://vercel.com/account/tokens)
 - `VERCEL_PROJECT_ID` - from your Vercel project **Settings → General** (or from `.vercel/project.json` after `vercel link`)
 
+### Ask AI backend and preview behavior
+
+The Ask AI panel in this repo calls `https://chat.devdocify.com/api/widget-chat` from the browser.
+
+For production and Vercel preview environments to work:
+
+- `chat-devdocify` must be deployed and healthy.
+- The widget API CORS policy must allow:
+  - `https://www.devdocify.com`
+  - `https://devdocify.com`
+  - `http://localhost:*`
+  - `https://doc-platform*.vercel.app` preview origins
+
+If preview origins are not allowed by CORS, Ask AI requests fail in browser and the panel shows:
+`Sorry, something went wrong. Please try again.`
+
 ## Optional: self-hosted deployment
 
 For containerized or on-prem deployments, the repo includes Docker, nginx, and a monitoring stack.
diff --git a/docs/devdocify/how-to/add-docset.md b/docs/devdocify/how-to/add-docset.md
index ee7240b..d420e36 100644
--- a/docs/devdocify/how-to/add-docset.md
+++ b/docs/devdocify/how-to/add-docset.md
@@ -9,6 +9,12 @@ description: "How to add a new product docset to a DevDocify site, including dir
 
 Follow these steps to add a new product docset to your DevDocify site.
 
+## Prerequisites
+
+- You are in the project root.
+- You can edit `docusaurus.config.ts`.
+- You have the `docify` CLI installed.
+
 ## 1. Create the docs directory
 
 Create a directory for your new product under `docs/`:
@@ -17,13 +23,13 @@ Create a directory for your new product under `docs/`:
 mkdir -p docs/myproduct/getting-started
 ```
 
-Add a minimal index page:
+Create a minimal index page:
 
 ```bash
 touch docs/myproduct/getting-started/index.md
 ```
 
-## 2. Add a navigation.json
+## 2. Add `navigation.json`
 
 Create `docs/myproduct/navigation.json`. This file defines the sidebar for the docset:
 
@@ -39,11 +45,11 @@ Create `docs/myproduct/navigation.json`. This file defines the sidebar for the d
 ]
 ```
 
-See the [Navigation contract](/docs/reference/navigation-contract) for the full schema and validation rules.
+See the [Navigation contract](/docs/reference/navigation-contract) for the schema and validation rules.
 
-## 3. Add the plugin to docusaurus.config.ts
+## 3. Add the docs plugin in `docusaurus.config.ts`
 
-Add a `@docusaurus/plugin-content-docs` entry inside the `plugins` array in `docusaurus.config.ts`:
+Add a `@docusaurus/plugin-content-docs` entry inside the `plugins` array:
 
 ```ts
 [
@@ -86,13 +92,23 @@ In `docusaurus.config.ts`, add an entry to `themeConfig.navbar.items`:
 
 ## 6. Add a footer link (optional)
 
-Add a link to `themeConfig.footer.links` in the appropriate column.
+Add a link to `themeConfig.footer.links` in the relevant column.
 
 ## 7. Validate
 
-Run validation to check that your navigation contract is valid and the build succeeds:
+Run validation to confirm your navigation contract is valid and the site builds:
 
 ```bash
 docify validate
 docify build
 ```
+
+## 8. Verify in the browser
+
+Run the dev server and verify the new docset route and sidebar:
+
+```bash
+docify dev
+```
+
+Open `http://localhost:3000/myproduct/getting-started` and confirm the sidebar loads your `navigation.json` entries.
diff --git a/docs/devdocify/how-to/add-playground.md b/docs/devdocify/how-to/add-playground.md
index 47831f2..325aca9 100644
--- a/docs/devdocify/how-to/add-playground.md
+++ b/docs/devdocify/how-to/add-playground.md
@@ -11,9 +11,9 @@ Follow these steps to add an interactive API playground to a DevDocify docset.
 
 ## Before you start
 
-You'll need:
+You need:
 
-- An OpenAPI description file (JSON or YAML) for your API
+- An OpenAPI description file (`.json` or `.yaml`)
 - An existing docset directory under `docs/`
 - Write access to `docusaurus.config.ts`
 
@@ -21,23 +21,23 @@ You'll need:
 
 Place your OpenAPI file in the `openapi/` directory at the project root:
 
-```
+```text
 openapi/my-api.json
 ```
 
-Keep the spec scoped to the operations you want to expose in the playground. Curated three-to-five operation specs work better than full API surface dumps for onboarding purposes.
+Keep the spec scoped to the operations you want to expose in the playground.
 
 ## 2. Install the OpenAPI plugin
 
-Install the plugin if it's not already present:
+Install the plugin if it isn't already present:
 
 ```bash
 npm install docusaurus-plugin-openapi-docs @docusaurus/plugin-content-docs
 ```
 
-## 3. Configure the plugin in docusaurus.config.ts
+## 3. Configure the plugin in `docusaurus.config.ts`
 
-Add a plugin entry for your docset:
+Add a plugin entry:
 
 ```ts
 [
@@ -60,38 +60,45 @@ Add a plugin entry for your docset:
 
 ## 4. Create the playground page
 
-Add a playground page to your docset. A minimal page needs:
-
-- A route under your docset base path (for example `/my-product/api-playground`)
-- A React component that renders the interactive explorer
+Add a page under your docset base path, for example `/my-product/api-playground`, that renders the interactive explorer.
 
-Use the TfL or Petstore playground pages as reference implementations:
+Use these pages as reference implementations:
 
 - `src/pages/tfl/api-playground.tsx`
 - `src/pages/petstore/api-playground.tsx`
 
-## 5. Add a playground guide to your docset
+## 5. Add a playground guide in your docset
 
-Create a `getting-started/playground.md` file in your docset directory that explains:
+Create `getting-started/playground.md` in your docset and explain:
 
 1. What the playground demonstrates
-2. Scope and limits (number of operations, auth requirements)
+2. Scope and limits (operations, auth requirements)
 3. Try-it defaults and why you chose them
 4. Expected response behavior
 5. Where to go next
 
-Add the file to your docset's `navigation.json` inside the Getting started category.
+Add this file to your docset `navigation.json` under your Getting started category.
 
 ## 6. Validate
 
-Run the following to confirm the build succeeds:
+Run:
 
 ```bash
 docify build
 ```
 
-Or check for broken links specifically:
+If you only want to check link integrity:
 
 ```bash
 docify broken-links
 ```
+
+## 7. Verify behavior
+
+Start local dev and test at least one request in the playground UI:
+
+```bash
+docify dev
+```
+
+Confirm the route loads and the sample requests return expected responses.
diff --git a/docs/devdocify/how-to/configure-search.md b/docs/devdocify/how-to/configure-search.md
index 7ad87ee..f9f7c09 100644
--- a/docs/devdocify/how-to/configure-search.md
+++ b/docs/devdocify/how-to/configure-search.md
@@ -7,23 +7,29 @@ description: "How to configure Algolia DocSearch for a DevDocify site, including
 
 # Configure search
 
-DevDocify uses Algolia DocSearch for full-text search across all docsets. Follow these steps to configure it.
+DevDocify uses Algolia DocSearch for full-text search across docsets.
+
+## Prerequisites
+
+- A deployed docs URL that Algolia can crawl
+- Access to your `docusaurus.config.ts`
+- Access to Algolia DocSearch or Algolia dashboard
 
 ## 1. Apply for DocSearch
 
-Go to [docsearch.algolia.com](https://docsearch.algolia.com) and apply with your site's URL.
+Go to [docsearch.algolia.com](https://docsearch.algolia.com) and apply with your site URL.
 
-Algolia reviews applications for documentation sites manually. Approval typically takes a few days. You'll receive an email with your `appId`, `apiKey`, and `indexName` when approved.
+After approval, Algolia sends your `appId`, `apiKey`, and `indexName`.
 
-If you need immediate access, create an Algolia account directly at [algolia.com](https://www.algolia.com) and set up a free application.
+If you need immediate access, create an Algolia app directly at [algolia.com](https://www.algolia.com).
 
 ## 2. Run a test crawl
 
-Once your Algolia application is provisioned, run a manual crawl from the Algolia Crawler dashboard to confirm the index populates correctly before wiring it into the site.
+Run a manual crawl from the Algolia Crawler dashboard and verify records are indexed before wiring search into the site.
 
-## 3. Add the credentials to docusaurus.config.ts
+## 3. Add credentials in `docusaurus.config.ts`
 
-In `docusaurus.config.ts`, add an `algolia` block inside `themeConfig`:
+Add an `algolia` block inside `themeConfig`:
 
 ```ts
 themeConfig: {
@@ -36,26 +42,24 @@ themeConfig: {
 },
 ```
 
-Do not commit your write API key. The `apiKey` here is the public **search-only** key. It's safe to include in source.
+Use a public search-only key here. Do not commit write/admin API keys.
 
 ## 4. Enable contextual search
 
-For multi-docset sites, `contextualSearch: true` scopes search results to the current docset. Algolia uses the Docusaurus `docusaurus_tag` facet to filter results.
+For multi-docset sites, `contextualSearch: true` scopes results to the current docset.
 
-If your index doesn't include the tag facet, update your Algolia crawler configuration to include it. The Docusaurus documentation has an [example crawler config](https://docusaurus.io/docs/search#using-algolia-docsearch) you can adapt.
+If your index doesn't include the Docusaurus facet tags, update your crawler config to include `docusaurus_tag` in `attributesForFaceting`.
 
 ## 5. Test locally
 
-Start the dev server:
-
 ```bash
 docify dev
 ```
 
-Use the search box to confirm results are scoped correctly to the active docset.
+Use the search box in at least two docsets to confirm scoped results.
 
 ## Troubleshooting
 
-- **No results**: Check that your Algolia index has been crawled and contains documents. Run a manual crawl from the Algolia dashboard.
-- **Results from other docsets showing up**: Confirm `contextualSearch: true` is set and the crawler config includes `docusaurus_tag` in the `attributesForFaceting` list.
-- **Search box not appearing**: Confirm your `themeConfig.algolia` block is inside the correct preset config and not duplicated.
+- No results: verify crawl success and index contents in Algolia.
+- Cross-docset results: confirm `contextualSearch: true` and `docusaurus_tag` faceting.
+- Search box missing: verify `themeConfig.algolia` is present once in the active config.
diff --git a/docs/devdocify/reference/index.md b/docs/devdocify/reference/index.md
index a10c679..9991e3b 100644
--- a/docs/devdocify/reference/index.md
+++ b/docs/devdocify/reference/index.md
@@ -2,7 +2,7 @@
 sidebar_position: 1
 slug: /reference
 title: Reference
-description: "Technical reference for DevDocify. CLI commands, navigation contract schema, route model, and configuration entry points."
+description: "Technical reference for DevDocify: CLI commands, navigation contract schema, route model, and configuration entry points."
 ---
 
 # Reference
@@ -16,9 +16,7 @@ Use reference pages when you need exact facts, supported options, and stable tec
   </p>
 </div>
 
-## CLI reference
-
-See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, and examples.
+## Reference pages
 
 <div className="docs-link-grid">
   <a href="/docs/reference/cli">CLI reference</a>
@@ -29,7 +27,7 @@ See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, a
 
 <div className="docs-route-list">
   <p><code>/</code> marketing-first root surface</p>
-  <p><code>/docs</code> first-party technical product docs (Diátaxis)</p>
+  <p><code>/docs</code> first-party technical product docs (Diataxis)</p>
   <p><code>/tfl</code> demo TfL product docs</p>
   <p><code>/petstore</code> demo Petstore product docs</p>
   <p><code>/tfl/api-playground</code> and <code>/petstore/api-playground</code> interactive demo routes</p>
@@ -40,8 +38,5 @@ See the [CLI reference](/docs/reference/cli) for all `docify` commands, flags, a
 - Site config: `docusaurus.config.ts`
 - Sidebars: `sidebarsDevDocify.ts`, `sidebarsTfl.ts`, `sidebarsPetstore.ts`
 - Navigation contract loader: `navigation-contract.ts`
-- Navigation definitions:
-  - `docs/devdocify/navigation.json`
-  - `docs/tfl/navigation.json`
-  - `docs/petstore/navigation.json`
+- Navigation definitions: `docs/*/navigation.json`
 - Workflows: `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`, `.github/workflows/preview.yml`
diff --git a/docs/devdocify/reference/navigation-contract.md b/docs/devdocify/reference/navigation-contract.md
index b1b799b..b5e6c0e 100644
--- a/docs/devdocify/reference/navigation-contract.md
+++ b/docs/devdocify/reference/navigation-contract.md
@@ -16,7 +16,7 @@ These files are loaded and validated by `navigation-contract.ts` and then consum
 
 ## Supported node types
 
-Each node must declare a `type`:
+Each node must declare `type`:
 
 - `doc`: `{"type":"doc","id":"path/to/doc","label":"Optional label"}`
 - `category`: `{"type":"category","label":"Section","items":[...]}`
@@ -26,20 +26,20 @@ Each node must declare a `type`:
 
 Validation runs at build/start time and fails fast when the contract is invalid.
 
-Examples of invalid input that fail the build with actionable errors:
+Examples that fail validation:
 
-- root is not an array
-- missing or unsupported `type`
-- `doc` node without `id`
-- `link` node without `href`
-- `category` node without non-empty `items`
+- Root isn't an array.
+- Missing or unsupported `type`.
+- `doc` node without `id`.
+- `link` node without `href`.
+- `category` node without non-empty `items`.
 
 ## Deep nesting support
 
-The contract parser is recursive and supports deeply nested category trees, including trees deeper than five levels.
+The parser is recursive and supports deeply nested category trees.
 
 ## Why this model
 
-- one navigation file per docset/version
-- deterministic, validated behavior before publish
-- easier ownership and change review for information architecture updates
+- One navigation file per docset or version.
+- Deterministic behavior before publish.
+- Easier ownership and review for information architecture changes.
diff --git a/docs/devdocify/tutorials/quick-start.md b/docs/devdocify/tutorials/quick-start.md
index 6ee5227..407a393 100644
--- a/docs/devdocify/tutorials/quick-start.md
+++ b/docs/devdocify/tutorials/quick-start.md
@@ -11,18 +11,17 @@ This tutorial walks you from installing the CLI to deploying a DevDocify site. I
 
 ## What you'll build
 
-A new documentation site running locally, with content validation and broken-link checks passing, ready to push to Vercel.
+A new documentation site running locally, with content validation and broken-link checks passing, ready to deploy to Vercel.
 
 ## Prerequisites
 
-- Node.js 20.17.0 or later
-- An npm account (for global install)
-- A GitHub account (for the deploy step)
-- A Vercel account (for the deploy step)
+- Node.js 20.17.0 or later (includes npm)
+- A GitHub account (for deployment)
+- A Vercel account (for deployment)
 
 ---
 
-## Step 1 — Install the CLI
+## Step 1: Install the CLI
 
 Install the Docify CLI globally:
 
@@ -30,7 +29,7 @@ Install the Docify CLI globally:
 npm install -g @devdocify/cli
 ```
 
-Confirm it's working:
+Confirm it's available:
 
 ```bash
 docify --version
@@ -38,7 +37,7 @@ docify --version
 
 ---
 
-## Step 2 — Create a project
+## Step 2: Create a project
 
 Scaffold a new DevDocify project in a directory called `my-docs`:
 
@@ -46,8 +45,6 @@ Scaffold a new DevDocify project in a directory called `my-docs`:
 docify new my-docs
 ```
 
-The CLI creates the directory with a minimal Docusaurus project, a placeholder doc, and a `.gitignore`.
-
 Change into the new directory and install dependencies:
 
 ```bash
@@ -57,7 +54,7 @@ npm install
 
 ---
 
-## Step 3 — Start the dev server
+## Step 3: Start the dev server
 
 ```bash
 docify dev
@@ -65,13 +62,13 @@ docify dev
 
 Open [http://localhost:3000](http://localhost:3000) in your browser. You should see your new docs site.
 
-Edit `docs/index.md` and save — the browser reloads automatically.
+Edit `docs/index.md` and save. The browser should reload automatically.
 
-Press `Ctrl+C` to stop the dev server when you're done.
+Press `Ctrl+C` to stop the dev server when you are done.
 
 ---
 
-## Step 4 — Validate content
+## Step 4: Validate content
 
 Run the content linter to catch common issues before you build:
 
@@ -79,7 +76,7 @@ Run the content linter to catch common issues before you build:
 docify validate
 ```
 
-If your project's `package.json` doesn't have a `lint-content` script yet, add one:
+If your `package.json` doesn't have a `lint-content` script yet, add one:
 
 ```json
 "lint-content": "echo \"No linter configured\""
@@ -87,7 +84,7 @@ If your project's `package.json` doesn't have a `lint-content` script yet, add o
 
 ---
 
-## Step 5 — Check for broken links
+## Step 5: Check for broken links
 
 Build the site and check every internal link:
 
@@ -99,7 +96,7 @@ Fix any broken links reported before continuing.
 
 ---
 
-## Step 6 — Build and deploy
+## Step 6: Build and deploy
 
 Build a production bundle:
 
@@ -107,15 +104,19 @@ Build a production bundle:
 docify build
 ```
 
-To deploy to Vercel:
+Deploy to Vercel:
 
 1. Push your project to a GitHub repository.
 2. Log in to [vercel.com](https://vercel.com) and click **Add New Project**.
 3. Import your GitHub repository.
-4. Set the following in the Vercel project settings:
-   - **Build command**: `npm run build`
-   - **Output directory**: `build`
-   - **Install command**: `npm install`
+4. Set the following in Vercel project settings:
+
+| Setting | Value |
+|---|---|
+| Build command | `npm run build` |
+| Output directory | `build` |
+| Install command | `npm install` |
+
 5. Click **Deploy**.
 
 Vercel runs a build on every push to `main` and creates preview deployments for every pull request.
@@ -124,7 +125,7 @@ Vercel runs a build on every push to `main` and creates preview deployments for
 
 ## What's next
 
-- [Add a docset](/docs/how-to/add-docset) — bring a new product into your site
-- [Add an API playground](/docs/how-to/add-playground) — add an interactive OpenAPI explorer
-- [Configure search](/docs/how-to/configure-search) — set up Algolia DocSearch
-- [CLI reference](/docs/reference/cli) — all commands and flags
+- [Add a docset](/docs/how-to/add-docset)
+- [Add an API playground](/docs/how-to/add-playground)
+- [Configure search](/docs/how-to/configure-search)
+- [CLI reference](/docs/reference/cli)