docs: update README and AGENTS.md with update, install-daemon, and all v0.4.0 features

Author: Loki

AGENTS.md

@@ -10,36 +10,44 @@ Single-binary Go proxy that translates OpenAI `/v1/embeddings` to Amazon Bedrock
 | **Test** | `go test ./... -v -count=1` |
 | **Lint** | `golangci-lint run ./...` |
 | **Run** | `./embedrock --port 8089 --region us-east-1` |
+| **Update** | `./embedrock update` |
+| **Install daemon** | `sudo ./embedrock install-daemon` |
 
 ## Before You Start
 
 - Read `ARCHITECTURE.md` for the full design and file layout.
-- This is a **small codebase** (~6 files). Read it all before making changes.
+- This is a **small codebase** (~10 files). Read it all before making changes.
 - Go 1.26+ required. Dependencies: `go mod download`.
 
 ## File Layout
 
 ```
-types.go          → Embedder interface, OpenAI-compatible request/response types
-handler.go        → HTTP handler (routing, input parsing, responses)
-bedrock.go        → BedrockEmbedder (Titan + Cohere model families)
-mock_test.go      → MockEmbedder for tests
-handler_test.go   → HTTP handler tests
-bedrock_test.go   → Model detection tests
-cmd/embedrock/    → CLI entry point (main.go)
+types.go                    → Embedder interface, OpenAI-compatible request/response types
+handler.go                  → HTTP handler (routing, input parsing, responses)
+bedrock.go                  → BedrockEmbedder (Titan + Cohere model families)
+mock_test.go                → MockEmbedder for tests
+handler_test.go             → HTTP handler tests (20 tests)
+bedrock_test.go             → Model detection tests
+cmd/embedrock/main.go       → CLI entry point (flags, subcommands, server startup)
+cmd/embedrock/update.go     → Self-update command (GitHub releases, checksum verification)
+cmd/embedrock/update_test.go → Update tests (mock GitHub API, 6 tests)
+cmd/embedrock/daemon.go     → Install-daemon command (systemd unit file generation)
+cmd/embedrock/daemon_test.go → Daemon tests (unit file generation, root check)
 ```
 
 ## Rules
 
 1. **Always run tests before committing:** `go test ./... -v -count=1`
 2. **Always run build to verify:** `go build ./cmd/embedrock/`
 3. **TDD preferred:** Write a failing test first, then implement.
-4. **No new dependencies** without a strong reason — keep the binary small.
+4. **No new dependencies** without a strong reason — keep the binary small (stdlib only in cmd/).
 5. **Don't break the OpenAI API contract** — clients expect exact `/v1/embeddings` format.
 6. **Single-model design:** One embedrock process = one Bedrock model. Per-request model switching is rejected (HTTP 400).
 7. **Context propagation:** All `Embed()` calls take `context.Context`. Always pass request context through.
-8. **Error hygiene:** Never leak internal/AWS errors to API clients. Return generic messages; log details server-side.
+8. **Error hygiene:** Never leak internal/AWS errors to API clients. Return generic `"embedding failed"` message; log details server-side.
 9. **No hardcoded AWS credentials.** Uses instance profile / env vars / shared config.
+10. **HTTP timeouts required:** All HTTP clients must have explicit timeouts. Server uses `http.Server` with read/write/idle timeouts.
+11. **Test stability:** Tests must NOT modify the real test binary. Use `t.TempDir()` for temp files. Run tests twice to verify stability.
 
 ## Architecture Notes
 
