feat: bootstrap initial Convex backend

[BASIC-BIT]

Summary

• initialize a repo-root Convex backend with an explicit empty schema and a minimal health:status query
• add isolated local bootstrap scripts plus committed Convex codegen so backend setup works without colliding with other local Convex projects
• extend docs and baseline checks to cover the backend bootstrap and update the web placeholder copy to reflect the new stack state

Closes #54

[greptile-apps]

Greptile Summary

This PR bootstraps the initial Convex backend for VRDex: an explicit empty schema, a health:status query, committed generated types, an isolated local dev wrapper script, an extended CI pipeline (backend typecheck + local verification + drift detection), and thorough documentation updates. All eight issues raised in the previous review round have been fully resolved.

Key changes:

• convex/schema.ts, convex/health.ts, convex.json, and convex/tsconfig.json establish the minimal backend foothold
• scripts/run-convex-local.mjs isolates Convex state under .convex-home/ and .convex-tmp/ to avoid collisions with other local Convex projects; HOME, USERPROFILE, XDG, and TMPDIR overrides are all correctly scoped and documented
• pnpm verify:backend:local now includes --local so CI never falls back to cloud auth; pnpm bootstrap:backend:local delegates to it; CONVEX_AGENT_MODE: "anonymous" is retained as an explicit belt-and-suspenders fallback with a comment explaining its intent
• CI adds typecheck-backend (runs tsc --noEmit) and verify-backend-local (runs convex dev --local --once then git diff --exit-code -- convex/_generated); build-web is gated on both new jobs and all pre-existing checks
• All CI jobs now have timeout-minutes to prevent indefinite hangs
• Two minor style observations: the ?? 1 fallback in the exit handler is unreachable per Node.js contract, and run:backend:health:local is a third alias that delegates identically to verify:backend:local (alongside bootstrap:backend:local)

Confidence Score: 4/5

• Safe to merge — all previous review issues resolved, no logic or security bugs identified in the new code.
• The implementation is clean and well-structured. All eight issues from the prior review round are addressed. The two remaining observations are style-level: an unreachable ?? 1 fallback in the exit handler and a third alias (run:backend:health:local) that duplicates verify:backend:local and bootstrap:backend:local. Neither is a blocking concern. Score is 4 rather than 5 only because the CONVEX_AGENT_MODE: "anonymous" env var is not an officially documented Convex CLI variable (retained intentionally as a fallback), and the three-alias pattern for one operation adds minor cognitive overhead for new contributors.
• No files require special attention — scripts/run-convex-local.mjs and package.json have the minor style observations noted above but are not blocking.

Important Files Changed

Filename	Overview
scripts/run-convex-local.mjs	New isolation wrapper for the Convex CLI — creates .convex-home/ and .convex-tmp/ directories, redirects HOME/XDG/TMPDIR env vars, and forwards POSIX signals correctly. No logic errors; the code ?? 1 fallback in the exit handler is dead code per Node.js docs (code is always non-null when signal is null) but harmless.
.github/workflows/baseline-checks.yml	Added typecheck-backend and verify-backend-local jobs, gated build-web on all four jobs, and added timeout-minutes to every job — all previously flagged gaps are closed. The generated-file drift check (git diff --exit-code -- convex/_generated) is correctly placed after the verification step.
package.json	Backend scripts added correctly: bootstrap:backend:local and run:backend:health:local both delegate to verify:backend:local (which now includes --local), typecheck:backend added, and verify extended to cover the full backend gate. Three aliases ultimately running the same command may be mildly confusing but is documented.
convex/health.ts	Minimal public health query returning a static object — clean and correct. Handler omitting the unused ctx parameter is valid TypeScript.
convex/schema.ts	Intentionally empty schema definition — provides a typed baseline for future table additions without premature domain decisions.
convex/tsconfig.json	Standard Convex-recommended TypeScript config with strict: true, moduleResolution: "Bundler", and _generated/ excluded as root files. TypeScript still resolves _generated/ imports from health.ts correctly despite the exclusion.
convex/_generated/api.d.ts	Auto-generated Convex API types — correctly reflects the single health module. Committed intentionally; drift detection guards this in CI.
convex.json	Minimal Convex project config pinning Node 22 to match the repo baseline. $schema path is relative to node_modules/ so it validates correctly once dependencies are installed.

Sequence Diagram

sequenceDiagram
    participant Dev as Developer / CI
    participant Script as run-convex-local.mjs
    participant CLI as convex CLI (local)
    participant Backend as Local Convex Backend
    participant Git as git diff

    Dev->>Script: node scripts/run-convex-local.mjs dev --local --once --run health:status --tail-logs disable
    Script->>Script: mkdirSync(.convex-home, .convex-tmp)
    Script->>CLI: spawn(convexBin, args, { HOME=.convex-home, XDG_*=..., TMPDIR=.convex-tmp })
    CLI->>Backend: Start local backend runtime
    Backend-->>CLI: Backend ready
    CLI->>CLI: Push functions & regenerate convex/_generated/
    CLI->>Backend: Run health:status query
    Backend-->>CLI: { status: "ok", backend: "convex", ... }
    CLI-->>Script: exit 0
    Script-->>Dev: exit 0
    Dev->>Git: git diff --exit-code -- convex/_generated
    Git-->>Dev: (empty diff = pass)

Loading

Comments Outside Diff (1)

1. package.json, line 11 (link)

   run:backend:health:local is a third alias for verify:backend:local

   bootstrap:backend:local, run:backend:health:local, and verify:backend:local now all resolve to the exact same shell command (after the previous thread's fix made bootstrap delegate to verify). Adding a brief inline comment — or consolidating into two aliases at most — would help contributors understand the intent without digging into the docs:

   Alternatively, consider whether the run:backend:health:local alias adds enough discoverability to justify a third name for the same operation.

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

Prompt To Fix All With AI

This is a comment left during a code review.
Path: scripts/run-convex-local.mjs
Line: 1335

Comment:
**Dead-code fallback in exit handler**

Per the Node.js docs, exactly one of `code` or `signal` is always non-null on the `exit` event. Because the `if (signal)` branch above always `return`s before reaching this line, execution here only arrives when `signal` is falsy — meaning `code` is guaranteed to be a non-null number at this point. The `?? 1` fallback can therefore never activate.

This is harmless, but the fallback silently communicates an assumption (that `code` could be `null` here) that is contrary to the Node.js contract, which may mislead future readers.

```suggestion
  process.exit(code);
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: package.json
Line: 11

Comment:
**`run:backend:health:local` is a third alias for `verify:backend:local`**

`bootstrap:backend:local`, `run:backend:health:local`, and `verify:backend:local` now all resolve to the exact same shell command (after the previous thread's fix made `bootstrap` delegate to `verify`). Adding a brief inline comment — or consolidating into two aliases at most — would help contributors understand the intent without digging into the docs:

```suggestion
    "run:backend:health:local": "pnpm verify:backend:local", // one-shot health check alias for local dev
```

Alternatively, consider whether the `run:backend:health:local` alias adds enough discoverability to justify a third name for the same operation.

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: 18d9c65}

[BASIC-BIT]

Addressed the latest Greptile summary follow-ups in 09a7f81:

• added timeout-minutes: 10 to typecheck-backend
• normalized the Windows shim path to convex.cmd in scripts/run-convex-local.mjs