Bring untracked local design/setup docs into the repo (#165)

## Summary

Several design and setup docs were sitting in a gitignored `ldocs/`
directory outside the repo. Reviewed them all and moved the ones that
are still accurate/useful into `docs/`, fixing them up along the way;
the rest were left out (stale planning artifacts, scratch notes, or
personal deploy scripts hardcoded to specific hosts/IPs).

- **`docs/development/guest-identity.md`** and
**`guest-identity-implementation.md`** — the guest identity design docs.
Turned out to be load-bearing: `kbox/identity.py`, `merge_users.py`,
`user.py`, `database/users.py`, and `web/server.py` all cite
`ldocs/GUEST_IDENTITY_CONTINUITY.md` /
`ldocs/GUEST_IDENTITY_TECHNICAL_DESIGN.md` by path as their design
rationale — a dead link for anyone cloning the repo. Repointed every one
of those in-code references to the new tracked paths.
- **`docs/development/relay-proposal.md`** — the cloud-relay proposal
these docs reference as future context.
- **`docs/setup/youtube-api.md`** (new directory, for operator-facing
setup guides as distinct from developer guidance) — API key setup
walkthrough, with the stale "configure via a script that no longer
exists" step replaced by the actual web UI config-screen flow. Linked
from both Quick Start sections in README.
- **`docs/development/macos-setup.md`** — macOS dev environment setup,
trimmed of a `run_kbox.sh` wrapper script reference that doesn't exist
in the repo.
- Folded the dual-HDMI-display `kmssink` investigation into
`gstreamer-pipeline.md`'s existing "Traps" section as a new entry,
rather than keeping it as a standalone file.

Left out: an old pre-implementation architecture doc (superseded by the
actual code), scratch notes, an empty test-plan file, a karaoke
party-lifecycle reference doc (vision doc, not useful to future
contributors), onboarding notes built around scripts that no longer
exist, and two personal deploy scripts hardcoded to specific hosts.

## Test plan

- [x] `uv run ruff check .` / `mypy` / pre-commit hooks all pass (ran
automatically on commit)
- [ ] Skim the new/moved docs for accuracy against current behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: mdz

README.md

@@ -50,6 +50,7 @@ All settings are managed through the web UI with a schema-driven settings panel:
 - [YouTube IFrame Player API](https://developers.google.com/youtube/iframe_api_reference) for the display page
 - [YouTube Data API v3](https://developers.google.com/youtube/v3) for search
 - [LiteLLM](https://github.com/BerriAI/litellm) for AI suggestions and metadata extraction
+- `signalsmithpitch` — a native GStreamer element (`native/gst-signalsmith-pitch/`) for real-time pitch shifting, built on [signalsmith-stretch](https://github.com/Signalsmith-Audio/signalsmith-stretch)
 
 ## Quick Start (Docker)
 
@@ -58,7 +59,7 @@ docker-compose build
 docker-compose up
 ```
 
-Then open `http://localhost:8000` in your browser and configure your YouTube API key in Settings.
+Then open `http://localhost:8000` in your browser and configure your YouTube API key in Settings (see `docs/setup/youtube-api.md` if you need help getting one).
 
 ## Quick Start (Native)
 
@@ -67,7 +68,15 @@ uv sync
 uv run python -m kbox.main
 ```
 
-Open `http://localhost:8000` on your phone to queue songs, and `http://localhost:8000/display` on your TV/monitor for the fullscreen karaoke display. Configure your YouTube API key in Settings.
+Open `http://localhost:8000` on your phone to queue songs, and `http://localhost:8000/display` on your TV/monitor for the fullscreen karaoke display. Configure your YouTube API key in Settings (see `docs/setup/youtube-api.md` if you need help getting one).
+
+Pitch shifting requires the native `signalsmithpitch` GStreamer plugin, which the Docker image builds automatically but a native install does not — without it kbox falls back to no pitch shifting. Build it once with:
+
+```bash
+native/gst-signalsmith-pitch/build.sh
+```
+
+See `native/gst-signalsmith-pitch/README.md` for build requirements.
 
 ## Platform Support
 

docs/development/gstreamer-pipeline.md

@@ -347,6 +347,32 @@ fixing, not its resolution.
 Useful when investigating: `GST_DEBUG=kmssink:7` prints the plane rectangle it
 actually programs, which beats guessing from what the screen looks like.
 
+### `kmssink` cannot run two instances against one DRM device
+
+The Pi 5 has two micro-HDMI ports and the hardware fully supports driving
+both independently — the DRM connectors enumerate fine in `/sys/class/drm/`,
+each at its own connector ID. It is tempting to route a `tee` into two
+`kmssink`s, one per `connector-id`, to show different overlays on each
+display. This fails:
+
+```
+drmModeSetPlane failed: Permission denied (13)
+```
+
+or a "failed to configure video mode" error, depending on the exact
+combination of properties tried. Each `kmssink` instance tries to become DRM
+master, and they conflict — this held across privileged Docker mode, adding
+the `video`/`render` groups, and toggling `force-modesetting`, so it is not a
+permissions issue to work around.
+
+Two real options if independent per-display overlays are ever needed: switch
+to a Wayland/Weston compositor and `waylandsink` (significant pipeline
+changes), or drive both outputs with identical content via OS-level display
+mirroring (`wlr-randr`/`xrandr`), which needs no pipeline changes at all. For
+same-content-on-both-screens (the common karaoke case), a plain HDMI
+splitter downstream of a single `kmssink` sidesteps the problem entirely and
+is what kbox uses today.
+
 ### `textoverlay` already scales its own font
 
 `auto-resize` is on by default and scales the font relative to a 640-pixel-wide

docs/development/guest-identity-implementation.md

@@ -0,0 +1,53 @@
+# macOS Setup Guide
+
+## Prerequisites
+
+1. **Install Homebrew** (if not already installed):
+   ```bash
+   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+   ```
+
+2. **Install GStreamer and dependencies**:
+   ```bash
+   brew install gstreamer glib pygobject3
+   ```
+
+3. **Install Python dependencies**:
+   ```bash
+   uv pip install pygobject pycairo
+   ```
+
+## Running kbox
+
+Due to macOS's library path restrictions, GStreamer needs a few environment
+variables set before it will load:
+
+```bash
+export DYLD_LIBRARY_PATH="$(brew --prefix glib)/lib:$(brew --prefix gstreamer)/lib:$DYLD_LIBRARY_PATH"
+export GI_TYPELIB_PATH="$(brew --prefix gstreamer)/share/gir-1.0:$GI_TYPELIB_PATH"
+export GST_PLUGIN_PATH="$(brew --prefix gstreamer)/lib/gstreamer-1.0:$GST_PLUGIN_PATH"
+
+uv run python -m kbox.main
+```
+
+## Troubleshooting
+
+### "No module named 'gi'"
+- Install pygobject: `uv pip install pygobject`
+
+### "Failed to load shared library 'libglib-2.0.0.dylib'"
+- Set `DYLD_LIBRARY_PATH` as shown above.
+
+### "Could not locate g_option_error_quark"
+- This is a library path issue. Set the environment variables above.
+
+## Note on Python Version
+
+The project uses Python 3.9.6 by default (from Xcode). For better compatibility, consider using Python 3.10+ via Homebrew:
+
+```bash
+brew install python@3.12
+uv python install 3.12
+```
+
+Then use: `uv run --python 3.12 python -m kbox.main`