---
name: zenbu-bazel-c
description: Use this skill when working anywhere in the Zenbu monorepo, especially C/C++ libraries, Bazel targets, Mercurial workflow, shared assets, or cross-project dependencies.
---

# Zenbu Bazel/C Monorepo

Use this skill to orient yourself before changing first-party code in this workspace.

## What this repo is

Zenbu is a Mercurial/Bazel monorepo for reusable C libraries, web servers, frontend bundles, and experiments. Prefer first-party libraries over adding new external dependencies.

Important first-party packages:

- `dowa`: core C utilities, arena allocation, strings, math, dynamic arrays/hash maps.
- `seobeo`: HTTP/TCP/WebSocket/networking library.
- `mrjunejune`: personal website and production server.
- `hg-web`: Mercurial repository browser served by a C backend.
- `markdown_converter`: markdown-to-HTML C/WASM converter.
- `deita`: SQLite wrapper library.
- `s3`: S3 presigned upload helper.
- `gui_ze`: Bazel macros for bundling/copying web assets.
- `design_system`: light-DOM Web Components, shared CSS tokens, and a Seobeo
  component catalog.

Avoid broad searches in `third_party/`, Bazel output directories, virtualenvs, `node_modules`, and generated bundles unless the task specifically requires them.

For cross-codebase audits, inspect `BUILD` files and Bazel dependencies first.
Use the dependency graph to identify actual first-party consumers before broad
text search, then audit only those targets and their transitive owners.

## Build and test commands

Use Bazel targets from the repository root:

```bash
bazel build //seobeo:seobeo
bazel test //seobeo:seobeo_client_test
bazel test //seobeo:seobeo_websocket_test
bazel test //seobeo:seobeo_websocket_server_test

bazel build //mrjunejune:mrjunejune_server
bazel test //mrjunejune/test:integration_test

bazel build //hg-web:hg_web_server
```

For debug builds, prefer existing debug targets where present:

```bash
bazel build //mrjunejune:mrjunejune_server_debug -c dbg
bazel build //seobeo:seobeo_debug -c dbg
```

If a change only touches docs or assistant skill files, Bazel verification is not required.

### Parallel test structure

- Do not let unrelated browser, integration, or end-to-end concerns accumulate
  in one long serial test process.
- Split slow suites into independently runnable Bazel test targets by concern.
  Use a `test_suite` target to preserve a single aggregate command.
- Run related targets in one `bazel test` invocation so Bazel schedules them in
  parallel. Do not loop over targets or invoke Bazel separately for each test.
- Parallel shards must use independent ports, temporary directories, databases,
  and mutable fixtures. Never share process-global test state between shards.
- During iteration, run only the narrow shard for the changed behavior; run the
  aggregate suite before completion.

### Runtime configuration

- Each service uses one ignored, documented config file as its normal runtime
  configuration source. Do not introduce `.env` files or require users to
  export shell variables before ordinary Bazel run/deploy commands.
- Committed config templates contain placeholders only. Real config and secrets
  stay ignored and outside immutable production bundles.
- Supervisors may propagate parsed config to child processes through their
  process environment as an internal implementation detail. Environment
  overrides are compatibility/testing hooks, not the primary user workflow.

## Coding conventions to preserve

- Prefer Dowa's integer and boolean aliases (`uint8`, `uint16`, `uint32`,
  `uint64`, `int8`, `int16`, `int32`, `int64`, and `boolean`) plus
  `TRUE`/`FALSE` in first-party C. Do not introduce `<stdint.h>` `_t` aliases
  or `<stdbool.h>` `bool` when a Dowa type already expresses the value.
- C code generally uses `Dowa_Arena` for request-scoped allocations.
- An arena owns every pointer returned by `Dowa_Arena_Allocate`, aligned arena
  allocation, arena string helpers, and arena array/hash-map macros. Never pass
  those pointers to libc `free()`, `Dowa_Free`, or an element-level destroy
  function.
- Release a locally created arena exactly once with `Dowa_Arena_Free()` on
  every return path. Do not release a borrowed request arena; its owner must
  free it.
- Prefer `Dowa_Free` over raw libc `free()` for separately heap-allocated
  first-party pointers. Keep the allocation source explicit when heap and arena
  ownership coexist in one function.
- HTTP responses are usually `Seobeo_Request_Entry *resp = NULL` maps filled with `Dowa_HashMap_Push_Arena`.
- Route handlers return response maps; streaming handlers receive `Seobeo_Handle *` directly.
- Existing code favors explicit status/content-type/body response fields.
- Use `Seobeo_Log` for seobeo-aware logging instead of introducing another logger.
- Keep Bazel dependencies precise. Add deps to the smallest target that needs them.
- Preserve platform-aware `select()` aliases for macOS/Linux targets.

## Mercurial workflow

This repo is not a Git repository. Use Mercurial commands if you need VCS status:

```bash
hg status
hg diff
```

Do not create Git-specific metadata or workflows unless explicitly asked.