docs: refresh llms.txt, add AGENTS.md, fix stale public docs

AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md — working in fursy
+
+fursy is a Go 1.27 HTTP router (`github.com/coregx/fursy`) with type-safe generic handlers,
+RFC 9457 problem responses and OpenAPI 3.1 generation.
+
+## Start here
+
+- `README.md` — overview, quick start, middleware and examples.
+- `llms.txt` — the detailed guide for AI agents (this file is the short entry).
+- `CHANGELOG.md` — current version and changes.
+- `CONTRIBUTING.md` — contribution workflow and checks.
+
+## Rules that matter
+
+- `go 1.27` is the module floor. Core routing has zero external dependencies; middleware adds only
+  `golang-jwt/jwt` (JWT) and `golang.org/x/time` (rate limit).
+- Plain handlers use `router.Handle("GET", path, fn)` with `*fursy.Context`; typed handlers use
+  `router.GET(path, func(c *fursy.Box[Req, Res]) error)`.
+- `*fursy.Context` is pooled: never keep a reference after the handler returns.
+- Errors are RFC 9457 problems by default; JSON fields are camelCase.
+- `middleware.Timeout` is cooperative: it sets a context deadline and returns 503 when the handler
+  returns the deadline error before writing. Register header-setting middleware (CORS, Secure)
+  before `Timeout`, or their headers are discarded with the handler's on a 503.
+- Fixes and features start with a failing test. Before a PR: `gofmt`, `go test ./...`,
+  `golangci-lint run` (0 issues), and the example/plugin modules still build.

CONTRIBUTING.md

@@ -190,8 +190,7 @@ fursy/
 ├── internal/             # Internal implementation (not in Go docs)
 │   ├── radix/           # Radix tree routing engine
 │   ├── binding/         # Request body binding (JSON, XML, form)
-│   ├── negotiate/       # Content negotiation
-│   └── validation/      # Validation internals
+│   └── negotiate/       # Content negotiation
 ├── middleware/           # Built-in middleware (flat package, not subdirs)
 │   ├── logger.go        # log/slog logging
 │   ├── recovery.go      # Panic recovery
@@ -200,6 +199,7 @@ fursy/
 │   ├── jwt.go           # JWT authentication
 │   ├── ratelimit.go     # Rate limiting
 │   ├── circuitbreaker.go # Circuit breaker
+│   ├── timeout.go       # Cooperative request timeout
 │   └── secure.go        # Security headers (OWASP)
 ├── plugins/              # Optional plugins (can have dependencies)
 │   ├── opentelemetry/   # Tracing + metrics

README.md

@@ -134,11 +134,13 @@ router.ServeOpenAPI("/openapi.json")
 
 ### Production-Ready Performance
 
-- **~53 ns/op** static routes, **~75 ns/op** parametric routes
-- **0 allocations/op** (zero-allocation routing)
+- **Zero allocations per request** (zero-allocation routing)
+- **Sub-microsecond routing** for static and parametric routes
 - Zero-allocation radix tree routing
 - Efficient context pooling
 
+Measured example: **142 ns/op** static and **213 ns/op** parametric, **0 B/op**, on a 12th Gen Intel i7-1255U (go1.27.4, 2026-11-11). Routing time depends on the hardware; run `go test -bench=BenchmarkRouter -benchmem ./` for your own numbers.
+
 ---
 
 ## 📦 Installation
@@ -153,7 +155,7 @@ go get github.com/coregx/fursy
 
 ## 🚀 Features
 
-- ✅ **High Performance Routing** - ~53 ns/op static, ~75 ns/op parametric, 0 alloc/op
+- ✅ **High Performance Routing** - sub-microsecond routing, 0 allocations/op
 - ✅ **Type-Safe Generic Methods** - `router.POST()` with Box[Req, Res] and Go 1.27 type inference
 - ✅ **Automatic Validation** - Set once, validate everywhere with 100+ tags
 - ✅ **Content Negotiation** - RFC 9110 compliant, AI agent support
@@ -1257,7 +1259,7 @@ We welcome contributions! Please see:
 **Development Requirements**:
 - Go 1.27+
 - golangci-lint
-- Follow git-flow branching model
+- GitHub Flow: feature branch → PR → main (no direct pushes)
 
 **Want to help?**
 - ⭐ Star the repo

ROADMAP.md

@@ -3,7 +3,7 @@
 > **Strategic Advantage**: Modern Go 1.27+ features + proven routing patterns!
 > **Approach**: Combine best practices from httprouter, Gin, Echo with type-safe generics
 
-**Last Updated**: 2026-09-11 | **Current Version**: v0.6.1 (RFC 9457 Default Errors + Security Fixes + AIP-136) | **Phase**: Phase 4 In Progress (Ecosystem) | **Target**: v1.0.0 LTS (TBD, after full API stabilization)
+**Last Updated**: 2026-11-11 | **Current Version**: v0.7.0 (see CHANGELOG.md) | **Phase**: Phase 4 In Progress (Ecosystem) | **Target**: v1.0.0 LTS (TBD, after full API stabilization)
 
 ---
 
