docs(readme): add Ask AI preview CORS and backend dependency notes

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.

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.

docs/devdocify/how-to/add-playground.md

@@ -11,33 +11,33 @@ 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`
 
 ## 1. Add your OpenAPI spec
 
 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.

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.

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`

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.