Strapi Docs "v7" full redesign

.github/workflows/docs-self-healing.yml

@@ -273,7 +273,7 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_SELF_HEALING_DOCS_API_KEY }}
           github_token: ${{ secrets.PAT_TOKEN_PIWI }}
           prompt: ${{ steps.load-triage-prompt.outputs.prompt }}
-          claude_args: '--model claude-haiku-4-5-20251001 --max-turns 10 --allowedTools "Bash,Read"'
+          claude_args: '--model claude-haiku-4-5-20251001 --max-turns 20 --allowedTools "Bash,Read"'
           show_full_output: true
         env:
           FILTERED_PRS: ${{ steps.check-prs.outputs.pr_list }}
@@ -484,7 +484,7 @@ jobs:
           anthropic_api_key: ${{ secrets.ANTHROPIC_SELF_HEALING_DOCS_API_KEY }}
           github_token: ${{ secrets.PAT_TOKEN_PIWI }}
           prompt: ${{ steps.load-drafter-prompt.outputs.prompt }}
-          claude_args: '--model claude-sonnet-4-6 --max-turns 25 --allowedTools "Bash,Read,Write,Edit,Glob,Grep"'
+          claude_args: '--model claude-sonnet-4-6 --max-turns 50 --allowedTools "Bash,Read,Write,Edit,Glob,Grep"'
           show_full_output: true
         env:
           DOC_REPO: ${{ github.workspace }}

.github/workflows/sync-content-to-next.yml

@@ -11,6 +11,9 @@ on:
   pull_request:
     types: [labeled, closed]
 
+env:
+  TARGET_BRANCH: repo/redesign-v7-cutover
+
 jobs:
   # Job for debugging purposes
   debug-event:
@@ -91,17 +94,17 @@ jobs:
           PR_TITLE="${{ github.event.pull_request.title }}"
           SOURCE_BRANCH="${{ github.event.pull_request.head.ref }}"
           SOURCE_REPO="${{ github.event.pull_request.head.repo.full_name }}"
-          TARGET_BRANCH="next-port-pr$PR_NUMBER"
-          
+          HEAD_BRANCH="next-port-pr$PR_NUMBER"
+
           echo "Source Branch: $SOURCE_BRANCH"
           echo "Source Repo: $SOURCE_REPO"
-          echo "Target Branch: $TARGET_BRANCH"
-          
-          # Fetch next branch
-          git fetch origin next
-          
-          # Create new branch based on next
-          git checkout -b $TARGET_BRANCH origin/next
+          echo "Head Branch: $HEAD_BRANCH"
+
+          # Fetch sync target branch
+          git fetch origin "$TARGET_BRANCH"
+
+          # Create new branch based on the sync target branch
+          git checkout -b $HEAD_BRANCH "origin/$TARGET_BRANCH"
 
           # Fetch source branch
           if [ "$SOURCE_REPO" != "${{ github.repository }}" ]; then
@@ -162,15 +165,15 @@ jobs:
         run: |
           # Commit changes - force commit even if git thinks there are no changes
           git add .
-          git commit --allow-empty -m "Port PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }} to next branch"
+          git commit --allow-empty -m "Port PR #${{ github.event.pull_request.number }}: ${{ github.event.pull_request.title }} to the redesign branch"
 
           # Push branch
           git push origin next-port-pr${{ github.event.pull_request.number }}
 
           # Create PR with a special tag in the body to identify it later
-          PR_CMD="gh pr create --base next --head next-port-pr${{ github.event.pull_request.number }} \
+          PR_CMD="gh pr create --base \"$TARGET_BRANCH\" --head next-port-pr${{ github.event.pull_request.number }} \
             --title \"${{ steps.load-config.outputs.title_prefix }} ${{ github.event.pull_request.title }}\" \
-            --body \"Automatic port of PR #${{ github.event.pull_request.number }} to next branch.\n\nOriginal PR: #${{ github.event.pull_request.number }}\nCreated automatically after adding the 'temp - port to docs-next' label.\n\n<!-- SYNC_PR_MARKER -->\" \
+            --body \"Automatic port of PR #${{ github.event.pull_request.number }} to the redesign branch.\n\nOriginal PR: #${{ github.event.pull_request.number }}\nCreated automatically after adding the 'temp - port to docs-next' label.\n\n<!-- SYNC_PR_MARKER -->\" \
             --assignee ${{ steps.load-config.outputs.assignee }}"
 
           # Add labels if configured
