From ef989a140373f69b65b8c8d79748d1e389edb07d Mon Sep 17 00:00:00 2001
From: Dion Timmer <825343+diontimmer@users.noreply.github.com>
Date: Fri, 13 Mar 2026 01:28:16 -0400
Subject: [PATCH] docs: add AGENTS handoff notes and comprehensive README

---
 AGENTS.md |  69 +++++++++++++++++++++++++++++++++
 README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 182 insertions(+), 1 deletion(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7b3e050
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,69 @@
+# AGENTS.md
+
+Critical developer notes for future sessions working in this repo.
+
+## Project identity
+- Name: VeryExtraOS-ARG
+- Repo: https://github.com/diontimmer/VeryExtraOS-ARG
+- Local path: /home/diont/veryextra-arg-site
+- Stack: static HTML/CSS/vanilla JS served by nginx via Docker Compose
+
+## Runtime / deploy
+- Compose file: /home/diont/veryextra-arg-site/ops/docker-compose.yml
+- Service name: veryextra-arg
+- Container name: veryextra-arg
+- Host port: 8008 -> container 80
+- Static site root mounted read-only: ../site -> /usr/share/nginx/html
+
+Common commands:
+- Start/redeploy: docker compose -f /home/diont/veryextra-arg-site/ops/docker-compose.yml up -d
+- Stop: docker compose -f /home/diont/veryextra-arg-site/ops/docker-compose.yml down
+- JS syntax check: node --check /home/diont/veryextra-arg-site/site/script.js
+
+## Current UX implementation highlights
+- Desktop with draggable icons and saved layout in localStorage key:
+  - veryextraOS.iconLayout.v1
+- Window manager with taskbar buttons, minimize/close, z-index focus, show desktop.
+- Start menu wired actions:
+  - Open apps (IE, Notepad, Paint, My Computer)
+  - Open paths (My Documents, My Pictures, Music)
+  - System actions (Control Panel mock, Run mock, Help mock, Log Off mock, Shutdown mock)
+- File Explorer:
+  - Back/Forward/Up icon-style nav buttons
+  - Root is conceptualized as "My Computer" (not Desktop)
+  - Quick Access sidebar with drives and key folders
+  - Virtual filesystem + openable txt/image/audio files
+- Custom right-click context menus:
+  - Desktop icons: Open, Open All Selected, Reset Icon Layout, Properties
+  - Explorer items: Open, Open in New Window (folder), Open Parent Folder (file), Properties
+
+## Important source files
+- UI shell markup: /home/diont/veryextra-arg-site/site/index.html
+- App logic: /home/diont/veryextra-arg-site/site/script.js
+- Styling: /home/diont/veryextra-arg-site/site/styles.css
+- Fake web pages index: /home/diont/veryextra-arg-site/site/fakeweb/index.json
+
+## Editing conventions / gotchas
+- Keep it dependency-free unless user asks otherwise (vanilla JS + static assets).
+- Prefer incremental patching in script.js; many features are interlinked through rerender() flows.
+- Explorer UI is re-rendered often; event listeners for explorer items/nav are rebound inside rerender().
+- If adding new Start items:
+  - data-open-app for ICON_APPS keys
+  - data-open-path for direct explorer paths
+  - data-system-action for action dispatcher
+- If touching context menu behavior, ensure hideContextMenu() is still triggered on:
+  - outside click
+  - escape key
+  - window resize
+  - global contextmenu fallback
+
+## Git / collaboration state
+- Default branch: main
+- Remote: origin https://github.com/diontimmer/VeryExtraOS-ARG.git
+- Repo is private.
+
+## High-value next steps (if requested)
+- Replace emoji icons with cohesive tiny bitmap icon set (16x16 + optional 24x24).
+- Add desktop-background context menu (View/Arrange/Refresh style).
+- Add mock Rename/Delete/New file-folder interactions in Explorer context menu.
+- Add command parsing to Run dialog.
diff --git a/README.md b/README.md
index 904fab1..844ee8a 100644
--- a/README.md
+++ b/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.