docs: consolidate English documentation under root docs

2026-10-05 10:11:35 -03:00
parent b91762a927
commit 6b8c27fd76
38 changed files with 2261 additions and 5594 deletions
@@ -0,0 +1,50 @@
+# Vocero speech-to-speech
+
+Vocero provides a browser voice interface, a Python speech pipeline, and an
+optional Node-RED reasoning service. The interface defaults to Spanish;
+documentation, source identifiers, comments, and internal instructions use English.
+
+| Component | Purpose |
+|---|---|
+| [s2s-client](s2s-client) | Browser UI, FastAPI server, realtime WebSocket proxy, search and ApiPilot bridges |
+| [speech_to_speech](speech_to_speech) | Queue-driven VAD, speech recognition, language model, and speech synthesis pipeline |
+| [s2s-reasoning-engine](s2s-reasoning-engine) | Optional Node-RED HTTP reasoning and conversation logging flows |
+
+Start with [client setup and usage](docs/client/usage.md), then read the
+[architecture](docs/client/architecture.md) and [documentation index](docs/README.md).
+The speech backend needs its own installed model and runtime dependencies;
+`s2s-client/requirements.txt` installs only the UI server dependencies.
+
+## Run the browser client
+
+From the repository root, point the client at an existing realtime backend:
+
+```bash
+SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime ./start_ui.sh
+```
+
+Open <http://localhost:8420/> and allow microphone access. The launcher creates
+`.venv`, installs missing UI requirements, loads the root `.env` if present, and
+starts the server. For the local WebSocket proxy instead of a direct browser
+connection, configure `S2S_PROXY_TARGET` and leave `SPEECH_TO_SPEECH_URL` unset.
+
+To build the UI container, use the repository root as the Docker build context so
+the root documentation is included:
+
+```bash
+docker build -f s2s-client/Dockerfile -t s2s-client .
+docker run --rm -p 7860:7860 \
+  -e SPEECH_TO_SPEECH_URL=ws://localhost:8765/v1/realtime s2s-client
+```
+
+The direct WebSocket URL is resolved by the user's browser. For a server-side
+proxy deployment, supply a backend address reachable from the container instead.
+
+## Project references
+
+- [Change history](s2s-client/CHANGELOG.md)
+- [Realtime protocol and pipeline](docs/speech/realtime-api.md)
+- [Context injection](docs/client/context-injection.md)
+- [Tool calling](docs/client/tool-calling.md)
+- [Troubleshooting](docs/client/troubleshooting.md)
+- [Historical architecture proposal](docs/proposals/vocero-architecture.html)