@@ -238,7 +241,7 @@ jobs:
           PR_NUMBER="${{ github.event.pull_request.number }}"
 
           # Check if there's an existing PR 
-          EXISTING_PR_NUMBER=$(gh pr list --base next --head "next-port-pr$PR_NUMBER" --state open --json number --jq '.[0].number')
+          EXISTING_PR_NUMBER=$(gh pr list --base "$TARGET_BRANCH" --head "next-port-pr$PR_NUMBER" --state open --json number --jq '.[0].number')
 
           if [ -n "$EXISTING_PR_NUMBER" ]; then
             echo "Existing PR found: #$EXISTING_PR_NUMBER"
@@ -287,15 +290,15 @@ jobs:
             echo "branch_name=$BRANCH_NAME" >> $GITHUB_OUTPUT
           fi
 
-          # Create branch from next
-          git fetch origin next
-          
+          # Create branch from the sync target branch
+          git fetch origin "$TARGET_BRANCH"
+
           if [ "${{ steps.check-existing.outputs.strategy }}" = "update" ]; then
             echo "Checking out existing branch $BRANCH_NAME"
-            git checkout $BRANCH_NAME || git checkout -b $BRANCH_NAME origin/next
+            git checkout $BRANCH_NAME || git checkout -b $BRANCH_NAME "origin/$TARGET_BRANCH"
           else
             echo "Creating new branch $BRANCH_NAME"
-            git checkout -b $BRANCH_NAME origin/next
+            git checkout -b $BRANCH_NAME "origin/$TARGET_BRANCH"
           fi
 
           # Try to cherry-pick
@@ -329,16 +332,16 @@ jobs:
           PR_TITLE="${{ github.event.pull_request.title }}"
 
           # Create the new PR first
-          PR_CMD="gh pr create --base next --head $BRANCH_NAME \
+          PR_CMD="gh pr create --base \"$TARGET_BRANCH\" --head $BRANCH_NAME \
             --title \"${{ steps.load-config.outputs.title_prefix }} $PR_TITLE\" \
-            --body \"Synchronization of merged PR #${{ github.event.pull_request.number }} to next branch. This PR contains the final state of the changes as they were merged to main.\" \
+            --body \"Synchronization of merged PR #${{ github.event.pull_request.number }} to the redesign branch. This PR contains the final state of the changes as they were merged to main.\" \
             --assignee ${{ steps.load-config.outputs.assignee }}"
-          
+
           # Add labels if configured
           if [ -n "${{ steps.load-config.outputs.labels }}" ]; then
             PR_CMD="$PR_CMD --label ${{ steps.load-config.outputs.labels }}"
           fi
-          
+
           NEW_PR=$(eval "$PR_CMD --json number --jq '.number'")
 
           # Now close the existing PR with a reference to the new one
@@ -352,10 +355,10 @@ jobs:
           BRANCH_NAME="${{ steps.create-branch.outputs.branch_name }}"
           PR_TITLE="${{ github.event.pull_request.title }}"
 
-          # Create new PR 
-          PR_CMD="gh pr create --base next --head $BRANCH_NAME \
+          # Create new PR
+          PR_CMD="gh pr create --base \"$TARGET_BRANCH\" --head $BRANCH_NAME \
             --title \"${{ steps.load-config.outputs.title_prefix }} $PR_TITLE\" \
-            --body \"Synchronization of merged PR #${{ github.event.pull_request.number }} to next branch. This PR contains the final state of the changes as they were merged to main.\" \
+            --body \"Synchronization of merged PR #${{ github.event.pull_request.number }} to the redesign branch. This PR contains the final state of the changes as they were merged to main.\" \
             --assignee ${{ steps.load-config.outputs.assignee }}"
 
           # Add labels if configured
@@ -430,18 +433,18 @@ jobs:
             exit 0
           fi
 
-          # Create branch from next
+          # Create branch from the sync target branch
           BRANCH_NAME="sync-push-$(date +%Y%m%d-%H%M%S)"
