From 7f922c0aa49c30d6f34d089723e606c60515ddb5 Mon Sep 17 00:00:00 2001
From: Andres Cera <Andres.cera@hotmail.com>
Date: Mon, 1 Jun 2026 01:44:46 -0500
Subject: [PATCH] docs(agents): add group-aware AGENTS.md (root +
 bindings/typescript)

---
 AGENTS.md                     | 67 +++++++++++++++++++++++++++++++++++
 bindings/typescript/AGENTS.md | 38 ++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 bindings/typescript/AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..10ca5e0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,67 @@
+# ceracoder
+
+Parent: [../AGENTS.md](../AGENTS.md)
+
+## ROLE IN THE GROUP
+
+GStreamer-based hardware video encoder. Reads a pipeline from file, streams output over SRT with dynamic bitrate control. Fork of [irlserver/belacoder](https://github.com/irlserver/belacoder) (itself from BELABOX/belacoder).
+
+**Depends on:** `libsrt` (compile-time, `pkg-config srt`), GStreamer 1.0  
+**Consumed by:** CeraUI backend (TypeScript bindings at `bindings/typescript`), device image (packaged as `belacoder` .deb)
+
+## STRUCTURE
+
+```
+ceracoder/
+├── src/
+│   ├── ceracoder.c          # entry point
+│   ├── core/                # bitrate control, balancers, config
+│   ├── gst/                 # encoder_control, overlay_ui
+│   ├── io/                  # cli_options, pipeline_loader
+│   └── net/                 # srt_client
+├── camlink_workaround/      # submodule → BELABOX/camlink.git
+├── bindings/typescript/     # TS bindings consumed by CeraUI backend
+├── docs/                    # architecture, bitrate-control, dependencies, versioning
+├── tests/                   # cmocka unit tests
+└── Makefile                 # primary build entry
+```
+
+## BUILD
+
+```bash
+# Requires: libsrt >= 1.4.0, gstreamer-1.0, gstreamer-app-1.0, cmocka (tests)
+make              # builds ceracoder binary; inits camlink_workaround submodule
+make test         # runs cmocka tests
+```
+
+`VERSION` = `git rev-parse --short HEAD` (short SHA, not semver). Baked in at compile time via `-DVERSION`.
+
+**pkg-config deps:** `gstreamer-1.0 gstreamer-app-1.0 srt` — all must be present before `make`.
+
+## SUBMODULE
+
+`camlink_workaround/` → `https://github.com/BELABOX/camlink.git`  
+Run `git submodule init && git submodule update` if missing. `make submodule` does this automatically.
+
+## TYPESCRIPT BINDINGS
+
+`bindings/typescript/` — consumed by CeraUI backend via `link:../../../ceracoder/bindings/typescript` in its `package.json`. Built with `bun`. Don't edit `dist/` directly; source is in `bindings/typescript/src/`.
+
+## WHERE TO LOOK
+
+| Task | Location |
+|------|----------|
+| Bitrate algorithm | `src/core/bitrate_control.c` + [docs/bitrate-control.md](docs/bitrate-control.md) |
+| Architecture overview | [docs/architecture.md](docs/architecture.md) |
+| Runtime dependencies | [docs/dependencies.md](docs/dependencies.md) |
+| Versioning scheme | [docs/versioning.md](docs/versioning.md) |
+| SRT send logic | `src/net/srt_client.c` |
+| Pipeline loading | `src/io/pipeline_loader.c` |
+| TS bindings source | `bindings/typescript/src/` |
+
+## ANTI-PATTERNS
+
+- Don't hardcode a semver string for VERSION — it's always the git short-SHA.
+- Don't modify `camlink_workaround/` directly; it's a submodule.
+- Don't duplicate docs content here — link to `docs/` instead.
+- Don't run `make` without `libsrt >= 1.4.0` installed; pkg-config will fail silently on some systems.
diff --git a/bindings/typescript/AGENTS.md b/bindings/typescript/AGENTS.md
new file mode 100644
index 0000000..032dcd8
--- /dev/null
+++ b/bindings/typescript/AGENTS.md
@@ -0,0 +1,38 @@
+# ceracoder/bindings/typescript
+
+Parent: [../../AGENTS.md](../../AGENTS.md)
+
+## OVERVIEW
+
+Package `@ceralive/ceracoder` — type-safe TypeScript bindings for the ceracoder C encoder. Zod v4 schemas, config/CLI builders, process helpers, and a `PipelineBuilder` for hardware-specific GStreamer launch strings.
+
+**Consumer:** `CeraUI/apps/backend` via `"@ceralive/ceracoder": "link:../../../ceracoder/bindings/typescript"` in its `package.json`. Breaking the public API here breaks CeraUI backend.
+
+## PUBLIC API SURFACE
+
+| Export | Source | Purpose |
+|--------|--------|---------|
+| `ceracoderConfigSchema`, `CeracoderConfig` | `types.ts` | Zod schema + inferred type for ceracoder config |
+| `buildCeracoderConfig`, `serializeCeracoderConfig` | `config.ts` | Config object builder + serializer |
+| `buildCeracoderArgs` | `cli.ts` | CLI args array builder (always uses `-c <config>`, never legacy `-b`) |
+| `spawnCeracoder`, `sendHup`, `sendTerm` | `process.ts` | Process lifecycle helpers |
+| `writeConfig`, `writePipeline` | `process.ts` | Write config/pipeline files to disk |
+| `PipelineBuilder` | `pipeline/` | Hardware-specific GStreamer launch string generator |
+| Constants (`DEFAULT_*`) | `constants.ts` | Bitrate/latency defaults aligned with C implementation |
+
+## WHERE TO LOOK
+
+| Task | Location |
+|------|----------|
+| Add/change a config field | `src/types.ts` (schema) + `src/config.ts` (defaults) + `src/constants.ts` |
+| Add a new pipeline hardware target | `src/pipeline/` — add hardware dir + update `PipelineBuilder` |
+| Change CLI flags | `src/cli.ts` — check C source `src/io/cli_options.c` stays in sync |
+| Build / type-check | `bun run build` or `bun run lint` |
+
+## ANTI-PATTERNS
+
+- Don't edit `dist/` directly — generated by `bun run build` from `src/`.
+- Don't remove or rename exported symbols without updating `CeraUI/apps/backend` first.
+- Don't add a `-b` bitrate flag to `buildCeracoderArgs` — legacy, removed intentionally.
+- Don't publish to npm; this package is consumed only via `link:` from sibling checkout.
+- Don't bump `version` in `package.json` independently — ceracoder uses git-SHA versioning.