diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 65d1e24..e6d1030 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,22 @@ cargo test --workspace
 If you touch S3-backed flows, the CI model uses a local RustFS instance for
 integration tests.
 
+### Cargo features
+
+`omnigraph-server` has an optional `aws` feature that pulls in the AWS
+Secrets Manager SDK for a bearer-token backend. Default builds omit it —
+most contributors never compile the AWS code path.
+
+When you touch `crates/omnigraph-server/src/auth.rs` or any AWS-conditional
+code, verify both configurations:
+
+```bash
+cargo test -p omnigraph-server                  # default
+cargo test -p omnigraph-server --features aws   # AWS enabled
+```
+
+CI runs both.
+
 ## Pull Requests
 
 - keep changes focused
diff --git a/docs/deployment.md b/docs/deployment.md
index 42b814d..e611245 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -110,11 +110,65 @@ docker run --rm -p 8080:8080 \
 ## Auth
 
 The server can run unauthenticated for local development, but any shared or
-internet-facing deployment should set:
+internet-facing deployment should set a bearer token source.
 
-- `OMNIGRAPH_SERVER_BEARER_TOKEN`
+### Token sources
 
-The health endpoint `/healthz` remains suitable for load balancer health checks.
+The server reads bearer tokens from one of three places, in precedence order:
+
+1. **AWS Secrets Manager** (build with `--features aws`, see below) — set
+   `OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` to the secret ID or ARN.
+2. **JSON file or env** — set one of:
+   - `OMNIGRAPH_SERVER_BEARER_TOKENS_FILE` — path to a JSON `{"actor": "token", ...}` file.
+   - `OMNIGRAPH_SERVER_BEARER_TOKENS_JSON` — the JSON literal inline.
+3. **Single-token env** — `OMNIGRAPH_SERVER_BEARER_TOKEN` (assigns the
+   implicit actor `default`).
+
+Tokens are hashed with SHA-256 immediately on ingest; plaintext does not
+persist in process memory after startup.
+
+The health endpoint `/healthz` remains suitable for load balancer health checks
+and is never gated.
+
+## Build Variants
+
+The server binary ships in two flavors:
+
+| Variant | Command | Contents |
+|---------|---------|----------|
+| **Default** (on-prem / local dev) | `cargo build --release` | Core server, no AWS SDK |
+| **AWS** | `cargo build --release --features aws` | Adds AWS Secrets Manager backend for bearer tokens |
+
+Release artifacts are published with matching suffixes —
+`omnigraph-server-<version>-<platform>.tar.gz` for the default build and
+`omnigraph-server-<version>-<platform>-aws.tar.gz` for the AWS-enabled build.
+
+The AWS build adds ~150 transitive deps and ~30-60s of first-build compile
+time. Default builds don't pay that cost.
+
+## AWS Secrets Manager
+
+When the binary is built with `--features aws`, set
+`OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET` to the ARN or name of a Secrets
+Manager secret whose `SecretString` is a JSON object of
+`{"actor_id": "token", ...}`:
+
+```bash
+omnigraph-server-aws s3://my-bucket/repos/example ...
+  # Environment:
+  # OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET=arn:aws:secretsmanager:us-east-1:123456789012:secret:omnigraph-tokens-AbCdEf
+```
+
+Credentials are resolved via the AWS default chain (env vars, shared config,
+IMDSv2 instance role, ECS task role) — no explicit credential plumbing is
+needed when running under an IAM instance role on EC2/ECS/EKS.
+
+The IAM role must permit `secretsmanager:GetSecretValue` on the referenced
+secret.
+
+Setting the env var without building with `--features aws` is a hard error
+with a rebuild instruction — it does not silently fall back to the env/file
+source.
 
 ## S3-Compatible Storage