tuturuuu-ci-docs

Tuturuuu CI Docs

Core Workflow

For CI changes, inspect the existing workflow family before adding a new file. Most workflows use .github/workflows/ci-check.yml as a reusable switchboard and are enabled from tuturuuu.ts.

For docs changes, update the MDX page and apps/docs/docs.json together when adding a new page. A page that is not in docs.json is not discoverable in the docs site.

Consult references/ci-docs-checklist.md for workflow wiring or docs navigation changes. Read references/blue-green-patterns.md when CI/docs work touches Docker web deployment, blue/green watcher behavior, BuildKit, monitoring, or deployment runbooks that used to live in root AGENTS.md.

If the user asks to commit the finished work, route to $tuturuuu-commit and keep docs, CI, and validator changes split only when they are independently revertible.

CI Patterns

• Prefer narrow validation jobs that do not install the full monorepo unless the check needs dependencies.
• Keep plugin and script validators standard-library based when feasible so CI stays fast and stable.
• Add new workflows to tuturuuu.ts so the repo CI switchboard can enable or disable them consistently.
• Use read-only permissions for validation jobs unless a workflow truly writes commits, comments, or artifacts.
• Finite builds needed to validate the authorized change may run; starting a long-lived server requires the runtime task to need it. Deployment authority remains separate.

Documentation Patterns

• Put durable team-facing knowledge in apps/docs.
• Prefer updating an existing page when the topic already fits the docs tree.
• Add new pages to apps/docs/docs.json in the relevant navigation group.
• Document validation commands and known environment requirements next to the workflow they support.
• Keep runbooks operational and specific: paths, commands, failure modes, and expected outputs are more useful than broad prose.

Verification

For CI and docs work:

• Run the changed validator directly.
• Parse changed JSON with python3 -m json.tool.
• Run formatter/linter commands required by the repo for touched files.
• Run git diff --check.
• If root TypeScript config changed, finish with bun check when feasible.