AI Handoff Rules — SONAN DIGITAL Docs

XYZ Aquarium Cleaning Services

AI Handoff Rules

Read this at the start of every AI session before touching any code or git

⚠ This page defines mandatory rules for AI coding sessions on this project. Skipping any step has caused git corruption and lost work in the past.

Project Context
FUSE Mount Rules
FUSE-Safe Commit Pattern
Git Rules
Known Gotchas
Deploy Steps

Project Context

Item	Value
Project	XYZ Aquarium Cleaning Services Portal
Repo	`sonantechai/aquarium-portal`
Local path	`E:\Claude_Projects\sonan-trackersquarium-portal\`
Bash path	`/sessions/.../mnt/sonan-trackers/aquarium-portal/`
Stack	React 18 + TypeScript (Vite 5) · Cloudflare Worker · D1
Live site	xyzaquarium.sonandigital.com

FUSE Mount Rules

The project folder is FUSE-mounted. This causes two critical problems:

Large file truncation — Write/Edit tools AND bash writes to FUSE paths silently truncate large files. Both disk and blob end up truncated to the same count, so line-count verification passes. You CANNOT detect this from within the sandbox.
.git/config corruption — Any write to .git/config via the FUSE path corrupts it (reads back as spaces). A .git/config.lock file is also left behind, blocking all git remote operations.

Rule: Never write files directly to the FUSE path for anything going into git. Always write to /tmp first, then copy.

FUSE-Safe Commit Pattern

Because the FUSE mount prevents standard git operations from the sandbox, the AI prepares file content and the user runs git from their Windows terminal.

Step 1: Write to /tmp (not FUSE path)

python3 << 'EOF'
content = r"""...full file content..."""
with open('/tmp/filename.tsx', 'w') as f:
    f.write(content)
EOF

Step 2: Copy to FUSE path from bash

cp /tmp/filename.tsx "/sessions/.../mnt/sonan-trackers/aquarium-portal/src/components/admin/filename.tsx"

Step 3: User runs from Windows terminal

cd E:\Claude_Projects\sonan-trackersquarium-portal
git add src/components/admin/filename.tsx
git commit -m "feat: ..."
git push origin main

⚠ If git push fails with "does not appear to be a git repository": .git/config is corrupted. Run from Windows terminal: del .git\config.lock, then manually recreate .git\config with the core section and re-add the remote.

Git Rules

Always push to main directly — no dev branch on this project
Push with explicit SHA: git push origin <sha>:refs/heads/main
Never use an intermediate failed commit as parent — hardcode parent to last pushed SHA
The user runs all git push commands from Windows terminal (sandbox gets 403)
If refs/heads/main is broken, find the last good SHA in ORIG_HEAD or git reflog

Known Gotchas

Issue	Fix
FUSE truncates large files silently	Write to `/tmp` first, hash from `/tmp`
`.git/config` corruption + lock file	User deletes `.git\config.lock`, recreates `.git\config` from Windows terminal
`refs/heads/main` broken ref	Find last good SHA from `ORIG_HEAD`, write to ref file
Non-fast-forward push after failed commit	`git fetch origin && git reset --hard origin/main` then re-copy files
Wrangler pages deploy `--env` flag fails	Use `--branch main` instead of `--env aquarium`
AppContext `setView` not imported in component	Add `setView` to `useApp()` destructure
Supabase-style array returns	N/A — this project uses D1 with raw JSON returns, not Supabase

Deploy Steps

After committing and pushing from the Windows terminal:

# From the aquarium-portal directory on Windows terminal
npm run build
npx wrangler pages deploy dist --project-name aquarium-portal --branch main

The Cloudflare Worker is deployed separately (only when worker/index.ts changes):

npx wrangler deploy worker/index.ts --name aquarium-api

D1 migrations run with: npx wrangler d1 execute aquarium_db --file migrations/001_init.sql — only needed when schema changes.

Contents