-          
-          git fetch origin next
-          git checkout -b $BRANCH_NAME origin/next
+
+          git fetch origin "$TARGET_BRANCH"
+          git checkout -b $BRANCH_NAME "origin/$TARGET_BRANCH"
 
           # Try to cherry-pick
           if git cherry-pick $COMMIT_HASH; then
             git push origin $BRANCH_NAME
 
             # Create PR
-            PR_CMD="gh pr create --base next --head $BRANCH_NAME \
+            PR_CMD="gh pr create --base \"$TARGET_BRANCH\" --head $BRANCH_NAME \
               --title \"${{ steps.load-config.outputs.title_prefix }} $COMMIT_MSG\" \
               --body \"Automatic sync of commit from main\" \
               --assignee ${{ steps.load-config.outputs.assignee }}"

.gitignore

@@ -8,3 +8,7 @@ docs/superpowers/
 # Inki plugin run logs, in case a user points --log-dir at a local .inki/ folder.
 # By default logs go to ~/.inki/logs/ (outside any repo); this is a safety net.
 .inki/
+
+# Playwright MCP local artifacts (snapshots, screenshots, console logs) created
+# during local visual QA. Never tracked.
+.playwright-mcp/

AGENTS.md

@@ -77,7 +77,7 @@ Path‑based policy (applies to folders and all subfolders):
 ### Key files
 - AI toolbar: `docusaurus/src/components/AiToolbar/openLLM.js`, `.../config/aiToolsConfig.js`, `.../config/aiPromptTemplates.js`
 - Generators/validators: `docusaurus/scripts/generate-llms-code.js`, `docusaurus/scripts/generate-llms.js`, `docusaurus/scripts/validate-prompts.js`
-- Authoring templates: `claude-plugins/inki/references/templates/*.md` (see `claude-plugins/inki/references/templates/INDEX.md`)
+- Authoring templates: `claude-plugins/inki/references/templates/*.md` (see `claude-plugins/inki/references/templates/README.md`)
 - Agent prompts: `claude-plugins/inki/references/prompts/` (see table in Documentation Review System section)
 - Components guidance: `claude-plugins/inki/references/templates/components/tabs.md` (Tabs/TabItem rules)
 - Configuration: `docusaurus.config.js`, `sidebars.js`, `package.json`

claude-plugins/inki/references/authoring/AGENTS.cms.api.md

@@ -15,7 +15,7 @@ Frontmatter (mandatory)
 
 Templates
 - Start from `claude-plugins/inki/references/templates/api-template.md` to align sections and example layout.
-- See `claude-plugins/inki/references/templates/INDEX.md` for a quick catalog of available templates with paths and purposes.
+- See `claude-plugins/inki/references/templates/README.md` for a quick catalog of available templates with paths and purposes.
 
 API Overview Pages (e.g., Content API)
 1) H1 title — matches `title` frontmatter.
@@ -50,13 +50,26 @@ Heading Conventions
 
 Component Patterns by Page Type
 
-API pages use custom MDX components that vary by sub-section. When editing an existing page, always match the page's established patterns:
+API pages use custom MDX components that vary by sub-section. When editing an existing page, always match the page's established patterns. `<Endpoint>` is the current component for all reference endpoints. See `claude-plugins/inki/references/templates/components/endpoint.md` for the full `<Endpoint>` contract and copy-pasteable examples.
 
