docs: add repo CLAUDE.md contract - #1
Conversation
TorqLens had no Claude Code instruction file. Documents the verified stack (Next.js 16 static export + Capacitor 6, iPhone-only) and the invariants that have already caused shipped bugs: - Anthropic SDK is server-side only; nothing secret behind NEXT_PUBLIC_* since the static bundle ships verbatim to every device. - No same-origin backend fallback (removed in bfa975f) - the native app has no same-origin server. - Backend CORS must permit the Capacitor origin; a missing header fails silently on device while working in a browser (ba61679, and the cause of the App Store 2.1(a) rejection). - scripts/check-cap-env.mjs must not be weakened - it blocks builds with a missing, localhost, or plaintext-http backend URL. - Static export means changes reach users only via a new native release, never via a web deploy. No test runner is configured; verification is lint + typecheck + build plus manual device checks, and the file says so rather than implying a suite exists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9f6d1c4690
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - The client bundle **bakes `NEXT_PUBLIC_API_BASE_URL` at build time** and calls a **remote backend** for identification. | ||
| - **No API keys or secrets exist in the client bundle.** Keep it that way — anything `NEXT_PUBLIC_*` ships to every device in plaintext. | ||
| - `scripts/check-cap-env.mjs` fails `cap:build` early if that URL is missing, points at localhost, or uses plaintext `http` (iOS App Transport Security blocks it). Do not weaken this guard to make a build pass. | ||
| - `.env.production` (or an exported shell/CI var) takes precedence over `.env.local` for production builds. Setting the URL only in `.env.local` is a known way to ship a broken bundle. |
There was a problem hiding this comment.
.env.production build guidance
When a Mac builder follows this instruction and defines the URL only in .env.production, npm run cap:build first invokes the plain Node process scripts/check-cap-env.mjs via package.json; that process does not load Next.js env files, so it sees the URL as missing and exits before next build can load the file. The precedence claim is also reversed for Next.js itself, where .env.local is considered before .env.production. This contract therefore directs release builds into a failure and may misidentify which endpoint is embedded; either require/export the shell variable or make the guard explicitly load the intended env file and document the actual precedence.
Useful? React with 👍 / 👎.
1 participant
TorqLens had no Claude Code instruction file, so sessions had no repo-local contract at all.
Documents the verified stack (Next.js 16 static export + Capacitor 6, iPhone-only) and the invariants that have already caused shipped bugs:
NEXT_PUBLIC_*— the static bundle ships verbatim to every device.bfa975f) — the native app has no same-origin server.ba61679, and the cause of the App Store 2.1(a) rejection).scripts/check-cap-env.mjsmust not be weakened — it blocks builds with a missing, localhost, or plaintext-httpbackend URL.Records that no test runner is configured: verification is
lint+typecheck+buildplus manual device checks, rather than implying a suite exists.Docs-only. No source, config, or native files touched.
🤖 Generated with Claude Code