docs: add what-aura-is-not doc

README.md

@@ -127,7 +127,7 @@ It runs in the browser; it is not a Node SSR runtime. Your server or static host
 
 Current release: **0.3.0**
 
-**Documentation:** [Guide](./docs/guide.md) · [Recipes](./docs/recipes/) · [MAGA](https://github.com/aura-ui/MAGA) · [Playground](./playground/) · [Known limitations](./LIMITATIONS.md)
+**Documentation:** [Guide](./docs/guide.md) · [What Aura is not](./docs/what-aura-is-not.md) · [Recipes](./docs/recipes/) · [MAGA](https://github.com/aura-ui/MAGA) · [Playground](./playground/) · [Known limitations](./LIMITATIONS.md)
 
 **Development:** [Changelog](./CHANGELOG.md) · [Roadmap](./ROADMAP.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
 

ROADMAP.md

@@ -1,8 +1,8 @@
 # Aura Router — Roadmap
 
-**Declarative routing for Web Components — what is shipped, what is being built, and why it matters.**
+**HTML-first navigation for Web Components and plain pages — what is shipped, what is being built, and why it matters.**
 
-> Current release: `0.3.0` · Updated: 2026-08-25
+> Current release: `0.3.0` · Updated: 2026-08-27
 >
 > [Tutorial](./docs/tutorial.md) · [README](./README.md) · [Guide](./docs/guide.md) · [Recipes](./docs/recipes/README.md) · [Limitations](./LIMITATIONS.md) · [Security](./SECURITY.md) · [Changelog](./CHANGELOG.md)
 
@@ -13,6 +13,7 @@
 | Build an app with Aura Router                 | [Guide](./docs/guide.md)                                                           |
 | See what is already available                 | [README](./README.md) → [Changelog](./CHANGELOG.md)                                |
 | Upgrade an existing HTML site from MPA to SPA | [10-minute tutorial](./docs/tutorial.md) → [MPA → SPA roadmap](#phase-8--mpa--spa) |
+| See what Aura is not (vs Turbo / Unpoly / swup / htmx) | [What Aura is not](./docs/what-aura-is-not.md) |
 | Copy a working pattern                        | [Recipes](./docs/recipes/README.md)                                                |
 | Understand what is being built now            | [Current focus](#current-focus)                                                    |
 | Contribute to a specific area                 | [Explore the roadmap](#explore-the-roadmap)                                        |

docs/guide.md

@@ -59,6 +59,7 @@ Use the [recipes](./recipes/README.md) when you want a focused copy-and-paste pa
 ## Related documentation
 
 - [10-minute tutorial](./tutorial.md) — upgrade two complete HTML pages and verify progressive enhancement
+- [What Aura is not](./what-aura-is-not.md) — boundaries vs Turbo / Unpoly / swup / htmx; forms stay in the app
 - [README](../README.md) — project overview and quick start
 - [Known limitations](../LIMITATIONS.md)
 - [Security policy](../SECURITY.md)

docs/what-aura-is-not.md

@@ -0,0 +1,49 @@
+# What Aura is not
+
+Boundaries for [`@auraui/router`](https://www.npmjs.com/package/@auraui/router) — what it does, what it refuses, and how that differs from Turbo, Unpoly, swup, and htmx.
+
+[Guide](./guide.md) · [Tutorial](./tutorial.md) · [Limitations](../LIMITATIONS.md)
+
+---
+
+## Aura is
+
+HTML-first **client navigation** on pages your host already serves: opt-in link upgrades (default `data-aura-link`), `extract` / first-paint adopt, nested layouts, route lifecycle. Plain HTML, Web Components, or Lit — no framework adapter, no Aura server.
+
+Complete documents per URL are the main path; fragment / template / component views are also supported.
+
+---
+
+## Aura is not
+
+| Not | Meaning |
+| --- | ------- |
+| React / Vue / TanStack-style SPA router | HTML + URL stay the substrate, not a virtual app tree |
+| Turbo / htmx replacement | Upgrades **link navigation**, not a hypermedia app runtime |
+| Form / mutation layer | No `<form>` intercept; mutations stay in the app, then `navigate()` / `invalidate()` |
+| Data framework | Has `load` / cache; not a query library. Nav-time SWR not shipped ([Limitations](../LIMITATIONS.md)) |
+| Incremental DOM / React-lite | Outlet replace/adopt — no DOM diffing |
+
+---
+
+## vs Turbo / Unpoly / swup / htmx
+
+| | **Aura** | **Turbo** | **Unpoly** | **swup** | **htmx** |
+| -- | -------- | --------- | ---------- | -------- | -------- |
+| **Idea** | Opt-in SPA nav on real HTML | Drive + Frames / Streams | PE via HTML attrs | Page transitions + cache | Hypermedia attrs + swaps |
+| **Links** | Marker (default `data-aura-link`) | Intercept by default | Attribute-driven | Enhanced nav | `hx-*` |
+| **Forms** | No — app + `navigate()` | Yes | Yes | No by default | Yes |
+| **Nested UI** | Routes / layouts / `<aura-outlet>` | Frames | Layers / fragments | Page-oriented | Swap targets |
+| **Pick when** | Keep pages; add nested SPA nav + lifecycle | Want Drive/Frames + form PE | Want rich HTML PE / layers | Want transition-focused MPA | Want hypermedia as the model |
+
+---
+
+## Forms
+
+Router owns **GET navigation**. The app owns submit / upload / validation.
+
+1. Handle the form in a component or plain JS.  
+2. `fetch` (or your handler) to the API / endpoint.  
+3. On success: `router.navigate(...)` / `invalidate()`.
+
+No-JS form submit = full page load. That is expected, not a gap.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@auraui/router",
   "version": "0.3.0",
-  "description": "HTML-first declarative router. Real HTML pages with client navigation (MPA→SPA). Works with plain HTML or Web Components.",
+  "description": "HTML-first client navigation for real HTML pages (MPA→SPA). Works with plain HTML, Web Components, or Lit.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,7 +21,8 @@
     "docs/tutorial.md",
     "docs/guide.md",
     "docs/guide/*",
-    "docs/recipes/*"
+    "docs/recipes/*",
+    "docs/what-aura-is-not.md"
   ],
   "sideEffects": false,
   "publishConfig": {