docs: comprehensive documentation overhaul for public release

Add 14 documentation guides covering all aspects of the registry:
- Getting started, installation, and configuration reference
- Storage backends (PostgreSQL, MySQL, Cassandra, memory)
- Schema types (Avro, Protobuf, JSON Schema) with references
- Compatibility modes, migration from Confluent, deployment
- Authentication (6 methods), security hardening, RBAC
- Monitoring (Prometheus metrics, alerting, Grafana)
- Development guide, troubleshooting, and error code reference

Add auto-generated API reference from OpenAPI spec:
- docs/api-reference.md (markdown, 7002 lines via widdershins)
- docs/api/index.html (ReDoc interactive HTML)
- scripts/generate-api-docs.sh for regeneration
- GitHub Actions workflow (workflow_dispatch) for CI generation

Rebuild README.md as a focused landing page with feature comparison
table, architecture diagrams, and documentation index.

Author: millerjp

.github/workflows/docs-api.yaml

@@ -0,0 +1,36 @@
+name: Generate API Documentation
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Generate API documentation
+        run: ./scripts/generate-api-docs.sh
+
+      - name: Check for changes
+        id: changes
+        run: |
+          git diff --quiet docs/api-reference.md docs/api/index.html && echo "changed=false" >> "$GITHUB_OUTPUT" || echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Commit and push
+        if: steps.changes.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/api-reference.md docs/api/index.html
+          git commit -m "docs: regenerate API reference from OpenAPI spec"
+          git push

.gitignore

@@ -32,8 +32,8 @@ config.local.yaml
 .env
 .env.local
 
-# Generated API documentation
-docs/api/
+# Generated API documentation (committed; regenerate with: make docs-api)
+# docs/api/
 
 # Debug
 debug

Makefile

@@ -480,12 +480,9 @@ docker-build:
 docker-run:
 	docker run -p 8081:8081 axonops/schema-registry:latest
 
-## Generate static API documentation (requires npx)
+## Generate API documentation from OpenAPI spec (markdown + ReDoc HTML)
 docs-api:
-	@echo "Generating static API documentation..."
-	@mkdir -p docs/api
-	npx @redocly/cli build-docs api/openapi.yaml -o docs/api/index.html
-	@echo "Documentation generated at docs/api/index.html"
+	@./scripts/generate-api-docs.sh
 
 ## Clean build artifacts
 clean:
@@ -552,5 +549,5 @@ help:
 	@echo "  fmt                 Format code"
 	@echo "  run                 Build and run the server"
 	@echo "  dev                 Run with hot reload (requires air)"
-	@echo "  docs-api            Generate static API documentation"
+	@echo "  docs-api            Generate API docs from OpenAPI (markdown + HTML)"
 	@echo "  clean               Clean build artifacts"