docs/add examples (#9)

* chore: add microservice architecture scaffolding

Add .env.example, api/openapi.yaml, deploy/docker/docker-compose.yml,
docs/architecture.md, and .github/workflows/docker.yml for GHCI build+push CI.

* fix: resolve lint, module hygiene, and markdown CI failures

Fix errcheck on rows.Close(), simplify bool comparison,
remove unused knownFields var, fix empty badge links,
and run go work sync to update module consistency.

* fix: exclude go.work from Docker build context

hawk's go.work references external/ symlinks to sibling
repos that don't exist in the Docker build context.

* fix: add Windows support for safewrite and update go.sum

Add //go:build !windows constraint to safewrite.go (uses unix
syscalls), create safewrite_windows.go with portable fallback,
skip tests on Windows, and run go mod download to add missing
go.sum entry for golang.org/x/tools.

* fix: gofumpt format safewrite_windows.go and add missing go.sum entry

The Windows stub needed formatting. Also add the /go.mod hash
for golang.org/x/tools v0.45.0 that was missing from go.sum,
causing the Docker build to fail.

* fix: clone eyrie in Docker build for unpublished packages

hawk depends on eyrie packages (credentials, runtime, setup,
catalog/registry) that aren't in the published v0.5.0. Clone
eyrie into the builder and add a replace directive.

* fix: use go mod tidy in Docker to resolve eyrie replace directive

The replace directive needs go mod tidy (not just download) to
resolve all transitive dependencies from the local eyrie clone.
Use -mod=mod to allow go.mod changes during build.

* fix: add eyrie replace directive after source copy

COPY . . was overwriting go.mod that had the replace directive.
Move the replace + go mod tidy to after the source copy.

* docs: add examples directory with usage guide

Add examples/README.md demonstrating basic usage, advanced features, and MCP integration.

Author: Patel230

.dockerignore

@@ -9,3 +9,5 @@ hawk_bin
 hawk_test_bin
 coverage.out
 coverage.html
+go.work
+go.work.sum

.env.example

@@ -0,0 +1,10 @@
+# hawk daemon environment variables — copy to .env and fill in
+HAWK_DAEMON_API_KEY=
+HAWK_DAEMON_PORT=4590
+HAWK_DAEMON_HOST=127.0.0.1
+# Eyrie connection (LLM provider runtime)
+EYRIE_API_KEY=
+EYRIE_BASE_URL=http://localhost:8080
+# Yaad connection (memory service)
+YAAD_API_KEY=
+YAAD_ADDR=127.0.0.1:3456

.github/workflows/docker.yml

@@ -0,0 +1,63 @@
+name: Docker
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+    paths:
+      - "Dockerfile"
+      - "**.go"
+      - "go.mod"
+      - "go.sum"
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: graycodeai/hawk
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          build-args: |
+            VERSION=${{ github.ref_name }}
+            COMMIT=${{ github.sha }}
+            BUILD_DATE=${{ github.event.head_commit.timestamp }}

Dockerfile

@@ -4,11 +4,18 @@ FROM golang:1.26.3-alpine AS builder
 RUN apk add --no-cache git ca-certificates tzdata
 
 WORKDIR /build
+
+# Clone eyrie (unpublished dependency with local-only packages)
+RUN git clone --depth=1 https://github.com/GrayCodeAI/eyrie.git /eyrie
+
 COPY go.mod go.sum ./
-RUN go mod download && go mod verify
+RUN go mod download
 
 COPY . .
-RUN CGO_ENABLED=0 GOOS=linux go build -trimpath \
+# Add replace after source copy so it doesn't get overwritten
+RUN echo "" >> go.mod && echo "replace github.com/GrayCodeAI/eyrie => /eyrie" >> go.mod && go mod tidy
+
+RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -mod=mod \
     -ldflags="-s -w -X main.Version=$(git describe --tags --always 2>/dev/null || echo dev)" \
     -o hawk .