docs: clarify local readiness checks

[alramalho]

Summary

• Replaces PR fix: unblock local development readiness #26's broad code/test/lint changes with a docs-only correction to the stale local setup section.
• Explains that the app/build path works locally, while the reported failures are separate lint/test/e2e readiness checks.
• Leaves code unchanged because I did not reproduce a local app-startup blocker.

What originated the previous PR?

The trigger was not that the app could not run locally. A clean checkout can install and pnpm build successfully. The previous dev run also exercised local Supabase/backend/frontend startup successfully. The errors that led to PR #26 were secondary readiness checks: frontend ESLint exits non-zero with 7 errors, backend ESLint has no config, backend test:ci is a watch-style/integration-sensitive command, and e2e tests are outside the pnpm workspace. Those are CI/tooling hygiene problems, not proof that local startup is broken.

Why did the dev profile think changes were needed?

The dev profile treated all non-green verification commands as "local development readiness blockers". That was too broad: it mixed app startup readiness with optional CI hygiene and worker-environment constraints. This replacement keeps the useful part: the README's old frontend/backend yarn/Python instructions were stale and should point developers at the actual pnpm/Turbo monorepo commands.

Necessary vs optional

Necessary here: update stale README setup docs and explicitly separate app startup from lint/test/e2e checks. Optional follow-up, intentionally not included here: make frontend/backend lint green, convert backend CI tests to non-watch/credential-gated form, and add e2e-tests to the pnpm workspace. Those should be separate, clearly scoped PRs if desired.

Verification

• pnpm install --frozen-lockfile — passes.
• pnpm build — passes; frontend emits existing warnings about TanStack route exports, Prisma type re-exports, bundle size/precache.
• pnpm --filter frontend-vite lint — fails on current main with 228 problems (7 errors, 221 warnings); this PR documents it as CI hygiene and does not change code.
• pnpm --filter backend-node lint — fails on current main because ESLint cannot find a backend config; this PR documents it as CI hygiene and does not add config.
• pnpm --filter e2e-tests exec playwright test --list — reports no matching pnpm workspace project on current main; this PR documents it as CI hygiene and does not change workspace membership.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
tracking-software-vite	Ready	Preview, Comment	Jun 12, 2026 1:40pm

[alramalho]

Code Review Summary

Verdict: Changes requested — the PR is docs-only and correctly reframes lint/test/e2e failures as CI/readiness hygiene rather than proof that local app startup is broken. One setup instruction is still misleading and should be corrected before accepting.

Required doc edit

• README.md:70 — The new README says backend health should be at http://localhost:3000/health, but the same setup section tells developers to copy apps/backend-node/.env.example, whose PORT=8000. Since backend-node dev loads .env, a developer following these docs would expect the backend on port 8000, not 3000. Please make the README explicit, e.g. "Backend health should be available at http://localhost:${PORT:-3000}/health; if you copied the example env unchanged, use http://localhost:8000/health" or otherwise align the documented port with the env example.

Looks good

• Diff is minimal/docs-only: README.md only, 30 additions / 31 deletions.
• The stale frontend/backend yarn/Python instructions are replaced with the actual pnpm/Turbo monorepo paths and package scripts.
• The new "Readiness checks vs. app startup" section preserves the important distinction that build/startup can work locally while lint/test/e2e cleanup remains separate CI hygiene.

Note: GitHub would not allow a formal "request changes" review because this PR belongs to the same account, so I am recording the requested change as a PR comment instead. No merge performed.

[alramalho]

Follow-up review

Reviewed the latest PR #27 diff at e56ccf5d5f1de5b0e65e2ec626673a4533be3d10 against main. The PR is still README-only/minimal, and the prior health-check port issue is fixed: the README now points backend health to http://localhost:8000/health, matching apps/backend-node/.env.example (PORT=8000) while noting that a custom apps/backend-node/.env port can override it.

The explanation-first framing is preserved: local app startup is separated from lint/test/e2e CI/readiness hygiene.

Verdict: acceptable. I recommend unblocking/completing t_368c0c11 for PR #27.

[alramalho]

Vercel failure investigation

I checked the GitHub/Vercel status for the current PR head e56ccf5d5f1de5b0e65e2ec626673a4533be3d10:

• gh pr checks 27 reports only the Vercel context failing. GitGuardian and Vercel Preview Comments are green.
• The failing Vercel status description is: Deployment has failed — run this Vercel CLI command: npx vercel inspect dpl_5d4WzbmNsvQCY1ofWUyroB6jX53x --logs.
• Attempting that command locally is blocked by Vercel auth: No existing credentials found. Please run vercel login or pass --token.
• The public Vercel deployment page also redirects/SSR-fails without auth (The request is missing an authentication token), so I cannot inspect the actual Vercel build log from here.

