What every HTML file actually is, where it lives, how updates work, and how to think about the two completely separate things you're managing: your tools and your code.
01The key insight
Two separate things, not one project
Everything you have right now falls into one of two buckets — and keeping them separate is the most important organizational habit you can build. Mixing them causes confusion later.
Your old structure
PLANNING PHASE folder — vague, will overflow
USE EACH SESSION — works for now, won't scale
No separation of tools vs code
Unclear what goes where as project grows
Cleaner structure
/docs — read-only reference pages
/tools — interactive HTML apps you use daily
/session — the one file you open every time
/dj-platform — the actual code, on GitHub
⚡
The mental model that makes this click
Your HTML tools are like a physical desk setup — notebooks, reference cards, sticky notes. Your /dj-platform folder is the actual product you're building. You wouldn't staple your sticky notes into the product. Same idea here.
02Folder structure
Exact layout on your machine
Create this once on your Windows machine. Mirror it exactly on your MacBook and Dell — only /dj-platform syncs via GitHub. Everything else is local on each machine.
Booking and Management Platform/← your root, same name on all 3 machines
├─/docs← reference pages · open in browser · never edit
├─/session← everything you open to run your workflow
├─session-startup.html← open first, every session
├─session-prompt.html← fill fields, copy prompt, paste into Claude
├─session-end.html← run before closing VS Code
└─session-notes.txt← written at end of every session
├─/dj-platform← your codebase · lives on GitHub · Vercel deploys this
├─apps/
├─packages/
└─.gitignore · README.md · etc.
└─/archive← old versions, drafts, anything you want to keep but not look at
/docs
Read-only reference pages. Open in browser, read, close. When Claude gives you an updated version, replace the whole file — don't edit inside it.
roadmap-reference.html
dj-platform-build-plan.html
dj-platform-interactive.html
file-organization.html ← this file
/tools
Interactive apps you actively use while working. DevOS saves your tasks and notes locally in that browser. Future plan: sync to Supabase so it follows you across machines.
devos-project-manager.html
future tools go here too
/session
Everything you open to run your workflow. Start with session-startup, end with session-end. The prompt is how Claude knows your project. Notes are your handoff between sessions.
session-startup.html ← open first
session-prompt.html ← copy into Claude
session-end.html ← run before closing
session-notes.txt ← written every session
/dj-platform
Your actual product code. This is the only folder that goes on GitHub. Vercel watches this repo and auto-deploys when you push. Nothing from the other folders ever goes in here.
apps/web/ ← Next.js app
packages/db/ ← Supabase types
packages/api/ ← shared logic
/archive
Old HTML versions, scratch notes, experiments. Move things here instead of deleting — you might want them someday. Never look in here during a work session.
anything outdated
draft versions
03How HTML files work
What these files actually are
Understanding this prevents a lot of confusion about saving, updating, and syncing.
01They run entirely in your browser, with no server. Double-click the file, it opens in Chrome or Edge, and all the JavaScript runs locally on your machine. No internet required once downloaded.
02They are not a foundation you build on top of. Think of them like interactive PDF reference cards. When Claude gives you an improved version, you download the new file and replace the old one in your folder. You don't edit the HTML manually.
03The reference docs (/docs) have nothing to save. Roadmap, build plan, this file — they're purely for reading. No data, no state, no saves. Just replace the whole file when there's an update.
04DevOS (/tools) saves to localStorage — device and browser specific. Tasks and notes you add on Windows Chrome live only in Windows Chrome. They won't appear when you open the same file on your MacBook. This is a known limitation with a fix planned (Supabase sync).
05The session files (/session) are workflow tools, not reference docs. session-startup and session-end save checkbox state to localStorage — device specific, resets daily by design. session-prompt resets every open — which is what you want since every session is different. session-notes.txt is a plain text file that persists exactly as you save it.
04Saves and syncing
What saves, what doesn't, and the workaround
The honest picture on cross-machine data right now, and what to do about it until the Supabase sync is built.
⚠
localStorage does not follow you between machines
DevOS uses localStorage — data is stored inside the browser on that specific device. Open DevOS in Chrome on Windows → tasks save there. Open the same file on your MacBook → completely empty. Clearing your browser cache also wipes it.
✓
The workaround that works right now
Before ending every session, write 2 sentences in the DevOS Notes tab: what you did and what's next. When you sit down on a different machine, read those notes first. It takes 60 seconds and is actually a better habit than relying on sync anyway.
→
The real fix: Supabase sync (Phase 1 milestone)
Once you have Supabase set up for the DJ Platform (Step 3 in the roadmap), we wire DevOS into it. Your tasks and notes get stored in the cloud and load on any device you log into. This is about 2 hours of work and is good practice for exactly the skills you're building. It happens naturally as part of Phase 1 setup.
053-machine routine
Switching between Windows, MacBook, and Dell
The HTML tools are local to each machine — that's fine. Your code is synced via GitHub — that's the important part. Follow this routine and machine-switching takes less than 2 minutes.
↓Before leaving any machine: Write session notes in DevOS (what you did, what's next). Commit and push your code: git add . → git commit -m "wip: what you were doing" → git push. Takes 3 minutes.
↑When sitting down on a new machine: Open DevOS and read your last notes. Then git pull origin main to get the latest code. Then open session-prompt.html, fill in what you just read, copy, paste into Claude.
📁The HTML files don't need syncing — they never change between sessions (you only replace them when Claude gives you a new version). Keep identical copies on all 3 machines. If one gets out of date, just download the latest version from Claude and replace it.
🔑Keep your .env.local keys somewhere safe and offline — a password manager like 1Password, or a locked note on your phone. You need to paste them into each machine's .env.local file. Never put them in GitHub or in any of the HTML files.
→
Next step: get the tools accessible from any device
Right now everything is local. The fastest fix: drag your /docs, /tools, and /session folders to netlify.com/drop — they get a real URL in under 60 seconds that works on your phone and every machine. Then put /dj-platform on GitHub separately. Those are two distinct actions for two different purposes.