docs: add AGENTS handoff notes and comprehensive README
This commit is contained in:
Dion Timmer
69
AGENTS.md
Normal file
69
AGENTS.md
Normal file
@@ -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.
|
||||
114
README.md
114
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.
|
||||
|
||||
Reference in New Issue
Block a user