Technology

Repository Structure

Integrated System (two portals + shared backend)

These repos share the common Supabase backend (project gmjucacmbrumncfnnhua) and must be considered together:

~/code/sv-portal-2026  # LIVE customer portal (Vite 8 / React 19) — native Google Calendar; cut over Jun 10, 2026
~/code/sv-portal       # v1 portal (Vite 5 / React 18) — DECOMMISSIONED Jun 29, 2026 (frontend retired, repo archived)
~/code/sv-edge         # Supabase Edge Functions (Deno/TypeScript) — shared by both portals
~/code/sv-db           # Database migrations (SQL) — shared by both portals
~/code/sv-docs         # Ops scripts, runbooks, archives (orchestrates all 7 repos)

Cutover executed Jun 10, 2026 (~20:33 ET): portal.mystoragevalet.com now serves the sv-portal-2026 codebase — the Vercel domain was re-pointed per DEC-020, with the founder waiving the remaining checklist items (signup E2E, Manage-Billing verify, $2,000-cap verify; now post-flip tasks). The first live-domain booking was verified end-to-end the same evening: DB custody + audit trail + Google Calendar event. v1 (sv-portal) was decommissioned Jun 29, 2026 (DEC-021): frontend retired, v1-only edge functions + RPCs + views removed, repo archived. Ops now lives in the v2 portal’s staff /ops surface (W1.4).

Both portals run against the same Supabase project. The v2 backend (additive) was merged and applied to prod on Jun 9, 2026; native Google Calendar scheduling is the live booking layer on the customer domain (DEC-0001 executed): service account sv-calendar@sv-scheduling.iam.gserviceaccount.com writes to the founder-owned “SV Bookings” calendar (secrets GOOGLE_SERVICE_ACCOUNT_JSON + GOOGLE_CALENDAR_ID set in Supabase). Availability comes from get-available-slots (plan service windows ∩ 48-hour lead ∩ calendar FreeBusy), with bookings available up to 365 days out via the month-paged slot picker. Calendly remains only as v1’s legacy read-only webhook path.

Marketing & Docs Sites

sv-website is not standalone — its signup/partnership forms call three sv-edge functions (signup-webhook, create-checkout-trial, partnership-inquiry) on the shared Supabase project, so changing those contracts breaks the site. Only sv-wiki is fully standalone (no integrations).

Customer Portal (sv-portal-2026 — LIVE)

Overview

• Live since: Jun 10, 2026 — portal.mystoragevalet.com serves the sv-portal-2026 codebase (DEC-020 domain re-point)
• Tech: Vite 8 + React 19 + TypeScript (strict) + Tailwind 4 — v6 Operation Midnight Teal tokens
• Auth: Supabase magic links (email-based, no passwords)
• Write path: fn_v2_* SECURITY DEFINER RPCs only (sole exception: two-step photo upload)
• Scheduling: native Google Calendar — availability via get-available-slots; bookings up to 365 days out (month-paged picker)
• State: TanStack Query for server state; React Router 7

Customer Surfaces (6)

Per-item remove on Manage (F5, Jul 2026): the Dashboard Manage view exposes a per-item “Cancel Pickup/Delivery” action that removes a single item from a pending visit via the same revert RPC path as Item Detail; removing the last active item from a visit cancels the visit itself.

Staff operations live in the v2 portal’s /ops surface (shipped W1.4) — staff-gated (is_staff()) and AAL2-stepped-up, reading fn_v2_ops_queue / fn_v2_ops_booking_detail and acting through the staff edge wrappers (complete-service, staff-booking-cancel, staff-booking-reschedule, staff-item-revert).

v1 (sv-portal) — Decommissioned

v1 was decommissioned Jun 29, 2026 (DEC-021): frontend retired (static placeholder at sv-portal-gamma.vercel.app, git disconnected), its v1-only edge functions + RPCs + views removed from prod, repo archived. Its former staff routes (/ops, /admin/waitlist, /admin/customers) and the get_ops_actions RPC behind them no longer exist — ops moved to the v2 /ops surface above.

Commands

cd ~/code/sv-portal-2026
npm run dev          # Vite dev server (mock mode by default — every surface browsable)
npm run build        # tsc -b && vite build (must pass before any push)
npm run typecheck    # tsc -b
npm run test         # vitest run

