docs: refresh roadmap and modularization contribution guidance

ROADMAP.md

@@ -1,87 +1,102 @@
 # Roadmap / Help Wanted
 
-Odysseus is on a voyage, but not home yet. It works great for me (lol), but this ship is moving fast and feedback/help would be appreciated! (I don't know what I'm doing, help).
+Odysseus is an evolving self-hosted AI workspace. This roadmap highlights the areas where improvements and contributions are most useful.
 
-If you see weird CSS, strange layout behavior, or a suspiciously murky corner of
-the codebase, you are probably right to stay away.
+It describes current direction, not a fixed release schedule or a complete issue backlog. Specific implementations should be coordinated through existing issues and pull requests.
 
-## High Priority
+Contributions target `dev`. The `main` branch is curated for releases.
 
-- SQUASH BUGS
-- Fresh install smoke tests on Linux, macOS, and Windows. Docker, native Python,
-  and WSL all need coverage.
+## Stabilization and reliability
 
-- Integration audit: do integrations even work? Confirm what works, what needs setup docs, and what should be removed or hidden. 
-- Cookbook reliability on other computers. This is probably the area most likely to need work across different machines, GPUs, drivers, shells, and Python environments.
-- Cookbook SGLang support across platforms. Make sure SGLang setup/serve works
-  predictably on Linux, Windows/WSL, macOS where possible, Docker, and common
-  NVIDIA/AMD hardware paths.
-- Deep Research model presets by hardware. Recommend approved model/parameter
-  profiles for small, medium, and large local setups so people with different
-  hardware can use Deep Research without guessing. Surface this either in Deep
-  Research settings or as a Cookbook scan/dropdown suggestion.
-- Cookbook model scan/download ranking. Prioritize newer architectures and
-  better hardware-fit models instead of scoring everything almost the same.
-  Ranking should account for architecture age, quant format, VRAM/RAM fit,
-  backend support, vision/mmproj requirements, and likely serve reliability.
-- Cookbook error feedback and logging. Failed downloads, dependency installs,
-  preflights, and serve jobs should show the actual command/output/error in the
-  UI, with copyable logs and clear next steps instead of just "crashed".
-- Agent prompt/context bloat. Agent mode is too heavy for smaller local models:
-  tool schemas, skills, memory, documents, and instructions can eat the context
-  before the user request really starts. We need slimmer prompts, better tool
-  selection, smaller default tool sets, and clearer guidance for models with
-  4k/8k/16k context windows.
-- Local model speculative decoding support. For Odysseus-tuned local models,
-  plan to ship or recommend a small same-tokenizer draft model when the serving
-  backend supports it. Early vLLM testing showed a generic `Qwen3-0.6B` draft
-  beside `Qwen3-8B` can materially reduce wall time, while an unsupported
-  DSpark conversion performed poorly. Treat this as a supported draft-model lane
-  first; keep MTP-specific packaging as future work only when the architecture
-  and runtime support are real. Judge this by time-to-success, tool correctness,
-  grammar, and unchanged target output, not tokens/sec alone.
-- Skill/tool prompt-injection audit. User-editable skills, notes, documents,
-  fetched pages, and memories should be treated as untrusted data. Keep testing
-  whether models follow malicious instructions from those surfaces.
-- Better degraded-state reporting for ChromaDB, SearXNG, email, ntfy, and provider probes.
-- Email performance audit. Fetching, searching, opening, deleting, and sending
-  email can feel slow, especially over IMAP/SMTP providers with high latency.
-  Need someone who knows mail performance to profile the current flow, identify
-  whether the bottleneck is IMAP folder select/fetch, cache invalidation,
-  attachment/body loading, SMTP handshakes, or frontend refresh behavior, then
-  propose safer caching/prefetch/batching without breaking multi-account state.
-- Provider setup/probing audit for Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI, and DeepSeek.
+Reliable operation across installations, platforms, providers, and supported hardware remains a priority.
 
