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

[alexdukeinvertase]

Context

Follow-up to #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/:

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:

.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

[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.:

   {
     "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:

   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 Support for Generated Navigation #398 — original request and input format discussion

---

Input / output contract

Generator input (api-sidebar.json)

Minimum shape (from #398):

{
  "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:

{
  "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 Support for Generated Navigation #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 (Support for Generated Navigation #398 platform approach)
• Generating MDX pages themselves — skill only merges nav; generator still owns content
• OpenAPI/Swagger playground or Try It UI

---

Related

• Support for Generated Navigation #398 — original request for generated navigation support