new-docs-page

name	new-docs-page
description	Create a new MDX documentation page for the Eventum docs site - research, plan, write, verify, review.

Input

• Topic of the page, e.g. Kafka input plugin, Secrets, Upgrading from 1.x.
• Optional short description if the topic alone is ambiguous.

Output

• MDX page under ../docs/content/docs/ at a location chosen from the existing section layout.
• Entry in the nearest meta.json so the page shows up in navigation.
• Cross-references to and from related pages where they help.
• Docs site builds green.

Reference

• MDX authoring rules: .claude/rules/docs/mdx.md.
• Sibling pages in the same section - for tone, depth, and section order.

When to use

Any new technical docs page under ../docs/content/docs/.

Not for: blog posts (see .claude/rules/docs/blog.md), hub entries for generators (use the create-generator skill), release changelogs (use the release skill), API reference pages (auto-generated from OpenAPI).

Process

Six steps. Step 2 requires user approval. Step 5 sends work back to step 3 when it finds issues; fixes re-enter step 4 before re-reviewing.

1. Research

Four inputs before writing:

• Location - scan ../docs/content/docs/ and pick the section where the topic fits; propose a file name consistent with siblings.
• Sibling pages in the chosen section - open a few to anchor tone, depth, and section order.
• Feature source - the code or data being documented, typically under eventum/ or eventum/ui/. Skip if the page is a purely conceptual guide with no single source.
• Cross-references - target pages the new page should link to, and existing pages that should link back to it.

2. Plan

Outline: proposed location, section list, parameter table shape (if any), example count and variants, cross-reference targets. Match sibling pages for structure; deviate only with a reason tied to the content.

Present the outline and wait for approval.

3. Write

Create the MDX page following .claude/rules/docs/mdx.md:

• Frontmatter with title, description, and an icon when the section uses them.
• Sections from the plan, using Fumadocs components where they help.
• Parameter table in the five-column convention when documenting config.
• Cross-references to and from related pages.
• End-user language - describe what the user sees and configures, not engine internals.

Add the page to the nearest meta.json - entries omitted from pages are hidden.

4. Verify

cd ../docs && pnpm build

Catches broken MDX, missing nav entries, broken links, and type errors. All green is required to advance.

5. Review

Re-read the page against .claude/rules/docs/mdx.md and sibling pages. Typical gaps: engine jargon in prose, missing parameter rows, stale or contrived examples, orphaned cross-references.

Fix findings, return to step 4, and advance only when the review is clean.

6. Report

Summary to the user:

• Page path and URL: /docs/<location>.
• Cross-references added.
• pnpm build status.

Notes

• Never edit ../docs/content/docs/api/ (auto-generated from OpenAPI) or ../docs/.source/ (auto-generated by fumadocs-mdx).
• Match the quality and depth of sibling pages - consistency across the section matters more than novelty.