diff --git a/reference-design/obfuscate_entitlements/README.md b/reference-design/obfuscate_entitlements/README.md
new file mode 100644
index 0000000..b5970c3
--- /dev/null
+++ b/reference-design/obfuscate_entitlements/README.md
@@ -0,0 +1,12 @@
+# Obfuscate entitlements — reference design (archived)
+
+Frozen copy of the spike in `tmp/obfuscate_test/` (standalone demo APK + Linux tests).
+
+**Canonical integration** lives in the main app:
+
+- C: `ndk/obfuscate/`
+- JNI: `ndk/jni/entitlements_jni.c`
+- Java: `app/src/main/java/com/foxx/androidcast/entitlements/`
+- Native library name: `androidcast_entitlements`
+
+The per-account **key** (`uint64_t`) replaces wall-clock seed in production; encode/decode API unchanged at C level.
diff --git a/reference-design/obfuscate_entitlements/obfuscate.h b/reference-design/obfuscate_entitlements/obfuscate.h
new file mode 100644
index 0000000..82ac5bf
--- /dev/null
+++ b/reference-design/obfuscate_entitlements/obfuscate.h
@@ -0,0 +1,30 @@
+#ifndef OBFUSCATE_H
+#define OBFUSCATE_H
+
+#include <stdint.h>
+
+/* Payload uses lower 40 bits; upper 24 bits hold verification tag. */
+#define OBF_PAYLOAD_BITS 40u
+#define OBF_PAYLOAD_MASK ((1ULL << OBF_PAYLOAD_BITS) - 1ULL)
+
+/* Return codes */
+#define OBF_OK           0
+#define OBF_ERR_NULL    -1  /* out pointer is NULL */
+#define OBF_ERR_RANGE   -2  /* val exceeds encodable payload width */
+#define OBF_ERR_VERIFY  -3  /* tag mismatch (wrong seed or corrupted data) */
+
+/*
+ * Encode uint64_t payload (e.g. flag bits) using seed-derived keystream.
+ * seed is typically unix time in whole seconds shared by encoder and decoder.
+ *
+ * On success writes single uint64_t to *out and returns OBF_OK.
+ */
+int32_t encode(uint64_t val, uint64_t seed, uint64_t *out);
+
+/*
+ * Decode and verify. seed must match the value used at encode time.
+ * On success writes recovered payload to *out and returns OBF_OK.
+ */
+int32_t decode(uint64_t encoded_val, uint64_t seed, uint64_t *out);
+
+#endif /* OBFUSCATE_H */
diff --git a/reference-design/obfuscate_entitlements/obfuscate_file.h b/reference-design/obfuscate_entitlements/obfuscate_file.h
new file mode 100644
index 0000000..2c14770
--- /dev/null
+++ b/reference-design/obfuscate_entitlements/obfuscate_file.h
@@ -0,0 +1,28 @@
+#ifndef OBFUSCATE_FILE_H
+#define OBFUSCATE_FILE_H
+
+#include "obfuscate.h"
+#include <stddef.h>
+#include <stdint.h>
+
+/* 32-bit dummy header/tail — skipped by decode; only uint64_t payloads are processed. */
+#define OBF_FILE_HDR_SIZE  4u
+#define OBF_FILE_TAIL_SIZE 4u
+#define OBF_FILE_OVERHEAD  (OBF_FILE_HDR_SIZE + OBF_FILE_TAIL_SIZE)
+
+#define OBF_ERR_IO        -4
+#define OBF_ERR_FORMAT    -5
+#define OBF_ERR_OVERFLOW  -6
+
+int32_t write_to(const char *path, uint64_t val, uint64_t seed);
+int32_t read_from(const char *path, uint64_t seed, uint64_t *out);
+
+int32_t write_many_to(const char *path, const uint64_t *vals, size_t count, uint64_t seed);
+
+int32_t read_many_from(const char *path, uint64_t seed, uint64_t *out_vals, size_t out_cap,
+		       size_t *out_count);
+
+/* How many uint64_t payloads are stored (excludes 32-bit head/tail). */
+int32_t obf_file_payload_count(long file_size, size_t *count_out);
+
+#endif /* OBFUSCATE_FILE_H */