cd ~/code/sv-portal  # v1 — DECOMMISSIONED Jun 29, 2026 (archived; reference only, not deployed)

sv-edge (Edge Functions)

Overview

• Runtime: Deno (Supabase Edge Functions)
• Auth: JWT verification + RLS
• Deployment: supabase functions deploy

Functions (20 active)

Scheduling & v2 Booking (Google Calendar)

Stripe Integration

Calendly (Legacy v1 Path)

Booking Operations

Customer & Email

Utility

Deployment (CRITICAL)

cd ~/code/sv-edge

# Individual function
supabase functions deploy stripe-webhook --no-verify-jwt
supabase functions deploy calendly-webhook --no-verify-jwt

# Or deploy all customer-facing functions (recommended)
./scripts/deploy-customer-facing.sh   # 19 functions, all with --no-verify-jwt
./scripts/smoke-edge.sh               # post-deploy smoke check

Webhook URLs

Incident Log

Promo Page Architecture

How Routing Works

Vercel serves the filesystem first: /promo/beacon matches the generated promo/beacon.html (via cleanUrls: true). A rewrite rule in sv-website/vercel.json remains as the fallback for anything with no generated file:

{ "source": "/promo/:code", "destination": "/promo" }

The fallback serves the template for unknown slugs and for /promo/sample (deliberately never generated). On every page — generated or fallback — client-side JavaScript:

1. Reads the URL slug (e.g., beacon from /promo/beacon)
2. Looks it up in the PROPERTIES object embedded in the HTML (74 entries = 73 real + sample)
3. If found: populates the page with the property name, promo code, share links, and QR code
4. If not found: hides the promo content and shows a “Page Not Found” message with a link back to the main site

File Structure

Design Characteristics

• Brand-consistent: Uses the Operation Midnight Teal palette and the same DM Serif Display + Outfit typography as the rest of the Storage Valet brand system. Dark-first surfaces with Electric Teal accents. Text-only logo (no box icon). See Brand Identity for the full system.
• Mobile-first responsive: Tested at 390px (iPhone), 600px (tablet), and desktop widths. Two-column layouts collapse to single-column on mobile.
• Performance: All styles inline (no external CSS). GPU-accelerated scroll animations (translate3d, will-change lifecycle management). SVG noise texture instead of heavy images.
• Accessibility: prefers-reduced-motion support, focus-visible outlines, semantic HTML, sufficient color contrast
• Animation: translate3d(0, 28px, 0), 0.8s ease-out, IntersectionObserver with threshold: 0.1 and rootMargin: '0px 0px -40px 0px' — matches main site patterns

Analytics Events

Promo pages fire events to both Vercel Web Analytics and GA4:

Events use the window.va?.('event', ...) script-tag API pattern (not .track()). GA4 captures page views and scroll depth automatically via Enhanced Measurement.

QR Code Generation

