sillo-framework 0.3.2.dev1__tar.gz → 1.0.0__tar.gz

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0}/CHANGELOG.md

@@ -7,6 +7,139 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-09-26
+
+Sillo 1.0 is the stable release of the context-based framework API.
+
+### Added
+
+- Stable routing, dependency injection, middleware, queues, scheduler,
+  WebSockets, OpenAPI, records, authentication, storage, mail, and testing
+  integrations documented in the v1.0 manual.
+
+### Changed
+
+- The v1.0 handler and application APIs are now the supported public surface.
+- The package is published as a production/stable release for Python 3.10+.
+
+## [1.0.0rc1] - 2026-09-22
+
+The first release candidate of 1.0.
+
+### Changed
+
+- **`Depend(fn, get_context=...)` now defaults `get_context` to `False`.** Most dependencies need no context at all — a settings object, a computed value, a sub-dependency built from other extractors — and previously still had to declare a leading, unused context parameter (conventionally named `_`) to satisfy the old default of `True`. A dependency that does need the active context now opts in explicitly with `Depend(fn, get_context=True)`; without it, the dependency's own first parameter is analyzed like any other, eligible for `Depend` or an extractor default, and nothing is passed positionally at call time. **This is a breaking change**: every existing `Depend(fn)` call whose `fn` reads the context off its first parameter needs `get_context=True` added, or that parameter silently stops receiving the context (and instead has whatever `Query`/`Header`/`Depend` default it declares, if any, or a missing-argument error if none). `sillo.work.dependency`'s built-in providers (`scheduler`, `queue_connection`, `events`, `default_queue`) all need it, since each reads `ctx.base_app`.
+- **A `raise ... from ...` cascade in the terminal error block now boxes each link.** A chained cause used to collapse to a single `from Type: message` line, unreadable once a few wrapping layers stacked up. Each cause now gets its own bordered box (type, message, location, the line it broke on), stacked under `caused by`; a chain deeper than four links folds the rest into a one-line `… N more` summary.
+
+## [1.0.0a2] - 2026-09-18
+
+The second alpha of 1.0.
+
+### Added
+
+- **`Depend(fn, get_context=False)`.** A dependency previously always had its first positional parameter reserved for the context, forcing dependencies that don't need it to declare a leading, unused parameter (often named `_`). `get_context=False` opts out: no context is passed positionally, and the callable's own first parameter is analyzed normally, so it can carry a `Depend(...)` or extractor default of its own.
+
+### Fixed
+
+- **A rejected CSRF request now carries a usable token.** A 403 for a missing or invalid token went out without a `Set-Cookie`, even though a fresh token had already been minted for it — a client with no cookie yet (its first request is a POST, or an earlier `Set-Cookie` was dropped by a CDN or proxy) got a 403 with nothing to retry with, and every retry failed the same way.
+- **A `Group` whose own mount prefix carries a path parameter now matches.** `Group(path="/tenants/{id:int}", app=...)` stripped the *literal template text* (`{id:int}` included) off the request path instead of the text the pattern actually matched, so a request under such a group fell through to the mounted app with its path untouched and 404'd there instead.
+
+### Removed
+
+- **`SilloApp.wrap_asgi(...)` is gone.** `app.use(...)` now accepts a raw ASGI middleware factory directly, in place of a dispatch function — sillo infers which form it is from the middleware's `__call__` signature (three required positional parameters is raw ASGI, two is dispatch), or `raw=True`/`raw=False` states it explicitly. `app.wrap_asgi(mw, **kwargs)` becomes `app.use(mw, **kwargs)` (or `app.use(mw, raw=True, **kwargs)` when the signature is ambiguous, e.g. a factory taking only the next app). `Router.use(...)` gained the same `raw`/`*args`/`**kwargs` parameters.
+
+## [1.0.0a1] - 2026-09-12
+
+The first alpha of 1.0 — **the context rewrite**. This is a breaking release
+with no compatibility shims. Install with
+`pip install --pre sillo-framework==1.0.0a1`.
+
+An alpha: the surface below is what 1.0 is expected to look like, but it is not
+frozen yet, and API may still change before `1.0.0`.
+
+### Added
+
+- **Host-scoped routers — `Router(host=...)`.** A router only answers requests whose `Host` header matches. Exact (`admin.example.com`) or a single-label wildcard (`*.example.com`). A request to another host falls through to the rest of the app.
+- **Version-scoped routers — `Router(version=...)`.** A router only answers requests carrying a matching `X-API-Version` header, or an `Accept` media type with a `version=<value>` parameter. Lets a `v1` and `v2` router share the same paths and be picked by the client.
+- **`Router(middleware=[...])`.** Register router middleware at construction — dispatch callables, `DefineMiddleware`, or `(cls, args, kwargs)` tuples — instead of a run of `router.use(...)` calls. First in the list is the outermost layer.
+- **`SilloApp(root_path=...)`.** A mount prefix a reverse proxy strips before forwarding. It is folded into `scope["root_path"]`, removed before route matching, and re-added by `ctx.url_for(...)` and the OpenAPI `servers` block, so generated links stay correct.
+- **`SilloApp(force_https=True)`.** Any plain-`http` request is answered with a 308 to the `https` URL. `X-Forwarded-Proto: https` from a proxy is honoured, so a TLS-terminating proxy in front of an `http` app does not loop.
+- **`SilloApp(trailing_slash=...)` / `Router(trailing_slash=...)`.** `"strict"` (default, `/x` ≠ `/x/`), `"redirect"` (308 to the registered form), or `"ignore"` (serve it in place).
+- **Declarative redirects — `app.redirect(path, to, *, status_code=307, ...)`** (and `Router.redirect`). Registers a redirect-only route, no handler. Placeholders shared by both sides are substituted (`app.redirect("/u/{id}", "/users/{id}")`); a mount prefix and the query string are carried across. Hidden from the schema.
+- **`app.print_routes()`** and `sillo.core.routing.{iter_routes, format_routes, print_routes}` — walk the router and every mount, fold prefixes in, and render `METHODS  PATH  handler  (name)` rows for a startup log or a REPL.
+- **New path converters**: `bool` (`true`/`1`/`yes`/`on` and their negatives, any case → real `bool`), `date` (`YYYY-MM-DD` → `datetime.date`), `datetime` (ISO 8601, `Z` accepted → `datetime.datetime`), `ulid` (26 Crockford base32 chars), `alpha` (`[A-Za-z]+`), `alnum` (`[A-Za-z0-9]+`).
+- **`priority=` on routes.** `@app.get(..., priority=10)` (also on `Route(...)`, `add_route(...)`, and `ws_route(...)`) sets an explicit match-ordering weight. Routes are tried in descending priority, then by path specificity, then registration order. Raise it to force a route ahead of an overlapping one; use a negative value to make a route a deliberate fallback.
+- **`SilloApp(route_order=...)` / `Router(route_order=...)`.** `"specificity"` (the new default) or `"registration"` to restore the historical first-registered, first-matched behavior for a whole application. Documented in [Routing → Route matching order](https://sillo.build/v1.0/guides/routing/#route-matching-order).
+- **`app.dependency_overrides`** and **`app.override(original, replacement)`.** Swap a `Depend(...)` callable for a test double, FastAPI-style. Matched by identity against the exact function passed to `Depend`, and reached through every nested dependency in the tree, not only the top-level one. `app.override(...)` is a context manager that restores the previous mapping (present or absent) on exit, including on exception; assign `app.dependency_overrides[original] = replacement` directly for a suite-wide swap that outlives a single `with` block.
+
+### Changed
+
+- **A handler takes one leading argument: the context.** `HttpContext` on an
+  HTTP route, `WebSocketContext` on a WebSocket route. Path parameters,
+  dependencies and validation markers follow it, bound by name as before:
+
+  ```python
+  from sillo import SilloApp, HttpContext, json
+
+  app = SilloApp()
+
+  @app.get("/users/{id:int}")
+  def show(ctx: HttpContext, id: int):
+      return json({"id": id})
+  ```
+
+  `BaseContext` carries `scope`, `headers`, `cookies`, `path_params`,
+  `query_params`, `state`, `user`, `client`, `app` and `url_for`.
+  `HttpContext` adds `method`, `await ctx.json`, `await ctx.body`,
+  `await ctx.form`, `ctx.files` and `ctx.validated_data`.
+
+- **Responses are functions, in `sillo.responses`**, every name re-exported
+  from `sillo` — bodies (`json`, `text`, `html`, `xml`, `raw`, `empty`), status
+  shorthands (`created`, `accepted`, `no_content`), redirects, files
+  (`file`, `download`), streaming (`stream`, `ndjson`, `sse`), pagination
+  (`paginate`, `apaginate`, which take `ctx` first) and `abort` / `not_found`,
+  which raise rather than return. Each builder returns a `BaseResponse`
+  subclass carrying the chainable half (`status`, `cache`, `set_header`,
+  `set_cookie`, …), each returning `self`. Import from the module when the file
+  also needs the stdlib `json`/`html` or the `file` builtin.
+
+- **WebSocket routes bind path parameters.** They were read from
+  `scope["path_params"]`, which the router never writes, so the keyword
+  arguments a handler declared were always empty. Note that the registration
+  name is `ws_route` / `add_ws_route`; there is no `@app.websocket(...)`.
+
+- **An unhandled request error logs a structured block, not a raw traceback.** `sillo.handlers.error_report` keeps only the frames in *your* code:
+
+  ```
+  💥 oops — KeyError: 'ABC-9'
+      request   GET /catalog/ABC-9
+      at        api/catalog.py:14   in show
+                → price = lookup(catalog, sku)
+      at        pricing/rules.py:2   in lookup
+                   1   def lookup(catalog, sku):
+               ›   2       price = catalog["items"][sku]["price"]
+                                   ^^^^^^^^^^^^^^^^^^^^^
+                   3       return price * 1.2
+      with      catalog={'items': {}}, sku='ABC-9'
+  ```
+
+  Each calling frame is one line; the frame it broke on gets a window of real source with the line marked `›` (bright, its neighbours dim) and a caret under the exact expression (Python 3.11+, single-line). `file:line` is cyan, the function bold. `with` lists the raising frame's own locals — scalars and small containers verbatim, a big one as `<dict len=N>`, a name that reads like a secret as `***`. `SILLO_TRACE` sets the depth — `off`, `app` (default while `debug` is on), `full` (append the raw traceback). Off a terminal or with `debug` off, nothing is rendered; one structured line goes to the logger instead. Every 500 also stopped logging two-to-three times — `sillo.core.error.handler` was creating a child logger with its own handler that still propagated to the parent's.
+- **Overlapping routes now match most-specific-first, not registration-first.** A literal segment beats a parameter at the same position, a narrow converter (`:int`, `:float`, `:uuid`) beats a plain string parameter, and both beat a `:path` catch-all — decided left to right. `@app.get("/users/{id}")` no longer shadows a `@app.get("/users/me")` registered after it. The ordering is computed once, lazily, on the first request after registration, so per-request dispatch is unchanged. Pass `route_order="registration"` to opt out.
+- **A 404 response no longer carries a traceback.** The stack of `raise NotFoundException` is the router's, not the caller's — it named internal framework paths and told a developer nothing about their own code. Debug mode still widens the *message* (the exception's `detail` instead of the generic sentence); it no longer adds a `traceback` field.
+- **The 404 and debug (500) HTML pages are restyled** to match Sillo's own terminal aesthetic — dark background, monospace, brand red (`#fc0345`) — instead of a light Arial page for 404s and a page whose `--error`/accent variable was, by mistake, green (`#02ba42`) rather than red for the debug page. Both pages, and two other spots on the debug page that bypassed the CSS variables with a hardcoded color, now flow from the same palette as the terminal error log.
+- **`SilloApp(debug=...)` now defaults to `False`.** It previously defaulted to `True`, so a project that never passed `debug` explicitly shipped with the full debug page — and a verbose terminal error log — on by default. An app that wants debug output in local development now has to say so.
+- **The terminal error trace no longer depends on `debug`.** It only ever prints to the server's own terminal — nothing in it reaches a client — so it now defaults on whenever `stderr` is an actual terminal, regardless of `debug`. Previously it rode on `debug`'s default, so the flip above would otherwise have silently taken the pretty trace away from local development along with the (correct) HTTP-facing change. `SILLO_TRACE` still overrides either way.
+
+### Removed
+
+- **`Request`, the `Response` manager and the `Responder` builder are gone**,
+  and nothing is shimmed. `sillo/core/http/request.py` no longer exists.
+- **The built-in admin panel is no longer part of the framework.** It is its
+  own package now — [`warder`](https://sillo.build/packages/warder/).
+- **`Depend(get_request=True)` / `Depend(get_context=True)`** — a dependency
+  takes the context as its first positional parameter instead.
+
+
 ## [0.3.2.dev1] - 2026-09-07
 
 A development pre-release for testing. Install with `pip install --pre sillo-framework==0.3.2.dev1`.

{sillo_framework-0.3.2.dev1 → sillo_framework-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sillo-framework
-Version: 0.3.2.dev1
+Version: 1.0.0
 Summary: Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model.
 Project-URL: Homepage, https://github.com/sillohq/core
 Project-URL: Repository, https://github.com/sillohq/core
@@ -10,7 +10,7 @@ Author-email: Chidebele Dunamis <techwithdunamix@gmail.com>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
 Keywords: API,ASGI,HTTP,Python,async,asynchronous,backend,concurrent,framework,real-time,scalable,uvicorn,web,web server,websocket
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -31,6 +31,7 @@ Requires-Python: >=3.10
 Requires-Dist: anyio==4.14.1
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: tomli>=2.0.1; python_version < '3.11'
 Requires-Dist: typing-extensions>=4.12.2; python_version < '3.13'
 Requires-Dist: uvicorn>=0.27.0
 Provides-Extra: all
@@ -96,12 +97,14 @@ Provides-Extra: record
 Requires-Dist: tortoise-orm>=1.0; extra == 'record'
 Provides-Extra: storage-s3
 Requires-Dist: httpx>=0.23.3; extra == 'storage-s3'
+Provides-Extra: test
+Requires-Dist: httpx<0.29.0,>=0.23.3; extra == 'test'
 Description-Content-Type: text/markdown
 
 # Sillo
 
 <p align="center">
-  <img src="https://avatars.githubusercontent.com/u/199959103?s=400&u=2b9d0cb939318b295fefd0cdbc417f85d5d4ba87&v=4" alt="Sillo logo" width="160" height="160">
+  <img src="https://raw.githubusercontent.com/sillohq/core/main/docs/docs/public/logo-colored.svg" alt="Sillo logo" width="160" height="160">
 </p>
 
 <p align="center">
@@ -123,53 +126,38 @@ Description-Content-Type: text/markdown
   <a href="https://github.com/sillohq/core/blob/main/LICENSE"><img src="https://img.shields.io/pypi/l/sillo-framework?color=green" alt="License"></a>
 </p>
 
-> [!IMPORTANT]
-> **This branch is Sillo 1.0, and 1.0 is not released.**
->
-> `main` is where 1.0 is being built. Nothing here is on PyPI, the API is still
-> moving, and it is not backwards compatible with the released line — handlers
-> take a single `ctx` argument, `sillo.graphql` and the WebSocket room layer
-> have moved into [their own packages](https://docs.sillo.build/packages/), and
-> more will change before it ships.
->
-> **`pip install sillo-framework` installs 0.x, not this.** The released code
-> lives on **[`v0.x`](https://github.com/sillohq/core/tree/v0.x)**, which is
-> where fixes and dependency updates go and where releases are cut from. Its
-> documentation is at
-> **[docs.sillo.build/v0.x](https://docs.sillo.build/v0.x/guides/introduction/)**.
->
-> Reading about the version you have installed? You want
-> [`v0.x`](https://github.com/sillohq/core/tree/v0.x). Building against 1.0
-> before it ships? Install from this branch:
->
-> ```bash
-> pip install "git+https://github.com/sillohq/core.git@main"
-> ```
->
-> The 1.0 documentation is at
-> [docs.sillo.build/v1.0](https://docs.sillo.build/v1.0/guides/introduction/),
-> and every page in it says the same thing at the top.
+<sub>Sillo 1.0 is the stable release. Install it from PyPI with `pip install sillo-framework`, or add it with `uv add sillo-framework`. Read the [v1.0 docs](https://docs.sillo.build/v1.0/guides/introduction/).</sub>
 
 Sillo is the buildsmith framework for APIs, real-time systems, and production backends: fast, async, and built with everything you need to ship, with the ORM, authentication, queues, scheduler, and WebSockets already in place. The language does not change. You write the same Python, with the same type hints and the same `async`/`await`. What changes is how much is waiting for you when you start: routing, request validation, dependency injection, middleware, sessions, authentication, records, background work, WebSockets, OpenAPI, and testing are first-party modules sharing one configuration model.
 
 Each of those is a solved problem with good packages behind it. The work that remains is the fitting, and that is what Sillo does once so you do not do it per project. One `auth=` declaration gates a route and writes its `securityScheme` into the OpenAPI spec. The queue and the scheduler start with the application lifecycle. Range requests, ETags, and content negotiation are middleware rather than something each project rewrites.
 
-## Project Health
-
-| | |
-|---|---|
-| Tests | 5,243 passing with none skipped, on CPython 3.10 through 3.14. Python 3.15 is in the matrix too and passes, but is not claimed on PyPI until it ships final |
-| Coverage | 91%, with a 90% floor enforced in CI before anything is published |
-| Types | Ships `py.typed`, so your own checker sees Sillo's annotations rather than `Any` |
-| Type check | `ty` clean across the package |
-| Lint and format | `ruff` clean, checked on every push |
-| Dependencies | Five at install time. Everything else is an opt-in extra |
-| License | BSD-3-Clause |
-
-None of this is aspirational. The coverage floor fails the build rather than
-printing a warning, the type check runs on every supported Python, and the
-badges above read from those same workflows rather than from a number written
-here by hand.
+The badges above are the only numbers this README states about itself — they
+read live from the workflows that produce them, so they can't drift out of
+date the way a hand-typed table does. `py.typed` ships in the package, so
+your own checker sees Sillo's actual annotations rather than `Any`; five
+dependencies land at install time, and every feature group past that —
+records, JWT, Redis-backed cache and events, mail, encryption, S3, extra
+hashing schemes, Granian — is opt-in, so a service that never sends mail
+never carries a templating engine for it.
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Hello World](#hello-world)
+- [Request Validation](#request-validation)
+- [Dependency Injection](#dependency-injection)
+- [Routing](#routing)
+- [Authentication](#authentication)
+- [Record — the ORM Layer](#record--the-orm-layer)
+- [Background Work: Tasks, Queues, and a Scheduler](#background-work-tasks-queues-and-a-scheduler)
+- [WebSockets](#websockets)
+- [OpenAPI, Without a Second Source of Truth](#openapi-without-a-second-source-of-truth)
+- [Storage, Cache, and Events](#storage-cache-and-events)
+- [What Sillo Provides](#what-sillo-provides)
+- [Scope And Boundaries](#scope-and-boundaries)
+- [Documentation](#documentation)
+- [Testing](#testing)
+- [Release Principles](#release-principles)
 
 ## Requirements
 
@@ -178,15 +166,13 @@ here by hand.
 
 ## Installation
 
-**1.0 is not on PyPI yet.** `uv add sillo-framework` installs 0.x, which is a
-different API — see the note at the top. To build against this branch:
+Install the stable v1.0 release from PyPI:
 
 ```bash
-uv add "sillo-framework @ git+https://github.com/sillohq/core.git@main"
+uv add sillo-framework
 ```
 
-Everything below documents 1.0. For the released line, read
-[the v0.x branch](https://github.com/sillohq/core/tree/v0.x).
+Everything below documents the stable 1.0 API.
 
 ### Extras
 
@@ -217,6 +203,36 @@ packages that import into the `sillo` namespace:
 uv add sillo-graphql     # imports as sillo.graphql
 ```
 
+## Application setup
+
+Use `app.install(...)` for subsystems that own application state, request
+middleware or lifespan work.  It keeps the application's wiring together while
+leaving `app.use(...)` for explicitly ordered HTTP middleware and
+`app.on_startup(...)` for application-specific jobs:
+
+```python
+from sillo import SilloApp
+from sillo.mail import Mail, MailConfig
+from sillo.record import DatabaseConfig, Record
+from sillo.storage import StorageConfig, StorageInstallable
+from sillo.work import Work
+
+app = SilloApp()
+
+database = app.install(Record(DatabaseConfig.sqlite("app.db"), ("myapp.models",)))
+mail = app.install(Mail(MailConfig(suppress_send=False)))
+storage = app.install(StorageInstallable(StorageConfig()))
+work = app.install(Work())
+```
+
+An installable is idempotent per application name.  Its returned service is
+available through `app.installations` for diagnostics, and remains in its
+documented `app.state` location for framework integrations.  Existing
+`setup_record`, `setup_mail`, `setup_storage`, `setup_work` and
+`setup_scheduler` functions remain supported and delegate to the same path.
+See [Application Installables](https://docs.sillo.build/v1.0/advanced/installables/)
+to build a subsystem of your own.
+
 ## Hello World
 
 A handler takes one argument — the context — plus any path parameters,
@@ -257,23 +273,25 @@ async def old(ctx: HttpContext):
 importable from `sillo` directly. There is no `response` object to thread
 through your call stack.
 
-Run it with uvicorn:
+Run the local development server with Sillo:
 
 ```bash
-uv run uvicorn app:app --reload
+sillo dev
 ```
 
-No import string is needed. `uvicorn` looks for `app.main:app`, `main:app`
+No import string is needed. `sillo dev` looks for `app.main:app`, `main:app`
 and `app:app`, and you can pin it with the `SILLO_APP` environment variable or
 a `[tool.sillo] app` entry in `pyproject.toml`. Pass one explicitly when you
 want something else:
 
 ```bash
-uv run uvicorn api.main:app --port 9000 --workers 4
+sillo dev api.main:app --port 9000
 ```
 
-`uvicorn` is built for development. For production, run the application
-under a process supervisor with a reverse proxy in front of it.
+Sillo uses Uvicorn as the development transport but owns discovery, reload,
+startup links, and request logs. Direct Uvicorn invocation remains supported
+for custom server deployments; for production, run the application under a
+process supervisor with a reverse proxy in front of it.
 
 ## Request Validation
 
@@ -333,25 +351,41 @@ unwrapped:
 
 Use `Depend` to inject request-scoped dependencies into handlers.
 
-A dependency is called like a handler: its first positional parameter is the
-context (`HttpContext`, or `WebSocketContext` on a socket route).
+By default a dependency takes no context: nothing is passed positionally,
+and its first parameter is analyzed like any other, free to carry a
+`Depend` or extractor default of its own:
 
 ```python
-from sillo import Depend, HttpContext, SilloApp
+from sillo import Depend, HttpContext, SilloApp, json
 
 app = SilloApp()
 
 
+def settings() -> dict:
+    return {"feature_flags": []}
+
+
+@app.get("/config")
+async def show(ctx: HttpContext, cfg=Depend(settings)):
+    return json(cfg)
+```
+
+Pass `get_context=True` for a dependency that does need the context — it is
+then called like a handler, the active context (`HttpContext`, or
+`WebSocketContext` on a socket route) as its first positional parameter:
+
+```python
 async def get_current_user(ctx: HttpContext):
     return {"id": "user_1", "name": "Ada"}
 
 
 @app.get("/me")
-async def me(ctx: HttpContext, user=Depend(get_current_user)):
+async def me(ctx: HttpContext, user=Depend(get_current_user, get_context=True)):
     return user
 ```
 
-A dependency that reads the request does so straight off that first parameter:
+A dependency that reads the request does so straight off that first
+parameter, with `get_context=True`:
 
 ```python
 def auth_header(ctx: HttpContext):
@@ -378,6 +412,219 @@ app.mount_router(api)
 Path parameters are converted by the type in the pattern, so `user_id` arrives
 as an `int` and a request for `/api/users/abc` never reaches the handler.
 
+## Authentication
+
+One `AuthenticationMiddleware` accepts any number of backends — session,
+JWT, API key, or your own — and `useAuth` gates a route by naming which of
+them may answer it. The gate and the OpenAPI `securityScheme` it writes come
+from the same declaration, so the published contract can't say more or less
+than what the middleware actually enforces:
+
+```python
+from sillo import HttpContext, SilloApp, json
+from sillo.auth import AuthenticationMiddleware, JWTAuthBackend, useAuth
+from sillo.users import SimpleUser
+
+app = SilloApp()
+app.use(AuthenticationMiddleware(SimpleUser, JWTAuthBackend(secret_key="change-me")))
+
+
+@app.get("/me", auth=useAuth(schemes=["jwt"]))
+async def me(ctx: HttpContext):
+    return json({"id": ctx.user.identity})
+```
+
+Stack backends to accept more than one credential type on the same route
+(`useAuth(schemes=["jwt", "apikey"])`), or write a backend of your own —
+`AuthenticationBackend.authenticate(ctx)` returning an `AuthResult` is the
+entire contract. Users, groups, and permissions sit on top as ordinary
+mixins (`UserProtocol`, `HasScopes`-style permission checks), not a
+parallel object model bolted onto Sillo's own.
+
+## Record — the ORM Layer
+
+Records are Tortoise ORM models with the parts a Django-adjacent codebase
+expects layered back in: attribute casting, transactions with savepoints,
+query scopes, and upsert:
+
+```python
+from tortoise import fields
+
+from sillo.record import Model
+
+
+class User(Model):
+    id = fields.IntField(pk=True)
+    email = fields.CharField(max_length=255, unique=True)
+    plan = fields.CharField(max_length=50, default="free")
+    is_active = fields.BooleanField(default=True)
+    metadata = fields.TextField(null=True)
+
+    _casts = {"metadata": "json"}  # dict in Python, JSON column in the database
+
+    @classmethod
+    def scope_vip(cls, queryset):
+        return queryset.filter(plan="vip")
+
+    @classmethod
+    def scope_active(cls, queryset):
+        return queryset.filter(is_active=True)
+
+
+# from a handler, a script, a job -- scope_vip + scope_active, chained
+active_vip = await User.all().vip().active().order_by("email")
+```
+
+A transaction is a context manager with real savepoints, not a special case
+bolted onto the session:
+
+```python
+from sillo.record.transactions import transaction
+
+# from inside a handler, a job, or a script
+async with transaction() as tx:
+    await ledger.debit(from_account, amount)
+    async with tx.savepoint():
+        await audit_log.write(event)  # rolled back alone if this fails
+    await ledger.credit(to_account, amount)
+```
+
+Global scopes (multi-tenancy filters, soft-delete) attach once and apply to
+every query on the model, with an explicit escape hatch for the query that
+legitimately needs to see past them:
+
+```python
+User.add_global_scope(lambda qs: qs.filter(tenant_id=current_tenant()))
+
+# from a handler, a job, or a script
+await User.all()                     # tenant-filtered
+await User.without_global_scopes()   # everyone, on purpose
+```
+
+## Background Work: Tasks, Queues, and a Scheduler
+
+A job is a class with a `handle()` method; dispatching it is a classmethod
+call from anywhere in the request path, a script, or another job:
+
+```python
+from sillo.work.queue.job import Job
+
+
+class SendWelcomeEmail(Job):
+    queue = "emails"
+    tries = 3
+    timeout = 30
+
+    def __init__(self, user_id: str):
+        self.user_id = user_id
+
+    async def handle(self):
+        user = await User.get(id=self.user_id)
+        await mailer.send(user.email, "welcome")
+
+
+# from a handler, a job, or a script
+await SendWelcomeEmail.dispatch(new_user.id)
+await SendWelcomeEmail.dispatch_after(300, new_user.id)  # five minutes out
+```
+
+The scheduler runs alongside the queue, on the same application lifecycle —
+no separate cron process to keep in sync with the code it calls:
+
+```python
+from sillo.work.scheduler.manager import SchedulerManager
+from sillo.work.scheduler.triggers import CronTrigger
+
+scheduler = SchedulerManager()
+scheduler.schedule(cleanup_expired_sessions, CronTrigger("0 3 * * *"))
+scheduler.every(3600)(refresh_materialised_views)
+```
+
+Retries, timeouts, and rate limits are per-job middleware, not a global
+setting every job inherits whether it needs it or not.
+
+## WebSockets
+
+A socket handler is declared the same way an HTTP one is — a coroutine
+taking a context, with the same dependency injection and the same path
+parameter conversion:
+
+```python
+from sillo import SilloApp
+from sillo.websockets import WebSocketContext, WebSocketDisconnect
+
+app = SilloApp()
+
+
+@app.ws_route("/ws/rooms/{room_id:int}")
+async def chat(ws: WebSocketContext, room_id: int):
+    await ws.accept()
+    try:
+        while True:
+            message = await ws.receive_text()
+            await broadcast(room_id, message)
+    except WebSocketDisconnect:
+        await leave(room_id)
+```
+
+An HTTP route and a WebSocket route can share a path — a GraphQL endpoint
+serving queries over POST and subscriptions over a socket, say — without one
+shadowing the other or a mismatched scope reaching either handler.
+
+## OpenAPI, Without a Second Source of Truth
+
+The schema is generated from the same `request_model`, marker constraints,
+and `useAuth` declarations that already enforce the request at runtime —
+there is nothing to keep in sync by hand, and nothing the spec claims that
+the framework does not also check:
+
+```python
+from sillo.openapi import Scalar, Swagger
+
+app = SilloApp(title="My API", docs=[Swagger(path="/docs"), Scalar(path="/reference")])
+```
+
+Both interactive UIs read the one generated document; adding a second
+renderer is a list entry, not a second integration.
+
+## Storage, Cache, and Events
+
+Storage buckets abstract local disk and S3-compatible object storage behind
+one API, with signed URLs and per-bucket upload policies (content-type
+allowlists, size limits, ownership checks) enforced before a byte is
+written:
+
+```python
+from sillo.storage import BucketConfig, StorageConfig, setup_storage
+from sillo.storage.policies import Owned
+
+storage = setup_storage(app, StorageConfig(
+    default="attachments",
+    buckets={
+        "attachments": BucketConfig(driver="local", root="storage/attachments"),
+        "avatars": BucketConfig(driver="local", root="storage/avatars",
+                                 policy=Owned(), accepts=("image/png", "image/jpeg")),
+    },
+))
+```
+
+Caching is one decorator, backend-agnostic between an in-memory store and
+Redis:
+
+```python
+from sillo.cache import cache
+
+
+@cache(ttl=120, tags=["catalog"])
+async def get_product(product_id: int):
+    return await Product.get(id=product_id)
+```
+
+The event system is a plain emitter (`on`, `emit`) with an optional Redis
+transport for distributing events across processes — the same call site
+either way, so a service can start on the in-memory transport and move to
+Redis later without touching the code that emits or listens.
+
 ## What Sillo Provides
 
 - Async ASGI application core, with lifespan-managed startup and shutdown