Expand documentation hub (introduction, contributing index, usage cross-links)

[rosspeili]

Problem Statement

Skillware splits docs by audience: docs/introduction.md (architecture), docs/vision.md (roadmap/story), docs/usage/ (how-to), docs/contributing/, plus root COMPARISON.md / SECURITY.md. README has a documentation table linking all entry points.

Rooms has solid content in ARCHITECTURE.md and EXAMPLES.md but no doc hub, no vision/roadmap doc (roadmap is only "see GitHub Issues"), and settings/Ollama/preflight behavior is scattered. Issue #33 covers defaults vs overrides partially; this issue is the information architecture pass to match Skillware tightness without duplicating every paragraph.

Proposed Solution

1. Add docs/README.md (documentation index) listing:

   • Architecture & LiteLLM → ARCHITECTURE.md
   • Examples & scenarios → EXAMPLES.md
   • Testing → TESTING.md
   • Contributing → ../CONTRIBUTING.md
   • Agent workflow → contributing/ai_native_workflow.md
   • Changelog → ../CHANGELOG.md

2. Optional split (if not too churny):

   • docs/introduction.md — short onboarding extracted from README + ARCHITECTURE lead
   • Keep ARCHITECTURE.md for deep session/memory/routing detail

3. Add missing user-facing sections (can be sections within existing files):

   • Settings YAML reference table (keys, search paths, preflight, --skip-preflight) — complements Document global YAML defaults vs per-agent overrides in settings docs #33
   • Install paths: clone vs future pip install (stub until PyPI issue lands)

4. README Documentation Library → link docs/README.md as the hub.

5. Fix README project structure (rooms/__init__.py, ollama_preflight.py, test files) to match current tree.

Acceptance criteria

• Doc hub exists; README points to it
• No broken relative links
• Preflight and settings init documented in one discoverable place
• Overlap with Document global YAML defaults vs per-agent overrides in settings docs #33 called out: Document global YAML defaults vs per-agent overrides in settings docs #33 = semantics of defaults; this issue = structure/navigation

Alternatives Considered

• MkDocs / GitHub Pages site — defer; Skillware also uses in-repo markdown first.
• One giant ARCHITECTURE.md — rejected; harder for newcomers and agents to navigate.

Priority

Low 🟢

Additional Context

Skillware refs: docs/introduction.md, docs/vision.md, docs/usage/README.md, README documentation table.

Related open issues: #33 (defaults docs), #32 (config path filename).