-- **Document Service API pages** use `<ApiCall>` with `<Request>` / `<Response>` for code examples. The `noSideBySide` prop is used for longer examples. Response code blocks use JS object literal notation (not JSON).
-- **REST API pages** use `<ApiCall>` wrapping `<Request>`, a `<details>` block for the `qs.stringify` equivalent, and `<Response>`. Snippet imports (`QsForQueryBody`, `QsForQueryTitle`, `QsIntroFull`) are used inside the `<details>` blocks. Response code blocks use JSON.
+`<Endpoint>`, `<StepDetails>`, and `<NextSteps>` are registered as global MDX components in `docusaurus/src/theme/MDXComponents.js` (like `<Tabs>`, `<Annotation>`, and `<ApiCall>`), so they are used directly with no import line.
+
+- **Document Service API pages** use `<Endpoint kind="js">`. `path` is the JS method signature (e.g. `strapi.documents().findOne()`). `params={[{ name, type, required, description }]}`, where the `description` may contain inline HTML (`<code>`, `<a href>`). `codeTabs={[{ label: 'Request', code: \`...\` }]}` holds the example(s); multiple example tabs are idiomatic. `responses` render under a "Returns" label rather than an HTTP status. The final block on the page uses `isLast={true}`. Admonitions go INSIDE the block as children: use a closing `</Endpoint>` tag instead of self-closing `/>`, open with `>`, leave a blank line, write the `:::tip` / `:::note`, leave a blank line, then `</Endpoint>`.
+- **REST API pages** use `<Endpoint>` with `kind="http"` (the default, so it can be omitted): `method`, `path` with `:params` (e.g. `/api/:pluralApiId/:documentId`), `codePath` + `codePathHighlights` for the URL bar shown in the code panel, and `codeTabs` (e.g. cURL + JavaScript). `responses` take `{ status, statusText, time?, body: JSON.stringify(..., null, 2) }`; multiple responses render as colored status tabs (e.g. 200 + 404). A DELETE endpoint with no response body uses `responses={[]}` together with `isLast`. The snippet imports `QsForQueryBody`, `QsForQueryTitle`, and `QsIntroFull` remain valid and are used alongside `<Endpoint>` on migrated REST pages (they are NOT legacy).
 - **GraphQL API pages** use plain code blocks with `graphql` language identifier for query examples.
 
-Do not mix patterns across page types (e.g., do not use `<details>` on a Document Service page, or plain code blocks where `<ApiCall>` is expected).
+Do not mix patterns across page types: use `<Endpoint>` for all new, REST, and Document Service reference endpoints. The legacy `<ApiCall>`/`<Request>`/`<Response>` trio is an exception that applies ONLY to the not-yet-migrated pages listed below.
+
+Legacy (not-yet-migrated) pages
+- The legacy `<ApiCall>` / `<Request>` / `<Response>` trio (plus the `noSideBySide` prop and the `<details>` block wrapping the `qs.stringify` equivalent) is DEPRECATED for new content. Match it ONLY when patching these specific not-yet-migrated pages:
+  - `docs/cms/api/graphql.md`
+  - `docs/cms/api/graphql/**` (e.g. `graphql/locale.md`)
+  - `docs/cms/api/rest/upload.md`
+  - `docs/cms/api/rest/relations.md`
+  - `docs/cms/features/users-permissions/rest-api.md`
+  - `docs/cms/plugins/graphql.md`
+- Never introduce the `<ApiCall>`/`<Request>`/`<Response>` trio on new, REST, or Document Service reference pages.
+- NOTE: `QsForQueryBody` / `QsForQueryTitle` / `QsIntroFull` are NOT legacy: they are snippet imports still used alongside `<Endpoint>` on migrated REST pages.
 
 Cross‑linking
 - Link to neighboring APIs (Content API, Query Engine), relevant features, and migration notes.

claude-plugins/inki/references/authoring/AGENTS.cms.md

@@ -15,7 +15,7 @@ Frontmatter and structure
 
 Templates
 - CMS authoring templates live in `claude-plugins/inki/references/templates/` (guide, API, configuration, feature, migration, plugin). Start from a template to ensure structure and frontmatter are correct.
-- For a quick overview of available templates (paths and purposes), see `claude-plugins/inki/references/templates/INDEX.md`.
+- For a quick overview of available templates (paths and purposes), see `claude-plugins/inki/references/templates/README.md`.
 
 MDX and code blocks
 - Use MDX Tabs for language variants (JS/TS) under the same example.

claude-plugins/inki/references/authoring/AGENTS.snippets.md

@@ -41,4 +41,4 @@ Quality Checklist (before commit)
 
 Templates
 - When a snippet evolves into a full page, prefer starting from a suitable CMS template:
-- For a compact overview of all templates with paths and purposes, see `claude-plugins/inki/references/templates/INDEX.md`.
+- For a compact overview of all templates with paths and purposes, see `claude-plugins/inki/references/templates/README.md`.

claude-plugins/inki/references/prompts/drafter.md

@@ -203,13 +203,15 @@ If `existing_content` is not already provided:
 If `target.existing_section` is set, locate that section in the fetched content and focus on it. Keep the surrounding context available for reference.
 
 After fetching, analyze the page's **component patterns** before deriving edits:
