# Stario

Stario is a Python 3.14+ framework for server-rendered hypermedia apps: explicit `UrlPath` routes, async handlers, `Writer` responses, optional Datastar realtime over SSE, and built-in telemetry. It is not ASGI. Run apps with `stario serve` or `stario watch` and a bootstrap callable such as `app.main:bootstrap`.

## Start Here

- [AGENTS.md](https://stario.dev/AGENTS.md): copy this into every Stario app repo. It is the main agent guide: setup, project layout, commands, Datastar defaults, and common mistakes.
- [llms-full.txt](https://stario.dev/llms-full.txt): compact extended context for LLM tools that want more than `AGENTS.md`.
- [AI-assisted development](https://stario.dev/docs/how-tos/ai-assisted-development): shortest human walkthrough for starting a repo with an agent.

## Core Docs

- [Hello world](https://stario.dev/docs/tutorials/hello-world): first bootstrap, handler, markup, and signals.
- [Getting started](https://stario.dev/docs): live Tiles walkthrough.
- [Structuring apps](https://stario.dev/docs/how-tos/structuring-apps): `app/common/` and `app/features/<name>/` layout.
- [The go-to architecture](https://stario.dev/docs/explanation/go-to-architecture): Datastar, SSE, Relay, and broad morphs first.
- [Routing](https://stario.dev/docs/reference/routing): `App`, `UrlPath`, middleware, redirects, errors.
- [Runtime](https://stario.dev/docs/reference/runtime): bootstrap lifecycle and `STARIO_*` configuration.
- [Datastar](https://stario.dev/docs/reference/datastar): `data`, `at`, `SSE`, `read_signals`.
- [Testing](https://stario.dev/docs/reference/testing): `TestClient`.
- [Telemetry](https://stario.dev/docs/reference/telemetry): spans and tracers.

## Examples

- [chat-room](https://github.com/bobowski/stario/tree/main/examples/chat-room): recommended product-shaped app layout.
- [tiles](https://github.com/bobowski/stario/tree/main/examples/tiles): single-file Relay + SSE teaching example.
- [hello-world](https://github.com/bobowski/stario/tree/main/examples/hello-world): smallest Datastar intro.

## Defaults For New Apps

Scaffold `app/features/<name>/` and `app/common/` from day one. Keep `app/main.py` as the composition root, define paths in per-feature `urls.py`, register routes from `register_<feature>(app, ...)`, keep views as `data -> HTML`, and add Datastar realtime only when the UX needs push updates.

For the first feature, create `urls.py`, `handlers.py`, `views.py`, and `tests/test_<feature>.py`; use `examples/chat-room` as the structural reference.

For realtime, start by morphing the whole page or a large stable fragment. Switch to dedicated target patches only after the broad morph is correct and has proved too expensive or too disruptive.