feat: Create an agent skill to sync generated API navigation into docs.json

## Context

Follow-up to invertase/docs.page#398 — we decided not to add runtime `"load"` for external sidebar JSON on the platform. Instead, this is better served as an **optional agent skill** that users can copy into their repo when they auto-generate API reference docs.

The skill closes the loop on: keeping hand-authored nav in `docs.json` while syncing generated API sections without the doc generator owning the full config file.

## Problem

Teams that auto-generate API/reference documentation often have tooling that knows the page hierarchy and can express it as JSON. They still want to manually maintain `docs.json` for site title, top-level nav, and prose sections — but need generated nav to stay in sync on each regen without hand-editing the full file each time.

## Expected outcome

After adopting the skill, a maintainer can:

1. Run their API doc generator (OpenAPI, Typedoc, custom tool, etc.) as they do today
2. Run the skill workflow (agent + script, or script alone in CI) to merge fresh nav into `docs.json`
3. Review the diff, commit, and push — site updates with correct sidebar, no platform changes required

**Before:** generator must rewrite `docs.json`, or maintainer hand-merges hundreds of nav entries.
**After:** generator outputs a small nav JSON file; merge is deterministic and repeatable.

---

## Skill layout

Publish in the [docs.page]() repo under [`skills/sync-api-nav/`]():

```text
skills/sync-api-nav/
SKILL.md # Agent instructions + when to use
merge-sidebar.mjs # Deterministic merge script (Node, no deps)
example/
docs.json # Sample hand-authored config
api-sidebar.json # Sample generator output
docs.json.expected # Expected result after merge (for tests)
```

Users who need it copy the folder into their repo:

```text
.agents/skills/sync-api-nav/
```

Once copied and pushed, the skill is discoverable via MCP as `docs-page://skills/sync-api-nav` on their hosted site (optional — the script also works standalone in CI).

---

## How it works

### Typical workflow

```text
[API generator] → api-sidebar.json
↓
merge-sidebar.mjs (+ config: target group name, paths)
↓
docs.json (updated)
↓
git diff → review → commit → push
```

### Step-by-step (what SKILL.md should instruct)

1. **Generate API docs** — run your existing generator; confirm MDX pages land under `docs/` and nav JSON is written (path configurable, default `docs/api-sidebar.json`).
2. **Configure the merge target** — in `docs.json`, keep a stable sidebar group the skill owns, e.g.:

```json
{
"group": "API Reference",
"pages": []
}
```

Hand-authored groups (`Welcome`, `Guides`, etc.) sit above or below and are never touched.
3. **Run the merge** — invoke the script:

```bash
node .agents/skills/sync-api-nav/merge-sidebar.mjs \
--config docs.json \
--input docs/api-sidebar.json \
--group "API Reference"
```

Or ask an agent with this skill loaded to run the same command after generation.
4. **Review the diff** — check only the target group's `pages` array changed; titles, hrefs, and nested groups match generator output.
5. **Validate** — run `npx @docs.page/cli check` (and preview locally if needed).
6. **Commit and push** — include updated `docs.json` and any new/changed MDX pages from the generator.

### What `merge-sidebar.mjs` should do

* Read `docs.json` and generator nav JSON
* Locate the named sidebar group (by `group` title or a configurable marker)
* Replace **only** that group's `pages` with generated entries
* Preserve everything else byte-for-byte where possible (formatting, unrelated keys, other groups)
* Support nested groups if generator JSON includes them (same shape as `docs.json` sidebar entries)
* Exit non-zero with a clear error if:
* target group not found
* input JSON invalid or empty
* hrefs reference paths with no matching file under `docs/` (warn or `--strict` flag)

### What `SKILL.md` should contain

* **When to use** — auto-generated API/reference docs; regen nav on each release
* **When not to use** — small hand-written sites with no generated sections
* **Prerequisites** — [docs.page]() project with `docs.json`, generator that outputs nav JSON
* **Configuration** — input path, target group name, strict mode
* **CI example** — run merge script after generator in GitHub Actions before commit
* **Link to** invertase/docs.page#398 — original request and input format discussion

---

## Input / output contract

### Generator input (`api-sidebar.json`)

Minimum shape (from invertase/docs.page#398):

```json
{
"pages": [
{ "title": "Foo", "href": "/api/foo" },
{ "title": "Bar", "href": "/api/bar" },
{
"group": "Baz",
"pages": [
{ "title": "Baz overview", "href": "/api/baz" }
]
}
]
}
```

Entries use the same sidebar item shape as `docs.json` (`title`, `href`, `group`, `pages`, `tab`, etc.).

### Merge result (`docs.json`)

Hand-authored top of sidebar preserved; generated section injected:

```json
{
"name": "Example Project",
"sidebar": [
{
"pages": [
{ "title": "Welcome", "href": "/" },
{ "title": "Getting Started", "href": "/getting-started" },
{
"group": "API Reference",
"pages": [
{ "title": "Foo", "href": "/api/foo" },
{ "title": "Bar", "href": "/api/bar" }
]
}
]
}
]
}
```

---

## What to check (acceptance criteria)

### Skill quality

- [ ] `SKILL.md` has frontmatter (`name`, `description`) and runs without docs.page-specific secrets
- [ ] Merge script is deterministic — same inputs always produce same output
- [ ] Example fixtures in `example/` pass a simple test (`node merge-sidebar.mjs` → matches `docs.json.expected`)
- [ ] Works on Windows and Unix paths

### Merge correctness

- [ ] Hand-authored sidebar groups unchanged after merge
- [ ] Target group fully replaced (not appended duplicate entries)
- [ ] Nested groups preserved when generator outputs them
- [ ] Invalid/missing target group fails loudly
- [ ] `--dry-run` flag prints diff without writing (nice to have)

### Integration

- [ ] `npx @docs.page/cli check` passes after merge
- [ ] Local preview shows updated sidebar with correct active states
- [ ] CI snippet documented for post-generator merge + commit

### Docs

- [ ] Linked from agent skills docs (`/ai-agents/agent-skills` or `/features/agent-skills`)
- [ ] Comment on invertase/docs.page#398 with link when published

---

## Why a skill (not a platform feature)

* Keeps `docs.json` explicit at render time — no extra GitHub fetches or cache invalidation
* Fits docs-as-code — generated nav is reviewed in PRs like any other change
* Opt-in — copy only if you generate reference docs
* Pairs with broader API spec generation without new platform config primitives

---

## Out of scope (for this skill)

* Runtime `"load": "..."` in `docs.json` (invertase/docs.page#398 platform approach)
* Generating MDX pages themselves — skill only merges nav; generator still owns content
* OpenAPI/Swagger playground or Try It UI

---

## Related

* invertase/docs.page#398 — original request for generated navigation support

Start with the existing skills/ layout, then create skills/sync-api-nav/SKILL.md and merge-sidebar.mjs using the example docs.json, api-sidebar.json, and docs.json.expected fixtures described in the issue. Run the merge command against the fixtures and npx @docs.page/cli check; done means deterministic replacement of only the named group, preserved hand-authored content, clear failures, and documented CI usage.

Written by the indexing model from the issue text.