docs: add AGENTS handoff notes and comprehensive README

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.