docs: add AGENTS handoff notes and comprehensive README

README.md

@@ -1 +1,113 @@
-# veryextra ARG site
+# VeryExtraOS-ARG
+
+A retro pink XP-inspired ARG desktop experience built as a static web app.
+
+It includes a fake desktop, draggable icons, window management, a virtual file explorer, Start menu actions, mock apps (Notepad/Paint/IE), and custom right-click context menus.
+
+## Repository
+
+- GitHub: https://github.com/diontimmer/VeryExtraOS-ARG
+- Local path: `/home/diont/veryextra-arg-site`
+
+## Tech stack
+
+- HTML/CSS/Vanilla JavaScript
+- Static assets served by `nginx:alpine`
+- Docker Compose for local runtime
+
+## Project structure
+
+- `site/index.html` — desktop shell, taskbar, start menu, window template
+- `site/script.js` — all app logic (window manager, explorer, start actions, context menus)
+- `site/styles.css` — global styles and retro UI styling
+- `site/fakeweb/` — in-world fake web pages and route index
+- `site/assets/audio/violin.mp3` — sample media asset
+- `ops/docker-compose.yml` — nginx runtime config
+- `AGENTS.md` — critical handoff notes for future sessions
+
+## Run locally
+
+From the repo root:
+
+```bash
+docker compose -f ops/docker-compose.yml up -d
+```
+
+App will be available at:
+
+- http://localhost:8008
+
+Stop:
+
+```bash
+docker compose -f ops/docker-compose.yml down
+```
+
+## Development workflow
+
+No build step is required (static files).
+
+Typical loop:
+
+1. Edit files under `site/`
+2. Refresh browser
+3. Optional JS syntax check:
+
+```bash
+node --check /home/diont/veryextra-arg-site/site/script.js
+```
+
+If needed, redeploy container:
+
+```bash
+docker compose -f /home/diont/veryextra-arg-site/ops/docker-compose.yml up -d
+```
+
+## Feature overview
+
+### Desktop and windows
+- Draggable desktop icons with persisted layout
+- Multi-window taskbar integration
+- Show desktop toggle
+- Minimize/close controls
+
+### Start menu
+- Launches core apps (IE, Notepad, Paint, My Computer)
+- Direct folder shortcuts (My Documents, My Pictures, Music)
+- Mock system actions (Control Panel, Run, Help, Log Off, Turn Off)
+
+### Explorer and virtual filesystem
+- My Computer-centered navigation model
+- Back/Forward/Up icon nav buttons
+- Quick Access sidebar for drives and key folders
+- Openable text/image/audio virtual files
+- Details panel for selected items
+
+### Right-click context menus
+- Desktop icon context menu:
+  - Open
+  - Open All Selected
+  - Reset Icon Layout
+  - Properties
+- Explorer item context menu:
+  - Open
+  - Open in New Window (folders)
+  - Open Parent Folder (files)
+  - Properties
+
+## Notes
+
+- This is intentionally stylized and partially mock/simulated.
+- Several system entries are stubs by design and can be expanded incrementally.
+- Keep UX changes cohesive with the retro pink XP aesthetic.
+
+## Contributing guidelines
+
+- Keep dependencies minimal unless explicitly requested.
+- Prefer small, targeted changes to `script.js` and `styles.css`.
+- Validate with `node --check` after JS edits.
+- For handoff-critical updates, mirror them in `AGENTS.md`.
+
+## License
+
+No license has been declared yet. Add one before making the repo public.