@@ -48,16 +56,34 @@ cmd/embedrock/    → CLI entry point (main.go)
 - Handler parses three input formats: typed single, typed batch, raw JSON fallback.
 - Token usage is approximated (~4 chars/token) since we don't have a tokenizer.
 - Server binds to `127.0.0.1` by default (uses host IAM creds — don't expose).
+- `runUpdate` / `runUpdateTo` split allows tests to inject a temp binary path.
+- `updateHTTPClient` has 30s timeout — never use `http.DefaultClient` or bare `http.Get`.
+
+## CLI Structure
+
+```
+main.go:
+  1. Parse flags (--port, --host, --region, --model, --version)
+  2. Handle --version (before subcommands)
+  3. Handle subcommands: "update", "install-daemon", or unknown → error
+  4. Start server
+```
+
+Subcommands are positional args after flags: `embedrock --port 9090 install-daemon`
 
 ## Testing Patterns
 
 - Use `MockEmbedder` from `mock_test.go` — no AWS creds needed for handler tests.
 - `httptest.NewRecorder()` + `httptest.NewRequest()` for HTTP tests.
+- `httptest.NewServer` for mocking GitHub API in update tests.
+- `t.TempDir()` for temp files that auto-clean.
+- `runUpdateTo(version, apiBase, execPathOverride)` for update tests — never use `runUpdate` directly in tests (would overwrite the test binary).
 - Bedrock integration tests require real AWS credentials and model access.
-- Test both happy path AND error paths (invalid input, embedder failures, model mismatches).
+- Test both happy path AND error paths (invalid input, embedder failures, model mismatches, checksum mismatches, API errors).
 
 ## CI
 
 GitHub Actions (`.github/workflows/`):
-- Tests run on push/PR
-- Releases build cross-platform binaries via goreleaser
+- `ci.yml` — Tests run on push/PR
+- `release.yml` — Builds cross-platform binaries on tag push (linux/darwin × arm64/amd64)
+- `checksums.txt` included in every release for `embedrock update` verification

README.md

@@ -1,6 +1,6 @@
 # embedrock 🪨
 
-OpenAI-compatible Bedrock embedding proxy for OpenClaw and Friends. Drop-in replacement for any tool expecting `/v1/embeddings`.
+OpenAI-compatible embedding proxy for Amazon Bedrock. Drop-in replacement for any tool expecting `/v1/embeddings`.
 
 ## Why?
 
@@ -20,6 +20,8 @@ Zero API keys needed — uses your AWS credentials (instance profile, env vars,
 
 Model family is auto-detected by ID prefix. Titan and Cohere use different Bedrock request/response formats — embedrock handles this transparently.
 
+> **Single-model design:** Each embedrock process serves one model. If a request specifies a different model, it returns HTTP 400 with a clear error. Run multiple instances for multiple models.
+
 ## Install
 
 **From releases:**
@@ -32,6 +34,14 @@ chmod +x /usr/local/bin/embedrock
 # Linux amd64
 curl -fsSL https://github.com/inceptionstack/embedrock/releases/latest/download/embedrock-linux-amd64 -o /usr/local/bin/embedrock
 chmod +x /usr/local/bin/embedrock
+
+# macOS arm64 (Apple Silicon)
+curl -fsSL https://github.com/inceptionstack/embedrock/releases/latest/download/embedrock-darwin-arm64 -o /usr/local/bin/embedrock
+chmod +x /usr/local/bin/embedrock
+
+# macOS amd64
+curl -fsSL https://github.com/inceptionstack/embedrock/releases/latest/download/embedrock-darwin-amd64 -o /usr/local/bin/embedrock
+chmod +x /usr/local/bin/embedrock
 ```
 
 **From source:**
@@ -52,10 +62,75 @@ embedrock --model cohere.embed-v4:0
 # Custom config
 embedrock --port 9090 --region eu-west-1 --model cohere.embed-english-v3
 
-# Flags
+# Show version
+embedrock --version
+
+# All flags
 embedrock --help
 ```
 
+### CLI Reference
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port` | `8089` | Port to listen on |
+| `--host` | `127.0.0.1` | Host to bind to |
+| `--region` | `us-east-1` | AWS region for Bedrock |
+| `--model` | `amazon.titan-embed-text-v2:0` | Bedrock embedding model ID |
+| `--version` | | Show version and exit |
+
+### Subcommands
+
+| Command | Description |
+|---------|-------------|
+| `embedrock update` | Self-update to the latest release from GitHub |
+| `sudo embedrock install-daemon` | Install as a systemd service |
+
+## Self-Update
+
+embedrock can update itself in place:
+
+```bash
+embedrock update
+```
+
+This will:
+1. Check GitHub for the latest release
+2. Download the correct binary for your OS/architecture
+3. Verify the SHA-256 checksum
+4. Replace the current binary atomically
+5. Restart the systemd service if running as one (requires root)
+
+If running as a non-root user with a systemd service:
+```
+Updated embedrock from v0.3.0 to v0.4.0
+Restart embedrock.service manually (requires sudo)
+```
+
+## Install as Daemon
+
+Install embedrock as a systemd service with one command:
+
+```bash
+# Install with defaults (port 8089, us-east-1, Titan v2)
+sudo embedrock install-daemon
+
+# Install with custom settings
+sudo embedrock --port 9090 --region eu-west-1 --model cohere.embed-v4:0 install-daemon
+```
+
+This will:
+1. Copy the binary to `/usr/local/bin/embedrock`
+2. Write a systemd unit file to `/etc/systemd/system/embedrock.service`
+3. Run `systemctl daemon-reload`, `enable`, and `start`
+
+The CLI flags you pass (`--port`, `--region`, `--model`) are baked into the service's `ExecStart` command.
+
+To check service status:
+```bash
+systemctl status embedrock
+```
+
 ## API
 
 **Health check:**
@@ -81,30 +156,39 @@ curl -X POST http://127.0.0.1:8089/v1/embeddings \
   -d '{"input": ["First text", "Second text"], "model": "amazon.titan-embed-text-v2:0"}'
 ```
 
-## Run as a Service
+**Response format:**
 
-```bash
-sudo tee /etc/systemd/system/embedrock.service > /dev/null << 'EOF'
-[Unit]
-Description=embedrock - Bedrock embedding proxy
-After=network.target
-
-[Service]
-Type=simple
-User=ec2-user
-ExecStart=/usr/local/bin/embedrock --port 8089 --region us-east-1 --model cohere.embed-v4:0
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-EOF
-
-sudo systemctl daemon-reload
-sudo systemctl enable embedrock
-sudo systemctl start embedrock
+```json
+{
+  "object": "list",
+  "data": [
+    {
+      "object": "embedding",
+      "index": 0,
+      "embedding": [0.123, -0.456, ...]
+    }
+  ],
+  "model": "amazon.titan-embed-text-v2:0",
+  "usage": {
+    "prompt_tokens": 3,
+    "total_tokens": 3
+  }
+}
+```
+
+**Error responses:**
+
+```json
+{
+  "error": {
+    "message": "model 'cohere.embed-v4:0' is not available; this server is configured with 'amazon.titan-embed-text-v2:0'",
+    "type": "invalid_request"
+  }
+}
 ```
 
+Internal errors return a generic `"embedding failed"` message — no AWS internals are leaked to clients.
+
 ## OpenClaw Configuration
 
 ```json
@@ -130,19 +214,25 @@ sudo systemctl start embedrock
 ## Development
 
 ```bash
+# Install dependencies
+go mod download
+
 # Run tests
-go test ./... -v
+go test ./... -v -count=1
 
 # Build
 go build ./cmd/embedrock/
 
 # Build with version info
-go build -ldflags "-X main.version=v0.2.0" ./cmd/embedrock/
+go build -ldflags "-X main.version=v0.4.0 -X main.commit=$(git rev-parse --short HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" ./cmd/embedrock/
+
+# Lint (requires golangci-lint)
+golangci-lint run ./...
 ```
 
 ## Architecture
 
-See [ARCHITECTURE.md](ARCHITECTURE.md) for design details.
+See [ARCHITECTURE.md](ARCHITECTURE.md) for design details and [AGENTS.md](AGENTS.md) for AI coding agent guidelines.
 
 ## License