feat(scaffold): align monorepo layout and docker build patterns

Author: pitabwire

docs/ai-assistant-mode.md

@@ -67,6 +67,9 @@ Enabled via `WithDebugEndpoints()` or `FRAME_DEBUG_ENDPOINTS=true`.
 
 All responses must be deterministic and safe to parse by agents.
 
+Security note:
+- Keep debug endpoints disabled in production unless explicitly protected.
+
 ## CLI (v0.1)
 
 ```

docs/ai-assistants.md

@@ -35,12 +35,11 @@ For monorepos, prefer:
 
 ```text
 /cmd
-  /monolith
-  /users
-  /billing
+  /users/main.go
+  /billing/main.go
 /apps
-  /users
-  /billing
+  /users/cmd/main.go
+  /billing/cmd/main.go
 /pkg
   /plugins
   /openapi

docs/blueprints.md

@@ -81,7 +81,8 @@ These rules keep blueprints safe for AI agents and humans: extension is the defa
 Base:
 
 ```yaml
-service: users
+service:
+  name: users
 http:
   - name: list-users
     method: GET

docs/monorepo.md

@@ -1,169 +1,128 @@
 # Monorepo by Default: Monolith or Polylith
 
-Frame assumes a **monorepo-first** layout that can run as:
+Frame uses a **monorepo-first** layout. You can run the same codebase as:
 
-- **Monolith**: one binary, one service
-- **Polylith**: multiple independent binaries from one repo
+- **Monolith**: one Frame service, one mux, many routes.
+- **Polylith**: many independent binaries, each service deployed separately.
 
-Both modes share the same shared packages and conventions. The only difference is **how many entrypoints you build**.
-
-## Canonical Layout (Monorepo)
+## Canonical Layout
 
 ```text
 /README.md
 /go.mod
 /cmd
-  /monolith
-    main.go
-  /users
-    main.go
-  /billing
-    main.go
+  /users/main.go
+  /billing/main.go
 /apps
   /users
-    /cmd
-      /users
-        main.go
-      /users/Dockerfile
-    /service
+    /cmd/main.go
+    /service/routes.go
+    /queues
     /config
     /migrations
     /tests
+    /Dockerfile
   /billing
-    /cmd
-      /billing
-        main.go
-      /billing/Dockerfile
-    /service
+    /cmd/main.go
+    /service/routes.go
+    /queues
     /config
     /migrations
     /tests
+    /Dockerfile
 /pkg
-  /shared
   /plugins
   /openapi
+  /shared
 /configs
 /Dockerfile
 ```
 
-## Monolith Mode
-
-A single entrypoint composes multiple modules into one binary and runs one Frame service with one mux:
+## Monolith Mode (Single Service)
 
-```text
-/cmd/monolith/main.go
-/apps/users/service
-/apps/billing/service
-```
+Monolith means **one `frame.Service` + one `http.ServeMux`**. Multiple app routes are mounted into that one mux.
 
-All routes are wired into the same mux in one process. This is ideal for:
+Example shape:
 
-- fast local development
-- smaller deployments
-- shared runtime state
-
-## Polylith Mode (Composable)
+```go
+mux := http.NewServeMux()
+users.RegisterRoutes(mux)
+billing.RegisterRoutes(mux)
 
-Each service has its **own entrypoint** under `/apps/<service>/cmd/<service>`, and a Dockerfile next to it. Shared libraries live in `/pkg`:
+ctx, svc := frame.NewService(
+    frame.WithName("monolith"),
+    frame.WithHTTPHandler(mux),
+)
 
-```text
-/apps/users/cmd/users/main.go
-/apps/users/cmd/users/Dockerfile
-/apps/billing/cmd/billing/main.go
-/apps/billing/cmd/billing/Dockerfile
-/pkg/...
+if err := svc.Run(ctx, ":8080"); err != nil { ... }
 ```
 
