AI Writing Workflow

This workflow is for maintaining this documentation repository with Codex while keeping the content consistent, reviewable, and safe to publish.

Goal

Use Codex to accelerate writing and cleanup, not to bypass ownership of technical accuracy. The repository should remain easy for a human maintainer to review page by page.

Recommended Workflow

1. Classify The Page First

Before writing anything, decide whether the page belongs in public or internal.

• Put reader-facing setup, usage, and stable concepts in public
• Put architecture, maintenance process, and team-only notes in internal

If the content mixes both, split it into two pages instead of weakening the boundary.

2. Read Before Editing

When using Codex, start by reading:

• the target page
• related pages in the same section
• docs/.vitepress/config.ts

That avoids duplicate pages, broken navigation, and inconsistent naming.

3. Prefer Small, Directed Changes

Ask Codex to make specific updates:

• add a page
• tighten wording
• reorganize a section
• update steps after a workflow change

Avoid broad prompts that rewrite many pages without a clear review goal.

4. Keep Markdown Predictable

Ask Codex to keep the structure simple:

• one clear page purpose
• short sections with direct headings
• bullets for procedures and boundaries
• links to existing pages instead of repeated text

This makes future edits cheaper and reduces drift between pages.

5. Verify Locally

After Codex changes docs:

pnpm docs:dev
pnpm docs:build

Check that:

• links resolve
• sidebar entries still match the actual pages
• the page is placed in the correct public or internal section
• no internal detail leaked into public pages

What Codex Should Handle Well

Codex is useful for:

• drafting first-pass documentation from an agreed implementation
• normalizing tone and terminology
• splitting one long page into smaller pages
• keeping navigation and page links in sync
• updating setup steps after small repository changes

What Requires Human Confirmation

Do not rely on Codex alone for:

• secrets, credentials, or internal URLs
• unannounced product decisions
• security policy details
• architecture claims that have not been verified in code or operations
• internal process changes that were discussed but not approved

If the source of truth is unclear, verify it first and then update the docs.

Repository Conventions For Ongoing Maintenance

• Keep filenames stable and descriptive
• Update navigation when adding new pages
• Prefer editing existing pages over creating near-duplicates
• Move content across public and internal only when the audience has clearly changed
• Keep README aligned with the actual commands and deployment flow

The best long-term result is a small set of dependable pages that Codex can maintain incrementally.