feat(ci): add docs automation workflow with Claude Code

[aymeric-giraudet]

Summary

This PR introduces an automated documentation workflow that keeps algolia/docs-new in sync with InstantSearch releases using the Claude Code CLI.

A sample PR generated by this workflow can be found here : https://github.com/algolia/docs-new/pull/507

How it works

Push to master with "chore: release" commit message
    ↓
GitHub Action triggers
    ↓
Checkout instantsearch (for source reference)
Clone docs-new (for documentation updates)
    ↓
Run Claude Code CLI:
  - Read changelogs from instantsearch.js, react-instantsearch, 
    react-instantsearch-core, vue-instantsearch
  - Explore docs-new structure to understand the format
  - Update documentation for changes in the release
  - Run link validation and fix any broken links
  - Write CHANGES_SUMMARY.md with PR title/description
    ↓
Commit changes, push branch, create draft PR in docs-new
  - Reviewer: algolia/frontend-experiences-web

Manual trigger options

The workflow supports workflow_dispatch with these inputs for testing:

Input	Default	Description
run_claude	false	Whether to run Claude Code
create_pr	false	Whether to create PR in docs-new
max_turns	50	Max Claude turns (increase if hitting limit)

Testing modes:

run_claude	create_pr	What happens
false	false	Dry run: Shows what would happen
true	false	Preview: Runs Claude, shows changes, no PR
true	true	Full run: Runs Claude and creates draft PR

Flavor mapping

Each InstantSearch package maps to a documentation file extension:

Package	Flavor	File Extension
instantsearch.js	JavaScript	.js.mdx
react-instantsearch	React	.react.mdx
vue-instantsearch	Vue	.vue.mdx

Required secrets

The following secrets are already configured in the repo:

Secret	Description
ANTHROPIC_API_KEY	Anthropic API key for Claude
DOCS_REPO_PAT	GitHub PAT with repo scope for docs-new access

TODO before enabling on master

• Create a Personal Access Token from the instantsearch-bot account to replace the current PAT
  1. Log in as instantsearch-bot
  2. Go to https://github.com/settings/tokens/new
  3. Note: docs-automation
  4. Expiration: 90 days (or longer)
  5. Scopes: repo (full control), read:org (for team reviewer)
  6. Update the DOCS_REPO_PAT secret with the new token

Key design decisions

1. Claude Code CLI over custom parsing - Claude can read and understand changelogs better than regex-based parsing, making the system more robust to format changes

2. Single PR per release - Instead of one PR per package, we create one consolidated PR that includes all documentation changes for a release

3. Draft PRs with team review - PRs are created as drafts and assigned to frontend-experiences-web for human review before merging

4. Safety limits - 15-minute timeout and configurable max turns prevent runaway executions

---

🤖 Generated with Claude Code

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit d1a72de:

Sandbox	Source
example-instantsearch-getting-started	Configuration
example-react-instantsearch-getting-started	Configuration
example-react-instantsearch-next-app-dir-example	Configuration
example-react-instantsearch-next-routing-example	Configuration
example-vue-instantsearch-getting-started	Configuration

[Haroenv]

looks promising!