Add portable SKILL.md

SKILL.md

@@ -0,0 +1,193 @@
+---
+name: icey-server-operator
+description: Safely build, validate, package, release, and operate the icey-server CLI and media server surface.
+---
+
+# icey-server Operator Workflow
+
+This is a portable skill document for agents working in `nilstate/icey-cli`.
+Use it to preserve the repo's build, validation, packaging, and operator bring-up conventions.
+
+The file is useful as plain project documentation. Tools that understand `SKILL.md`, including runx, can optionally pair it with execution, verification, and receipts.
+
+## Evidence Sources
+
+This workflow is grounded in these repo files:
+
+- `README.md`: native quick start, Docker demo path, repo workflow, runtime modes, endpoints, browser smoke notes, and bring-up order.
+- `CMakeLists.txt`: C++20 project shape, `ICEY_SOURCE_DIR`, icey component requirements, install layout, and web UI install destination.
+- `CMakePresets.json`: `dev` and `release` configure/build presets using a sibling `../icey` checkout.
+- `Makefile`: canonical wrapper targets for configure, build, web, install, package, release, Docker, and package-manager validation.
+- `web/package.json`: Vite build and Playwright smoke commands for Chromium, Firefox, WebKit, and Docker smoke.
+- `.github/workflows/ci.yml`: Linux CI contract using Ubuntu 24.04, GCC 13, pinned `ICEY_VERSION`, web build, staged install, browser smoke, and package-manager cutover.
+- `.github/workflows/release.yml`: release package, Docker image, GitHub release assets, and optional package-manager publication flow.
+- `.github/workflows/publish-package-managers.yml`: Homebrew, AUR, APT, and rendered manifest publication gates.
+- `packaging/README.md`: package-manager model, artifact names, generator scripts, and validation expectations.
+- `docker/README.md`: fastest demo path, host-networking assumptions, runtime overrides, and Compose source path.
+- `VERSION` and `ICEY_VERSION`: release context for this repo and the pinned core `nilstate/icey` dependency.
+
+At generation time this repo declared icey-server 0.1.3 and pinned icey 2.4.5.
+
+## When To Use This Skill
+
+Use this skill when an agent needs to:
+
+- change `icey-server` C++ server behavior, CLI flags, config handling, operator endpoints, or install layout
+- update the bundled web UI or browser smoke expectations
+- validate native builds against a sibling `nilstate/icey` checkout
+- modify Docker demo behavior or runtime environment variables
+- modify packaging, release metadata, package-manager manifests, or publication workflows
+- help an operator bring up `stream`, `record`, `relay`, TURN, RTSP, or TLS paths without mixing failure domains
+
+Do not use this skill to change core media primitives in `nilstate/icey`; that belongs in the core repo. This repo consumes the pinned core release through `ICEY_VERSION`.
+
+## Inputs To Inspect First
+
+Always inspect these before planning changes:
+
+- `README.md` for the public operator contract and CLI option list
+- `Makefile` for preferred local commands
+- `CMakePresets.json` and `CMakeLists.txt` for build shape and dependency wiring
+- `ICEY_VERSION` before assuming core API behavior
+- `.github/workflows/ci.yml` before changing validation expectations
+- `web/package.json` before changing browser smoke behavior
+- `packaging/README.md` and `scripts/*release*` before changing release or package-manager output
+- `docker/README.md` and `docker/*` before changing demo behavior
+
+If a requested change touches release output, inspect `VERSION`, `CHANGELOG.md`, `scripts/validate-release-metadata.sh`, and `scripts/package-manager-check.sh` in the same pass.
+
+## Safe Operating Rules
+
+- Keep the express demo path simple: `docker run --rm --network host 0state/icey-server:latest`, then `http://localhost:4500`.
+- Do not claim Safari support from Linux Playwright WebKit results; the README explicitly withholds that claim until Apple-platform validation exists.
+- Keep runtime bring-up staged: local `stream` without TURN, then `record`, then `relay`, then TURN-enabled external or NAT testing.
+- Treat `--doctor` as the first machine-readable preflight for operator-facing runtime changes.
+- Preserve the pinned `ICEY_VERSION` model. Do not silently float to `nilstate/icey` main in release or CI paths.
+- Keep package-manager output tied to real artifacts. Do not emit placeholder manifests for package managers without a matching archive and checksum.
+- Do not weaken CI coverage when changing C++, web UI, packaging, or release surfaces.
+- Do not add hosted service assumptions; the README positions the app as one binary plus local ports.
+
+## Workflow
+
+### 1. Classify The Change
+
+Map the request to one or more surfaces:
+
+- `server`: C++ server, CLI flags, config, endpoints, runtime modes
+- `web`: Vite UI, Symple client/player integration, browser smoke
+- `docker`: published image, Compose source path, host-networking demo
+- `packaging`: staged layout, tar/zip/deb/APT/package-manager manifests
+- `release`: VERSION, ICEY_VERSION, changelog, GitHub release assets, Docker Hub
+- `docs`: README, docker README, packaging README, operator instructions
+
+If the change crosses surfaces, plan validation for each touched surface before editing.
+
+### 2. Build Or Configure Locally
+
+Preferred source-backed path with the sibling `icey` checkout:
+
+```bash
+cmake --preset dev
+cmake --build --preset dev
+```
+
+Equivalent Makefile path:
+
+```bash
+make configure
+make build
+```
+
+If the sibling checkout is not at `../icey`, pass `ICEY_SOURCE_DIR=/path/to/icey` explicitly.
+
+### 3. Validate Runtime Readiness
+
+Use `--doctor` before claiming the server is runnable:
+
+```bash
+./build-dev/src/server/icey-server --doctor
+```
+
+For RTSP paths, start from the tracked example:
+
+```bash
+cp config.rtsp.example.json config.local.json
+$EDITOR config.local.json
+./build-dev/src/server/icey-server --config config.local.json --doctor
+./build-dev/src/server/icey-server --config config.local.json
+```
+
+For a browser-visible local app, build the web UI first:
+
+```bash
+make web-install
+make web-build
+./build-dev/src/server/icey-server --web-root web/dist --source /path/to/video.mp4
+```
+
+### 4. Validate Browser And Demo Paths
+
+For UI changes or media-path claims, run the Chromium smoke path that CI treats as authoritative:
+
+```bash
+npm --prefix web ci
+npm --prefix web run build
+npm --prefix web run test:smoke:chromium
+```
+
+For the published-image demo contract, keep the public command stable:
+
+```bash
+docker run --rm --network host 0state/icey-server:latest
+```
+
+For local source-backed Docker validation:
+
+```bash
+docker compose -f docker/compose.yaml up --build
+```
+
+### 5. Validate Packaging Or Release Changes
+
+For staged app layout changes:
+
+```bash
+make install
+```
+
+For release metadata only:
+
+```bash
+make release-metadata-check
+```
+
+For the full package-manager cutover contract:
+
+```bash
+make package-managers
+```
+
+This must validate Linux tar/zip archives, Debian package contents, APT repo archive, Homebrew formula, AUR PKGBUILD, Nix expression, SHA256SUMS, and Windows-facing manifests only when real Windows artifacts exist.
+
+### 6. Report Results
+
+A useful agent result should report:
+
+- changed surfaces
+- commands run
+- whether `ICEY_VERSION` was relevant
+- browser engine used for smoke validation
+- package artifacts validated, if any
+- runtime mode tested: `stream`, `record`, `relay`, TURN, RTSP, or TLS
+- any skipped validation and the concrete reason
+
+Do not collapse failures into generic language. If a check fails, preserve the exact command, exit behavior, and likely surface.
+
+## Expected Outputs
+
+For implementation work, produce a concise change summary plus validation evidence. For operator help, produce an ordered bring-up path with the first command the operator should run next. For packaging or release work, name every artifact family affected.
+
+## Optional Compatible Tooling Note
+
+This file is a portable `SKILL.md`. Agents and tools that understand `SKILL.md` can use it as repo workflow context. runx can optionally pair it with a registry binding for execution, verification, and receipts, but this repo does not require runx to use the file.
+