@@ -46,7 +46,7 @@ Phase 0 (Setup) ✅ COMPLETE
 v0.1.0 (Foundation + Production Features) ✅ RELEASED (Phase 0-3)
       ↓ Radix tree, middleware, groups, generics, RFC 9457,
       ↓ Auth, rate limiting, circuit breaker, pooling
-v0.2.0 (Documentation & Examples) ← CURRENT RELEASE (Phase 4.1)
+v0.2.0 (Documentation & Examples) (historical, Phase 4.1)
       ↓ Validator plugin, 11 examples, comprehensive docs, AI guide
 v0.3.0+ (Future Ecosystem) ← FUTURE (Phase 4 - Q1-Q3 2026)
       ↓ Plugins, docs website, community
@@ -472,5 +472,5 @@ v1.0.0 LTS → Long-term support (Q3 2026)
 
 ---
 
-*Version 1.2 (Updated 2025-11-24)*
-*Current: v0.2.0 Production Ready + Documentation & Examples | Phase: Phase 4 In Progress ✅ | Next: v0.3.0+ (feature-driven) | Target: v1.0.0 LTS (TBD, after API stabilization)*
+*Version 1.3 (Updated 2026-11-11)*
+*Current: v0.7.0 (see CHANGELOG.md) | Phase: Phase 4 In Progress ✅ | Next: feature-driven releases | Target: v1.0.0 LTS (TBD, after API stabilization)*

examples/05-middleware/main.go

@@ -1,7 +1,7 @@
 // Package main demonstrates all built-in and custom middleware in fursy.
 //
 // This example showcases:
-//   - All 8 built-in middleware (Logger, Recovery, CORS, BasicAuth, JWT, RateLimit, CircuitBreaker, Secure)
+//   - All 9 built-in middleware (Logger, Recovery, CORS, BasicAuth, JWT, RateLimit, CircuitBreaker, Secure, Timeout)
 //   - Custom middleware patterns (RequestID, Timing, Authentication)
 //   - Middleware ordering best practices
 //   - Group-level middleware
@@ -294,6 +294,24 @@ func main() {
 		})
 	})
 
+	// ===========================================
+	// TIMEOUT DEMO
+	// ===========================================
+
+	timed := router.Group("/timed")
+
+	// Cooperative timeout: the handler must honor the request context.
+	timed.Use(middleware.Timeout(2 * time.Second))
+
+	timed.Handle("GET", "/slow", func(c *fursy.Context) error {
+		select {
+		case <-time.After(10 * time.Second):
+			return c.String(http.StatusOK, "done")
+		case <-c.Request.Context().Done():
+			return c.Request.Context().Err() // the middleware turns this into a 503 Problem
+		}
+	})
+
 	// ===========================================
 	// START SERVER
 	// ===========================================
@@ -319,6 +337,9 @@ func main() {
 	slog.Info("  Circuit Breaker:")
 	slog.Info("    GET  /circuit/flaky     - Flaky service (fails 3 times, then succeeds)")
 	slog.Info("")
+	slog.Info("  Timeout:")
+	slog.Info("    GET  /timed/slow        - Cooperative 2s timeout (503)")
+	slog.Info("")
 	slog.Info("Visit: http://localhost:8080")
 
 	if err := http.ListenAndServe(":8080", router); err != nil {

examples/10-production-boilerplate/README.md

@@ -1,8 +1,8 @@
 # Production Boilerplate - DDD Architecture
 
-> **Complete, production-ready REST API** with real-time features demonstrating modern Go development practices using **fursy + stream + Relica**.
+> **Complete, production-ready REST API** with real-time features demonstrating modern Go development practices using **fursy + stream + SQLite (database/sql)**.
 
-[![Go Version](https://img.shields.io/badge/Go-1.25+-blue.svg)](https://go.dev)
+[![Go Version](https://img.shields.io/badge/Go-1.27+-blue.svg)](https://go.dev)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ---
@@ -16,7 +16,7 @@ This is a **reference implementation** of a production-ready REST API showcasing
 - **Type-safe HTTP routing** with fursy
 - **Real-time communications** (SSE + WebSocket)
 - **JWT Authentication** & Authorization
-- **Database persistence** with Relica
+- **Database persistence** with database/sql and SQLite
 - **RFC 9457 Problem Details** for errors
 - **Docker support** for deployment
 
@@ -562,7 +562,6 @@ go build ./cmd/api
 - [Go Project Layout](https://github.com/golang-standards/project-layout)
 - [fursy Documentation](https://github.com/coregx/fursy)
 - [stream Documentation](https://github.com/coregx/stream)
-- [Relica Documentation](https://github.com/coregx/relica)
 
 ---
 
@@ -589,7 +588,7 @@ For questions or issues:
 **Built with**:
 - [fursy](https://github.com/coregx/fursy) - Fast Universal Routing SYstem
 - [stream](https://github.com/coregx/stream) - SSE + WebSocket library
-- [Relica](https://github.com/coregx/relica) - Fluent SQL query builder
+- [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) - Pure-Go SQLite driver
 - Go 1.27+ modern features
 
 **Status**: Production-ready reference implementation ✅