diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bf59943
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# AGENTS.md — amduat-api
+
+This repo hosts the **API/daemon surface** for Amduat.
+
+## Scope
+
+- `vendor/amduat/` is the **core C substrate** (ASL/PEL/TGK libs, codecs, adapters, reference CLIs).
+- This repo should keep `amduatd` **thin**: HTTP transport, request parsing, auth, and mapping to core library calls.
+- Do **not** re-implement substrate semantics here; add features to the core repo and call into it.
+
+## Build
+
+- Configure: `cmake -S . -B build`
+- Build: `cmake --build build -j`
+
+## Run (local Unix socket)
+
+- Prepare store root (from core tools): `vendor/amduat/build/amduat-asl init --root .amduat-asl`
+- Start daemon: `./build/amduatd --root .amduat-asl --sock amduatd.sock`
+
+## Submodule workflow
+
+- Update core to recorded commit: `git submodule update --init --recursive`
+- Bump core commit:
+  - `git -C vendor/amduat fetch`
+  - `git -C vendor/amduat checkout <commit-or-tag>`
+  - `git add vendor/amduat && git commit -m "Bump amduat core"`
+
+## API principles
+
+- Single daemon instance = single ASL store root.
+- Local auth = filesystem permissions on the socket (no extra auth yet).
+- Prefer streaming/batching endpoints (`missing`/`pack`) before adding complex higher-level APIs.
+- Keep the on-wire contract versioned (`/v1/...`) and additive.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..377b0f7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,73 @@
+# amduat-api
+
+`amduat-api` builds `amduatd`, a minimal HTTP server over a Unix domain socket that exposes Amduat substrate operations for a **single ASL store root**.
+
+## Build
+
+```sh
+cmake -S . -B build
+cmake --build build -j
+```
+
+## Core dependency
+
+This repo vendors the core implementation as a git submodule at `vendor/amduat`.
+
+```sh
+git submodule update --init --recursive
+```
+
+## Quickstart (local)
+
+Initialize a store:
+
+```sh
+./vendor/amduat/build/amduat-asl init --root .amduat-asl
+```
+
+Run the daemon:
+
+```sh
+./build/amduatd --root .amduat-asl --sock amduatd.sock
+```
+
+Query store meta:
+
+```sh
+curl --unix-socket amduatd.sock http://localhost/v1/meta
+```
+
+Upload raw bytes:
+
+```sh
+curl --unix-socket amduatd.sock -X POST http://localhost/v1/artifacts \
+  -H 'Content-Type: application/octet-stream' \
+  --data-binary 'hello'
+```
+
+Download raw bytes:
+
+```sh
+curl --unix-socket amduatd.sock http://localhost/v1/artifacts/<ref>
+```
+
+Download artifact framing (`ENC/ASL1-CORE v1`):
+
+```sh
+curl --unix-socket amduatd.sock \
+  'http://localhost/v1/artifacts/<ref>?format=artifact' --output artifact.bin
+```
+
+## Current endpoints
+
+- `GET /v1/meta` → `{store_id, encoding_profile_id, hash_id}`
+- `POST /v1/artifacts`
+  - raw bytes: `Content-Type: application/octet-stream` (+ optional `X-Amduat-Type-Tag: 0x...`)
+  - artifact framing: `Content-Type: application/vnd.amduat.asl.artifact+v1`
+- `GET|HEAD /v1/artifacts/{ref}`
+  - raw bytes default
+  - artifact framing: `?format=artifact`
+
+## Notes
+
+- This is intentionally a local-first surface (Unix socket, no TLS). HTTPS can be added later without changing the semantics.