Refactor: move feature modules into packages/ (root layout cleanup)

[rosspeili]

Summary

Reorganize the OPSIE 0.3.80 XP codebase so the repository root stays focused on the entry point, operator config, assets, and governance, while feature modules live under a dedicated package directory (e.g. modules/ or opsie/). Today ~12 Python modules sit beside OPSIIE_0_3_80_XP.py, which complicates navigation, imports, and future packaging.

Parent epic: #20 (.github work is done; this was listed as out of scope there). Reference snapshot branch: 0_3_80_XP.

Problem

Current state	Pain
Flat root with mail.py, dna.py, markets.py, web3_handler.py, video.py, room.py, agentic_network.py, etc.	Hard to see what is “core” vs “plugin-like”
Main file imports many siblings by bare module name	Any move breaks imports, docs paths, and operator mental model
docs/MODULES.md and README layout table describe root files	Docs drift if structure changes without a deliberate pass

Proposed layout (starting point — refine in implementation)

Keep at repository root

• OPSIIE_0_3_80_XP.py — entry point (rename to opsie.py or similar is optional, separate decision)
• kun.py, kun.example.py — operator profiles (or config/ if agreed)
• requirements.txt, .env.example, LICENSE, governance (CONTRIBUTING.md, SECURITY.md, etc.)
• README.md, docs/, assets/, system_sounds/, .github/
• Shared UX/helpers if they stay “core-adjacent”: e.g. terminal_colors.py, help.py, utils.py (or move under opsie/core/ — decide in design comment on this issue)

Move under package (example: modules/ or opsie/modules/)

Module(s)	Area label
agentic_network.py	area:agentic
markets.py, markets_mappings.py	area:markets
web3_handler.py	area:web3
mail.py	area:mail
dna.py	area:dna
video.py	area:genai
room.py	area:rooms

Add __init__.py (or PEP 420 namespace layout) as needed so imports stay explicit and testable.

Acceptance criteria

• Root directory lists only entry, config/templates, assets, docs, governance, and agreed shared helpers
• Feature code lives under the new package path with working imports
• Documentation reflects the new layout
• Smoke path above passes on Windows (primary platform)
• Changes are one focused PR series (or sub-issues) — not mixed with unrelated features

Suggested implementation phases (optional sub-issues)

1. Design — comment on this issue with final tree + import style (from modules.mail import … vs opsie.mail)
2. Move + imports — mechanical refactor PR
3. Docs — README + docs/ alignment PR if split for review

Related

• Infrastructure: add .github directory (templates, PR template, CI/CD, docs) #20 — infrastructure epic
• Branch 0_3_80_XP — pre-refactor reference
• docs/MODULES.md — current module map

Nature of work (informational)

Refactor — same intended behavior, cleaner structure

Primary area

Cross-cutting / multiple modules

Also affects (optional)

Not applicable

Scope and files

• Agree final directory name (modules/ vs opsie/ package) and what stays at root
• Move files; update all imports in OPSIIE_0_3_80_XP.py and cross-module imports
• Preserve lazy-load behavior (e.g. Web3) and boot order
• Update docs/MODULES.md, docs/ARCHITECTURE.md, docs/COMMANDS.md, README layout table, CONTRIBUTING.md dev paths if needed
• Smoke test: theme → splash → gate → boot → interactive loop; spot-check /markets, /mail, /0x, /room, /dna, /video on a dev machine
• No secrets or production kun.py in the diff

Out of scope (unless explicitly added)

• Renaming OPSIIE_0_3_80_XP.py (can be follow-up)
• Splitting the monolith into installable Skillware packages
• CI/CD pipeline (Infrastructure: add .github directory (templates, PR template, CI/CD, docs) #20 sub-issue — separate)
• Behavior changes beyond import/path fixes

Risks or breaking changes

• Windows path assumptions and system_sounds/ relative paths
• Global state and circular imports when package boundaries change
• External docs or forks that reference old root module paths

Checklist

• I explained why this is maintenance rather than a feature request
• I searched existing issues for overlapping refactors