QR codes are generated dynamically via api.qrserver.com (external API). Each encodes the full promo URL (e.g., https://mystoragevalet.com/promo/beacon). The QR image uses Midnight (#0A1628) for brand consistency with the Operation Midnight Teal palette. Suitable for lobby flyers, elevator screens, move-in packets, and digital signage.

Dual-View: Resident vs Property Manager

Promo pages support two view modes controlled by a URL parameter:

When PM mode activates, the ?pm=true parameter is stripped from the URL bar via history.replaceState so the clean URL can be shared, and the mode is persisted in localStorage so a reload or bookmark on the PM's own browser keeps the toolkit (added Jul 21, 2026 — previously a reload lost it permanently). The toggle is client-side — the .share-section element is hidden by default and displayed only when isPM is true. PM share outputs carry real attribution tokens: the copied email snippet links with ?src=email, the copy-link button with ?src=link, and the QR code with ?src=pm-qr; a visit with no token attributes as direct. (An earlier version of this page documented a ?src=pm token that the code never emitted.)

Slug Convention

• Lowercase only, no spaces, no hyphens, no special characters
• Must be unique across all entries in the PROPERTIES object
• Should be recognizable (e.g., beacon, greyson, sable)

Adding a New Property (Technical Steps)

1. Create a Stripe promotion code on coupon W8K6JWCH (LIVE mode — confirm with Zach):

   stripe promotion_codes create \
     -d coupon=W8K6JWCH \
     -d code=NEWPROPERTY \
     -d metadata[property_slug]=newproperty \
     -d metadata[property_name]="New Property Name"

2. Add to the PROPERTIES object in sv-website/promo/index.html (alphabetical by slug):

   "newproperty": { name: "New Property Name", code: "NEWPROPERTY" },

3. Regenerate the per-property pages: python3 promo/generate.py (creates promo/newproperty.html and updates the sitemap).
4. Commit and push the template plus the regenerated files to main. Vercel auto-deploys within ~60 seconds.
5. Verify: Visit mystoragevalet.com/promo/newproperty and confirm property name, promo code, QR code, and share tools render correctly.

Removing a Property

1. Remove the entry from the PROPERTIES object in promo/index.html
2. Run python3 promo/generate.py — it deletes the orphaned generated page and updates the sitemap
3. Deactivate the corresponding Stripe promotion code
4. Commit and push — the URL will then show the “Page Not Found” fallback

Planned Enhancements

Future phases (documented in the archived spec, sv-docs/archive/2026-06-05-cleanup/promo-landing-pages.md) would add:

• Embedded signup form with address fields pre-filled from property data
• Promo code auto-application at Stripe Checkout (no manual entry)
• Database attribution (promo_code column on pre_customers table)
• Additional analytics events: promo_signup_submit, promo_checkout_redirect, promo_signup_waitlist

Integrations

Stripe

Google Calendar (Native Scheduling — LIVE)

The live booking layer on the customer domain since Jun 10, 2026 (DEC-0001 executed). Booking confirm creates the calendar event; cancel/revert deletes it. Custody never mutates without a calendar event (block-on-outage).

Calendly (Legacy — v1 read-only path)

Calendly is no longer the live booking layer. The calendly-webhook function remains deployed as a legacy webhook path (kept past the v1 decommission, pending a separate Calendly-retirement decision) with HMAC verification ENABLED (fails closed — keep CALENDLY_WEBHOOK_SIGNING_KEY set in Supabase secrets). Events: invitee.created, invitee.canceled. Webhook only, no outbound API calls.

Supabase Storage

Transactional Email (Resend)

All transactional mail renders via the send-email edge function (Resend). Customer-facing types, plus the internal ops_alert:

Deliverability (Jun 15, 2026): every customer email send is wrapped in EdgeRuntime.waitUntil across all 7 sending functions, so the Supabase isolate cannot freeze before the Resend POST completes (previously these fire-and-forget sends could silently never deliver). send-email also fires an ops_alert when a customer send returns non-200. Booking emails + their ICS now include the service address (LOCATION).

Website Analytics

GA4 (G-9SBYJ8QEC1) and Vercel Web Analytics Plus ($10/month) run on all sv-website pages. GA4 handles behavioral analytics, acquisition channels, and UTM attribution. Vercel handles custom event tracking and privacy-friendly visitor counts. Vercel Speed Insights tracks Core Web Vitals.

Full analytics documentation → — configuration, internal traffic filtering, custom events, UTM attribution, and GA4 MCP tools.

Error Monitoring (Sentry)

Sentry error monitoring is LIVE on the v2 portal since Jul 11, 2026 — org my-storage-valet-llc (us.sentry.io), project sv-portal-2026.

• Wiring: all Sentry code lives in src/lib/sentry.ts (the only module importing @sentry/react); init is gated on PROD && VITE_SENTRY_DSN — dev and mock mode never initialize.
• Privacy: sendDefaultPii: false plus a deep scrubber (src/lib/sentryScrub.ts) that strips auth tokens, magic-link hashes, emails, phones, and street addresses from every event and breadcrumb. User correlation is the opaque auth user id only — never email. No Session Replay (deliberate).
• DSN: write-only ingest key in Vercel env VITE_SENTRY_DSN (Production target only, build-time embedded — changing it requires a redeploy).
• Deferred (reviewer-gated): source-map upload, release tagging, and the Deno edge SDK in sv-edge.

HubSpot CRM

Added Mar 2026. Partnership sales pipeline management — tracks prospective property partners from research through signed partnership. Separate from product infrastructure (Supabase, Stripe, Google Calendar handle customer-facing operations).

Pipeline Stages

Custom Deal Properties

property_address, unit_count, property_type, city, outreach_status, data_source, date_sent, followup_date, response_date, promo_code, promo_url, activity_log

Scope & Boundaries

• HubSpot is sales pipeline ONLY — tracks B2B partnership outreach to property management companies
• Not connected to product infrastructure — Stripe handles billing, Supabase handles customer data, Google Calendar handles scheduling
• Promo tracking: 69 deals have promo_code + promo_url linking to property-specific promo landing pages
• Company associations: deals are progressively linked to their management companies (counts drift with enrichment) — see HubSpot for live association status

E-Signature & Contracts (Jun 2026)

Go-to stack for generating and sending Storage Valet agreements (partners, customers, vendors). Decided Jun 12, 2026: Google Workspace eSignature is primary; PandaDoc Free eSign is the backup for recipient preference or outages. No additional paid tool. Full step-by-step workflow → Legal § Contracts & E-Signature.

SEO & Performance (Feb 2026)

Security

Authentication

• Method: Magic links (email-based, no passwords)
• Provider: Supabase Auth
• Email link format (since Jul 14, 2026): magic-link emails land at /auth/confirm?token_hash=…&type=email and the portal completes sign-in via verifyOtp — the same pattern as the welcome email. This replaced the PKCE ?code= flow in magic-link emails, which structurally failed when the link was requested in one browser context and opened in another (QA finding F5). The token-hash pattern is prefetch-safe and works cross-context. Do not revert the GoTrue mailer template to {{ .ConfirmationURL }}.
• Input normalization: the login form and signIn strip a pasted mailto: prefix and whitespace before validating or submitting (QA finding F4).
• Token: JWT with user ID
• Session: Persisted to localStorage; survives new tabs, refresh, and browser restart. Auth guard (ProtectedRoute) gates on Supabase INITIAL_SESSION event before rendering redirects. An 8-second boot timeout fails open to signed-out (clean /login) if session restoration hangs — the app can never sit on an infinite splash.

Row Level Security (RLS)

All customer tables are protected by RLS:

• Users can only see/modify their own data
• auth.uid() used in all policies
• Service role bypasses RLS (edge functions only)

Billing Protection

Billing fields on customer_profile are protected:

• Users CANNOT update subscription_status, stripe_customer_id, subscription_id
• Updates only via SECURITY DEFINER functions from webhooks

Secrets Management

Secret Inventory

Approved Patterns

# Fetch a secret (never prints to terminal)
OP_BIOMETRIC_UNLOCK_ENABLED=true op read 'op://Storage Valet/Stripe Live/secret_key'

# Push to Supabase without exposing the value
OP_BIOMETRIC_UNLOCK_ENABLED=true op read 'op://Storage Valet/Stripe Live/secret_key' \
  | xargs -I {} supabase secrets set STRIPE_SECRET_KEY="{}" --project-ref gmjucacmbrumncfnnhua

# Shell env vars — lazy-loaded via sv-env function (run once per session)
# Secrets are NOT resolved at shell startup to avoid macOS permission popups
sv-env         # loads SUPABASE_ACCESS_TOKEN, STRIPE_SECRET_KEY, RESEND_API_KEY
               # also caches to ~/.sv-session (chmod 600) for sub-agent inheritance
               # session file PERSISTS across shells; run sv-env-clear to wipe manually

Rotation Procedures

1. Generate/rotate the credential in the service's dashboard
2. Update the value in 1Password (Storage Valet vault)
3. If the secret is in Supabase secrets, push via: op read '...' | xargs -I {} supabase secrets set KEY="{}"
4. Verify the dependent service still works (e.g., test checkout, test email)

Deferred: Supabase service role key rotation. High blast radius (breaks all 20 edge functions). Requires planned maintenance window. See DEC-011.

Tripwire (Automated Detection)

sv-final-audit.sh includes a secrets tripwire that scans ~/.zshrc, ~/.claude/settings.json, and ~/.claude/settings.local.json for plaintext credential patterns at the end of every session. It also flags any .env files in ~/code/ repos. Additionally, the audit script includes a GitHub hygiene layer that detects stale PRs (open >7 days) and orphan remote branches (>30 days with no associated PR) across all 7 repositories.

Deployment

Portal (Vercel)

cd ~/code/sv-portal-2026
npm run build        # tsc -b && vite build — must pass before any push
vercel               # Preview deploy (NOT --prod)

sv-portal-2026 auto-deploys from its GitHub main branch; the customer domain has pointed at it since Jun 10, 2026. AI commits, pushes, and merges PRs to main directly to ship — no manual promotion step. Do not run vercel --prod directly.

PR validation: there is no CI on any live repo. The pr-validation.yml GitHub Actions workflow existed only in the archived v1 sv-portal; sv-portal-2026 has no .github/workflows. The pre-push gate is local and manual: npm run build (which runs tsc -b first) plus npm run test. Branch protection is trust-based.

Edge Functions

cd ~/code/sv-edge
./scripts/deploy-customer-facing.sh   # Deploy all 19 customer-facing functions
./scripts/smoke-edge.sh               # Post-deploy smoke test
# OR manually:
supabase functions deploy <function-name> --no-verify-jwt

Always run ./scripts/check-deps.sh before deploying. Deploy ALL customer-facing functions together to avoid version drift.

Database Migrations

cd ~/code/sv-db
supabase db push --linked

Requires: Docker Desktop running

Git Configuration

Use only real, verified email addresses. Fabricated emails cause Vercel permission failures.

Architecture Constraints (Non-Negotiable)

1. 6 customer surfaces only: Login, Dashboard, Items + Add Item, Item Detail, Booking, Account
2. Staff routes live in the v2 portal’s /ops surface (portal.mystoragevalet.com/ops), staff-gated (is_staff()) and AAL2-stepped-up
3. Supabase backend only — no custom API servers
4. Stripe Hosted flows only — no custom card UI
5. Single pricing tier: $299/month
6. Magic links only — no password auth
7. Portal is authentication-only — account creation happens exclusively through the website registration flow (Stripe Checkout). The portal login does not create new users.
8. RLS on all tables — zero cross-tenant access
9. Private storage bucket — signed URLs, 1h expiry

Architecture Notes

Common Issues & Solutions

Platform Operations Toolkit

A tiered toolkit for session integrity, repository hygiene, and infrastructure observability. Introduced March 2026 after an orphaned PR went undetected for 35 days. See DEC-017 for rationale.

Commands

All Shell Shortcuts

Defined in ~/.zshrc. Run sv-help to see this list in the terminal.

iTerm2 Tab Auto-Naming

Tabs automatically show the current directory name via a precmd hook in ~/.zshrc. Use title "My Topic" to set a custom title, or title (no args) to reset to auto. Claude Code also sets the tab title to the chat name when running.

Setup (one-time per machine): Disable custom tab titles in iTerm2’s plist (quit iTerm2 first, run via Terminal.app), then add the _update_tab_title precmd function and title() helper to ~/.zshrc. Both machines were configured March 2026.

Ghostty Config Sync

Ghostty configuration lives in iCloud at ~/Documents/storagevalet/Technology/Ghostty/config and is symlinked to ~/.config/ghostty/config on each machine.

Clickable folder paths — use file:// URLs, not Ghostty config. Agents render folder/file deliverables as bare file:// URLs (absolute path, spaces as %20) so Zach can Cmd+click straight to Finder — verified working in Ghostty 1.3.1 on Jul 15, 2026. This works because link-url = true already matches URL schemes. It must be a bare URL: a markdown link hides the URL text and the matcher never sees it. Do not attempt to configure this via Ghostty’s link option (custom regex → clickable file paths) — it is documented but stubbed out (TODO: This can’t currently be set! as of 1.3.1), so any such config silently does nothing. Re-check link on major Ghostty upgrades; a real regex matcher would supersede the convention. Enforced as rule 9 in the global CLAUDE.md.

1Password SSH Agent

The 1Password SSH agent is configured on both machines for any SSH-based operations (ssh to other hosts, SSH-backed git clones, etc.). Git commit signing is intentionally disabled — 1Password’s signing-authorization prompts appear on the Mac Studio screen and cannot be answered when working remotely via the Claude app’s code tab. Sole-developer context plus private repos means signing has no practical benefit to offset that friction.

SSH_AUTH_SOCK (in ~/.zshrc):

export SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

agent.toml (in ~/.config/1Password/ssh/):

[[ssh-keys]]
item = "Github SSH Key (SV)"
vault = "Storage Valet"

Key details: The SSH key is a single ed25519 key named “Github SSH Key (SV)” stored in the Storage Valet vault. Both machines share the same key via 1Password vault sync. The key is registered on GitHub for authentication on any SSH-based git remotes.

Script Locations

All scripts are canonical in ~/code/sv-docs/scripts/ (git-tracked). A convenience symlink at ~/code/sv-final-audit.sh points to the canonical audit script for manual use, but no script depends on this symlink.

Backups and Desktop-Sync Retirement

Current business source: ~/Documents/storagevalet/. Start with its START-HERE.md for working locations. Preserved local cloud exports are filed at ~/Documents/storagevalet/_Archive/2026-09-16-cloud-retirement/preserved/; the retained cloud accounts remain the access path for cloud-only objects.

Replacement backup status: a local restore ZIP was created and verified on Sep 17, 2026 at ~/Library/Application Support/Storage Valet/Backups/Storage-Valet-local-restore-20260917T072833Z.zip (5,237 regular files; 6,963,218,581 ZIP bytes). Every archive member passed CRC and SHA-256 checks, and the postcard PDFs and source files passed sample restore checks. The capture had no dataless or read gaps; regenerable caches and Git metadata were excluded, and symbolic links were preserved without following them. This is a file-data restore point, not a complete Mac image. An off-device backup replacement is not configured. iCloud is sync, not backup — deletions can propagate. A local restore point alone does not protect against losing the Mac. GitHub separately retains pushed repository history.

Historical Drive pipeline — retired Sep 16, 2026

sv-backup.sh previously zipped ~/Documents/storagevalet locally in /tmp, checked the archive, then moved it to Google Drive as My Drive/SV-Backups/SV-Full-Backup-YYYY-MM-DD.zip. The com.storagevalet.backup launchd agent ran at 03:00; its log was ~/Library/Logs/sv-backup.log. It was weekly with eight retained versions before Jul 28, then daily with 21 retained versions. These are historical settings, not a current schedule.

The job ran on the Mac Studio because it held the local Documents copy. The MacBook Air’s Optimize Storage setting could leave dataless placeholders and produce incomplete archives. A Jul 28 verification measured 1.6GB and 2,588 entries; those dated figures are not current coverage or size guarantees.

Historical lesson: the 40-day silent failure (Jun 7 – Jul 12, 2026)

The old script published six consecutive 124-byte archives containing only an empty storagevalet/ entry and logged Backup OK. Discovered Jul 15, the cause was that the launchd process did not inherit Full Disk Access from the terminal. It could read the source directory entry but not the contents. The historical fix granted access to the interpreter, /bin/zsh.

Lesson retained: zip -T proves structural validity, not useful contents. A terminal run also cannot prove that a scheduled job has permission to read its sources. Validate any replacement in its real execution context and inspect the resulting content, size, age and ability to restore.

The Jul 15 guards (c932fe5) rejected archives below 500 entries or 50MB and left the previous good snapshot untouched. Rotation also required zsh’s (N) NULL_GLOB qualifier: redirecting stderr does not prevent a shell-level unmatched-glob abort. Preserve these lessons when designing a replacement; do not restart the retired agent to test them.

Historical lesson: the 19-day silent failure (Aug 7 – Aug 26, 2026)

The last good run was Aug 7 at 03:00, after which the log stopped growing. The agent remained loaded with a registered calendar trigger but did not run; the root cause was not established. The Aug 26 repair re-registered the agent and verified that launchd could spawn it. Those recovery steps applied to the former workflow and are not instructions to re-enable it now.

Lesson retained: a backup can fail by producing unusable output or by never running, with no new error entry. Check the newest artifact’s age, contents and size. The historical [BACKUP FRESHNESS] check used a two-day age limit and 50MB floor; a skipped check when Drive was unmounted did not prove backup coverage.

Design Principles

• Non-destructive audits: sv-audit reads only (except 1Password socket cleanup). It never modifies git state, GitHub, or infrastructure.
• Explicit cleanup: sv-hygiene is a separate, opt-in command. It only deletes branches confirmed merged into main.
• Canonical paths: Scripts reference ~/code/sv-docs/scripts/ directly. Symlinks exist for convenience but are not dependencies.
• Dual observability: Stale PRs are detected at session start (bootstrap snippet) and session end (audit script).

Developer Setup

Code Repositories

~/code/
├── sv-portal-2026/  # LIVE customer portal (Vite 8 / React 19 / Tailwind 4) — cut over Jun 10, 2026
├── sv-portal/       # v1 portal (Vite 5 / React 18 / Tailwind 3) — DECOMMISSIONED + archived Jun 29, 2026
├── sv-edge/         # Supabase Edge Functions (Deno/TypeScript)
├── sv-db/           # Database migrations (SQL)
├── sv-docs/         # Operational scripts, runbooks, and archive
├── sv-website/      # Landing page (www.mystoragevalet.com)
└── sv-wiki/         # Internal wiki (wiki.mystoragevalet.com)

New Machine Setup

When setting up Claude Code on a new machine:

1. Ensure iCloud Desktop & Documents sync is enabled (System Settings → Apple ID → iCloud → iCloud Drive)
2. Create symlinks:

   ln -sf ~/Documents/storagevalet/Technology/Reference/CLAUDE.md ~/.claude/CLAUDE.md
   ln -sf ~/Documents/storagevalet/Technology/Reference/code-CLAUDE.md ~/code/CLAUDE.md

3. Clone repos to ~/code/: sv-portal, sv-portal-2026, sv-edge, sv-db, sv-docs, sv-website, sv-wiki
4. Install Node.js via Homebrew: brew install node@24 (do NOT use .pkg installer)
5. Install CLI tools: brew install supabase gh stripe deno pipx
6. Install Homebrew-managed casks: brew install --cask 1password-cli appcleaner bettermouse claude-code@latest cleanshot codex cursor font-jetbrains-mono framer gcloud-cli ghostty hazel loom miro obsidian rectangle-pro spotify textexpander typora visual-studio-code whimsical wispr-flow
   Note: claude-code cask is used on Mac Studio. On MacBook Air, Claude Code is installed via the native installer (claude install, installs to ~/.local/bin/claude). Do NOT install via npm — the npm package @anthropic-ai/claude-code is deprecated in favor of native installers.
7. Install remaining apps directly: Docker Desktop (required for Supabase CLI), 1Password (biometric agent for op CLI), iTerm2 (custom Dock icon; has reliable built-in updater), Google Chrome — these must NOT be installed via Homebrew as replacement can break system integrations
8. Do not install or enable Google Drive / Dropbox desktop sync or the retired 03:00 Drive backup as part of default machine setup. Use manual web access to retained cloud files until a replacement workflow is approved.
9. Run op signin to authenticate 1Password

Session Startup Checklist

Run these steps at the beginning of each Claude Code session (human or agent):

1. Check for CLAUDE.md sync conflicts:

   CLAUDE_DIR="$(cd "$(dirname "$(readlink ~/.claude/CLAUDE.md || echo ~/.claude/CLAUDE.md)")" && pwd)"
   ls "$CLAUDE_DIR" 2>/dev/null | grep -i conflict && echo "CLAUDE.md CONFLICT — resolve before continuing"

2. Pull latest for all repos:

   for repo in sv-portal sv-edge sv-db sv-docs sv-website sv-wiki; do (cd ~/code/$repo && git pull); done

3. Verify migrations: supabase migration list --linked
4. Read context: ~/.claude/CLAUDE.md and ~/code/CLAUDE.md
5. Docker Desktop must be running for Supabase CLI

Session End Protocol

1. Run sv-audit (or sv-check for full platform verification) — do not declare clean until Audit: CLEAN
2. If the audit flags GitHub hygiene issues (stale PRs, orphan branches): review and resolve
3. If session was significant (deploy, E2E verification, architecture decision): update the relevant SV-Wiki pages and bump each page’s Last updated: line
4. Run python3 ~/code/sv-wiki/generate-llms.py — skipping it leaves llms.txt and llms-full.txt stale even when the HTML is correct, and those endpoints are what most agents actually read
5. Commit the HTML plus both regenerated endpoints together and push to main (instant production; there is no CI)

See Platform Operations Toolkit for the full command reference.