-- What components wrap code examples? (`<ApiCall>`, `<Tabs>`, plain code blocks?)
-- What snippet imports does the page use? (e.g., `<QsForQueryBody />`)
-- How are Request/Response pairs structured? (side-by-side vs. stacked, with or without titles?)
-- Does the page use `<details>` blocks? If so, are they standalone or nested inside `<ApiCall>`?
+- What components wrap code examples? (`<Endpoint>` for API reference pages; `<Tabs>`; plain code blocks; the legacy `<ApiCall>`/`<Request>`/`<Response>` trio ONLY on not-yet-migrated GraphQL/upload/relations/users-permissions pages?)
+- What snippet imports does the page use? (e.g., `<QsForQueryBody />`, `<QsForQueryTitle />`, `<QsIntroFull />`; these are still current and are used alongside `<Endpoint>` on migrated REST pages.)
+- How are Request/Response pairs structured? On migrated pages they are expressed through `<Endpoint>`'s `codeTabs`/`responses` model; on legacy pages they may still appear as side-by-side or stacked `<Request>`/`<Response>` blocks (with or without titles).
+- Does the page use `<details>` blocks? If so, are they standalone, expressed as a `<details>` slot inside `<Endpoint>`, or nested inside a legacy `<ApiCall>` (for example, the `qs.stringify` block)?
 
 New content must replicate these patterns exactly. Do not introduce component patterns that the page does not already use, unless explicitly instructed otherwise by the user.
 
+**Always use `<Endpoint>` for new API reference content and for any REST or Document Service page** (`kind="http"` for REST, `kind="js"` for Document Service). Never introduce the legacy `<ApiCall>`/`<Request>`/`<Response>` trio on new, REST, or Document Service reference pages.
+
 ### Step 3: Read reference materials
 
 If `template` and/or `guide` paths are provided:
@@ -618,7 +620,7 @@ For Patch mode, metadata is embedded in the output header (File, Section, Edits
 
 16. **Patch: never invent context.** When deriving instructions, only produce edits that are directly supported by the source material. If `target.notes` suggests a change but the source material does not contain the technical details to write it, produce the instruction with a `<!-- TODO -->` placeholder in the content rather than guessing.
 
-17. **Match component patterns exactly.** In Patch mode, study the existing page's MDX component structure before writing. Pay attention to how the page wraps code examples (for instance, `<ApiCall>`, `<Tabs>`, `<details>`), which snippet imports it uses (`<QsForQueryBody />`, etc.), and how Request/Response pairs are structured. Replicate these patterns in new content. Generic Markdown (plain code blocks, standalone `<details>`) should not be used when the page already uses custom components for the same purpose.
+17. **Match component patterns exactly.** In Patch mode, study the existing page's MDX component structure before writing. Pay attention to how the page wraps code examples (for instance, `<Endpoint>`, `<Tabs>`, `<details>`), which snippet imports it uses (`<QsForQueryBody />`, etc.), and how Request/Response pairs are structured. Replicate these patterns in new content. Generic Markdown (plain code blocks, standalone `<details>`) should not be used when the page already uses custom components for the same purpose. **Carve-out for deprecated API markup:** the legacy `<ApiCall>`/`<Request>`/`<Response>` trio (along with `noSideBySide` and the `<details>` `qs.stringify` block) is DEPRECATED. Do NOT replicate it when patching a migrated page or creating new content; use `<Endpoint>` instead. Replicate the trio ONLY when patching one of these specific not-yet-migrated pages: `docs/cms/api/graphql.md`, `docs/cms/api/graphql/**` (e.g. `graphql/locale.md`), `docs/cms/api/rest/upload.md`, `docs/cms/api/rest/relations.md`, `docs/cms/features/users-permissions/rest-api.md`, `docs/cms/plugins/graphql.md`. The `QsForQueryBody` / `QsForQueryTitle` / `QsIntroFull` snippet imports are NOT legacy and remain in use alongside `<Endpoint>` on migrated REST pages.
 
 18. **Preserve structural coherence.** When adding a new section at a given heading level, check whether parallel content at the same level also has explicit headings. If the new section introduces an H2 but existing content of comparable scope sits directly under the H1 without its own H2, wrap the existing content in a matching H2 to maintain symmetry. Similarly, update the H1 title if the page's scope has expanded (e.g., from covering `status` to covering both `status` and `hasPublishedVersion`).