diff --git a/.agents/docs/2026-10-11-add-apriltag-plan.md b/.agents/docs/2026-10-11-add-apriltag-plan.md
new file mode 100644
index 00000000..2cd43768
--- /dev/null
+++ b/.agents/docs/2026-10-11-add-apriltag-plan.md
@@ -0,0 +1,25 @@
+# AprilTag 3.4.5 compat package
+
+- Source: [AprilRobotics/apriltag](https://github.com/AprilRobotics/apriltag), release `v3.4.5`.
+- Shape: Form B, C-source compat. The descriptor follows the upstream CMake
+  library target: detector/pose/thresholding sources, `common/*.c`, all
+  generated `tag*.c` families, and the `aruco/tag*.c` families. Examples and
+  the optional Python wrapper are not library sources.
+- Platform: Linux, macOS, and Windows. The same source set is used on all
+  three platforms. The descriptor supplies `_GNU_SOURCE` plus pthread/libm on
+  Linux, `_DARWIN_C_SOURCE` plus pthread/libm on macOS, and the Windows
+  CRT/math defines used by the upstream CMake build.
+- API/build language: `c_standard = "c99"` for the C sources; the package
+  manifest remains `language = "c++23"` so it follows mcpp's C++20-and-newer
+  consumer contract. Platform-specific defines are supplied to the package's
+  C translation units because the upstream CMake build uses platform CRT
+  extensions for declarations such as `timespec`, `strdup`, and math constants.
+- Archive: `https://github.com/AprilRobotics/apriltag/archive/refs/tags/v3.4.5.tar.gz`.
+  SHA-256 is
+  `3749f48220db78c29c375a373861f4e1f4138e5dbae3c298584e96cfcc556515`.
+  No CN mirror is declared because no mcpp-res upload was available; the
+  descriptor uses the permitted plain upstream URL fallback.
+- Test: `tests/examples/apriltag` is a cross-platform member that creates a detector and the
+  `tagStandard41h12` family, runs detection on a blank image, checks the empty
+  result, and destroys every object. This verifies header exposure, all
+  required symbols, pthread linkage, and the basic runtime lifecycle.
diff --git a/mcpp.toml b/mcpp.toml
index 9733cf0e..a96c9edc 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -106,6 +106,7 @@ members = [
     "tests/examples/glm",
     "tests/examples/libaio",
     "tests/examples/libserial",
+    "tests/examples/apriltag",
     "tests/examples/libassert",
     "tests/examples/libcoro",
     "tests/examples/libdrm",
diff --git a/pkgs/c/compat.apriltag.lua b/pkgs/c/compat.apriltag.lua
new file mode 100644
index 00000000..37d2988e
--- /dev/null
+++ b/pkgs/c/compat.apriltag.lua
@@ -0,0 +1,72 @@
+-- compat.apriltag — AprilTag 3.4.5, a visual fiducial detection library.
+--
+-- Shape A (C-source compat). The upstream CMake target consists of the
+-- detector, pose/thresholding code, all common helpers, and every generated
+-- tag family (including the ArUco families). Keep the source globs aligned
+-- with that target rather than compiling examples or the Python wrapper.
+--
+-- The same source set builds on Linux, macOS, and Windows. Platform-specific
+-- defines and system libraries mirror the upstream CMake target.
+package = {
+    spec        = "1",
+    namespace   = "compat",
+    name        = "apriltag",
+    description = "AprilTag visual fiducial detection library",
+    licenses    = {"BSD-2-Clause", "MIT"},
+    repo        = "https://github.com/AprilRobotics/apriltag",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["3.4.5"] = {
+                url    = "https://github.com/AprilRobotics/apriltag/archive/refs/tags/v3.4.5.tar.gz",
+                sha256 = "3749f48220db78c29c375a373861f4e1f4138e5dbae3c298584e96cfcc556515",
+            },
+        },
+        macosx = {
+            ["3.4.5"] = {
+                url    = "https://github.com/AprilRobotics/apriltag/archive/refs/tags/v3.4.5.tar.gz",
+                sha256 = "3749f48220db78c29c375a373861f4e1f4138e5dbae3c298584e96cfcc556515",
+            },
+        },
+        windows = {
+            ["3.4.5"] = {
+                url    = "https://github.com/AprilRobotics/apriltag/archive/refs/tags/v3.4.5.tar.gz",
+                sha256 = "3749f48220db78c29c375a373861f4e1f4138e5dbae3c298584e96cfcc556515",
+            },
+        },
+    },
+
+    mcpp = {
+        language     = "c++23",
+        import_std   = false,
+        c_standard   = "c99",
+        include_dirs = { "*" },
+        sources      = {
+            "*/apriltag.c",
+            "*/apriltag_pose.c",
+            "*/apriltag_quad_thresh.c",
+            "*/common/*.c",
+            "*/tag*.c",
+            "*/aruco/tag*.c",
+        },
+        targets = { ["apriltag"] = { kind = "lib" } },
+        linux = {
+            cflags  = { "-D_GNU_SOURCE" },
+            ldflags = { "-lpthread", "-lm" },
+        },
+        macosx = {
+            cflags  = { "-D_DARWIN_C_SOURCE" },
+            ldflags = { "-lpthread", "-lm" },
+        },
+        windows = {
+            cflags = {
+                "-D_USE_MATH_DEFINES",
+                "-DWIN32_LEAN_AND_MEAN",
+                "-D_CRT_SECURE_NO_WARNINGS",
+                "-D_CRT_NONSTDC_NO_DEPRECATE",
+            },
+        },
+        deps    = { },
+    },
+}
diff --git a/tests/examples/apriltag/mcpp.toml b/tests/examples/apriltag/mcpp.toml
new file mode 100644
index 00000000..e068b374
--- /dev/null
+++ b/tests/examples/apriltag/mcpp.toml
@@ -0,0 +1,6 @@
+[package]
+name = "apriltag-tests"
+version = "0.1.0"
+
+[dependencies.compat]
+apriltag = "3.4.5"
diff --git a/tests/examples/apriltag/tests/detector.cpp b/tests/examples/apriltag/tests/detector.cpp
new file mode 100644
index 00000000..dc54cf8f
--- /dev/null
+++ b/tests/examples/apriltag/tests/detector.cpp
@@ -0,0 +1,28 @@
+#include <cassert>
+
+#include <apriltag.h>
+#include <common/image_u8.h>
+#include <tagStandard41h12.h>
+
+int main() {
+    apriltag_detector_t* detector = apriltag_detector_create();
+    assert(detector != nullptr);
+    assert(detector->nthreads > 0);
+
+    apriltag_family_t* family = tagStandard41h12_create();
+    assert(family != nullptr);
+    assert(family->ncodes > 0);
+    apriltag_detector_add_family(detector, family);
+
+    image_u8_t* image = image_u8_create(64, 64);
+    assert(image != nullptr);
+    zarray_t* detections = apriltag_detector_detect(detector, image);
+    assert(detections != nullptr);
+    assert(zarray_size(detections) == 0);
+
+    apriltag_detections_destroy(detections);
+    image_u8_destroy(image);
+    apriltag_detector_destroy(detector);
+    tagStandard41h12_destroy(family);
+    return 0;
+}