docs: align examples, add plugin/AI guidance and samples

Author: pitabwire

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,51 @@
+name: "Bug report"
+description: "Report a bug in Frame"
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: Provide minimal steps.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Stack Traces
+      render: shell
+  - type: input
+    id: version
+    attributes:
+      label: Frame Version / Commit
+      placeholder: e.g. v0.9.1 or commit SHA
+    validations:
+      required: true
+  - type: input
+    id: go
+    attributes:
+      label: Go Version
+      placeholder: e.g. go1.22.2
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: OS
+      placeholder: e.g. Ubuntu 22.04
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions / Discussions
+    url: https://github.com/pitabwire/frame/discussions
+    about: Ask questions or propose ideas.

.github/ISSUE_TEMPLATE/docs_request.yml

@@ -0,0 +1,22 @@
+name: "Docs request"
+description: "Ask for documentation improvements"
+title: "[Docs]: "
+labels: ["documentation"]
+body:
+  - type: textarea
+    id: gap
+    attributes:
+      label: Documentation Gap
+      description: What is missing or unclear?
+    validations:
+      required: true
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested Content
+      description: What should be added?
+  - type: textarea
+    id: context
+    attributes:
+      label: Use Case
+      description: How do you plan to use this?

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,27 @@
+name: "Feature request"
+description: "Suggest a new feature or improvement"
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem Statement
+      description: What problem are you trying to solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed Solution
+      description: What should Frame do?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Frame
+
+Thanks for helping make Frame better. We welcome contributions of all sizes: docs, examples, tests, new integrations, and core features.
+
+## What We’re Looking For
+
+High-impact contributions that improve usability and adoption:
+
+- Clear onboarding docs, tutorials, and recipes
+- Example services that demonstrate real patterns
+- New Go Cloud drivers (queue, cache, datastore)
+- Middleware, interceptors, or plugins
+- Testing utilities and benchmarks
+- Performance or reliability improvements
+
+## AI-Assisted Contributions
+
+AI-assisted contributions are welcome. If you use AI tools, please:
+
+- Verify behavior locally and include test coverage when relevant
+- Avoid copy-pasting unverified output into production code
+- Clearly describe what the change does and why
+- Include any prompts or tool notes if they help reviewers understand the change
+
+## Development Workflow
+
+1. Fork the repo and create a branch.
+2. Make changes with tests when possible.
+3. Run:
+
+```bash
+go test -json -cover ./...
+```
+
+4. Open a pull request with a clear description, screenshots/logs if helpful.
+
+## Style Expectations
+
+- Keep APIs simple and composable
+- Prefer explicit configuration via interfaces
+- Avoid breaking changes unless clearly justified
+- Keep docs up to date with code changes
+
+## Reporting Issues
+
+When filing issues, include:
+
+- Frame version or commit hash
+- Reproduction steps
+- Logs or stack traces
+- Environment details (Go version, OS)
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the repository’s license.

README.md

@@ -1,68 +1,86 @@
-# frame        [![Build Status](https://github.com/pitabwire/frame/actions/workflows/run_tests.yml/badge.svg?branch=main)](https://github.com/pitabwire/frame/actions/workflows/run_tests.yml)   [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pitabwire/frame)
+# Frame
 
