Rename Learn tab to Capabilities with full restructure

.claude/commands/check-links.md

@@ -0,0 +1,26 @@
+Scan the documentation for broken internal links, orphaned pages, and redirect chain issues.
+
+## Steps
+
+### 1. Broken internal links
+Search all .mdx files (excluding `snippets/`, `reference/api_v0/`, `changelog/`) for markdown links matching the pattern `](/path...)`. For each link:
+- Strip any anchor (`#...`) from the path
+- Check if a corresponding .mdx file exists at that path
+- If not, check if the path is covered by a redirect in docs.json
+- Report any links that point to neither an existing file nor a redirect
+
+### 2. Orphaned pages
+List all .mdx files under the main content directories (`getting_started/`, `learn/`, `reference/`, `resources/`, `guides/`) and check if each appears in the docs.json navigation. Exclude:
+- `snippets/` (include files, expected orphans)
+- `reference/api_v0/` (archived, in .mintignore)
+- Files that are the target of an `openapi:` directive
+- `home.mdx` (Mintlify landing page)
+
+### 3. Redirect chains
+Check the `redirects` array in docs.json for chains: where a redirect's `destination` is itself a `source` of another redirect. Report any chains found.
+
+### 4. Missing nav pages
+Check every page listed in docs.json navigation and verify the corresponding .mdx file exists on disk.
+
+## Output
+Report findings grouped by category. For broken links, show the file containing the link and the broken target path. For orphaned pages, list the file paths. Keep the output concise.

.claude/commands/check-redirects.md

@@ -0,0 +1,45 @@
+Analyze redirects using real traffic data from Fathom Analytics. Finds missing redirects (old URLs people still visit) and unused redirects (redirects nobody hits).
+
+## Prerequisites
+
+Requires `FATHOM_API_KEY` and `FATHOM_SITE_ID` in `.env` at the repo root.
+
+## Steps
+
+### 1. Run the script
+
+Run `node scripts/check-missing-redirects.mjs` and wait for it to complete. The script:
+- Fetches all `/docs/*` page views from Fathom Analytics (last 90 days)
+- Fetches the production sitemap to know all live pages (including OpenAPI-generated routes)
+- Walks local .mdx files for pages not yet deployed
+- Compares traffic against known pages + existing redirects in docs.json
+- Reports two lists: missing redirects and unused redirects
+- Filters out junk URLs (trailing dots, double /docs/, internal Mintlify props, error pages)
+- Only reports URLs with >= 10 views
+
+### 2. Review missing redirects
+
+For each missing redirect, find the best destination page:
+- Search local .mdx files and docs.json navigation for the matching topic
+- Check the production sitemap for similar paths
+- Prefer the most specific match (e.g. `/guides/laravel_scout` -> `/getting_started/frameworks/laravel`)
+- If no good match exists, redirect to the closest parent or overview page
+
+### 3. Review unused redirects
+
+These are redirects in docs.json that got zero traffic in 90 days. They are safe to remove to keep docs.json clean. Remove them from the `redirects` array.
+
+### 4. Apply changes
+
+- Add missing redirects to the `redirects` array in docs.json
+- Remove unused redirects from docs.json
+- Validate docs.json is still valid JSON
+- Re-run the script to confirm 0 missing and 0 unused
+
+## Output
+
+Report:
+- How many missing redirects were found and added (with the top 5 by traffic)
+- How many unused redirects were removed
+- Final redirect count in docs.json
+- Confirmation that the re-run shows 0/0

.claude/commands/move-page.md

