Align docs with api

Author: BleedingXiko

docs/app/content/docs/framework/auth.md

@@ -10,24 +10,27 @@ SPRAG includes a built-in auth surface for session management and access control
 
 ## Setup
 
-Wire auth providers into your App:
+Wire auth providers into your `App`. SPRAG looks for `session_store` and `auth` in `app.providers`, and falls back to in-memory sessions plus anonymous auth if you do not provide them:
 
 ```python
-from sprag import App, shell
-from sprag import InMemorySessionStore, AnonymousAuthService
+from sprag import App, InMemorySessionStore, SessionPolicy
 
 app = App(
     routes="app.routes",
-    shell=app_shell,
     providers={
         "session_store": InMemorySessionStore(),
-        "auth": AnonymousAuthService(),
+        "auth": MyAuthService(),
     },
+    session_policy=SessionPolicy(
+        idle_ttl_seconds=3600,
+        absolute_ttl_seconds=86400,
+        remember_me_ttl_seconds=2592000,
+    ),
 )
 ```
 
 - **`InMemorySessionStore`** — stores sessions in memory. Fine for development; swap for Redis/database-backed store in production.
-- **`AnonymousAuthService`** — no-op auth that treats every request as unauthenticated. Replace with your auth provider.
+- **`auth` provider** — implements user loading, login session stamping, authorization, and the public auth snapshot.
 
 ## Login and logout
 
@@ -38,18 +41,18 @@ From any controller:
     "email": Field(str, required=True),
     "password": Field(str, required=True),
 }))
-def login(self, email, password):
+def submit_login(self, email, password):
     user = authenticate(email, password)
     if not user:
         return {"errors": {"email": "Invalid credentials"}}
 
-    # Sets session, rotates session ID
+    # Sets session data and rotates the session ID
     self.login(user, viewer=user.id, active_profile=user.profile)
     return self.redirect("/dashboard")
 
-@action()
-def logout(self):
-    self.logout()  # Invalidates session
+@action(name="logout", schema=Schema("logout", {}))
+def sign_out(self):
+    self.logout()
     return self.redirect("/")
 ```
 
@@ -61,8 +64,9 @@ Inside any controller method:
 
 ```python
 self.request.user          # Authenticated user object (or None)
-self.request.session       # Session dict
+self.request.session       # RequestSession helper
 self.request.session_id    # Session ID string
+self.request.active_profile # Active profile object (or None)
 self.request.cookies       # Request cookies
 ```
 
@@ -102,30 +106,36 @@ class ProfileController(Controller):
 
 ## Browser-side auth
 
-The auth state is included in the browser boot payload at `window.__SPRAG_PAYLOAD__.auth`. Your Module can read it to conditionally render UI:
+SPRAG injects an auth snapshot into route data under `__sprag_auth__`. That same snapshot is also shipped in the browser boot payload, but the stable author-facing name in route data is `__sprag_auth__`:
 
 ```python
-class NavModule(Module):
-    def on_start(self):
-        auth = self.state.get("auth", {})
-        if auth.get("user"):
-            self.set_state({"logged_in": True, "username": auth["user"]["name"]})
+class DashboardScreen(Screen):
+    def render(self, data):
+        auth = data["__sprag_auth__"]
+        viewer = auth.get("viewer") or {}
+        return ui.div(viewer.get("name", "anonymous"))
 ```
 
+For SSR and route data flows, prefer reading `data["__sprag_auth__"]` or explicitly projecting the fields your Module needs from `load()`.
+
 ## Custom auth providers
 
 To integrate a real auth backend (Firebase, Auth0, database), implement the auth service interface and provide it to the App:
 
 ```python
 class MyAuthService:
-    def authenticate(self, request):
-        # Return user object or None
+    def load_user(self, session, request):
         token = request.cookies.get("auth_token")
         return verify_token(token)
 
