# Jibo Hub-Shim Server: Deployment & Usage Guide

## Quick Start
1. **Install dependencies** (if needed):
   - Node.js v16+ (recommended v18+)
   - `npm install` (if package.json present)
2. **Configure**:
   - Edit `config.json` (or use `config.example.json`):
     - `listen.port`: Port to listen on (default: 9000)
     - `listen.path`: WebSocket path (default: `/v1/listen`)
     - `asr.baseUrl`: Local ASR HTTP endpoint
     - `logging.level`: `info`, `debug`, etc.
3. **Run the server**:
   ```sh
   node index.js config.json
   ```
   - Or set `JIBO_HUB_SHIM_CONFIG` env var.

## Integration with Jibo Robot
- The robot's `jibo-jetstream-service` binary must be configured to connect to the hub-shim:
  - `hub_port`: 9000 (or your chosen port)
  - `hub_hostname`: IP of the machine running hub-shim
  - `listen_url`: `/v1/listen`
- Confirm with logs: hub-shim should show `ws connected` and `listen result` for each turn.

## How It Works
- The robot opens a WebSocket to hub-shim for every listen turn.
- hub-shim receives CONTEXT and LISTEN messages, runs ASR/NLU, and sends a TURN_RESULT.
- The TURN_RESULT is always local (`global: false`), with `status: 'SUCCEEDED'` and the correct intent/entities.
- This resolves the skill's local turn and allows menu/intro flows to advance by voice.

## Troubleshooting
- **No skill advancement?**
  - Check that TURN_RESULT is sent with `status: 'SUCCEEDED'`, `global: false`, and correct `requestID` (should match transID).
  - Use robot-logger (`/tmp/jibo-skills.log` or web panel) to trace intent and state.
- **ASR timeouts?**
  - Ensure ASR service is running and reachable from hub-shim.
- **NLU not matching?**
  - Edit `inferNluFromText()` in `index.js` to adjust rule patterns.

## Advanced
- **Custom NLU**: You can extend `inferNluFromText()` for more complex intent/entity extraction.
- **Client-supplied ASR/NLU**: Send CLIENT_ASR or CLIENT_NLU messages before LISTEN to inject results.
- **Logging**: Adjust `logging.level` in config for more/less verbosity.

## File Locations
- Main server: `index.js`
- Config: `config.json` or `config.example.json`
- Protocol doc: `HUB-SHIM_PROTOCOL.md`

## Support
- For protocol or integration issues, see HUB-SHIM_PROTOCOL.md and the source code comments.
- For robot-side debugging, use robot-logger and check `/tmp/jibo-skills.log`.

---

# Enjoy fully offline Jibo skills and menus!