@@ -0,0 +1,18 @@
+Move a documentation page from one path to another, handling all side effects.
+
+Arguments: $ARGUMENTS (format: `<old-path> <new-path>`, e.g. `resources/self_hosting/docker resources/self_hosting/getting_started/docker`)
+
+## Steps
+
+1. **Validate**: Check that the source .mdx file exists and the destination directory exists (create it if needed)
+2. **Move the file**: Use `git mv` to move the .mdx file from old path to new path
+3. **Update docs.json navigation**: Find the old path in the `pages` arrays and replace it with the new path
+4. **Add a redirect**: Add a redirect entry in the `redirects` array of docs.json mapping the old path to the new path
+5. **Fix redirect destinations**: Check if any existing redirects in docs.json have the old path as their `destination` and update them to point to the new path (prevent redirect chains)
+6. **Fix all internal links**: Search ALL .mdx files in the repo (excluding `snippets/`, `reference/api_v0/`, and `changelog/`) for links containing the old path and update them to the new path. Be careful to preserve anchors (e.g. `old-path#section` becomes `new-path#section`)
+7. **Report**: List all files modified and the total number of links updated
+
+Important:
+- Paths should NOT include the `.mdx` extension or leading `/`
+- Do NOT modify links inside the `redirects` array source fields (those are backward-compat sources)
+- Do NOT touch files in `snippets/`, `reference/api_v0/`, or `changelog/`

.claude/commands/new-capability.md

@@ -0,0 +1,37 @@
+Scaffold a new capability in the Learn tab following the standard structure.
+
+Arguments: $ARGUMENTS (the capability name, e.g. `geosearch` or `faceted_search`)
+
+## Steps
+
+1. **Create the directory**: `learn/<capability_name>/`
+
+2. **Create the pages** with proper frontmatter. Each page should have a `title` and `description` field. Create the following files:
+
+   - `overview.mdx` - What this capability is, why it matters, key features, how it works at a high level. Include a CardGroup at the bottom linking to the other pages in the group.
+   - `getting_started.mdx` - Step-by-step tutorial to use this capability for the first time. Prerequisites, minimal working example, expected results.
+   - `how_to.mdx` - Task-oriented guides for common use cases. Each section answers "How do I do X?"
+   - `advanced.mdx` - Deep-dive content: edge cases, performance tuning, architecture details, advanced configuration.
+   - `reference.mdx` - Configuration options, API parameters, settings reference specific to this capability. Link to the relevant API reference pages.
+
+3. **Add to docs.json navigation**: Add a new group in the Learn tab:
+   ```json
+   {
+     "group": "<Capability Name>",
+     "pages": [
+       "learn/<capability_name>/overview",
+       "learn/<capability_name>/getting_started",
+       "learn/<capability_name>/how_to",
+       "learn/<capability_name>/advanced",
+       "learn/<capability_name>/reference"
+     ]
+   }
+   ```
+
+4. **Ask the user** where in the Learn tab nav order this group should be placed (after which existing group).
+
+## Writing rules
+- Never use em dashes in content
+- Use Meilisearch Cloud examples first, then self-hosted alternatives
+- Include code examples with curl and at least one SDK
+- Add `<Tip>` callouts for Meilisearch Cloud when relevant

.claude/commands/new-comparison.md

@@ -0,0 +1,67 @@
+Create a new comparison page for Meilisearch vs another product.
+
+Arguments: $ARGUMENTS (the product name, e.g. `Typesense` or `Elasticsearch`)
+
+## Template
+
+Create the file at `resources/comparisons/<product_lowercase>.mdx` following this structure:
+
+```mdx
+---
+title: Meilisearch vs <Product>
+sidebarTitle: <Product>
+description: Compare Meilisearch and <Product>. Learn key differences and when to choose each.
+---
+
+<One paragraph introducing the product: what it is, when it was created, what it's built with, its primary focus.>
+
+## Quick comparison
+
+|  | Meilisearch | <Product> |
+|---|:---:|:---:|
+| **License** | MIT (CE) / BUSL-1.1 (EE) | ... |
+| **Built with** | Rust | ... |
+| **Data storage** | Disk (memory-mapped) | ... |
+| **Sharding** | Yes (Enterprise Edition) | ... |
+| **Language support** | Optimized for CJK, Arabic, Hebrew, Thai | ... |
+| **Embedding generation** | Built-in local (Candle) + any HTTP API provider | ... |
+| **Conversational search** | Yes (built-in chat) | ... |
+
+## When to choose Meilisearch
+
+<Lead with Meilisearch's strengths. Be confident but honest. Highlight: disk-based storage, Rust stability/safety, sharding, multilingual support, embedding flexibility, conversational search, MIT license, analytics dashboard, developer experience.>
+
+## What <Product> does well
+
+<Honestly acknowledge the competitor's genuine strengths. Scope them where appropriate (e.g. "for small datasets", "if you already use X ecosystem").>
+
+## When to choose <Product>
+
+Consider <Product> if:
+- <bullet points for genuine use cases where the competitor is a better fit>
+
+## Migration resources
+
+If you're considering Meilisearch:
+- [Meilisearch quick start](/getting_started/first_project)
+- [AI-powered search](/learn/ai_powered_search/getting_started_with_ai_search)
+- [Conversational search](/learn/chat/getting_started_with_chat)
+- <Add migration guide link if one exists>
+
+<Note>
+<Product> is a registered trademark of <Company>. This comparison is based on publicly available information and our own analysis.
+</Note>
+```
+
+## Steps
+
+1. Create the file from the template above
+2. Add the page to docs.json in the "Comparisons" group under the Resources tab
+3. Ask the user to fill in product-specific details or research publicly available information
+4. Never lie or invent features. If unsure about a competitor feature, ask the user.
+
+## Tone
+- Write from Meilisearch's perspective: confident, not neutral
+- Highlight Meilisearch strengths before competitor strengths
+- Be honest about competitor advantages but scope them appropriately
+- Never use em dashes

