docs: commit markdown previously hidden by the *.md ignore

taicpp/docs/embed.md

@@ -0,0 +1,9 @@
+# Embedding detz: research notes
+
+Options compared:
+1. **Dynamic .so plugin** (`dlopen`): flexible versioning, but host must ship/resolve the .so at runtime; symbol drift risk; packaging burden.
+2. **Subprocess/IPC** (spawn detz binary): simplest isolation, but per-call latency + serialization cost; no in-process context hook.
+3. **Static archive link (chosen)**: `build/libdetz.a` + C ABI header `src/glue/detz_embed.h` (`detz_set_context`, `detz_context`, `detz_version`) plus C++ hook `detz::embed::apply_context()`. Single artifact, no runtime deps beyond system libs, version pinned at build time. `make static` additionally yields fully static `build/detz-static` (verified `file`: statically linked, `ldd`: not a dynamic executable) using vendored `third_party/{curl,sqlite,jitterentropy}` archives. Re-verified 2026-10-27 at 1.44.3: `make static` exits 0, the binary is 29 MB, `file` says statically linked, `--version` prints `tai 1.44.3`, and the link shows only the standard glibc static warnings (`dlopen`, `getaddrinfo`, `gethostbyname`, `getpwuid`).
+4. **Header-only**: rejected — codebase too large, would explode host build times.
+
+Why this API: minimal C surface (stable ABI, callable from C/Rust/Python-ctypes) with a thin C++ `apply_context()` injection point wired into `GlueApp::one_shot`, so hosts prepend context without touching agent internals. Proven: third-party TU links against `libdetz.a` and `apply_context("ping")` → `[ctx] STATIC-PROOF\nping`, version `1.44.3`.