autoyou-lite Engineering Guardrails

Scope
- Applies to the autoyou_lite/ directory.
- This is the lightweight AutoYou server package, not the full server.py runtime.

Critical files
- server.py
- config.py
- admin_ui.py
- ai_backend.py
- cloud_pairing.py
- sessions.py
- persisted_config.py
- __main__.py
- _runtime/

Primary goal
- Keep autoyou-lite a thin, stable pairing, WebRTC, browser-proxy, audio, and AI-gateway package that can run standalone or inside the main repo.

Critical invariants

1) Public versus internal API contract
- Public auth and signaling surface stays compatible with the AutoYou app:
  - POST /auth
  - POST /signal/{session_id}
  - GET /signal/{session_id}
- Internal localhost API remains the orchestration surface:
  - GET /api/v1/status
  - GET /api/v1/sessions
  - POST /api/v1/pair
  - POST /api/v1/send/{sid}
  - POST /api/v1/speak/{sid}
  - GET /api/v1/events
- OpenAI-compatible chat entrypoints remain under /v1/...

2) Lightweight boundary
- autoyou-lite is intentionally lighter than the full AutoYou server.
- The full runtime is now composed from root server.py, core_server/, and routers/; those modules are not part of Lite and must not be copied here to solve full-server packaging or import failures.
- Do not add the full ADK root-agent install or uninstall workflow, full messaging-partner orchestrators, or unrelated server-only admin surfaces here.

3) Pairing security compatibility
- User-facing pairing modes remain open, secure, and secure-pro. The admin-only
  `secure_professional_maximus` mode adds local at-rest protection while Lite
  continues to expose the established `secure-pro` pairing wire mode to clients.
- Legacy aliases normal, otp, and password remain compatibility shims where already supported.
- Do not break /pair, /autopair, encrypted /otp, or encrypted /autopair_answer compatibility with existing clients.

4) Shared transport compatibility
- The packaged _runtime helpers must stay wire-compatible with the full repo transport contract.
- Keep canonical DataChannel message types, chunking, SSE relay, WebSocket relay, HTTP proxy flow, and voice control flow aligned with the main repo runtime.

5) Config and env contract
- Default ports remain 8099 for the internal API and 8098 for auth/signaling.
- Keep AUTOYOU_LITE_*, AUTOYOU_AGENT_URL, OPENCLAW_*, HERMES_*, and cloud pairing env names stable unless you provide a coordinated migration.
- config.py is the source of truth for runtime settings and defaults.

6) AI routing boundary
- autoyou-lite may route through Ollama, OpenClaw-compatible APIs, Hermes, or the AutoYou AI agent.
- Keep provider selection rules centralized in config.py and ai_backend.py.
- Do not scatter backend-selection logic across unrelated request handlers.
- /v1/chat/completions (oai_chat_completions) routes by the SAME precedence as the datachannel dispatch: openclaw_api to hermes (provider+hermes_api) to agent_url to Ollama (explicit or local fallback). Keep the two in lockstep.
- All providers (ollama/openclaw/hermes/custom/none) are admin-UI selectable. Adding or persisting a provider field is a 4-layer change: admin_ui.py (dropdown + section + save/load), AdminSaveRequest (server.py), persisted_config.py (_PERSISTED_CONFIG_KEYS + defaults), and config.py (LibConfig + to_runtime_dict for round-trip). Missing any layer silently drops the value.

7) Repo-root optionality
- When running inside the AutoYou checkout, the package may reuse repo-shared runtime helpers.
- When running standalone, it must degrade gracefully instead of crashing on missing repo-only modules.

8) Package entrypoint stability
- python -m autoyou_lite must continue to work through __main__.py.
- Keep the CLI and programmatic wrapper contracts aligned with the published package behavior.

Change checklist
- If you change pairing payloads or message types, update the full repo clients and the OpenClaw extension together.
- If you change config keys or defaults, update README.md, CLI help, and any package-publish notes.
- If you change _runtime transport helpers, verify they still match the full server transport semantics.
- If you change AI routing behavior, verify both direct app messaging and /v1/chat/completions.

Do not do casually
- Turn autoyou-lite into a second copy of the full AutoYou server.
- Rename public or internal API paths without a coordinated client migration.
- Drift the lightweight runtime away from the shared DataChannel contract.
- Break standalone execution by assuming the full repo is always on disk.

Minimum validation after runtime changes
- Run "python -m autoyou_lite --help".
- Exercise /pair or /autopair through "POST /api/v1/pair".
- Verify /auth and /signal/{session_id} still support a client pairing flow.
- Verify /api/v1/status and /api/v1/events.
- Verify /v1/chat/completions still reaches the configured backend.