.claude/commands/update-api-ref.md

@@ -0,0 +1,41 @@
+Update the API reference documentation from the OpenAPI spec.
+
+## Steps
+
+1. **Fetch the latest OpenAPI spec** from the Meilisearch repository:
+   ```
+   npm run fetch-meilisearch-openapi-file
+   ```
+
+2. **Generate the Mintlify-compatible OpenAPI file**:
+   ```
+   npm run generate-mintlify-openapi-file
+   ```
+
+3. **Check for new routes** that need coverage:
+   ```
+   npm run check-openapi-routes-coverage
+   ```
+
+4. **Generate code sample snippets**:
+   ```
+   npm run generate-code-sample-snippets-file
+   ```
+
+5. **Check code samples**:
+   ```
+   npm run check-openapi-code-samples
+   npm run check-code-samples-usage
+   npm run check-missing-sdk-samples
+   npm run check-unused-sdk-samples
+   ```
+
+6. **Report**: Summarize what changed:
+   - New routes added (if any)
+   - Missing code samples (if any)
+   - Any errors from the scripts
+
+If new routes were added, remind the user that they may need to:
+- Add MDX stub files for new endpoints
+- Update the docs.json navigation if new route groups were created
+- Add code samples for the new endpoints

.claude/commands/update-changelog.md

@@ -0,0 +1,19 @@
+Update the changelog from GitHub releases.
+
+## Steps
+
+1. **Generate the changelog**:
+   ```
+   npm run generate-changelog
+   ```
+
+2. **Review the output**: Check for any errors or warnings from the script.
+
+3. **Verify the generated files**: Look at the changelog directory for new or updated entries. Show the user a summary of what releases were added or updated.
+
+4. **Check docs.json**: If new changelog pages were generated, verify they are included in the Changelog tab navigation in docs.json. Add any missing entries.
+
+5. **Report**: Summarize what was generated:
+   - Number of new releases added
+   - Any releases that failed to generate
+   - Whether docs.json navigation needs updating

.code-samples.meilisearch.yaml

@@ -1463,7 +1463,7 @@ chat_index_settings_1: |-
 chat_completions_1: |-
   curl -N \
     -X POST 'MEILISEARCH_URL/chats/WORKSPACE_NAME/chat/completions' \
-    -H 'Authorization: Bearer MEILISEARCH_API_KEY' \
+    -H 'Authorization: Bearer MEILISEARCH_KEY' \
     -H 'Content-Type: application/json' \
     --data-binary '{
       "model": "PROVIDER_MODEL_UID",

.gitignore

@@ -136,3 +136,6 @@ yarn-error.log
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+
+# Script output
+missing-redirects.txt

CLAUDE.md

@@ -1,5 +1,15 @@
 # Meilisearch Documentation
 