-## Refactor Targets
-- CSS cleanup. `static/style.css` basically Calypso's island atm.
-- Tour core helper. The onboarding tours have too much copy-pasted scaffolding; promote a shared `tour-core.js` helper before adding more tours.
-- Modal/window positioning cleanup. Some window controls have improved, but the
-  underlying popup/dropdown/fixed-position behavior is still too fragile.
-- Mobile media override discoverability. A lot of "CSS did not move" bugs are mobile `@media` overrides of the same selector; comments or linting around desktop/mobile paired rules would help.
-- Dead code pass for old routes, stale feature flags, and unused UI states.
+- **CI and validation:** Improve the reliability of automated checks, exact-revision validation, and release confidence. See #5932 and the confirmed docs-only CI regression, #7109.
+- **Test quality:** Continue improving deterministic tests, isolation, focused execution, and maintainable test structure. See #2523 and the [testing standard](tests/TESTING_STANDARD.md).
+- **Fresh installations:** Expand smoke-test coverage for native Linux, macOS, Windows, WSL, and Docker. Verify clean startup, health reporting, and graceful handling of unavailable optional services. See #3968.
+- **Cookbook reliability:** Improve model installation, dependency management, hardware detection, and serving across supported platforms, GPUs, drivers, and execution backends.
+- **Email integration:** Resolve remaining Google OAuth regressions, preserve account isolation, and improve cross-provider reliability. See #5637.
+- **Storage integrity:** Investigate upload payloads, database growth, indexing, and file lifecycle without introducing unsafe or destructive cleanup. See #4889.
+- **Security:** Continue hardening authorization, agent tool execution, prompt-injection boundaries, filesystem access, and handling of untrusted content.
+- **Integration diagnostics:** Verify provider and optional-service behavior, improve failure reporting, and ensure unavailable dependencies degrade predictably.
 
