HT-008 - Local to Cloud Sync

Overview

This guide establishes the Atlantis ITS standard for maintaining a Single Source of Truth across three layers: GitHub (remote master), Local HD (working copy), and VS Code (editor). It covers the daily sync workflow, MkDocs-specific rules, drive migration gotchas, and recovery procedures for common sync failures.

Applies to all Atlantis projects on D:\Data\AtlantisITS --- including the atlantisits.info KB (MkDocs), all app repos, and the Roofing Lead Engine.

1. The Hierarchy of Truth

Always follow this chain of command. When in doubt --- GitHub wins.

Layer Role

1. GitHub (Remote) Master / Source of Truth --- the final authority

2. Local HD (D: drive) Working copy --- where you edit (D:\Data\AtlantisITS)

3. VS Code Editor / Lens --- must always open the correct repo root

⚠️ Sync Drift happens when these three layers fall out of alignment --- usually after a drive migration, switching machines, or forgetting to pull before editing. This guide prevents it.

2. Pre-Flight Checklist (Do This Every Session)

Before editing any file or committing any code --- run through this checklist every time.

2.1 Open the Correct Folder in VS Code

  • File → Open Folder → select the exact folder containing the hidden .git folder

  • Example: D:\Data\AtlantisITS\docs (not D:\Data\AtlantisITS which is a parent)

  • In VS Code terminal (Ctrl+`) run:

+-----------------------------------------------------------------------+ | # Confirm you are in the right directory | | | | pwd | | | | # or | | | | git rev-parse --show-toplevel | | | | # Output should end with your project name, not a parent folder | +-----------------------------------------------------------------------+

📸 SCREENSHOT PLACEHOLDER --- VS Code Explorer pane showing correct folder open with .git folder visible

2.2 Pull Before You Edit

+-----------------------------------------------------------------------+ | # Always pull latest from GitHub before starting work | | | | git pull origin main | | | | # Check which branch you are on | | | | git branch | | | | # Should show: * main | | | | # If you see \'detached HEAD\' or a feature branch --- fix before | | proceeding | +-----------------------------------------------------------------------+

⚠️ Never edit files before pulling. If you edit on a stale local copy and someone else (or a Vercel deploy) pushed changes, you will get merge conflicts. Pull first, always.

2.3 Verify .gitignore Exists

Confirm your .gitignore file exists and includes these critical entries:

+-----------------------------------------------------------------------+ | # Contents of .gitignore --- minimum required for Atlantis projects | | | | /site/ # MkDocs generated output --- never commit this | | | | .env # Secrets --- never commit this | | | | node_modules/ # Dependencies --- never commit this | | | | *.vhdx # Docker virtual disk --- never commit this | | | | service-account.json # Google service account key --- never commit | | this | +-----------------------------------------------------------------------+

⚠️ If .gitignore is missing or incomplete --- create/update it and commit it BEFORE staging any other files. Committing .env or service-account.json to GitHub exposes your secrets publicly.

3. Clean Sync Execution (The Safe Workflow)

After finishing a session or fixing a versioning issue --- follow these 5 steps in order. Never skip step 2.

Step Command / Action What it does / Safety check

1. Stage VS Code: Source Control Tells Git to track your changes. → click + on changed Only stage what you intend. files OR: git add .

2. Review VS Code Source Control Confirm no .env, no /site/, no (CRITICAL) view OR: git status huge files (>100MB). Unstage mistakes: git reset HEAD \<file>

3. Commit VS Code: enter message → Packages changes with a timestamp. click Commit OR: git Use descriptive messages --- commit -m \"Brief include version/ticket if description\" applicable.

4. Push VS Code: Sync Changes Uploads to GitHub. Only push after button (cloud arrow) OR: pull and review. git push origin main

5. Verify Open repo in browser → Double-check files match local. refresh → confirm commit Confirm no /site/ pollution in appears GitHub.

💡 Use VS Code Source Control sidebar for day-to-day commits --- it\'s faster than the terminal and gives a visual diff of every changed file. Use terminal commands when troubleshooting or when VS Code shows stale state.

📸 SCREENSHOT PLACEHOLDER --- VS Code Source Control sidebar showing staged changes + git status output in terminal

4. MkDocs-Specific Syncing Rules

The atlantisits.info KB runs on MkDocs. MkDocs generates a /site/ folder every time you build --- this folder must NEVER be committed to GitHub.

4.1 The .gitignore Rule

  • Always include /site/ in .gitignore --- it is auto-generated and changes on every build

  • Only commit the Markdown source files (.md) and mkdocs.yml --- not the generated HTML

  • Vercel builds the site automatically from the source --- you do not need to commit /site/

4.2 Lock Version Metadata in mkdocs.yml

Hard-code versioning metadata to prevent AI agents from guessing the version number during rebuilds:

+-----------------------------------------------------------------------+ | # In mkdocs.yml --- add this under extra: | | | | extra: | | | | version: | | | | provider: mike | | | | default: latest | +-----------------------------------------------------------------------+

4.3 Preview Before Push

+-----------------------------------------------------------------------+ | # Preview MkDocs site locally before committing | | | | mkdocs serve | | | | # Opens at: http://127.0.0.1:8000 | | | | # Confirm site looks correct BEFORE pushing | | | | # DO NOT commit /site/ after building | | | | # Ctrl+C to stop the server | +-----------------------------------------------------------------------+

📸 SCREENSHOT PLACEHOLDER --- Terminal showing mkdocs serve running + browser preview at 127.0.0.1:8000

5. Drive Migration Gotchas (D: Drive --- Atlantis Specific)

Atlantis projects live on D:\Data\AtlantisITS (migrated from E: in March 2026). After any drive migration, Git may flag repositories as unsafe. Fix with:

+-----------------------------------------------------------------------+ | # Run after any drive migration --- fixes Git safe.directory errors | | | | git config --global --add safe.directory | | D:/Data/AtlantisITS/projects/popoff-app | | | | git config --global --add safe.directory D:/Data/AtlantisITS/docs | | | | # Repeat for each repo that throws a safe.directory error | | | | # Verify remote origin is correct after migration | | | | git remote -v | | | | # Expected output: | | | | # origin https://github.com/Golboni/[repo-name] (fetch) | | | | # origin https://github.com/Golboni/[repo-name] (push) | | | | # If remote URL is wrong: | | | | git remote set-url origin https://github.com/Golboni/[repo-name] | +-----------------------------------------------------------------------+

💡 EAS Build (Pop Off) also requires a clean GitHub sync before triggering a build. If EAS fails with a repo error --- run the safe.directory fix and re-sync GitHub before retrying.

6. Troubleshooting Common Sync Issues

Issue Cause Fix

VS Code shows Stale Git cache in Ctrl+Shift+P → \'Git: Refresh\' or different files VS Code close and reopen the folder than GitHub

\'detached HEAD\' Checked out a git checkout main → git pull state commit directly
instead of a
branch

Merge conflict Edited without git pull origin main → resolve after push pulling first conflicts → git add . → git commit → git push

Large file File added without git reset HEAD \<file> → add to accidentally checking size .gitignore → git add .gitignore → staged first commit

.env committed to Missing .gitignore Immediately rotate all secrets → GitHub entry git rm --cached .env → add to .gitignore → force push

/site/ folder .gitignore missing git rm -r --cached site/ → add appearing in /site/ entry /site/ to .gitignore → commit GitHub

safe.directory Git security check git config --global --add error after D: on new path safe.directory migration D:/Data/AtlantisITS/[project]

EAS build fails GitHub not synced Fix safe.directory → git pull → after drive before build git push → retry eas build migration trigger

Credentials n8n excludes Re-enter all API keys manually in missing after n8n credentials from n8n UI --- budget 30-60 min clone export by design

7. Nuclear Reset (Local Mess --- GitHub Correct)

Use this only when the local folder is hopelessly out of sync and GitHub is confirmed correct. This is the last resort.

  1. Copy any uncommitted work from current folder to a temp location: D:\TempBackup\

  2. Rename current folder to \<name>_OLD (do not delete --- keep as safety net)

  3. Clone a fresh copy from GitHub:

+-----------------------------------------------------------------------+ | cd D:\Data\AtlantisITS\projects | | | | git clone https://github.com/Golboni/[repo-name] | +-----------------------------------------------------------------------+

  1. Copy back only the specific files you need from _OLD folder --- avoid /site/, .env, node_modules

  2. Re-open in VS Code → git pull → verify clean state

  3. Delete the _OLD folder once confirmed working

⚠️ Never copy .env, /site/, or node_modules from the _OLD folder into the fresh clone. These will corrupt the clean state. Start fresh with secrets and run npm install for dependencies.

Quick Reference

Item Value

Working directory D:\Data\AtlantisITS

GitHub org https://github.com/Golboni

Default branch main

Pull latest git pull origin main

Check branch git branch

Check status git status

Stage all git add .

Unstage file git reset HEAD \<file>

Commit git commit -m \"Description\"

Push git push origin main

Check remote git remote -v

Fix safe.directory git config --global --add safe.directory D:/Data/AtlantisITS/[project]

Fix detached HEAD git checkout main → git pull

VS Code Git refresh Ctrl+Shift+P → \'Git: Refresh\'

MkDocs preview mkdocs serve → http://127.0.0.1:8000

Remove /site/ from Git git rm -r --cached site/