Refresh docs with latest Vercel/Supabase guidance and security hardening#6
Merged
jeffgreendesign merged 5 commits intomainfrom Mar 4, 2026
Merged
Conversation
…ance - CLAUDE.md: add DECISIONS.md + TROUBLESHOOTING.md to sync rules, add official references section with Vercel agent-resources links - AGENTS.md: expand documentation map with all docs/* files, add official references section - docs/ENV.md: add POSTGRES_URL vars for migration workflows, add VERCEL_PROJECT_PRODUCTION_URL, add Supabase publishable keys note - docs/RUNBOOK.md: add Supabase CLI migration commands, branching workflow, RLS testing guidance - docs/ARCHITECTURE.md: add Vercel Fluid Compute / use cache / cacheLife / cacheTag patterns, add Supabase branching guidance - docs/DECISIONS.md: add 2026-03-04 decision entry for this refresh - docs/TROUBLESHOOTING.md: add migration drift and Fluid Compute timeout sections - docs/AX_UPGRADE_REPORT.md: full rewrite with fresh inventory All guidance sourced from official docs: - https://vercel.com/docs/agent-resources - https://vercel.com/docs/functions - https://vercel.com/docs/runtime-cache - https://supabase.com/docs/guides/local-development/overview - https://supabase.com/docs/guides/deployment/branching/working-with-branches https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG
- .env.example: add POSTGRES_URL / POSTGRES_URL_NON_POOLING for Supabase branching/migration workflows, add publishable keys comment, add VERCEL_PROJECT_PRODUCTION_URL - CLAUDE.md.template: add verify alias in Quick Reference, add Fluid Compute maxDuration to build breakers, add service-role key leak to silent bugs, add Supabase migration workflow recipe - AGENTS.md.template: add verify alias, add Vercel agent-resources links Official docs: - https://supabase.com/docs/guides/deployment/branching/working-with-branches - https://supabase.com/docs/guides/deployment/database-migrations - https://vercel.com/docs/functions - https://vercel.com/docs/agent-resources https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG
- security-check.sh: add check for SUPABASE_SERVICE_ROLE_KEY usage in client-accessible paths (app/, pages/, components/). The service-role key bypasses RLS and must never be exposed in browser bundles. - .claude/settings.json: add pnpm verify, npm run verify, yarn verify to allow list. Add supabase CLI commands (migration, db, gen types) to allow list for downstream projects. Official docs: - https://supabase.com/docs/guides/api/api-keys - https://vercel.com/docs/environment-variables https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (1)
WalkthroughThis pull request expands and restructures project documentation (ARCHITECTURE.md, RUNBOOK.md, TROUBLESHOOTING.md, AX_UPGRADE_REPORT.md, DECISIONS.md, ENV.md, etc.), adds new docs (DECISIONS.md, TROUBLESHOOTING.md), updates scaffold templates and CLAUDE/AGENTS guidance, and expands scaffold/.claude/settings.json allowlists. It introduces commented example env vars (POSTGRES_URL, POSTGRES_URL_NON_POOLING, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, VERCEL_PROJECT_PRODUCTION_URL) and adds a security-check script (scaffold/scripts/security-check.sh) that detects SUPABASE_SERVICE_ROLE_KEY usage in client-accessible paths and warns. Several verification and migration commands and instructions were standardized across files. Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant Local as Local Env
participant Git as Git/Repo
participant CI as CI (Preview)
participant SB as Supabase (Remote)
Dev->>Local: create migration (supabase migration new)
Dev->>Local: apply locally (supabase migration up)
Local->>Git: commit & push migration + docs
Git->>CI: trigger preview build (uses POSTGRES_URL_NON_POOLING)
CI->>SB: supabase db push / supabase migration up
SB-->>CI: migration applied / status
CI->>Dev: build result / migration status
alt Drift detected
Dev->>Local: supabase db pull
Dev->>Local: supabase db diff --schema public
Dev->>Local: adjust migrations & repeat
end
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (4)
scaffold/AGENTS.md.template (1)
17-17: Use package-manager-neutral gate phrasing in this scaffold template.Line 17 currently assumes
pnpm; template consumers may standardize on npm or yarn.Based on learnings: Applies to scaffold/**/*.md : Non-shell templates (
.md) inscaffold/should use portable phrasing like "npm run gates/pnpm gates/yarn gates" instead of hardcoding a single package manager.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scaffold/AGENTS.md.template` at line 17, Update the hardcoded package-manager phrasing "**Canonical quality gate:** `[pnpm gates]` (alias: `[pnpm verify]`)" to a neutral form showing multiple package managers, e.g. "`npm run gates` / `pnpm gates` / `yarn gates` (alias: `npm run verify` / `pnpm verify` / `yarn verify`)", and apply the same replacement across all scaffold/*.md templates so non-shell markdown files use portable gate phrasing; locate and change the exact string "**Canonical quality gate:** `[pnpm gates]` (alias: `[pnpm verify]`)" in the AGENTS.md.template and analogous occurrences in other scaffold markdown files.scaffold/CLAUDE.md.template (1)
29-29: Make the quality-gate phrasing package-manager portable in the template.Line 29 hardcodes
pnpm, which reduces scaffold portability for npm/yarn projects.♻️ Suggested template tweak
-| **All checks** | **`[pnpm gates]`** (alias: `[pnpm verify]`) | +| **All checks** | **`[npm run gates]` / `[pnpm gates]` / `[yarn gates]`** (alias: `verify`) |Based on learnings: Applies to scaffold/**/*.md : Non-shell templates (
.md) inscaffold/should use portable phrasing like "npm run gates/pnpm gates/yarn gates" instead of hardcoding a single package manager.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scaffold/CLAUDE.md.template` at line 29, The table cell currently hardcodes the package manager as `[pnpm gates]` (the string `| **All checks** | **\`[pnpm gates]\`** (alias: \`[pnpm verify]\`) |`) which reduces portability; update that cell to a package-manager‑agnostic phrasing such as ``[npm run gates] / [pnpm gates] / [yarn gates]`` (or similar) so the template works for npm/yarn/pnpm projects, and apply the same wording convention across scaffold/*.md templates to replace other hardcoded `pnpm` occurrences.docs/ARCHITECTURE.md (1)
32-32: Consider clarifying when service-role key usage is appropriate.While the statement "server routes can use the service-role key for admin operations" is technically correct, it might benefit from additional guidance about when this is appropriate versus using RLS policies with the anon key. The service-role key bypasses RLS and should be used sparingly for genuine admin operations only.
📝 Suggested clarification
-- **Auth boundaries:** Use `@supabase/ssr` for server-side auth in Next.js. Browser clients use the anon key; server routes can use the service-role key for admin operations. +- **Auth boundaries:** Use `@supabase/ssr` for server-side auth in Next.js. Browser clients use the anon key; server routes typically use the anon key with RLS policies, but may use the service-role key for privileged admin operations that must bypass RLS.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/ARCHITECTURE.md` at line 32, Update the "Auth boundaries" bullet (the line referencing `@supabase/ssr`, anon key, and service-role key) to explicitly state when service-role key usage is appropriate: indicate it should be reserved for trusted server-side admin operations that must bypass RLS (e.g., background jobs, maintenance scripts, or privileged system tasks), recommend preferring the anon key plus Row Level Security (RLS) policies for regular server and browser flows, and add a short guidance sentence to audit and minimize service-role key surface area (rotate/stored in secure vaults) so readers know to use service-role sparingly and only for true admin use-cases.docs/TROUBLESHOOTING.md (1)
17-17: Consider generalizing the path restriction guidance.The guidance specifies
src/app/which assumes a particular Next.js App Router structure. Since this is a scaffold template that "targets both" (per line 6 of AX_UPGRADE_REPORT.md), consider making the path example more general or including both App Router and Pages Router patterns.📝 Suggested generalization
-- Confirm service-role key is server-only — never import it in files under `src/app/` or any `"use client"` component. +- Confirm service-role key is server-only — never import it in client-accessible paths (e.g., `app/`, `pages/client/`, or any `"use client"` component).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/TROUBLESHOOTING.md` at line 17, Update the TROUBLESHOOTING guidance that currently calls out "src/app/" to a more general warning about client-side code: state that the service-role key must be server-only and must never be imported into any client-side files or components (e.g., "src/app/" for App Router, "src/pages/" for Pages Router, or any file using "use client"). Replace the specific path-only example with this generalized phrasing so both App Router and Pages Router projects are correctly covered.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ENV.md`:
- Around line 15-16: Update the environment variable table to remove the
inconsistency by aligning the `NEXT_PUBLIC_SUPABASE_ANON_KEY` requirement with
the new guidance about publishable keys: change its "Required" column from "Yes"
to "Optional / recommended for client" (or similar) and add a short
parenthetical note clarifying that publishable anon keys are safe for client
use; keep `SUPABASE_SERVICE_ROLE_KEY` marked as server-only/optional and ensure
the table's description matches the separate section that recommends publishable
keys so both places convey the same guidance.
In `@docs/RUNBOOK.md`:
- Line 42: Update the single-line instruction "Open a PR to create a preview
branch automatically" to explicitly state the required Supabase setup: enable
the GitHub integration in your Supabase project settings, point it to your
repository and the supabase/ directory, and enable "Automatic branching" in the
integration settings; mention that the PR workflow assumes those integration and
automatic-branching steps are already configured so preview branches will be
created automatically.
In `@docs/TROUBLESHOOTING.md`:
- Line 35: Update the sentence about Vercel function timeouts to reflect Fluid
Compute defaults: state that with Fluid Compute enabled (the default on new
projects) the default timeout is 300s for both Hobby and Pro and that the
`export const maxDuration = 60;` syntax applies to Fluid Compute; also add a
brief note about legacy behavior when Fluid Compute is disabled (defaults 10s
Hobby, 15s Pro with maximums of 60s and 300s respectively) so readers can see
both current default and legacy values.
In `@scaffold/.claude/settings.json`:
- Around line 43-44: The allowlist entries "Bash(supabase migration *)" and
"Bash(supabase db *)" are too broad and permit destructive commands (e.g.,
`supabase db reset`, `supabase migration down`); replace them with explicit,
non-destructive subcommand patterns or tighter regexes that only permit safe
read-only operations (for example restrict "supabase migration" to commands like
status, list, show and "supabase db" to commands like list, remote list, info),
ensuring you remove or exclude reset/down/drop verbs; update the two strings in
the settings JSON (the lines containing "Bash(supabase migration *)" and
"Bash(supabase db *)") to the narrower whitelist entries or regex equivalents.
In `@scaffold/scripts/security-check.sh`:
- Around line 121-123: The case pattern mistakenly tests the filepath variable
"$file" for the string literal "use client" (which is in file content), causing
false negatives; change the logic to detect the "use client" directive by
inspecting file contents (e.g., run grep -qE '"use client"' "$file" or use
awk/sed to check the first non-empty line) instead of matching "*\"use
client\"*" against "$file", and update the branch that currently uses case
"$file" in ... to include a content-check branch that treats files containing
the directive as client files (use the existing "$file" and "$line" variables to
locate/scan the file and keep the SUPABASE_SERVICE_ROLE_KEY exclusion behavior
intact).
---
Nitpick comments:
In `@docs/ARCHITECTURE.md`:
- Line 32: Update the "Auth boundaries" bullet (the line referencing
`@supabase/ssr`, anon key, and service-role key) to explicitly state when
service-role key usage is appropriate: indicate it should be reserved for
trusted server-side admin operations that must bypass RLS (e.g., background
jobs, maintenance scripts, or privileged system tasks), recommend preferring the
anon key plus Row Level Security (RLS) policies for regular server and browser
flows, and add a short guidance sentence to audit and minimize service-role key
surface area (rotate/stored in secure vaults) so readers know to use
service-role sparingly and only for true admin use-cases.
In `@docs/TROUBLESHOOTING.md`:
- Line 17: Update the TROUBLESHOOTING guidance that currently calls out
"src/app/" to a more general warning about client-side code: state that the
service-role key must be server-only and must never be imported into any
client-side files or components (e.g., "src/app/" for App Router, "src/pages/"
for Pages Router, or any file using "use client"). Replace the specific
path-only example with this generalized phrasing so both App Router and Pages
Router projects are correctly covered.
In `@scaffold/AGENTS.md.template`:
- Line 17: Update the hardcoded package-manager phrasing "**Canonical quality
gate:** `[pnpm gates]` (alias: `[pnpm verify]`)" to a neutral form showing
multiple package managers, e.g. "`npm run gates` / `pnpm gates` / `yarn gates`
(alias: `npm run verify` / `pnpm verify` / `yarn verify`)", and apply the same
replacement across all scaffold/*.md templates so non-shell markdown files use
portable gate phrasing; locate and change the exact string "**Canonical quality
gate:** `[pnpm gates]` (alias: `[pnpm verify]`)" in the AGENTS.md.template and
analogous occurrences in other scaffold markdown files.
In `@scaffold/CLAUDE.md.template`:
- Line 29: The table cell currently hardcodes the package manager as `[pnpm
gates]` (the string `| **All checks** | **\`[pnpm gates]\`** (alias: \`[pnpm
verify]\`) |`) which reduces portability; update that cell to a
package-manager‑agnostic phrasing such as ``[npm run gates] / [pnpm gates] /
[yarn gates]`` (or similar) so the template works for npm/yarn/pnpm projects,
and apply the same wording convention across scaffold/*.md templates to replace
other hardcoded `pnpm` occurrences.
ℹ️ Review info
Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 67b8b9a1-a30f-47ab-8e63-5a48cc4a8d77
📒 Files selected for processing (13)
AGENTS.mdCLAUDE.mddocs/ARCHITECTURE.mddocs/AX_UPGRADE_REPORT.mddocs/DECISIONS.mddocs/ENV.mddocs/RUNBOOK.mddocs/TROUBLESHOOTING.mdscaffold/.claude/settings.jsonscaffold/.env.examplescaffold/AGENTS.md.templatescaffold/CLAUDE.md.templatescaffold/scripts/security-check.sh
Comment on lines
+43
to
+44
| "Bash(supabase migration *)", | ||
| "Bash(supabase db *)", |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# First, check the file exists and show the relevant section
echo "=== File Content (lines 35-50) ==="
sed -n '35,50p' scaffold/.claude/settings.json
echo -e "\n=== Full permissions.allow array ==="
python3 <<'PY'
import json
with open("scaffold/.claude/settings.json") as f:
cfg = json.load(f)
for item in cfg["permissions"]["allow"]:
print(f" {item}")
PY
echo -e "\n=== Testing Pattern Matching ==="
python3 <<'PY'
import json, fnmatch
with open("scaffold/.claude/settings.json") as f:
cfg = json.load(f)
# Extract all Bash patterns
bash_patterns = [p[5:-1] for p in cfg["permissions"]["allow"] if p.startswith("Bash(") and p.endswith(")")]
print(f"Found {len(bash_patterns)} Bash patterns")
print("\nBash patterns containing 'supabase':")
for p in bash_patterns:
if 'supabase' in p:
print(f" {p}")
# Test dangerous commands
dangerous_commands = [
"supabase db reset --linked",
"supabase db reset",
"supabase migration down --linked",
"supabase migration down",
"supabase db push",
]
print("\n=== Matching dangerous commands against current patterns ===")
for cmd in dangerous_commands:
matched = [pat for pat in bash_patterns if fnmatch.fnmatch(cmd, pat)]
if matched:
print(f"❌ {cmd}")
print(f" Matches: {matched}")
else:
print(f"✓ {cmd} - NOT MATCHED")
# Test suggested patterns
print("\n=== Testing suggested narrower patterns ===")
suggested = [
"supabase migration new *",
"supabase migration list*",
"supabase migration up*",
"supabase db diff*",
"supabase db lint*",
"supabase db pull*",
"supabase db push*",
]
safe_commands = [
"supabase migration new test_migration",
"supabase migration list",
"supabase migration up",
"supabase db diff",
"supabase db lint",
"supabase db pull",
"supabase db push",
]
for cmd in safe_commands:
matched = [pat for pat in suggested if fnmatch.fnmatch(cmd, pat)]
if matched:
print(f"✓ {cmd} - Matches suggested patterns")
else:
print(f"❌ {cmd} - Does NOT match suggested patterns")
print("\n=== Testing dangerous commands against suggested patterns ===")
for cmd in dangerous_commands:
matched = [pat for pat in suggested if fnmatch.fnmatch(cmd, pat)]
if matched:
print(f"❌ {cmd} - STILL MATCHES: {matched}")
else:
print(f"✓ {cmd} - Blocked by suggested patterns")
PYRepository: jeffgreendesign/project-scaffold
Length of output: 2836
Tighten Supabase allowlist patterns to prevent destructive command exposure.
Lines 43-44 currently allow any supabase migration or supabase db command. This enables destructive operations like supabase db reset and supabase migration down when an agent is linked to real environments.
🔒 Suggested narrowing
- "Bash(supabase migration *)",
- "Bash(supabase db *)",
+ "Bash(supabase migration new *)",
+ "Bash(supabase migration list*)",
+ "Bash(supabase migration up*)",
+ "Bash(supabase db diff*)",
+ "Bash(supabase db lint*)",
+ "Bash(supabase db pull*)",
+ "Bash(supabase db push*)",📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| "Bash(supabase migration *)", | |
| "Bash(supabase db *)", | |
| "Bash(supabase migration new *)", | |
| "Bash(supabase migration list*)", | |
| "Bash(supabase migration up*)", | |
| "Bash(supabase db diff*)", | |
| "Bash(supabase db lint*)", | |
| "Bash(supabase db pull*)", | |
| "Bash(supabase db push*)", |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@scaffold/.claude/settings.json` around lines 43 - 44, The allowlist entries
"Bash(supabase migration *)" and "Bash(supabase db *)" are too broad and permit
destructive commands (e.g., `supabase db reset`, `supabase migration down`);
replace them with explicit, non-destructive subcommand patterns or tighter
regexes that only permit safe read-only operations (for example restrict
"supabase migration" to commands like status, list, show and "supabase db" to
commands like list, remote list, info), ensuring you remove or exclude
reset/down/drop verbs; update the two strings in the settings JSON (the lines
containing "Bash(supabase migration *)" and "Bash(supabase db *)") to the
narrower whitelist entries or regex equivalents.
- ENV.md: align anon key requirement with publishable keys guidance - RUNBOOK.md: add Supabase GitHub integration prerequisites for branching - TROUBLESHOOTING.md: correct Fluid Compute timeout defaults (300s since Apr 2025) - TROUBLESHOOTING.md: generalize auth path guidance for App/Pages Router - ARCHITECTURE.md: expand service-role key guidance (prefer anon+RLS) - settings.json: narrow supabase CLI allowlist to non-destructive subcommands - security-check.sh: fix "use client" detection to check file contents - AGENTS.md.template + CLAUDE.md.template: PM-neutral gate phrasing https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
scaffold/CLAUDE.md.template (1)
29-29: Consider usingverifyconsistently once introduced.Line [29] introduces
verifyalias; optionally mirror that naming in other “run before finishing” checklist lines to reduce command drift.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@scaffold/CLAUDE.md.template` at line 29, The checklist introduces a `verify` alias for the gates command but other “run before finishing” checklist lines still spell out `npm run gates` / `pnpm gates` / `yarn gates`; update those entries to consistently reference the `verify` alias (e.g., replace or add `verify` alongside the explicit commands) so the file uses the same shorthand throughout—look for occurrences of the gates commands and the header row currently showing **`[npm run gates]`** / **`[pnpm gates]`** / **`[yarn gates]`** and make them consistently mention `verify`.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/ENV.md`:
- Around line 18-19: The table row for POSTGRES_URL incorrectly labels it as
"Optional (migration workflows)"; update the POSTGRES_URL entry so its usage
column and description match the later guidance: mark it for runtime/pooled
query use (e.g., "Optional (runtime/pooled queries)") and describe it as the
pooled Postgres connection string for ORM/query use, while keeping
POSTGRES_URL_NON_POOLING described as the direct connection used for schema
migrations; update the table row for POSTGRES_URL so the label and description
align with the documented rule for runtime pooled queries.
In `@docs/TROUBLESHOOTING.md`:
- Line 23: Update the ambiguous sentence that reads "If a preview branch has
stale migrations, delete and recreate the branch (`supabase db reset`
equivalent)" to explicitly distinguish local vs hosted operations: state that
`supabase db reset` resets the local development database, and for a stale
hosted preview branch instruct to either link the CLI and run `supabase db reset
--linked` or delete and recreate the preview branch; edit the line containing
that sentence in docs/TROUBLESHOOTING.md to use this clarified wording.
In `@scaffold/CLAUDE.md.template`:
- Line 120: Update the wording that follows the string "Missing `export const
maxDuration = N;` on Vercel function routes..." to reflect that Fluid Compute is
now enabled by default and the timeout defaults are 300s for both Hobby and Pro
plans; explicitly state that the previous values "(10s Hobby / 60s Pro)" only
apply if Fluid Compute is disabled and keep a brief note instructing users to
set `export const maxDuration = N;` when they need a custom timeout.
---
Nitpick comments:
In `@scaffold/CLAUDE.md.template`:
- Line 29: The checklist introduces a `verify` alias for the gates command but
other “run before finishing” checklist lines still spell out `npm run gates` /
`pnpm gates` / `yarn gates`; update those entries to consistently reference the
`verify` alias (e.g., replace or add `verify` alongside the explicit commands)
so the file uses the same shorthand throughout—look for occurrences of the gates
commands and the header row currently showing **`[npm run gates]`** / **`[pnpm
gates]`** / **`[yarn gates]`** and make them consistently mention `verify`.
ℹ️ Review info
Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 1356834f-7435-4ad9-8975-deb38bee8c8f
📒 Files selected for processing (8)
docs/ARCHITECTURE.mddocs/ENV.mddocs/RUNBOOK.mddocs/TROUBLESHOOTING.mdscaffold/.claude/settings.jsonscaffold/AGENTS.md.templatescaffold/CLAUDE.md.templatescaffold/scripts/security-check.sh
🚧 Files skipped from review as they are similar to previous changes (2)
- scaffold/scripts/security-check.sh
- docs/ARCHITECTURE.md
- ENV.md: relabel POSTGRES_URL as runtime/pooled queries (not migrations) - TROUBLESHOOTING.md: distinguish local db reset vs hosted preview branch - CLAUDE.md.template: update Fluid Compute timeout defaults (300s default) - CLAUDE.md.template: consistent verify alias across gates references https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR updates the control-plane documentation and scaffold templates to reflect the latest official Vercel and Supabase guidance, adds missing environment variable patterns for migration workflows, and hardens security checks for Supabase service-role key usage.
Key Changes
Documentation Updates
docs/AX_UPGRADE_REPORT.md: Expanded inventory summary with timestamp, detailed commit-by-commit changelog, and comprehensive official reference links for Vercel agent resources, Fluid Compute, runtime caching, and Supabase branching/migrations.docs/RUNBOOK.md: Added Supabase CLI migration commands, branching workflow guidance, RLS testing procedures, and Vercel system environment variable usage (VERCEL_ENV,VERCEL_PROJECT_PRODUCTION_URL).docs/ARCHITECTURE.md: Added Vercel Fluid Compute patterns (maxDuration),use cachedirectives withcacheLife()andcacheTag(), data cache patterns (time-based and tag-based revalidation), and Supabase branching/RLS guidance.docs/TROUBLESHOOTING.md: Added Supabase migration drift troubleshooting, Vercel Fluid Compute timeout guidance, and improved existing entries with specific command examples.docs/ENV.md: AddedPOSTGRES_URLandPOSTGRES_URL_NON_POOLINGfor migration workflows,VERCEL_PROJECT_PRODUCTION_URLfor canonical URLs, and note on Supabase publishable keys transition.docs/DECISIONS.md: Added 2026-03-04 decision entry documenting this incremental refresh.CLAUDE.mdandAGENTS.md: Added official references sections with Vercel agent resources and Supabase API key links; expanded documentation map.Scaffold Template Updates
scaffold/.env.example: AddedPOSTGRES_URL/POSTGRES_URL_NON_POOLINGvariables with branching workflow link, and Supabase publishable key comment.scaffold/CLAUDE.md.template: Addedverifyalias in Quick Reference, Fluid ComputemaxDurationto common mistakes, and Supabase migration workflow recipe.scaffold/AGENTS.md.template: Addedverifyalias note and official references section with Vercel agent resources links.scaffold/.claude/settings.json: Expanded allow list to includepnpm verify,supabase migration,supabase db, andsupabase gen typescommands.Security Hardening
scaffold/scripts/security-check.sh: Added check forSUPABASE_SERVICE_ROLE_KEYusage in client-accessible paths (files underapp/,pages/,components/, or marked with"use client"), preventing accidental exposure of elevated-privilege keys in browser bundles.Notable Implementation Details
POSTGRES_URL) and direct (POSTGRES_URL_NON_POOLING) connections for different use cases.https://claude.ai/code/session_01SY7eFoYPoWusnqmFPR3UXG