-## Frontend
+Current stabilization work is coordinated through the [Stabilization & Modularization milestone](https://github.com/odysseus-dev/odysseus/milestone/1).
 
-- Expand the Editor for quicker, more robust everyday use. Better file/document
-  handling, smoother window behavior, clearer save/export flows, stronger image
-  editing affordances, and fewer brittle edge cases.
-- Better AI integration for Notes and Todos. Notes should be easier for the
-  agent to read, update, summarize, and turn into actions. Todos should be
-  assignable to an agent from the UI, possibly through a button, task action,
-  or dedicated skill/tool flow.
-- Mobile gallery/editor polish. Easier to launch/download inpaint model or any missing pieces.
-- Accessibility pass: keyboard navigation, focus states, contrast, reduced motion.
-- Improve empty states and error messages on fresh installs.
-- Tighten first-run setup, hints, and tours so they do not repeat or fight each other.
-- Vendor CDN assets eventually for a more fully self-hosted/offline mode.
+## Modularization and maintainability
 
-## Backend
+The goal is to make the codebase easier to navigate, test, review, and extend while preserving existing behavior and compatibility.
 
-- More tests around endpoint probing and provider setup.
-- Better task scheduler defaults and visibility.
-- Backup/restore guide and helper flow for `data/`.
-- Security hardening around admin-only tools and clear docs for their risk.
+The initial CSS extraction and substantial tool-domain decomposition have established a foundation, but responsibility boundaries still need improvement.
 
-## Not The Focus Right Now
+Current areas of interest:
 
-I prob shouldnt add more themes.
+- **Frontend:** Continue focused decomposition of large document, gallery, settings, calendar, and other UI modules.
+- **CSS:** The former `static/style.css` has been split into ordered files under `static/css/`. Improve maintainability without inadvertently changing cascade order, theme behavior, or responsive layouts.
+- **Tools:** Continue clarifying ownership within `src/agent_tools/` and related implementations while preserving existing public contracts and compatibility.
+- **Backend:** Identify safe boundaries in large Cookbook routes, persistence modules, and feature-specific route handlers.
+- **Tests:** Keep test helpers, fixtures, and focused test ownership aligned with the implementation modules they exercise.
+- **UI infrastructure:** Reduce duplicated tour scaffolding, fragile modal/window positioning, stale feature flags, and cross-feature coupling.
+
+[#4071](https://github.com/odysseus-dev/odysseus/issues/4071) is the canonical coordination tracker for this work.
+
+Larger PRs can be appropriate for a single coherent decomposition when splitting the work into many smaller PRs would create unnecessary integration complexity. Coordinate the intended boundary before implementation and provide meaningful regression and runtime validation.
+
+### Agent runtime and Harness V2
+
+Harness V2 is under active development.
+
+The agent runtime, including `src/agent_loop.py` and closely related execution, authorization, orchestration, and context contracts, is temporarily frozen for unrelated changes while that work is developed and validated.
+
+Agent-runtime refactors must be coordinated with maintainers. Urgent bug and security reports remain welcome.
+
+This restriction does not apply to unrelated application modules.
+
+## AI, local models, and research
+
+The following improvements remain areas of product interest. Their exact implementations and priority relative to one another require normal issue triage and product decisions.
+
+- **Smaller-model agent efficiency:** Reduce unnecessary prompt, tool-schema, skill, memory, and document context overhead. Improve tool selection and behavior with constrained context windows.
+- **Cookbook SGLang support:** Improve setup and serving across relevant operating systems, hardware, and deployment methods.
+- **Model discovery and ranking:** Recommend appropriate models using architecture, quantization, RAM/VRAM availability, backend support, multimodal requirements, and expected serving reliability.
+- **Deep Research presets:** Explore hardware-appropriate model and parameter configurations for smaller and larger local systems.
+- **Cookbook diagnostics:** Expose actionable installation, download, preflight, and serving failures with useful, copyable logs.
+- **Speculative decoding:** Investigate supported draft-model configurations for compatible local backends. Evaluate end-to-end correctness and time to successful output, not throughput alone.
+- **Provider setup and probing:** Improve integration quality for supported local and hosted providers, including endpoint discovery and capability handling.
+
+## Frontend and user experience
+
+- Improve document and file editing, window behavior, save/export flows, and image-editing reliability.
+- Expand agent-assisted workflows for Notes and Todos, including reading, updating, summarizing, and turning information into actionable tasks.
+- Improve the mobile gallery and editor experience.
+- Strengthen keyboard navigation, accessibility, focus behavior, contrast, and reduced-motion support.
+- Improve first-run setup, empty states, error messages, and onboarding guidance.
+- Improve desktop/mobile CSS maintainability and responsive behavior.
+- Continue reducing unnecessary external asset dependencies where practical for self-hosted and offline operation.
+
+## Backend and operations
+
+- Improve email performance through measured investigation of fetching, caching, attachment handling, searching, and sending.
+- Expand regression coverage for provider setup, endpoint probing, and degraded service states.
+- Improve task-scheduler defaults, reliability, and operational visibility.
+- Improve backup and recovery guidance for persistent application data.
+- Continue reviewing administrative capabilities, sensitive integrations, and their authorization boundaries.
+
+## Not a current priority
+
+- Adding more themes without a clear product need.
+- Broad rewrites without demonstrated value.
+- Framework migrations or architectural changes undertaken solely to reduce file counts.
+- Uncoordinated changes to the temporarily frozen agent-runtime contracts.
+
+## Contributing
+
+Before starting work:
+
+1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
+2. Search existing issues and PRs to avoid duplicating work.
+3. Coordinate structural changes through #4071 and stabilization work through the milestone.
+4. Open a focused issue where needed and follow the existing contribution templates.
+5. Provide relevant tests, runtime evidence, and screenshots or recordings for visual changes.
+
+For changes involving product direction or difficult-to-reverse contracts, follow the [feature proposal process](docs/maintainers/product-and-features.md).
+
+Security vulnerabilities must be reported privately through [SECURITY.md](SECURITY.md).