docs(build): define canonical build contract across scripts and CI

[shazzar00ni]

Motivation

• Establish a single, unambiguous build contract so contributors and CI run the same exact steps before producing a production bundle.
• Ensure TypeScript type-checking always runs before emitting a Vite production bundle to avoid shipping type errors.
• Provide a single verification command for pre-commit and CI to reduce developer friction and accidental mismatches between local and CI behavior.

Description

• Updated package.json scripts so npm run build runs npm run typecheck && vite build, added npm run build:bundle for bundle-only local diagnostics, and added npm run ci:verify to run lint + tests + canonical build.
• Aligned GitHub Actions CI (.github/workflows/ci.yml) to run the same stages (npm run lint, npm run test:run, npm run typecheck, and npm run build) and adjusted job ordering to reflect the contract.
• Added a clear Build Contract section to docs/DEVELOPMENT.md and updated README.md, docs/README.md, and AGENTS.md to document the canonical commands and verification flow (npm run build and npm run ci:verify).
• Replaced pre-commit guidance with the unified verification command in documentation to make the expected local workflow explicit (npm run ci:verify).

Testing

• Ran the full verification locally with npm run ci:verify and the command completed successfully.
• vitest run executed and reported all tests passing (13 files, 86 tests), indicating unit tests succeeded.
• tsc --noEmit (typecheck) completed without errors, indicating TypeScript validation passed.
• vite build produced a production dist/ output successfully (build completed), so the canonical build contract executed end-to-end.

---

Codex Task

[strix-security]

Strix is installed on this repository, but we could not run this PR security review because this workspace does not have an active plan. If you'd like to continue receiving code reviews, you can add a payment method or manage billing here.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docugen	Canceled		May 14, 2026 5:42am

[coderabbitai]

Warning

Rate limit exceeded

@shazzar00ni has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 48 minutes and 32 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 860f5726-7a86-4788-a461-948e64935ce8

📥 Commits

Reviewing files that changed from the base of the PR and between 2d442a9 and 54d1b04.

📒 Files selected for processing (6)

• .github/workflows/ci.yml
• AGENTS.md
• README.md
• docs/DEVELOPMENT.md
• docs/README.md
• package.json

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/document-and-implement-build-policy

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

• .github/workflows/ci.yml

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 0 complexity · 0 duplication

Metric	Results
Complexity	0
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[greptile-apps]

Greptile Summary

This PR establishes a canonical build contract for DocuGen: npm run build now always runs TypeScript type-checking before emitting the Vite production bundle, npm run ci:verify is introduced as a single command covering lint + tests + build, and all documentation and CI jobs are aligned to this contract.

• package.json gains build:bundle (bare Vite build for local diagnostics) and ci:verify; build is updated to npm run typecheck && vite build.
• The CI workflow is cleaned up (duplicate permissions block and a malformed Super-Linter step removed), jobs are reordered, and the build job is renamed to Build Contract.
• docs/DEVELOPMENT.md, README.md, docs/README.md, and AGENTS.md are updated to document the new commands and replace the old per-step pre-commit guidance with npm run ci:verify.

Confidence Score: 4/5

Safe to merge; both findings are minor CI efficiency and documentation observations with no functional regressions.

The script and CI changes are correct and the cleanup of the duplicate permissions block and malformed Super-Linter step is a clear improvement. The build CI job now re-runs TypeScript type-checking (via npm run build) after the dedicated typecheck job already ran, doubling that check on every push. The README wording suggesting ci:verify should be run "in CI" slightly misrepresents how the workflow actually operates (separate parallel jobs, not a single composite command).

.github/workflows/ci.yml — the build job embeds a second typecheck pass via npm run build. README.md — wording around ci:verify and CI usage.

Important Files Changed

Filename	Overview
package.json	Adds build:bundle (bare vite build) and ci:verify (lint + test:run + build); changes build to run typecheck && vite build. Script definitions are correct and internally consistent.
.github/workflows/ci.yml	Cleans up duplicate permissions block and a malformed Super-Linter step; reorders jobs. The build job runs npm run build which now internally re-runs typecheck, doubling that check on every CI run.
docs/DEVELOPMENT.md	Adds a new Build Contract section documenting canonical commands and updates pre-commit guidance to use npm run ci:verify. Content is accurate and internally consistent.
README.md	Adds a Verification Contract section promoting ci:verify; slightly misleading claim that ci:verify should be run "in CI" when the workflow actually uses separate jobs.
AGENTS.md	Updates two lines: build description and pre-commit guidance. Both changes are accurate and aligned with the new build contract.
docs/README.md	Appends a short Build Contract blurb. Accurate summary of the commands.

Comments Outside Diff (1)

1. .github/workflows/ci.yml, line 49-61 (link)

   Redundant typecheck in build CI job

   The build job runs npm run build, which now resolves to npm run typecheck && vite build. Because the job also declares needs: [lint, test, typecheck], TypeScript type-checking effectively runs twice per CI invocation — once in the dedicated typecheck job and again inside npm run build. This doubles the cost of type-checking on every push without any additional correctness guarantee.

_{Reviews (1): Last reviewed commit: "docs(build): define canonical build cont..." | Re-trigger Greptile}

[greptile-apps]

ci:verify is not what actually runs in the CI pipeline

The README says to use npm run ci:verify "in CI", but the CI workflow (ci.yml) runs each stage as a separate parallel job — lint, test, typecheck, and build — not through ci:verify. A contributor reading this could reasonably believe the GitHub Actions workflow uses ci:verify as its entry point, when it does not. Consider rephrasing to "run locally before pushing" or "to replicate the CI checks locally" to avoid the ambiguity.