-Each binary is independent, but uses the same `/apps` and `/pkg` packages. This matches the structure used in `service-profile`.
-
-## How to Switch Modes
-
-You do **not** need to restructure anything. You only:
-
-- add or remove `apps/<service>/cmd/<service>/main.go` entrypoints
-- build different binaries or Docker images
+## Polylith Mode (Independent Binaries)
 
-This makes the repo **composable** by default.
+Each app has its own binary entrypoint and Dockerfile:
 
-## Recommended Conventions
+- `apps/<service>/cmd/main.go`
+- `apps/<service>/Dockerfile`
 
-- `/apps/<service>` is the source of truth for a service
-- `/apps/<service>/cmd/<service>` is the polylith entrypoint
-- `/cmd/<service>` is the monorepo-level entrypoint (optional)
-- `/pkg` is shared infrastructure and cross-cutting plugins
-- `/configs` holds environment or YAML configs for all services
+The repo-level `cmd/<service>/main.go` gives a consistent top-level build/run entrypoint.
 
 ## One-Command Scaffold
 
-Frame includes a scaffold tool that creates the monorepo layout with per-service entrypoints and Dockerfiles.
-
 ```bash
 go run github.com/pitabwire/frame/cmd/frame@latest init \
   -root . \
   -services users,billing \
   -module your/module
 ```
 
-This generates:
+`-module` is optional. If omitted, Frame tries `go.mod`, then falls back to `example.com/project`.
 
-- `/apps/<service>/cmd/<service>/main.go`
-- `/apps/<service>/cmd/<service>/Dockerfile`
-- `/cmd/monolith/main.go`
-- `/Dockerfile`
-- `/pkg` and `/configs` folders
+Generated artifacts:
 
-## Example: Polylith Entry Point
+- `apps/<service>/cmd/main.go`
+- `apps/<service>/service/routes.go`
+- `apps/<service>/Dockerfile`
+- `cmd/<service>/main.go`
+- `Dockerfile`
+- `pkg` and `configs`
 
-```go
-package main
+## Build Patterns
 
-import (
-	"context"
-	"log"
+Polylith binary:
 
-	"github.com/pitabwire/frame"
-	"your/module/apps/users/service"
-)
+```bash
+go build ./apps/users/cmd
+```
 
-func main() {
-	ctx, svc := frame.NewService(
-		frame.WithName("users"),
-		frame.WithHTTPHandler(service.Router()),
-	)
+Monorepo-level binary for one app:
 
-	if err := svc.Run(ctx, ":8080"); err != nil {
-		log.Fatal(err)
-	}
-}
+```bash
+go build ./cmd/users
 ```
 
-## Example: Monolith Entry Point
+Single-binary monolith is generated from blueprints in monolith mode (`frame build`), producing `cmd/main.go` that composes all routes into one mux.
 
-```go
-package main
+## Docker Build Patterns
 
-import (
-	"context"
-	"log"
-	"net/http"
+Monorepo-level Dockerfile (`/Dockerfile`) uses a multi-stage builder and copies:
 
-	"github.com/pitabwire/frame"
-	"your/module/apps/users/service"
-	"your/module/apps/billing/service"
-)
+- `/apps`
+- `/pkg`
+- `/cmd`
+
+Build an app via top-level cmd entrypoint:
 
-func main() {
-	mux := http.NewServeMux()
-	service.RegisterRoutes(mux)
-	billing.RegisterRoutes(mux)
+```bash
+docker build -t users-service --build-arg APP=users .
+```
 
-	ctx, svc := frame.NewService(
-		frame.WithName("monolith"),
-		frame.WithHTTPHandler(mux),
-	)
+Per-service Dockerfile (`/apps/<service>/Dockerfile`) copies:
 
-	if err := svc.Run(ctx, ":8080"); err != nil {
-		log.Fatal(err)
-	}
-}
+- `/apps/<service>`
+- `/pkg`
+
+Build a single polylith app:
+
+```bash
+docker build -t users-service -f apps/users/Dockerfile .
 ```