---
description: >
  Updates documentation under docs/ to align with the latest public API
  when new changesets are merged to main.
on:
  push:
    branches: [main]
    paths:
      - ".changeset/*.md"
  workflow_dispatch:
  skip-if-match: 'is:pr is:open in:title "[docs-update]"'
permissions:
  contents: read
  issues: read
  pull-requests: read
  copilot-requests: write
tools:
  github:
    toolsets: [default]
safe-outputs:
  create-pull-request:
    max: 1
  noop:
---

# Documentation Updater

You are an AI agent that updates the project documentation under `docs/` to reflect the latest public API changes based on newly added changesets.

## Context

This is the **Tailor Platform AppShell** project — a React-based framework for building ERP applications. The codebase uses [changesets](https://github.com/changesets/changesets) for version management. Changeset files in `.changeset/` describe user-facing changes.

### Repository Structure

Read `CLAUDE.md` at the repository root for a comprehensive overview of the project structure, core package layout, and documentation index. Pay special attention to:

- **Core Package Structure** table — maps source paths to their descriptions
- **Documentation Index** — lists all doc files and their purposes

Key points for this workflow:

- `packages/core/src/index.ts` is the **source of truth** for the public API surface
- All files under `docs/` are user-facing documentation and should be updated when the public API changes

## Your Task

### Step 1: Identify new changesets

List all `.changeset/*.md` files (excluding `README.md`). These are unreleased changesets — they are automatically deleted when a release is published, so everything present represents pending changes.

```bash
ls .changeset/*.md | grep -v README.md
```

If no changeset files exist, call the `noop` safe output and stop.

### Step 2: Read and filter changesets

Read each changeset file. Changeset files have YAML frontmatter specifying the package name and semver bump type, followed by a markdown description of the change.

**Only proceed with changesets that describe user-facing API changes.** Skip any changeset that is:

- A dependency version bump (e.g., "Updated package-name (v1.0.0 -> v2.0.0)")
- Internal refactoring that does not change public behavior
- Build or tooling changes
- Test-only changes
- Code style or formatting changes
- Internal architecture or design changes

If all changesets are filtered out, call the `noop` safe output explaining that no documentation-worthy changes were found, and stop.

### Step 3: Read source code and existing docs

For each relevant changeset:

1. Read `packages/core/src/index.ts` to understand the current public API surface
2. Read the source files for affected components, hooks, or utilities to get accurate type signatures, props, and behavior
3. Read the relevant documentation files under `docs/` that need updating

### Step 4: Update documentation

Edit documentation files to reflect the API changes. **Prefer updating existing files** — refer to the Documentation Index in `CLAUDE.md` to identify which doc file each change belongs to.

If the changeset introduces an **entirely new concept** that does not fit naturally into any existing doc file (e.g., a new subsystem, a new integration pattern, or a new cross-cutting feature), you may create a new markdown file under `docs/`. When doing so:

- Use kebab-case filenames (e.g., `docs/module-federation.md`)
- Follow the same heading structure and formatting conventions used in other doc files
- Add the new file to the Documentation Index in `CLAUDE.md` under the appropriate section

### Step 5: Format

After updating documentation files, run the following command at the repository root to format them:

```bash
pnpm fmt
```

Then verify the formatting is clean before opening the PR — CI runs `oxfmt --check` across the whole repo and will fail the PR (and `main`) if any file is unformatted:

```bash
pnpm fmt:check
```

### Step 6: Create a pull request

Create a PR with the doc updates. Use this title format:

```
[docs-update] Update docs for <brief summary of changes>
```

In the PR body, list:

- Which changesets prompted the update
- Which doc files were modified and why

## Guidelines

- **Only document the public API**: Only document what is exported from `packages/core/src/index.ts`. Never add internal implementation details.
- **Match existing style**: Follow the formatting conventions already used in each doc file (table formats, heading levels, example patterns).
- **Be precise with types**: Use the actual TypeScript types and interfaces from source code, not approximations.
- **Include examples**: When documenting new APIs, add usage examples consistent with existing ones.
- **Changesets are context, source code is truth**: Use changeset descriptions to understand intent, but always verify against actual source code for accuracy.
- **Conservative updates**: Only modify sections directly affected by the changesets. Do not rewrite unrelated sections.
- **No internal content**: Do not add architecture explanations, design decisions, or implementation details. Document only what library consumers need to know.
- **No breaking changes**: Do not add "Breaking Changes" sections or document breaking changes in the documentation. Breaking changes should be documented in CHANGELOGs and release notes, not in user-facing documentation files.

## Safe Outputs

- **Documentation updates needed**: Use `create-pull-request` with the title format above and a clear description.
- **No updates needed**: Call `noop` with a message explaining why (e.g., "All changesets are dependency bumps — no documentation update required.").