+## Documentation structure
+
+The documentation is organized into five tabs:
+
+- **Getting Started**: Where everyone starts. First steps with Meilisearch, SDK quick starts, framework integrations.
+- **Capabilities**: All Meilisearch capabilities documented. Each capability follows the structure: Overview, Getting Started, How To, Advanced. Organized under `capabilities/` with sub-folders per capability (full_text_search, hybrid_search, geo_search, conversational_search, multi_search, filtering_sorting_faceting, personalization, analytics, security, teams, indexing).
+- **References**: API reference documentation for the HTTP API. Generated from the OpenAPI spec. Must be updated whenever there is a new route. See scripts in `package.json`.
+- **Resources**: Secondary references. Self-hosting, comparisons and migration guides for alternatives, under the hood internals, demos, and other resources.
+- **Changelog**: Changelog of the Engine (and soon Cloud too). Automatically generated from GitHub releases. See scripts in `package.json`.
+
 ## Writing style
 
 - **Never use em dashes (`—`)** in documentation content. Use commas, parentheses, or rewrite the sentence instead.

capabilities/analytics/advanced/analytics_metrics.mdx

@@ -0,0 +1,80 @@
+---
+title: Analytics metrics reference
+description: This reference describes the metrics you can find in the Meilisearch analytics interface.
+---
+
+## How metrics are computed
+
+Analytics metrics are based on **search IDs**, which represent search intents rather than individual HTTP requests. When a user types "run", "runn", "running shoes" in a search-as-you-type interface, those keystrokes generate multiple requests but count as a single search intent. This means metrics like click-through rate, conversion rate, and no-result rate reflect actual user behavior rather than keystroke volume.
+
+For more details on the relationship between search IDs, request IDs, and query IDs, see the [analytics overview](/capabilities/analytics/overview#search-id-request-id-and-query-id).
+
+## Total searches
+
+Total number of search intents during the specified period. Multiple requests within the same search intent count as a single search.
+
+## Total users
+
+Total number of users who performed a search in the specified period.
+
+Include the [user ID](/capabilities/analytics/how_to/bind_events_to_user) in your search request headers for the most accurate metrics. If search requests do not provide any user ID, Meilisearch generates an anonymous identifier automatically. Providing your own user IDs gives more accurate tracking, especially for users across multiple sessions.
+
+## No result rate
+
+Percentage of searches that did not return any results.
+
+## Click-through rate
+
+The ratio between the number of times users clicked on a result and the number of times Meilisearch showed that result. Since users will click on results that potentially match what they were looking for, a higher number indicates better relevancy.
+
+Meilisearch does not have access to this information by default. You must [configure your application to submit click events](/capabilities/analytics/getting_started) to Meilisearch if you want to track it in the analytics interface.
+
+## Average click position
+
+The average list position of clicked search results. A lower number means users have clicked on the first search results and indicates good relevancy.
+
+Meilisearch does not have access to this information by default. You must [configure your application to submit click events](/capabilities/analytics/getting_started) to Meilisearch if you want to track it in the analytics interface.
+
+## Conversion
+
+The percentage of searches resulting in a conversion event in your application. Conversion events vary depending on your application and indicate a user has performed a specific desired action. For example, a conversion for an e-commerce website might mean a user has bought a product.
+
+You must explicitly [configure your application to send conversion](/capabilities/analytics/getting_started) events when conditions are met.
+
+<Note>
+It is not possible to associate multiple `conversion` events with the same query.
+</Note>
+
+## Search requests
+
+Total number of search requests within the specified time period.
+
+## Search latency
+
+The amount of time between a user making a search request and Meilisearch returning search results. A lower number indicates users receive search results more quickly.
+
+## Most searched queries
+
+Most common query terms users have used while searching.
+
+## Searches without results
+
+Most common query terms that did not return any search results.
+
+## Countries with most searches
+
+List of countries that generate the largest amount of search requests. Meilisearch determines geographic distribution automatically based on the user's IP address. No additional configuration is required.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Get started with analytics" href="/capabilities/analytics/getting_started">
+    Set up analytics and start collecting search data.
+  </Card>
+  <Card title="Track click events" href="/capabilities/analytics/how_to/track_click_events">
+    Configure your application to send click events to Meilisearch.
+  </Card>
+  <Card title="Track conversion events" href="/capabilities/analytics/how_to/track_conversion_events">
+    Measure how often searches lead to desired user actions.
+  </Card>
+</CardGroup>