Local reproduction notes:

• The current GitHub compare is no longer README-only because main has moved/re-written since this PR was opened; GitHub now shows this branch as diverged (ahead_by: 25, behind_by: 92). The two intentional PR commits are still docs-only (docs: clarify local readiness checks and docs: align backend health check port), but the branch should be updated/rebased before merge to restore a clean README-only diff.
• A frontend production build fails immediately after a fresh pnpm install --frozen-lockfile because Prisma generated files are absent (Cannot find module './generated/prisma', missing exported Prisma types). Running pnpm db:generate first makes CI=1 pnpm --filter frontend-vite run build pass locally on both current main and PR docs: clarify local readiness checks #27 head.

Verdict: I do not have enough authenticated Vercel evidence to prove the exact remote failure, but the failure is not plausibly caused by the README-only docs commits themselves. The actionable next step is to inspect the private Vercel log with:

npx vercel inspect dpl_5d4WzbmNsvQCY1ofWUyroB6jX53x --logs

using an account/token with access to alramalhos-projects/tracking-software-vite. If that log shows the same missing Prisma generated client error, the smallest repo fix is to make the Vercel frontend build run Prisma generation before tsc/Vite, then update/rebase PR #27 onto current main.

[alramalho]

Follow-up on the Vercel failure:

• Authenticated Vercel logs for the previous deployment (dpl_5d4WzbmNsvQCY1ofWUyroB6jX53x) showed the build itself completed successfully (Tasks: 3 successful, 3 total) and frontend-vite wrote files under dist/....
• The final failure was Vercel looking for a root dist output directory: Error: No Output Directory named "dist" found after the Build completed.
• That is a monorepo Vercel output-directory mismatch, not something caused by the README-only docs changes in this PR.

I pushed the smallest repo-side fix in 1be877986dd8026ee4fb1846eb50426ca2aaacd8: add root vercel.json with outputDirectory: "apps/frontend-vite/dist" and copy the existing frontend rewrites so Vercel reads them from the repo root.

Local verification:

• pnpm db:generate passed.
• CI=1 pnpm --filter frontend-vite run build passed.
• apps/frontend-vite/dist exists after build.
• vercel.json parses as valid JSON.

New Vercel deployment: https://vercel.com/alramalhos-projects/tracking-software-vite/82WxQy1HzrzGnAnQXW4ersAYNxmh

At the time of this comment GitHub still reports Vercel as pending/initializing, while GitGuardian and Vercel Preview Comments pass. If it stays stuck, the next action is to rerun/check that Vercel deployment in the Vercel dashboard; there is no longer evidence of the prior missing-output-directory error on the new deployment.

[alramalho]

Follow-up Vercel investigation result:

• Previous failing deployment dpl_82WxQy1HzrzGnAnQXW4ersAYNxmh still showed the repo-root vercel.json workaround as a Vercel build with no framework output.
• vercel projects inspect tracking-software-vite shows the Vercel project root directory is apps/frontend-vite, framework preset is Vite, and the project-level Output Directory was unset.
• I replaced the root-level workaround with the minimal app-root config: apps/frontend-vite/vercel.json now sets "outputDirectory": "dist" alongside the existing rewrites.
• Local verification passed: python3 -m json.tool apps/frontend-vite/vercel.json, pnpm db:generate, and CI=1 pnpm --filter frontend-vite run build.
• Pushed commit 097268e95a5bf15bd9034989faaf89b3924dcdfc; new Vercel deployment dpl_8UMdASihvQu5swCBkMtg5rHzeHbi is READY and GitHub now reports Vercel success.

Verdict: the failure was a Vercel monorepo output-directory config issue, not caused by the README-only docs change. Remaining non-Vercel caveat: GitHub still reports the PR merge state as DIRTY because the branch is behind/diverged from current main; resolve that separately before merge if required.

[alramalho]

Merge-readiness update from review pass:

• Vercel config fix looks correct for the current Vercel project root (apps/frontend-vite): apps/frontend-vite/vercel.json now sets "outputDirectory": "dist"; the temporary repo-root vercel.json was removed, so the config scope stays within the app root.
• Current head 097268e95a5bf15bd9034989faaf89b3924dcdfc has passing GitHub/Vercel signals: Vercel commit status is success (Deployment has completed), GitGuardian is success, and Vercel Preview Comments is success.
• GitHub still reports the PR as CONFLICTING / DIRTY. I attempted a local git merge origin/main to see whether this was mechanical, but it produced broad non-trivial conflicts across backend routes/services and frontend coach/message/plan files, not just the Vercel config.

Recommendation: do not resolve this as part of the Vercel config fix. The config change itself is ready; merge-readiness is blocked on a separate branch-divergence/conflict cleanup decision.