+    def load_active_profile(self, user, session, request):
+        return None
+
+    def authorize(self, user, active_profile, session, request, *, roles=None, permissions=None):
+        return user is not None
+
 app = App(
     routes="app.routes",
-    shell=app_shell,
     providers={
         "session_store": RedisSessionStore(redis_url),
         "auth": MyAuthService(),

docs/app/content/docs/framework/codegen.md

@@ -127,8 +127,8 @@ Compiles to an arrow function: `(item) => item["id"]`.
 ### Walrus operator
 
 ```python
-if (result := self.call_action("check", {})):
-    self.set_state({"result": result})
+if (count := self.state.get("count", 0)) > 10:
+    self.set_state({"is_large": True})
 ```
 
 Works in statements. Not supported inside comprehensions or lambdas.
@@ -223,17 +223,19 @@ self.on(el, "click", self.handle)  # → this.on(el, "click", (...args) => this.
 
 ## `__init__` (Module only)
 
-Module `__init__` supports field assignments only:
+Module `__init__` can contain normal compilable statements. The main restriction is that `self.state` and `self.screen` are runtime-owned:
 
 ```python
 class MyModule(Module):
     def __init__(self, screen=None, state=None):
         super().__init__(screen=screen, state=state or {})
         self.draft = None
-        self.child = ChildModule()
+        self.config = {"mode": "compact"}
+        if state and state.get("expanded"):
+            self.open = True
 ```
 
-`super().__init__()` calls are stripped. Other statements raise an error.
+`super().__init__()` calls are stripped. Direct assignment to `self.state` or `self.screen` raises an error.
 
 ## `env()` — environment variables
 

docs/app/content/docs/framework/controllers.md

@@ -17,13 +17,14 @@ class TodoController(Controller):
     route = "/todos"
 
     def load(self):
-        return {"items": [], "filter": "all"}
+        todos = self.service("todos")
+        return {"items": todos.list_items(), "filter": "all"}
 
     @action(schema=Schema("add_item", {"text": Field(str, required=True)}))
     def add_item(self, text):
-        items = self.request.data.get("items", [])
-        items.append({"text": text, "done": False})
-        return {"items": items}
+        todos = self.service("todos")
+        todos.add_item(text)
+        return {"items": todos.list_items()}
 ```
 
 ## `load()`
@@ -85,10 +86,10 @@ Inside any controller method, `self.request` gives you the current request:
 |---|---|
 | `self.request.params` | URL params (`slug`, `segments`, etc.) |
 | `self.request.query` | Query string as a dict |
-| `self.request.data` | Current page state (from load or previous action) |
-| `self.request.session` | Session dict |
+| `self.request.session` | `RequestSession` helper |
 | `self.request.session_id` | Session ID string |
 | `self.request.user` | Authenticated user (or `None`) |
+| `self.request.active_profile` | Active auth profile (or `None`) |
 | `self.request.cookies` | Request cookies |
 | `self.request.file(name)` | Uploaded file by field name |
 | `self.request.files_list(name)` | List of uploaded files |
@@ -126,7 +127,7 @@ def build_routes(self, router):
 
     @router.route("/api/items", methods=["POST"])
     def create_item():
-        data = request.json
+        data = self.request.body
         return {"created": True}
 ```
 

docs/app/content/docs/framework/realtime.md

@@ -14,7 +14,7 @@ Instead of pushing full state snapshots over the socket, the server emits a ligh
 
 ```
 Server: emit_socket("items_changed", {})
-Browser: on_socket("items_changed") → call_action("get_items", {})
+Browser: on_socket("items_changed") → call_action("get_items", {}).then(...)
 ```
 
 This keeps the socket channel thin and ensures the browser always has validated, authoritative state.
@@ -49,7 +49,10 @@ class ChatModule(Module):
 
     def _on_message(self, data):
         # Refetch authoritative state from server
-        self.call_action("get_messages", {})
+        self.call_action("get_messages", {}).then(self._on_messages)
+
+    def _on_messages(self, result):
+        self.set_state(result.value or {})
 ```
 
 ## Topics (rooms)
@@ -89,7 +92,7 @@ On the server side, there's a matching shortcut:
 
 ```python
 # Emit the signal and include the refetch hint in one call
-self.emit_socket_refetch("items_changed", action="get_items")
+self.emit_socket_refetch("get_items", event="items_changed")
 ```
 
 ## Session targeting
@@ -111,4 +114,4 @@ Store the `session_id` when you need to push from a background job or service la
 sprag routes
 ```
 
-Controllers that use the socket bridge are tagged with `[socket]` in the output.
+Use this to confirm the route exists and to inspect the action names and schemas your browser code is expected to call.

docs/app/content/docs/framework/routes.md

@@ -16,7 +16,7 @@ app/routes/
 ├── counter/    → /counter
 ├── about/      → /about
 └── blog/
-    └── [slug]/ → /blog/:slug
+    └── [slug]/ → /blog/[slug]
 ```
 
 Route directories are discovered automatically. No manual registration.
@@ -45,9 +45,10 @@ my_page = page(
 | `path` | Yes | URL path for this route |
 | `controller` | Yes | Controller class that handles data and actions |
 | `screen` | Yes | Screen class that renders the page |
-| `mode` | No | `"document"`, `"hybrid"` (default), or `"mount"` |
+| `mode` | No | `"document"` or `"hybrid"` (default) |
 | `shell` | No | Override the app-level shell for this route |
 | `css` | No | Route-specific CSS files |
+| `js` | No | Extra classic scripts to include for this route |
 | `modules` | No | JS import aliases: `{"alias": "path/to/module.js"}` |
 | `static_paths` | No | Function returning path params for static builds |
 | `metadata` | No | Dict of metadata (title, description, etc.) |
@@ -81,7 +82,7 @@ my_page = page(
 
 ```python
 class BlogController(Controller):
-    route = "/blog/:slug"
+    route = "/blog/[slug]"
 
     def load(self):
         post = get_post(self.request.params["slug"])
@@ -132,11 +133,11 @@ Merge order: **app metadata → page metadata → `__sprag_meta__`** (last wins)
 
 ## Route modes
 
-- **`document`** — Pure SSR. The server renders HTML and sends it. No JavaScript is loaded. Best for content pages, marketing pages, and anything that doesn't need interactivity.
+- **`document`** — Server-first rendering for content-heavy pages. The route still ships the standard SPRAG boot payload, but you typically avoid browser-owned Module logic here.
 
 - **`hybrid`** — SSR first, then hydrate. The server renders the initial HTML for a fast first paint, then the browser loads JavaScript to make it interactive. This is the default and the right choice for most pages.
 
-- **`mount`** — No SSR body. The server sends a shell, and the browser mounts everything. Use when the page content is entirely dynamic (dashboards, editors, etc.).
+If you want a browser-owned client app instead of a page route, use `mount(...)` under `app/mounts/`. Mounts are separate from page modes.
 
 ## Dynamic routes
 
@@ -155,7 +156,7 @@ from .web import BlogScreen
 from app.content import blog_static_paths
 
 blog_page = page(
-    path="/blog/:slug",
+    path="/blog/[slug]",
     controller=BlogController,
     screen=BlogScreen,
     mode="document",
@@ -186,4 +187,4 @@ sprag add route about --mode document
 sprag routes
 ```
 
-This prints all discovered routes, their modes, and tags like `[socket]` for controllers that use the socket bridge.
+This prints discovered routes, mounts, actions, and any schema fields declared on those actions.

docs/app/content/docs/framework/stores.md

@@ -18,7 +18,7 @@ counter_store = store("counter", initial={"count": 0})
 
 This single declaration works in both runtimes:
 
-- **Server**: backed by a Specter `Model` — persistent, shared across requests
+- **Server**: backed by a Specter `Model`
 - **Browser**: compiled to a Ragot `createStateStore` shim via `stores.js` — reactive, local to the tab
 
 ## API
@@ -27,20 +27,27 @@ The full store API is identical on both sides:
 
 ```python
 # Read
-value = counter_store.get("count")       # Single key
-state = counter_store.get_state()         # Full state dict
+value = counter_store.get("count")      # Single path/key
+state = counter_store.get_state()       # Full state snapshot
+snap = counter_store.snapshot()         # Deep snapshot
 
 # Write
-counter_store.set("count", 42)            # Set single key
-counter_store.patch({"count": 99})        # Merge partial state
-counter_store.update("count", lambda v: v + 1)  # Transform a value
-counter_store.delete("count")             # Remove a key
+counter_store.set("count", 42)           # Set a path/key
+counter_store.patch({"count": 99})       # Root-level merge
+counter_store.delete("count")            # Remove a path/key
+
+def bump(state):
+    state["count"] = state.get("count", 0) + 1
+
+counter_store.update(bump)               # Atomic mutator
+counter_store.reset()                    # Reset to declared initial state
 
 # Subscribe to changes
-counter_store.subscribe(lambda state, meta, store: print(state))
+counter_store.subscribe(lambda state: print(state), immediate=True)
+counter_store.listen("count", lambda value: print(value))
 
 # Select a derived value
-counter_store.select("count", lambda count: count * 2)
+double = counter_store.select(lambda s: s.get("count", 0) * 2, default=0)
 ```
 
 ## Server-side usage
@@ -56,7 +63,7 @@ class CounterService(Service):
     def on_start(self):
         counter_store.subscribe(self._on_change)
 
-    def _on_change(self, state, meta, s):
+    def _on_change(self, state):
         if state["count"] > 100:
             self.emit("counter:overflow", state)
 ```
@@ -74,15 +81,15 @@ class CounterModule(Module):
     def on_start(self):
         self.subscribe(counter_store, self._on_store)
 
-    def _on_store(self, state, meta, s):
+    def _on_store(self, state):
         self.set_state({"count": state["count"]})
 ```
 
 `self.subscribe()` auto-cleans on Module stop — no manual unsubscribe needed.
 
 ## When to use stores
 
-**Use `store()`** for state that needs to be shared across routes or between multiple components/modules in the same page. Stores persist across navigations on the server and are reactive on the browser.
+**Use `store()`** for state that needs to be shared across routes or between multiple components/modules in the same page. It gives you one authoring surface backed by Specter on the server and a generated store shim in the browser.
 
 **Use controller state** (the dict from `load()`) for per-page state that lives within a single route. This is simpler and covers most cases.
 

docs/app/content/docs/framework/two-runtimes.md

@@ -43,7 +43,7 @@ These patterns are intentionally identical across runtimes:
 Each runtime owns its boundary:
 
 - **DOM** — browser only. Components render `ui.*` trees; the server never touches the DOM.
-- **Sockets** — the server *sends* socket events, the browser *receives* them. The Module has `on_socket()`; the Controller has `emit_socket()`.
+- **Sockets** — both runtimes can participate through the shared socket bridge. Controllers can emit and handle socket traffic; Modules can subscribe with `on_socket()` and emit with `emit_socket()`.
 - **HTTP** — the server handles requests. The browser calls `call_action()` to invoke server actions over HTTP.
 - **File system** — server only. The browser has no access.
 

docs/app/content/docs/getting-started/first-app.md

@@ -50,11 +50,14 @@ class CounterModule(Module):
 
     def on_increment(self, event, target):
         event.prevent_default()
-        self.call_action("increment", {"count": self.state["count"]})
+        self.call_action("increment", {"count": self.state["count"]}).then(self.on_result)
+
+    def on_result(self, result):
+        self.set_state(result.value)
 ```
 
 - `Module` owns non-visual lifecycle — event listeners, server calls, state.
-- `self.call_action("increment", payload)` calls the server `@action` and applies the returned state.
+- `self.call_action("increment", payload)` calls the server `@action` and returns a Promise-like result; update local state in the success handler.
 - This Python compiles to Ragot ESM JavaScript at build time.
 
 ### The browser component: `app/routes/counter/components.py`

docs/app/content/docs/getting-started/installation.md

@@ -8,9 +8,8 @@ order: 1
 
 ## Prerequisites
 
-- **Python 3.11+** — SPRAG uses modern Python features throughout
+- **Python 3.9+**
 - **pip** — or any Python package manager (uv, poetry, etc.)
-- **gevent** — the server runtime uses gevent for cooperative concurrency
 
 ## Install SPRAG