Feature/http server implementation

.gitignore

@@ -128,9 +128,14 @@ config.local.*
 # models.dev sources (created during sync)
 models.dev-git/
 
-# Hugo generated directories
+# Hugo-generated files (Hugo is no longer used but files may exist locally)
 /public/
-/resources/
-/site/public/
-/site/resources/
 *.lock
+
+# OpenAPI intermediate files (cleaned up during generation)
+internal/embedded/openapi/docs.go      # Generated Go code (not needed, we use //go:embed)
+internal/embedded/openapi/swagger.json # Temporary file (renamed to openapi.json)
+internal/embedded/openapi/swagger.yaml # Temporary file (renamed to openapi.yaml)
+
+# Nix build artifacts
+/devbox/swag/result  # Nix build output symlink

API.md

@@ -90,14 +90,15 @@ Package starmap provides a unified AI model catalog system with automatic update
   - [func WithAutoUpdatesDisabled\(\) Option](<#WithAutoUpdatesDisabled>)
   - [func WithEmbeddedCatalog\(\) Option](<#WithEmbeddedCatalog>)
   - [func WithLocalPath\(path string\) Option](<#WithLocalPath>)
-  - [func WithRemoteServer\(url string, apiKey \*string\) Option](<#WithRemoteServer>)
-  - [func WithRemoteServerOnly\(\) Option](<#WithRemoteServerOnly>)
+  - [func WithRemoteServerAPIKey\(apiKey string\) Option](<#WithRemoteServerAPIKey>)
+  - [func WithRemoteServerOnly\(url string\) Option](<#WithRemoteServerOnly>)
+  - [func WithRemoteServerURL\(url string\) Option](<#WithRemoteServerURL>)
 - [type Persistence](<#Persistence>)
 - [type Updater](<#Updater>)
 
 
 <a name="AutoUpdateFunc"></a>
-## type [AutoUpdateFunc](<https://github.com/agentstation/starmap/blob/master/options.go#L98>)
+## type [AutoUpdateFunc](<https://github.com/agentstation/starmap/blob/master/options.go#L105>)
 
 AutoUpdateFunc is a function that updates the catalog.
 
@@ -211,7 +212,7 @@ type ModelUpdatedHook func(old, updated catalogs.Model)
 ```
 
 <a name="Option"></a>
-## type [Option](<https://github.com/agentstation/starmap/blob/master/options.go#L51>)
+## type [Option](<https://github.com/agentstation/starmap/blob/master/options.go#L52>)
 
 Option is a function that configures a Starmap instance.
 
@@ -220,7 +221,7 @@ type Option func(*options) error
 ```
 
 <a name="WithAutoUpdateFunc"></a>
-### func [WithAutoUpdateFunc](<https://github.com/agentstation/starmap/blob/master/options.go#L101>)
+### func [WithAutoUpdateFunc](<https://github.com/agentstation/starmap/blob/master/options.go#L108>)
 
 ```go
 func WithAutoUpdateFunc(fn AutoUpdateFunc) Option
@@ -229,7 +230,7 @@ func WithAutoUpdateFunc(fn AutoUpdateFunc) Option
 WithAutoUpdateFunc configures a custom function for updating the catalog.
 
 <a name="WithAutoUpdateInterval"></a>
-### func [WithAutoUpdateInterval](<https://github.com/agentstation/starmap/blob/master/options.go#L90>)
+### func [WithAutoUpdateInterval](<https://github.com/agentstation/starmap/blob/master/options.go#L97>)
 
 ```go
 func WithAutoUpdateInterval(interval time.Duration) Option
@@ -238,7 +239,7 @@ func WithAutoUpdateInterval(interval time.Duration) Option
 WithAutoUpdateInterval configures how often to automatically update the catalog.
 
 <a name="WithAutoUpdatesDisabled"></a>
-### func [WithAutoUpdatesDisabled](<https://github.com/agentstation/starmap/blob/master/options.go#L82>)
+### func [WithAutoUpdatesDisabled](<https://github.com/agentstation/starmap/blob/master/options.go#L89>)
 
 ```go
 func WithAutoUpdatesDisabled() Option
@@ -247,7 +248,7 @@ func WithAutoUpdatesDisabled() Option
 WithAutoUpdatesDisabled configures whether automatic updates are disabled.
 
 <a name="WithEmbeddedCatalog"></a>
-### func [WithEmbeddedCatalog](<https://github.com/agentstation/starmap/blob/master/options.go#L126>)
+### func [WithEmbeddedCatalog](<https://github.com/agentstation/starmap/blob/master/options.go#L133>)
 
 ```go
 func WithEmbeddedCatalog() Option
@@ -256,32 +257,41 @@ func WithEmbeddedCatalog() Option
 WithEmbeddedCatalog configures whether to use an embedded catalog. It defaults to false, but takes precedence over WithLocalPath if set.
 
 <a name="WithLocalPath"></a>
-### func [WithLocalPath](<https://github.com/agentstation/starmap/blob/master/options.go#L117>)
+### func [WithLocalPath](<https://github.com/agentstation/starmap/blob/master/options.go#L124>)
 
 ```go
 func WithLocalPath(path string) Option
 ```
 
 WithLocalPath configures the local source to use a specific catalog path.
 
-<a name="WithRemoteServer"></a>
-### func [WithRemoteServer](<https://github.com/agentstation/starmap/blob/master/options.go#L65>)
+<a name="WithRemoteServerAPIKey"></a>
+### func [WithRemoteServerAPIKey](<https://github.com/agentstation/starmap/blob/master/options.go#L72>)
 
 ```go
-func WithRemoteServer(url string, apiKey *string) Option
+func WithRemoteServerAPIKey(apiKey string) Option
 ```
 
-WithRemoteServer configures the remote server for catalog updates. A url is required, an api key can be provided for authentication, otherwise use nil to skip Bearer token authentication.
+WithRemoteServerAPIKey configures the remote server API key.
 
 <a name="WithRemoteServerOnly"></a>
-### func [WithRemoteServerOnly](<https://github.com/agentstation/starmap/blob/master/options.go#L74>)
+### func [WithRemoteServerOnly](<https://github.com/agentstation/starmap/blob/master/options.go#L80>)
 
 ```go
-func WithRemoteServerOnly() Option
+func WithRemoteServerOnly(url string) Option
 ```
 
 WithRemoteServerOnly configures whether to only use the remote server and not hit provider APIs.
 
+<a name="WithRemoteServerURL"></a>
+### func [WithRemoteServerURL](<https://github.com/agentstation/starmap/blob/master/options.go#L64>)
+
+```go
+func WithRemoteServerURL(url string) Option
+```
+
+WithRemoteServerURL configures the remote server URL.
+
 <a name="Persistence"></a>
 ## type [Persistence](<https://github.com/agentstation/starmap/blob/master/persistence.go#L12-L15>)
 
@@ -312,4 +322,4 @@ type Updater interface {
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)
 
 
-<!-- gomarkdoc:embed:end -->
+<!-- gomarkdoc:embed:end -->

ARCHITECTURE.md

@@ -1076,7 +1076,19 @@ starmap/
 │
 ├── internal/                 # Internal packages
 │   ├── embedded/             # Embedded catalog data
-│   │   └── catalog/          # Embedded YAML files
+│   │   ├── catalog/          # Embedded YAML files
+│   │   └── openapi/          # OpenAPI 3.1 specs (JSON/YAML)
+│   ├── server/               # HTTP server implementation
+│   │   ├── server.go         # Server struct & lifecycle
+│   │   ├── config.go         # Configuration management
+│   │   ├── router.go         # Route registration & middleware
+│   │   └── handlers/         # HTTP request handlers
+│   │       ├── models.go     # Model endpoints
+│   │       ├── providers.go  # Provider endpoints
+│   │       ├── admin.go      # Admin operations
+│   │       ├── health.go     # Health checks
+│   │       ├── realtime.go   # WebSocket/SSE
+│   │       └── openapi.go    # OpenAPI spec endpoints
 │   ├── sources/              # Source implementations
 │   │   ├── providers/        # Provider API clients
 │   │   │   ├── openai/       # OpenAI client

CLAUDE.md

@@ -256,7 +256,7 @@ for _, provider := range providers {
 
 **Core packages**: catalogs, reconciler, authority, sources, errors, logging, constants, convert
 
-**Internal**: embedded, sources/{providers,modelsdev,local,clients}, transport
+**Internal**: embedded, server, server/handlers, sources/{providers,modelsdev,local,clients}, transport
 
 **Application**: cmd/application (interface), cmd/starmap/app (implementation)
 
@@ -289,6 +289,10 @@ GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
 | `sync.go` | 12-step sync pipeline |
 | `cmd/application/application.go` | Application interface (idiomatic location) |
 | `cmd/starmap/app/app.go` | App implementation |
+| `cmd/starmap/cmd/serve/command.go` | HTTP server CLI command |
+| `internal/server/server.go` | Server lifecycle & dependencies |
+| `internal/server/router.go` | Route registration & middleware |
+| `internal/server/handlers/handlers.go` | Handler base structure |
 | `pkg/reconciler/reconciler.go` | Multi-source reconciliation |
 | `pkg/authority/authority.go` | Field-level authorities |
 | `internal/sources/providers/providers.go` | Concurrent provider fetching |

Makefile

@@ -501,11 +501,28 @@ testdata: ## Update testdata for all providers (use PROVIDER=name for specific p
 	fi
 
 # Documentation
-generate: ## Generate all documentation (Go docs only)
+openapi: ## Generate OpenAPI 3.1 documentation (embedded in binary)
+	@echo "$(BLUE)Generating OpenAPI 3.1 documentation...$(NC)"
+	@$(RUN_PREFIX) which swag > /dev/null || (echo "$(RED)swag not found. Run 'devbox shell' to enter the development environment$(NC)" && exit 1)
+	@echo "$(YELLOW)Step 1/3: Generating OpenAPI 3.1 with swag v2...$(NC)"
+	@$(RUN_PREFIX) swag init -g internal/server/docs.go -o internal/embedded/openapi --parseDependency --parseInternal --v3.1
+	@echo "$(YELLOW)Step 2/3: Renaming generated files...$(NC)"
+	@mv internal/embedded/openapi/swagger.json internal/embedded/openapi/openapi.json
+	@mv internal/embedded/openapi/swagger.yaml internal/embedded/openapi/openapi.yaml
+	@rm -f internal/embedded/openapi/docs.go
+	@echo "$(YELLOW)Step 3/3: Verifying embedded specs...$(NC)"
+	@test -f internal/embedded/openapi/openapi.json || (echo "$(RED)Error: openapi.json not found$(NC)" && exit 1)
+	@test -f internal/embedded/openapi/openapi.yaml || (echo "$(RED)Error: openapi.yaml not found$(NC)" && exit 1)
+	@echo "$(GREEN)OpenAPI 3.1 specs generated and ready for embedding$(NC)"
+	@echo "$(GREEN)  - internal/embedded/openapi/openapi.json$(NC)"
+	@echo "$(GREEN)  - internal/embedded/openapi/openapi.yaml$(NC)"
+	@echo "$(BLUE)Specs will be embedded in binary via //go:embed$(NC)"
+
+generate: openapi ## Generate all documentation (Go docs and OpenAPI)
 	@echo "$(BLUE)Generating Go documentation...$(NC)"
 	@$(RUN_PREFIX) which gomarkdoc > /dev/null || (echo "$(RED)gomarkdoc not found. Install with: go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest$(NC)" && exit 1)
 	$(GOCMD) generate ./...
-	@echo "$(GREEN)Go documentation generation complete$(NC)"
+	@echo "$(GREEN)All documentation generation complete$(NC)"
 
 godoc: ## Generate only Go documentation using go generate
 	@echo "$(BLUE)Generating Go documentation...$(NC)"