-A simple frame for quickly setting up api servers based on [gocloud](https://github.com/google/go-cloud) framework.
+[![Build Status](https://github.com/pitabwire/frame/actions/workflows/run_tests.yml/badge.svg?branch=main)](https://github.com/pitabwire/frame/actions/workflows/run_tests.yml)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/pitabwire/frame)
 
-Features include:
+A fast, extensible Golang framework with a clean plugin-based architecture.
 
-- An http server
-- A grpc server
-- Database setup using [Gorm](https://github.com/go-gorm/gorm) with migrations and multitenancy support
-- Easy queue publish and subscription support
-- Localization
-- Authentication adaptor for oauth2 and jwt access
-- Authorization adaptor
+Frame helps you spin up HTTP and gRPC services with minimal boilerplate while keeping strong runtime management, observability, and portable infrastructure via Go Cloud.
 
-The goal of this project is to simplify starting up servers with minimal boiler plate code.
-All components are very pluggable with only the necessary configured items loading at runtime 
-thanks to the power of go-cloud under the hood.
+## Features
 
-# Getting started:
+- HTTP and gRPC servers with built-in lifecycle management
+- Datastore setup using GORM with migrations and multi-tenancy
+- Queue publish/subscribe (Go Cloud drivers: `mem://`, `nats://`, etc.)
+- Cache manager with multiple backends
+- OpenTelemetry tracing, metrics, and logs
+- OAuth2/JWT authentication and authorization adapters
+- Worker pool for background tasks
+- Localization utilities
 
-```
-    go get -u github.com/pitabwire/frame
+## Install
+
+```bash
+go get -u github.com/pitabwire/frame
 ```
 
-# Example
+## Minimal Example
+
+```go
+package main
 
-````go 
 import (
-	"context"
-	"fmt"
-	"github.com/gorilla/mux"
-	"github.com/pitabwire/frame"
-	"log"
-	"net/http"
+    "context"
+    "net/http"
+
+    "github.com/pitabwire/frame"
 )
 
-func handler(w http.ResponseWriter, r *http.Request) {
-	fmt.Fprintf(w, "Frame says yelloo!")
+func main() {
+    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+        w.Write([]byte("Frame says hello"))
+    })
+
+    _, svc := frame.NewService(
+        frame.WithName("hello"),
+        frame.WithHTTPHandler(http.DefaultServeMux),
+    )
+
+    _ = svc.Run(context.Background(), ":8080")
 }
+```
 
+## Documentation
 
-func main() {
+- Start here: `docs/index.md`
+- Live site: https://pitabwire.github.io/frame/
+
+## Docs Site (MkDocs)
 
-	serviceName := "service_authentication"
-	ctx := context.Background()
+```bash
+pip install mkdocs mkdocs-material
+mkdocs serve
+```
 
-	router := mux.NewRouter().StrictSlash(true)
-	router.HandleFunc("/", handler)
+## Development
 
-	server := frame.HttpHandler(router)
-	service := frame.NewService(frame.WithName(serviceName,server))
-	err := service.Run(ctx, ":7654")
-	if err != nil {
-		log.Fatal("main -- Could not run Server : %v", err)
-	}
+To run tests, start the Docker Compose file in `./tests`, then run:
 
-}
-````
+```bash
+go test -json -cover ./...
+```
+
+## Contributing
+
+If Frame helped you, please consider starring the repo and sharing it.
+
+We’re actively looking for contributions that make Frame easier to use and more productive for Go teams. Examples:
 
-Detailed guides can be found in `docs/index.md` (and on https://pitabwire.github.io/frame/).\n+\n+## Docs site (MkDocs)\n+\n+```bash\n+pip install mkdocs mkdocs-material\n+mkdocs serve\n+```\n*** End Patch"}**
+- Improve onboarding guides or add real-world examples
+- Add new Go Cloud drivers (queue, cache, datastore)
+- Add middleware, interceptors, or CLI tooling
+- Expand testing utilities or reference architectures
 
+AI-assisted contributions are welcome. If you use AI tools, please verify behavior locally and include tests where relevant.
 
-## development
-To run tests start the docker compose file in ./tests
-then run : 
-````
-    go test -json -cover ./...
-````
+Open an issue or PR with your idea — even small improvements make a big difference.

docs/ai-assistants.md

@@ -0,0 +1,48 @@
+# Using Frame with AI Coding Assistants
+
+This page exists to help humans and AI tools converge on the **correct** Frame usage patterns.
+
+## Preferred Bootstrap Pattern
+
+Always start services like this:
+
+```go
+ctx, svc := frame.NewService(
+    frame.WithName("my-service"),
+    frame.WithHTTPHandler(router),
+    // other options...
+)
+
+if err := svc.Run(ctx, ":8080"); err != nil {
+    log.Fatal(err)
+}
+```
+
+This is the canonical pattern that matches Frame’s API.
+
+## Recommended Project Layout
+
+```text
+/cmd/myservice/main.go
+/internal/handlers/...
+/internal/plugins/...
+/internal/clients/...
+/configs/...
+```
+
+## How to Ask AI for Frame Code
+
+Use these prompt patterns:
+
+- “Generate a new HTTP service using Frame, using the canonical `ctx, svc := frame.NewService(...)` bootstrap pattern.”
+- “Create a new Frame plugin as a `WithXxx` option that registers a queue subscriber.”
+- “Add a datastore setup using `WithDatastore` and a migration step.”
+
+## Frame Plugin Mental Model
+
+A plugin is a `frame.Option` helper that configures a `Service` and registers startup/cleanup hooks. See `docs/plugins-options.md`.
+
+## Don’ts
+
+- Don’t assume `NewService` returns `*Service` directly; it returns `(context.Context, *Service)`.
+- Don’t assume `WithName` accepts a handler; use `WithHTTPHandler` separately.

docs/architecture.md

@@ -11,6 +11,15 @@ Frame is a fast, extensible Go framework built around a minimal core `Service` a
 
 Frame bootstraps a `Service` that owns shared runtime state and managers. Options configure the service and register startup hooks. The service then starts HTTP/gRPC servers, background workers, and pluggable components.
 
+```
+ctx, svc := frame.NewService(
+  frame.WithName("my-service"),
+  frame.WithHTTPHandler(handler),
+  // other options...
+)
+_ = svc.Run(ctx, ":8080")
+```
+
 ```
 Service
   -> Config (env, YAML, or custom)

docs/examples.md

@@ -0,0 +1,23 @@
+# Examples
+
+These examples are small, compilable, and use the canonical Frame bootstrap pattern.
+
+## HTTP Basic
+
+- Path: `examples/http-basic`
+- Run: `go run ./examples/http-basic`
+
+## gRPC Basic
+
+- Path: `examples/grpc-basic`
+- Run: `go run ./examples/grpc-basic`
+
+## Queue Basic
+
+- Path: `examples/queue-basic`
+- Run: `go run ./examples/queue-basic`
+
+## Datastore Basic
+
+- Path: `examples/datastore-basic`
+- Run: `go run ./examples/datastore-basic`