# Oclaw Migration Guide

This repository now uses **repo-root relative** runtime wiring.

## Current status
- The repository root is the only runtime base path.
- `oclaw/app_server/*` compatibility modules have been removed.
- Gateway dispatch now routes through shared `server_methods` handlers for both WS and HTTP method endpoints.

## Path baseline (important for open-source portability)
- Do not hardcode `PROJECT_ROOT / "oclaw" / ...`.
- Use repo-root relative paths such as:
  - config: `oclaw.json`
  - data: `data/ai_ops.sqlite`
  - workspaces: `runtime/workspaces/*`
  - wiki root default: `docs/memory-system/wiki`
- Startup scripts should run from repo root and explicitly set workspace env vars; avoid relying on parent-directory cwd.

## Developer rules
- Add new business logic under `oclaw/` (interfaces/application/domain/infrastructure/shared).
- Avoid adding new core logic into legacy `oclaw/` modules.
- Keep `oclaw/` changes limited to re-export or compatibility adaptation.
- Before deleting compatibility modules, use:
  - `oclaw/docs/OCLAW_COMPAT_REMOVAL_CHECKLIST.md`

## Runtime notes
- Gateway HTTP method adapter: `POST /gateway/method`
- WS dispatch first resolves method handlers from shared dispatcher.
- Inbound payload use-case entrypoint: `runtime.application.gateway.process_inbound_payload_usecase`
- HTTP app entrypoint moved to: `interfaces.http.fastapi_app`
- WS entrypoint moved to: `interfaces.ws.entrypoint`
- WS runtime bridge path: `interfaces.ws.runtime`
- WS runtime implementation seam:
  - `oclaw/interfaces/ws/runtime_impl.py`
  - `runtime.py` points to this module as stable import surface.
- Server-method WS bridge extracted to:
  - `oclaw/interfaces/ws/server_methods_bridge.py`
  - legacy class now delegates dispatch/context construction to this bridge.
- Agent turn execution extracted to:
  - `oclaw/interfaces/ws/turn_runner.py`
  - legacy `run_agent_turn` now delegates to this module.
- WS request dispatch path is now single-source:
  - connected requests go through `server_methods` bridge first;
  - unknown methods return standardized invalid-request errors.
- Legacy WS `handle_*` and schema-specific validate helpers were removed from the class;
  runtime behavior now comes from dispatcher + bridge modules.
- WS schema access is now routed via:
  - `oclaw/interfaces/ws/ws_schema.py`
  - legacy gateway imports schema helpers through the oclaw namespace.
- WS schema implementation has been migrated to:
  - `oclaw/interfaces/ws/schema_impl.py`
  - no legacy `oclaw/app_server/ws_schema.py` dependency remains.
- WS auth + hello payload builders moved to:
  - `oclaw/interfaces/ws/auth_and_hello.py`
  - legacy gateway delegates `resolve_ws_auth` and `build_hello_ok`.
- WS frame/event emit helpers moved to:
  - `oclaw/interfaces/ws/events.py`
  - legacy gateway delegates `send_res/send_event/emit_*`.
- WS runtime helpers moved to:
  - `oclaw/interfaces/ws/runtime_helpers.py`
  - legacy gateway delegates `_recv_frame` and `_handle_connect`.
- WS main loop + close behavior moved to:
  - `oclaw/interfaces/ws/runtime_loop.py`
  - legacy gateway delegates `run()` and `_close_ws()`.
- WS connected-request dispatch moved to:
  - `oclaw/interfaces/ws/runtime_dispatch.py`
  - legacy gateway delegates `_dispatch_connected()`.

## Extension source policy
- Primary source: `oclaw/extensions/`
- Legacy root `extensions/` has been merged into `oclaw/extensions/` and removed.

## Prompt and skills policy
- Role context is loaded from `oclaw/runtime/workspaces/*`.
- Skills root priority:
  1. `AIA_SKILLS_ROOT`
  2. `oclaw/skills`（仓库根）
  3. `oclaw/runtime/skills`（旧布局，若仍存在则 `runtime_skills_root()` 会回退）