Contributing

Read AGENTS.md and system.md before changing the application. The installed @fixportal/design standard is binding for interface work.

Work safely

Never develop in the primary checkout. Create a branch from fresh origin/main in an isolated worktree. Keep unrelated user changes out of your diff and use Conventional Commits.

Reuse the existing seams

• REST shapes come from the backend-owned OpenAPI snapshot.
• UI code consumes src/api/types.ts, not generated modules directly.
• Server state uses React Query; small client preferences use Zustand.
• Reuse design-system and repository components before adding another abstraction.
• Keep customer-site assets and copy isolated through the existing site build.

Content

Docs and blog entries live under content/ and are compiled as MDX. Frontmatter must match the CMS schema. Bodies may use Callout, Detail, Figure, and Image. Blog bodies start at h2 because the page supplies the h1.

Run the content schema guard and a production build after MDX changes. Content is executable build input.

Quality gate

Before pushing:

npx tsc -b --noEmit

npx eslint .

npx vitest run

npx vite build

Run the relevant Playwright, visual, Lighthouse, or mutation lane when the change touches those risks. Scheduled workflows supplement the local gate; they do not replace it.

Pull requests

Push once when the branch is complete and green. The committed review policy determines the reviewer tier. Dependency PRs are gated by CI and advisory data rather than consuming AI review capacity. Product changes need concise evidence: what changed, which risks were exercised, and the commands that passed.

Updated 2026-09-08 · Edit on GitHub