Add architecture, planning, and conventions documents

Initial documentation for the multi-peer video routing system:
- architecture.md covers graph model, transport protocol, relay design,
  and the Pi get-it-on-the-wire-first rationale
- planning.md defines module build order and directory structure
- conventions.md captures C11 code style, naming, error handling approach,
  and directory layout rules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

conventions.md

@@ -0,0 +1,171 @@
+# Conventions and Preferences
+
+## Language
+
+- **C11** throughout
+- Target platform: Linux (V4L2, epoll, etc. are Linux-specific)
+
+---
+
+## Naming
+
+| Kind | Convention | Example |
+|---|---|---|
+| Structs | `Title_Snek_Case` | `struct App_Error`, `struct Frame_Header` |
+| Enums (type) | `Title_Snek_Case` | `enum Error_Code` |
+| Enum values | `CAPITAL_SNEK_CASE` | `ERR_NONE`, `ERR_SYSCALL` |
+| Functions | `lower_snek_case` | `v4l2_ctrl_open()`, `app_error_print()` |
+| Local variables | `lower_snek_case` | `frame_count`, `device_fd` |
+| Constants (`#define`, `const`) | `CAPITAL_SNEK_CASE` | `MAX_FRAME_SIZE` |
+| Module-level singletons | `lower_snek_case` | (treated as functions) |
+
+Identifiers are prefixed with their module name where disambiguation is needed (e.g. `v4l2_ctrl_`, `media_ctrl_`, `transport_`).
+
+---
+
+## Types
+
+### No typedefs for structs
+
+Always use the `struct` keyword at the call site. This makes composite types unambiguous without inspecting declarations.
+
+```c
+/* correct */
+struct App_Error err = app_error_ok();
+void process(struct Frame_Header *header);
+
+/* wrong */
+typedef struct { ... } App_Error;
+```
+
+### typedefs are acceptable for
+
+- Enums: `typedef enum Error_Code { ... } Error_Code;` — allows using the name without `enum` keyword
+- Scalar aliases where the underlying type is genuinely irrelevant to the caller (e.g. `typedef uint32_t Frame_Id;`)
+
+---
+
+## Formatting
+
+- **Indentation**: tabs (display width 4)
+- **Braces**: always use block braces, including single-statement bodies
+
+```c
+/* correct */
+if (err.code != ERR_NONE) {
+    return err;
+}
+
+/* wrong */
+if (err.code != ERR_NONE)
+    return err;
+```
+
+- **Quotes**: double quotes for string literals (C standard)
+
+---
+
+## Error Handling
+
+Errors are returned as `struct App_Error` values. Functions that can fail return `struct App_Error` directly, or take an out-parameter for the result alongside it.
+
+### Structure
+
+```c
+/* modules/common/error.h */
+
+typedef enum Error_Code {
+    ERR_NONE    = 0,
+    ERR_SYSCALL = 1,   /* errno is meaningful */
+    ERR_INVALID = 2,
+} Error_Code;
+
+struct Syscall_Error_Detail {
+    int err_no;
+};
+
+struct Invalid_Error_Detail {
+    /* fields added as concrete cases arise */
+};
+
+struct App_Error {
+    Error_Code  code;
+    const char *file;   /* __FILE__ — future: replaced by generated location code */
+    int         line;   /* __LINE__ — future: replaced by generated location code */
+    union {
+        struct Syscall_Error_Detail  syscall;
+        struct Invalid_Error_Detail  invalid;
+    } detail;
+};
+```
+
+### Macros
+
+```c
+#define APP_OK \
+    ((struct App_Error){ .code = ERR_NONE })
+
+#define APP_IS_OK(e) \
+    ((e).code == ERR_NONE)
+
+#define APP_ERROR(error_code, detail_field, ...) \
+    ((struct App_Error){ \
+        .code   = (error_code), \
+        .file   = __FILE__, \
+        .line   = __LINE__, \
+        .detail = { .detail_field = { __VA_ARGS__ } } \
+    })
+
+#define APP_SYSCALL_ERROR() \
+    APP_ERROR(ERR_SYSCALL, syscall, .err_no = errno)
+```
+
+### Presentation
+
+Each error kind is handled in `app_error_print()`, which writes a human-readable description to stderr. A JSON writer (`app_error_write_json()`) will be added later and will use the same structured fields.
+
+### Future upgrade
+
+When the custom preprocessor is available, `__FILE__` and `__LINE__` will be replaced by a generated numeric location code that uniquely identifies the error site in the project. JSON consumers will see the same struct shape either way.
+
+---
+
+## Directory Structure
+
+```
+video-setup/
+  modules/         - translation units; each has a .h, a .c, and a Makefile
+    common/        - shared types (error, base definitions); no external dependencies
+    <module>/
+  dev/             - development aids; not part of the final deliverable
+    cli/           - exploratory CLI drivers, one per module
+    experiments/   - freeform experiments
+  tests/           - automated tests (later)
+  Makefile         - top-level build
+```
+
+Modules live only in `modules/`. CLI drivers and experiments live in `dev/`. Nothing in `dev/` is a dependency of anything in `modules/`.
+
+---
+
+## Module Structure
+
+Each module directory contains:
+
+```
+modules/<name>/
+  <name>.h     - public API; minimal includes, no implementation details
+  <name>.c     - implementation
+  Makefile     - builds a static object; links against common only
+```
+
+The corresponding CLI driver lives at `dev/cli/<name>_cli.c`.
+
+---
+
+## Build
+
+- **GNU make** with tabs for recipe indentation
+- Each module builds to a static object (`.o`)
+- CLI drivers link the module object(s) they need
+- No CDN or vendored sources; dependencies are system libraries (libc, Linux kernel headers)