From a764b7e2b4009599c46e650e34f2968930ae21ab Mon Sep 17 00:00:00 2001
From: chidebele dunamis <techwithdunamix@gmail.com>
Date: Sat, 12 Sep 2026 23:57:11 +0100
Subject: [PATCH] docs: the packages import as sillo_wire and sillo_graphql

Follows sillohq/wire#1 and sillohq/graphql#1, which remove the
`sillo.wire` and `sillo.graphql` import aliases. Both packages are plain
top-level distributions now, so the docs teach the top-level names.

Safe to land ahead of those PRs: `sillo_wire` already works in the
published 0.1.0.dev1, which answers to both names.

Rewrites the prose that explained the aliasing rather than just swapping
imports under it. The "two import paths" sections in the Wire and GraphQL
manuals are gone; the Packages index's "How they attach" section no
longer describes a meta-path finder and a second set of stubs, and says
what happened to the aliases instead.

Three things are deliberately left alone:

- `v0.x/guides/graphql.md` is untouched. It documents the framework's own
  built-in `sillo.graphql` on the 0.x line, which is a different thing
  that still exists there.
- Logger names. `sillo.graphql.operations` in the observability page is a
  logging hierarchy under the framework's `sillo` logger, not an import.
- References to the pre-1.0 `sillo.graphql` the framework shipped, which
  are accurate history and are what the migration tables migrate from.

The v0.x and v1.0 caveats saying `sillo-graphql` "claims the same import
name" and so "refuses to load" against 0.x were describing a collision
that no longer exists. What actually rules it out on 0.x is the version
floor, which is what they now say.

Verified: docs build clean (526 pages), no broken internal links.
---
 .../content/docs/packages/graphql/context.md  |  2 +-
 .../content/docs/packages/graphql/errors.md   |  6 +--
 .../content/docs/packages/graphql/index.md    | 19 +++----
 .../content/docs/packages/graphql/limits.md   |  4 +-
 .../content/docs/packages/graphql/loaders.md  |  2 +-
 .../docs/packages/graphql/observability.md    |  4 +-
 .../docs/packages/graphql/persisted.md        |  6 +--
 .../docs/packages/graphql/resolvers.md        |  2 +-
 .../docs/packages/graphql/subscriptions.md    |  6 +--
 .../content/docs/packages/graphql/testing.md  |  6 +--
 .../docs/packages/graphql/transport.md        |  6 +--
 docs/docs/src/content/docs/packages/index.md  | 50 +++++++++----------
 .../src/content/docs/packages/wire/backlog.md |  4 +-
 .../content/docs/packages/wire/consumers.md   |  2 +-
 .../src/content/docs/packages/wire/hub.md     |  2 +-
 .../src/content/docs/packages/wire/index.md   | 17 +------
 .../src/content/docs/packages/wire/peers.md   |  4 +-
 .../content/docs/packages/wire/reference.md   |  8 +--
 .../src/content/docs/packages/wire/testing.md |  8 +--
 .../src/content/docs/v0.x/guides/ecosystem.md | 25 +++++-----
 docs/docs/src/content/docs/v0.x/guides/faq.md |  8 +--
 .../content/docs/v1.0/advanced/glossary.md    |  6 +--
 .../content/docs/v1.0/advanced/websockets.md  |  4 +-
 .../src/content/docs/v1.0/guides/ecosystem.md | 17 +++----
 docs/docs/src/content/docs/v1.0/guides/faq.md |  2 +-
 .../docs/v1.0/guides/websockets/events.mdx    |  4 +-
 26 files changed, 101 insertions(+), 123 deletions(-)

diff --git a/docs/docs/src/content/docs/packages/graphql/context.md b/docs/docs/src/content/docs/packages/graphql/context.md
index 9d4be7eb..48fa5fbc 100644
--- a/docs/docs/src/content/docs/packages/graphql/context.md
+++ b/docs/docs/src/content/docs/packages/graphql/context.md
@@ -19,7 +19,7 @@ What Strawberry is handed as `context_value`, and what a resolver gets by
 annotating `GraphContext`.
 
 ```python
-from sillo.graphql import GraphContext
+from sillo_graphql import GraphContext
 
 
 @field
diff --git a/docs/docs/src/content/docs/packages/graphql/errors.md b/docs/docs/src/content/docs/packages/graphql/errors.md
index 698ee420..6a3ae24c 100644
--- a/docs/docs/src/content/docs/packages/graphql/errors.md
+++ b/docs/docs/src/content/docs/packages/graphql/errors.md
@@ -7,7 +7,7 @@ description: Free builders with stable codes, masking of anything unexpected, an
 `redirect()`. Errors here follow the same shape.
 
 ```python
-from sillo.graphql import forbidden, not_found
+from sillo_graphql import forbidden, not_found
 
 
 @field
@@ -87,7 +87,7 @@ unusable; masking a `RuntimeError` is the whole point.
 ### Configuring it
 
 ```python
-from sillo.graphql import ErrorPolicy
+from sillo_graphql import ErrorPolicy
 
 Graph(schema, errors=ErrorPolicy(
     mask=True,                          # the default
@@ -120,7 +120,7 @@ An application raises its own exceptions, and masking them is the right default
 and a poor experience.
 
 ```python
-from sillo.graphql import bad_input, conflict, not_found
+from sillo_graphql import bad_input, conflict, not_found
 
 
 @graph.on_error(RecordNotFound)
diff --git a/docs/docs/src/content/docs/packages/graphql/index.md b/docs/docs/src/content/docs/packages/graphql/index.md
index f0a77b0f..6e76e942 100644
--- a/docs/docs/src/content/docs/packages/graphql/index.md
+++ b/docs/docs/src/content/docs/packages/graphql/index.md
@@ -9,14 +9,14 @@ A production GraphQL endpoint over a Strawberry schema.
 pip install sillo-graphql
 ```
 
-Installs as `sillo-graphql`, imports as `sillo.graphql`. Strawberry keeps the
+Installs as `sillo-graphql`, imports as `sillo_graphql`. Strawberry keeps the
 schema; this package owns everything around it — the transports, the safety,
 and the observability.
 
 ```python
 import strawberry
 from sillo import Depend, HttpContext, SilloApp
-from sillo.graphql import Graph, Limits, field
+from sillo_graphql import Graph, Limits, field
 
 
 @strawberry.type
@@ -101,17 +101,12 @@ If you are moving from the framework's module, the shortest path is
 `Mapping`, so the old subscript keeps working and a schema can migrate one
 resolver at a time.
 
-## The two import paths
+## Not the framework's `sillo.graphql`
 
-`sillo.graphql` and `sillo_graphql` are the same module object. The code lives
-in the top-level `sillo_graphql` package; a `.pth` registers a meta-path finder
-at interpreter startup, and PEP 561 partial stubs serve type checkers, which
-never run import hooks. Nothing is written into the framework's `sillo/`
-directory.
-
-Because the framework shipped its own `sillo.graphql` before 1.0, the alias
-**refuses to load** against an older framework rather than silently shadowing
-it, and says which two things disagree.
+Versions of `sillo-framework` before 1.0 shipped a GraphQL module of their own
+at `sillo.graphql`. This package is its replacement, not an upgrade of it: it
+installs separately, imports as `sillo_graphql`, and requires framework 1.0 or
+newer. The table above is the migration.
 
 ## Requirements
 
diff --git a/docs/docs/src/content/docs/packages/graphql/limits.md b/docs/docs/src/content/docs/packages/graphql/limits.md
index cf7b5f98..367ac780 100644
--- a/docs/docs/src/content/docs/packages/graphql/limits.md
+++ b/docs/docs/src/content/docs/packages/graphql/limits.md
@@ -17,7 +17,7 @@ So the document is measured **before** execution and refused if it is too
 large. Refusing afterwards would mean having already done the work.
 
 ```python
-from sillo.graphql import Graph, Limits
+from sillo_graphql import Graph, Limits
 
 Graph(schema, limits=Limits(depth=10, cost=1_000, aliases=15)).mount(app)
 ```
@@ -153,7 +153,7 @@ are refused.
 
 ```python
 from graphql import parse
-from sillo.graphql import Limits, analyze
+from sillo_graphql import Limits, analyze
 
 result = analyze(parse(document), limits=Limits(), schema=graph.schema._schema)
 result.depth, result.cost, result.aliases, result.breadth, result.fields
diff --git a/docs/docs/src/content/docs/packages/graphql/loaders.md b/docs/docs/src/content/docs/packages/graphql/loaders.md
index 9f3792de..380eee96 100644
--- a/docs/docs/src/content/docs/packages/graphql/loaders.md
+++ b/docs/docs/src/content/docs/packages/graphql/loaders.md
@@ -139,7 +139,7 @@ Prefer a tuple over a dict — a tuple hashes, so it caches.
 Background jobs and tests can open a scope of their own:
 
 ```python
-from sillo.graphql import LoaderRegistry
+from sillo_graphql import LoaderRegistry
 
 
 async def nightly_digest():
diff --git a/docs/docs/src/content/docs/packages/graphql/observability.md b/docs/docs/src/content/docs/packages/graphql/observability.md
index 54dbdeab..907ce416 100644
--- a/docs/docs/src/content/docs/packages/graphql/observability.md
+++ b/docs/docs/src/content/docs/packages/graphql/observability.md
@@ -11,7 +11,7 @@ year of rows are the same endpoint.
 What is worth measuring is per **operation**.
 
 ```python
-from sillo.graphql import Metrics, OperationLog
+from sillo_graphql import Metrics, OperationLog
 
 graph.on_operation(OperationLog(slower_than=0.5))
 
@@ -108,7 +108,7 @@ Pass a logger of your own as the first argument; it defaults to
 
 ```python
 from opentelemetry import trace
-from sillo.graphql import opentelemetry
+from sillo_graphql import opentelemetry
 
 graph.on_operation(opentelemetry(trace.get_tracer("graphql")))
 ```
diff --git a/docs/docs/src/content/docs/packages/graphql/persisted.md b/docs/docs/src/content/docs/packages/graphql/persisted.md
index bd84a198..fc655371 100644
--- a/docs/docs/src/content/docs/packages/graphql/persisted.md
+++ b/docs/docs/src/content/docs/packages/graphql/persisted.md
@@ -14,7 +14,7 @@ your application actually sends is generated at build time, and the server
 executes nothing else.
 
 ```python
-from sillo.graphql import Persisted
+from sillo_graphql import Persisted
 
 Graph(schema, persisted=Persisted(apq=True))                        # bandwidth
 Graph(schema, persisted=Persisted(trusted="operations.json"))       # safety
@@ -47,7 +47,7 @@ separately, which is correct and merely wasteful, so a shared store is worth
 configuring once there is more than one.
 
 ```python
-from sillo.graphql import MemoryStore
+from sillo_graphql import MemoryStore
 
 Graph(schema, store=MemoryStore(max_entries=5_000))
 ```
@@ -88,7 +88,7 @@ Generate it from your client's operations at build time and ship it with the
 server. It can also be passed inline, which is what a test wants:
 
 ```python
-from sillo.graphql import hash_document
+from sillo_graphql import hash_document
 
 document = "{ hello }"
 Graph(schema, persisted=Persisted(trusted={hash_document(document): document}))
diff --git a/docs/docs/src/content/docs/packages/graphql/resolvers.md b/docs/docs/src/content/docs/packages/graphql/resolvers.md
index 748593f3..bba6cb6b 100644
--- a/docs/docs/src/content/docs/packages/graphql/resolvers.md
+++ b/docs/docs/src/content/docs/packages/graphql/resolvers.md
@@ -9,7 +9,7 @@ it needs. A resolver here is the same thing.
 ```python
 import strawberry
 from sillo import Depend, HttpContext
-from sillo.graphql import field, mutation, subscription
+from sillo_graphql import field, mutation, subscription
 
 
 @strawberry.type
diff --git a/docs/docs/src/content/docs/packages/graphql/subscriptions.md b/docs/docs/src/content/docs/packages/graphql/subscriptions.md
index 4a9fef6f..7173f119 100644
--- a/docs/docs/src/content/docs/packages/graphql/subscriptions.md
+++ b/docs/docs/src/content/docs/packages/graphql/subscriptions.md
@@ -8,7 +8,7 @@ from typing import AsyncGenerator
 
 import strawberry
 from sillo import WebSocketContext
-from sillo.graphql import subscription
+from sillo_graphql import subscription
 
 
 @strawberry.type
@@ -72,7 +72,7 @@ the `connection_init` payload instead. `@graph.on_connect` is given it before
 any operation runs.
 
 ```python
-from sillo.graphql import unauthenticated
+from sillo_graphql import unauthenticated
 
 
 @graph.on_connect
@@ -111,7 +111,7 @@ and counted.
 ## Tuning
 
 ```python
-from sillo.graphql.transport.ws import WebSocketTransport
+from sillo_graphql.transport.ws import WebSocketTransport
 
 graph.ws = WebSocketTransport(graph, init_timeout=5.0, keepalive=20.0)
 ```
diff --git a/docs/docs/src/content/docs/packages/graphql/testing.md b/docs/docs/src/content/docs/packages/graphql/testing.md
index bd3d0008..54fd8ffe 100644
--- a/docs/docs/src/content/docs/packages/graphql/testing.md
+++ b/docs/docs/src/content/docs/packages/graphql/testing.md
@@ -7,7 +7,7 @@ A GraphQL test written through a plain HTTP client is four lines of JSON
 assembly and a dictionary walk before it reaches the thing under test.
 
 ```python
-from sillo.graphql.testing import GraphClient
+from sillo_graphql.testing import GraphClient
 
 
 def test_me():
@@ -155,7 +155,7 @@ slow afternoon.
 Outside a request, open a scope:
 
 ```python
-from sillo.graphql import LoaderRegistry
+from sillo_graphql import LoaderRegistry
 
 
 async def test_the_batch_function_aligns_its_results():
@@ -183,7 +183,7 @@ test cannot leak:
 ```python
 import pytest
 from sillo import SilloApp
-from sillo.graphql import Graph, Limits
+from sillo_graphql import Graph, Limits
 
 
 @pytest.fixture
diff --git a/docs/docs/src/content/docs/packages/graphql/transport.md b/docs/docs/src/content/docs/packages/graphql/transport.md
index 9e6c2c4a..9c2a3bea 100644
--- a/docs/docs/src/content/docs/packages/graphql/transport.md
+++ b/docs/docs/src/content/docs/packages/graphql/transport.md
@@ -41,7 +41,7 @@ a client parse a body to discover.
 ## Requests
 
 ```python
-from sillo.graphql import Transport
+from sillo_graphql import Transport
 
 Graph(schema, transport=Transport(
     get_queries=True,
@@ -101,7 +101,7 @@ that accepts files has a materially larger attack surface than one that does
 not, and that should be a decision.
 
 ```python
-from sillo.graphql import Uploads
+from sillo_graphql import Uploads
 
 Graph(schema, uploads=Uploads(
     enabled=True,
@@ -138,7 +138,7 @@ than a 500 on the first large request.
 ## The explorer
 
 ```python
-from sillo.graphql import IDE
+from sillo_graphql import IDE
 
 Graph(schema, ide=True)                                  # bundled, offline
 Graph(schema, ide=IDE(enabled=True, assets="cdn"))       # GraphiQL from unpkg
diff --git a/docs/docs/src/content/docs/packages/index.md b/docs/docs/src/content/docs/packages/index.md
index 1ffae00c..0059a1d0 100644
--- a/docs/docs/src/content/docs/packages/index.md
+++ b/docs/docs/src/content/docs/packages/index.md
@@ -10,8 +10,8 @@ cadence, or a scope that the core should not carry on everybody's behalf.
 
 | Package | Install | Import | What it is |
 |---|---|---|---|
-| [Wire](/packages/wire/) | `sillo-wire` | `sillo.wire` | Rooms, presence and fan-out for WebSockets |
-| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo.graphql` | A production GraphQL endpoint over a Strawberry schema |
+| [Wire](/packages/wire/) | `sillo-wire` | `sillo_wire` | Rooms, presence and fan-out for WebSockets |
+| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo_graphql` | A production GraphQL endpoint over a Strawberry schema |
 | [Warder](/packages/warder/) | `warder` | `warder` | A declarative admin over your models |
 
 Each has a manual of its own — pick one above and the sidebar becomes its
@@ -19,40 +19,38 @@ table of contents.
 
 ## How they attach
 
-Wire and GraphQL extend the framework's own surface, so they take a name inside
-it. The code lives in a top-level package — `sillo_wire`, `sillo_graphql` — and
-the framework name is an alias for it. Both bind the same objects:
+Every package is a plain top-level distribution with a plain top-level import
+name. Install `sillo-wire`, import `sillo_wire`:
 
 ```python
-from sillo.wire import Hub     # both of these
-from sillo_wire import Hub     # name the same class
+from sillo_wire import Hub, Peer
+from sillo_graphql import Graph, field
 ```
 
-Warder does not, and the difference is deliberate. It is not an extension of
-`sillo` — it is an application you mount on yours, the way you would mount any
-other. So it keeps its own name:
+Warder is the exception to the naming rule, and the difference is deliberate.
+It is not an extension of `sillo` — it is an application you mount on yours,
+the way you would mount any other — so it keeps its own name:
 
 ```python
 from warder import Admin
 admin.mount(app)
 ```
 
-The alias is a meta-path finder the package registers through a `.pth` at
-interpreter startup, plus PEP 561 partial stubs so type checkers resolve it
-too. Nothing is written into the `sillo` package directory.
-
-That last part is the point. Shipping `sillo/wire/` into the framework's own
-directory is simpler, and it is what Wire did first — but two distributions
-sharing one directory goes wrong in both directions. Installing the framework
-from a checkout moves where `sillo` resolves and orphans the copy in
-site-packages; removing or replacing the framework leaves that directory
-standing with no `__init__.py` in it, which is an override rather than an
-addition. Uninstalling either package now leaves the other untouched.
-
-One consequence is worth stating plainly: a package cannot claim a name the
-framework still uses. `sillo-graphql` claims `sillo.graphql`, which the
-framework shipped until 1.0 — so against an older framework the alias
-refuses to load and says why, rather than quietly shadowing it.
+Nothing is ever written into the framework's own `sillo` package directory.
+Shipping `sillo/wire/` in there is simpler, and it is what Wire did first — but
+two distributions sharing one directory goes wrong in both directions.
+Installing the framework from a checkout moves where `sillo` resolves and
+orphans the copy in site-packages; removing or replacing the framework leaves
+that directory standing with no `__init__.py` in it, which is an override
+rather than an addition. Uninstalling either package leaves the other
+untouched.
+
+Wire and GraphQL previously also answered to `sillo.wire` and `sillo.graphql`,
+through a meta-path finder registered by a `.pth` at interpreter startup and a
+second set of PEP 561 stubs to serve type checkers. It read as part of the
+framework, at the cost of a `.pth` running on every interpreter start and type
+declarations kept in two places. Those aliases are gone; the `sillo_` names
+above are the only ones.
 
 ## What stays in core
 
diff --git a/docs/docs/src/content/docs/packages/wire/backlog.md b/docs/docs/src/content/docs/packages/wire/backlog.md
index 530ab16b..daa3b852 100644
--- a/docs/docs/src/content/docs/packages/wire/backlog.md
+++ b/docs/docs/src/content/docs/packages/wire/backlog.md
@@ -7,7 +7,7 @@ Mobile clients disconnect. Laptops sleep. A backlog is what turns that from
 data loss into a gap the client can ask about.
 
 ```python
-from sillo.wire import Hub, MemoryBacklog
+from sillo_wire import Hub, MemoryBacklog
 
 hub = Hub(backlog=MemoryBacklog(capacity_bytes=4 * 1024 * 1024))
 ```
@@ -122,7 +122,7 @@ backlog at all.
 ## No backlog
 
 ```python
-from sillo.wire import Hub, NullBacklog
+from sillo_wire import Hub, NullBacklog
 
 hub = Hub(backlog=NullBacklog())    # the same as Hub()
 ```
diff --git a/docs/docs/src/content/docs/packages/wire/consumers.md b/docs/docs/src/content/docs/packages/wire/consumers.md
index 6eaa7b6a..2b760740 100644
--- a/docs/docs/src/content/docs/packages/wire/consumers.md
+++ b/docs/docs/src/content/docs/packages/wire/consumers.md
@@ -8,7 +8,7 @@ of application code, and the ceremony is where the leaks are. `RoomConsumer`
 writes it once.
 
 ```python
-from sillo.wire import Hub, RoomConsumer
+from sillo_wire import Hub, RoomConsumer
 
 hub = Hub()
 
diff --git a/docs/docs/src/content/docs/packages/wire/hub.md b/docs/docs/src/content/docs/packages/wire/hub.md
index 7a64414f..6062c01f 100644
--- a/docs/docs/src/content/docs/packages/wire/hub.md
+++ b/docs/docs/src/content/docs/packages/wire/hub.md
@@ -7,7 +7,7 @@ A `Hub` is a set of rooms, and a room is a set of peers. Everything that
 reaches more than one connection goes through it.
 
 ```python
-from sillo.wire import Hub
+from sillo_wire import Hub
 
 hub = Hub()
 ```
diff --git a/docs/docs/src/content/docs/packages/wire/index.md b/docs/docs/src/content/docs/packages/wire/index.md
index bf122aa5..0089ff5c 100644
--- a/docs/docs/src/content/docs/packages/wire/index.md
+++ b/docs/docs/src/content/docs/packages/wire/index.md
@@ -9,13 +9,13 @@ Rooms, presence and fan-out for WebSockets.
 pip install sillo-wire
 ```
 
-Installs as `sillo-wire`, imports as `sillo.wire`. The core keeps the socket
+Installs as `sillo-wire`, imports as `sillo_wire`. The core keeps the socket
 itself — [`WebSocketContext`](/v1.0/guides/websockets/) — and this adds
 everything about talking to more than one of them at a time.
 
 ```python
 from sillo import SilloApp
-from sillo.wire import Hub, Peer
+from sillo_wire import Hub, Peer
 
 app = SilloApp()
 hub = Hub()
@@ -105,19 +105,6 @@ counted in payload bytes and evicts oldest-first.
 The status enums are gone. `join` and `leave` return a plain `bool`, and
 `broadcast` returns a [`DeliveryReport`](/packages/wire/reference/).
 
-## The two import paths
-
-`sillo.wire` and `sillo_wire` are the same module object, not two copies. The
-code lives in the top-level `sillo_wire` package; a `.pth` shipped with the
-distribution registers a meta-path finder at interpreter startup, and PEP 561
-partial stubs serve type checkers, which never run import hooks.
-
-Nothing is written into the framework's own `sillo/` directory. Two
-distributions sharing one package directory goes wrong in both directions —
-installing the framework from a checkout orphans whatever the other package
-left in site-packages, and removing the framework leaves a directory standing
-with no `__init__.py` in it.
-
 ## Requirements
 
 Python 3.10 through 3.14, and `sillo-framework`. Nothing else.
diff --git a/docs/docs/src/content/docs/packages/wire/peers.md b/docs/docs/src/content/docs/packages/wire/peers.md
index 13c5ac4e..e5112db3 100644
--- a/docs/docs/src/content/docs/packages/wire/peers.md
+++ b/docs/docs/src/content/docs/packages/wire/peers.md
@@ -7,7 +7,7 @@ A `Peer` is one connection: a socket, an outbound queue, and a task that drains
 one into the other.
 
 ```python
-from sillo.wire import Peer
+from sillo_wire import Peer
 
 peer = Peer(socket, identity="ada")
 ```
@@ -62,7 +62,7 @@ This is a choice about your data, and there is no default that is right for
 everyone.
 
 ```python
-from sillo.wire import Overflow, Peer
+from sillo_wire import Overflow, Peer
 
 Peer(socket, overflow=Overflow.DROP_OLDEST)   # keep current
 Peer(socket, overflow=Overflow.DROP_NEWEST)   # keep order
diff --git a/docs/docs/src/content/docs/packages/wire/reference.md b/docs/docs/src/content/docs/packages/wire/reference.md
index c41f3dc2..b4ce7086 100644
--- a/docs/docs/src/content/docs/packages/wire/reference.md
+++ b/docs/docs/src/content/docs/packages/wire/reference.md
@@ -1,9 +1,9 @@
 ---
 title: API Reference
-description: Every public name in sillo.wire — signatures, defaults and what each one returns.
+description: Every public name in sillo_wire — signatures, defaults and what each one returns.
 ---
 
-Everything importable from `sillo.wire`. Types are as annotated in the package;
+Everything importable from `sillo_wire`. Types are as annotated in the package;
 `Any` means the value is yours and the library only carries it.
 
 ## Hub
@@ -164,7 +164,7 @@ because one client going away is not a failure of the broadcast.
 
 ## Testing
 
-`sillo.wire.testing`. See [Testing](/packages/wire/testing/).
+`sillo_wire.testing`. See [Testing](/packages/wire/testing/).
 
 | | |
 |---|---|
@@ -174,5 +174,5 @@ because one client going away is not a failure of the broadcast.
 ## Version
 
 ```python
-from sillo.wire import __version__
+from sillo_wire import __version__
 ```
diff --git a/docs/docs/src/content/docs/packages/wire/testing.md b/docs/docs/src/content/docs/packages/wire/testing.md
index a5ba644e..0bc7a51b 100644
--- a/docs/docs/src/content/docs/packages/wire/testing.md
+++ b/docs/docs/src/content/docs/packages/wire/testing.md
@@ -4,11 +4,11 @@ description: FakeSocket and drain — testing realtime code without a server, in
 ---
 
 A unit test of realtime code is missing exactly one thing: a socket.
-`sillo.wire.testing` supplies it.
+`sillo_wire.testing` supplies it.
 
 ```python
-from sillo.wire import Hub, Peer
-from sillo.wire.testing import FakeSocket, drain
+from sillo_wire import Hub, Peer
+from sillo_wire.testing import FakeSocket, drain
 
 
 async def test_a_broadcast_reaches_the_room():
@@ -105,7 +105,7 @@ differs per application and a change to it is easy to make by accident:
 
 ```python
 import pytest
-from sillo.wire import Overflow
+from sillo_wire import Overflow
 
 
 @pytest.mark.parametrize(
diff --git a/docs/docs/src/content/docs/v0.x/guides/ecosystem.md b/docs/docs/src/content/docs/v0.x/guides/ecosystem.md
index c5118e09..b8b151e7 100644
--- a/docs/docs/src/content/docs/v0.x/guides/ecosystem.md
+++ b/docs/docs/src/content/docs/v0.x/guides/ecosystem.md
@@ -129,24 +129,23 @@ scope that the framework should not carry on everybody's behalf.
 
 | Package | Install | Import | What it is |
 |---|---|---|---|
-| [Wire](/packages/wire/) | `sillo-wire` | `sillo.wire` | Rooms, presence, replay and fan-out for WebSockets |
-| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo.graphql` | A production GraphQL endpoint over a Strawberry schema — see the caveat below |
+| [Wire](/packages/wire/) | `sillo-wire` | `sillo_wire` | Rooms, presence, replay and fan-out for WebSockets |
+| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo_graphql` | A production GraphQL endpoint over a Strawberry schema — see the caveat below |
 | [Warder](/packages/warder/) | `warder` | `warder` | A declarative admin panel over your models, with a React interface |
 | [Inertia](/v0.x/guides/inertia/) | `sillo-inertia` | `sillo_inertia` | Server-driven pages with React or Vue, no API layer |
 | [OAuth](/v0.x/guides/oauth/) | `sillo-oauth` | `sillo_oauth` | Social login and OAuth2 providers |
 
-Wire and GraphQL extend the framework's own surface, so they also take a name
-inside it: `from sillo.wire import Hub` and `from sillo_wire import Hub` bind
-the same class. The others keep their own top-level names — Warder most
-deliberately of all, because it is not an extension of `sillo` but an
-application you mount on yours. The [Packages index](/packages/) explains how
-the aliasing works and why it is not a directory shipped into the framework.
+Every one of them is a plain top-level package: install `sillo-wire`, import
+`sillo_wire`. Warder is the exception to the naming, most deliberately of all,
+because it is not an extension of `sillo` but an application you mount on
+yours. Nothing here is ever installed into the framework's own `sillo`
+directory — the [Packages index](/packages/) explains why that matters.
 
 :::caution
-`sillo-graphql` claims `sillo.graphql`, which the framework itself still ships
-on this line. A package cannot claim a name the framework is using, so against
-0.x the alias refuses to load and says why — rather than quietly shadowing the
-built-in module. On 0.x, use the
+`sillo-graphql` requires framework 1.0 or newer — its resolver bridge is built
+on the context-handler API, which does not exist on this line. It imports as
+`sillo_graphql`, so it no longer collides with the `sillo.graphql` this line
+ships, but the version floor still rules it out. On 0.x, use the
 [framework's own GraphQL support](/v0.x/guides/graphql/); `sillo-graphql` is
 for 1.0.
 :::
@@ -173,7 +172,7 @@ about rather than discover later.
 | Built-in [admin panel](/v0.x/orm/admin/) | [`warder`](/packages/warder/) |
 | [HTML templating layer](/v0.x/guides/templating/) (Jinja) | Removed; templated email bodies are the one place a template is still rendered |
 | [WebSocket rooms, channels and groups](/v0.x/guides/websockets/channels/) | [`sillo-wire`](/packages/wire/) |
-| [`sillo.graphql`](/v0.x/guides/graphql/) in the framework | [`sillo-graphql`](/packages/graphql/), claiming the same import name |
+| [`sillo.graphql`](/v0.x/guides/graphql/) in the framework | [`sillo-graphql`](/packages/graphql/), imported as `sillo_graphql` |
 
 The same reason applies to all four: each had grown a dependency, a release
 cadence or a scope of its own, and keeping it in core made everybody carry it.
diff --git a/docs/docs/src/content/docs/v0.x/guides/faq.md b/docs/docs/src/content/docs/v0.x/guides/faq.md
index cbc51de1..76ad230b 100644
--- a/docs/docs/src/content/docs/v0.x/guides/faq.md
+++ b/docs/docs/src/content/docs/v0.x/guides/faq.md
@@ -209,15 +209,15 @@ Four things leave the framework and become packages of their own:
 | Built-in [admin panel](/v0.x/orm/admin/) | [`warder`](/packages/warder/), a separate install with a React interface |
 | [HTML templating layer](/v0.x/guides/templating/) (Jinja) | Gone from core; mail templates are the one place Jinja remains |
 | [WebSocket rooms, channels and groups](/v0.x/guides/websockets/channels/) | [`sillo-wire`](/packages/wire/) |
-| [`sillo.graphql`](/v0.x/guides/graphql/) | [`sillo-graphql`](/packages/graphql/), which claims that same import name |
+| [`sillo.graphql`](/v0.x/guides/graphql/) | [`sillo-graphql`](/packages/graphql/), which imports as `sillo_graphql` |
 
 Each of those leaves for the same reason: a dependency, a release cadence, or a
 scope that core should not carry on everyone's behalf. See
 [What's in the Box](/v0.x/guides/ecosystem/).
 
-One practical consequence today: because 0.x still ships `sillo.graphql`, the
-`sillo-graphql` package refuses to load against it rather than shadowing the
-module. On 0.x, use the [built-in GraphQL support](/v0.x/guides/graphql/).
+One practical consequence today: `sillo-graphql` requires framework 1.0 or
+newer, so it will not install against this line at all. On 0.x, use the
+[built-in GraphQL support](/v0.x/guides/graphql/).
 
 ###  Will there be an upgrade guide?
 
diff --git a/docs/docs/src/content/docs/v1.0/advanced/glossary.md b/docs/docs/src/content/docs/v1.0/advanced/glossary.md
index 8dbd9e2e..e8e4334c 100644
--- a/docs/docs/src/content/docs/v1.0/advanced/glossary.md
+++ b/docs/docs/src/content/docs/v1.0/advanced/glossary.md
@@ -1016,7 +1016,7 @@ Abstract base for event transport backends.
 
 ### Peer
 
-**Module:** `sillo.wire.peer` — the [`sillo-wire`](/packages/wire/) package
+**Module:** `sillo_wire.peer` — the [`sillo-wire`](/packages/wire/) package
 
 One connected client, with a bounded outbound queue so a broadcast never writes
 to a socket inline. Replaces `Channel`.
@@ -1030,7 +1030,7 @@ to a socket inline. Replaces `Channel`.
 
 ### Hub
 
-**Module:** `sillo.wire.hub` — the [`sillo-wire`](/packages/wire/) package
+**Module:** `sillo_wire.hub` — the [`sillo-wire`](/packages/wire/) package
 
 Rooms, membership and fan-out. An object rather than class-level state, so two
 hubs are two independent worlds. Replaces `ChannelBox`.
@@ -1240,7 +1240,7 @@ ASGI WebSocket wrapper.  Like `HttpContext` but for WebSocket connections.
 
 ### RoomConsumer
 
-**Module:** `sillo.wire.consumer` — the [`sillo-wire`](/packages/wire/) package
+**Module:** `sillo_wire.consumer` — the [`sillo-wire`](/packages/wire/) package
 
 Class-based WebSocket endpoint. Accepts the socket, builds the peer, joins its
 rooms and guarantees cleanup, including when a hook raises. Replaces
diff --git a/docs/docs/src/content/docs/v1.0/advanced/websockets.md b/docs/docs/src/content/docs/v1.0/advanced/websockets.md
index 5b33ced5..96808670 100644
--- a/docs/docs/src/content/docs/v1.0/advanced/websockets.md
+++ b/docs/docs/src/content/docs/v1.0/advanced/websockets.md
@@ -281,7 +281,7 @@ These moved to [`sillo-wire`](/packages/wire/) in v1 and are documented there.
 The core keeps the connection; the package adds everything about addressing
 more than one of them at once.
 
-| Was, in this module | Is, in `sillo.wire` |
+| Was, in this module | Is, in `sillo_wire` |
 |---|---|
 | `WebSocketConsumer` | `RoomConsumer` |
 | `Channel` | `Peer` |
@@ -407,7 +407,7 @@ app.ws_route("/ws/echo", websocket_handler)
 Both live in [`sillo-wire`](/packages/wire/):
 
 ```python
-from sillo.wire import Hub, Peer
+from sillo_wire import Hub, Peer
 
 hub = Hub()
 
diff --git a/docs/docs/src/content/docs/v1.0/guides/ecosystem.md b/docs/docs/src/content/docs/v1.0/guides/ecosystem.md
index 8956afdd..cea428a1 100644
--- a/docs/docs/src/content/docs/v1.0/guides/ecosystem.md
+++ b/docs/docs/src/content/docs/v1.0/guides/ecosystem.md
@@ -104,18 +104,17 @@ scope that the framework should not carry on everybody's behalf.
 
 | Package | Install | Import | What it is |
 |---|---|---|---|
-| [Wire](/packages/wire/) | `sillo-wire` | `sillo.wire` | Rooms, presence, replay and fan-out for WebSockets |
-| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo.graphql` | A production GraphQL endpoint over a Strawberry schema |
+| [Wire](/packages/wire/) | `sillo-wire` | `sillo_wire` | Rooms, presence, replay and fan-out for WebSockets |
+| [GraphQL](/packages/graphql/) | `sillo-graphql` | `sillo_graphql` | A production GraphQL endpoint over a Strawberry schema |
 | [Warder](/packages/warder/) | `warder` | `warder` | A declarative admin panel over your models, with a React interface |
 | [Inertia](/v1.0/guides/inertia/) | `sillo-inertia` | `sillo_inertia` | Server-driven pages with React or Vue, no API layer |
 | [OAuth](/v1.0/guides/oauth/) | `sillo-oauth` | `sillo_oauth` | Social login and OAuth2 providers |
 
-Wire and GraphQL extend the framework's own surface, so they also take a name
-inside it: `from sillo.wire import Hub` and `from sillo_wire import Hub` bind
-the same class. The others keep their own top-level names — Warder most
-deliberately of all, because it is not an extension of `sillo` but an
-application you mount on yours. The [Packages index](/packages/) explains how
-the aliasing works and why it is not a directory shipped into the framework.
+Every one of them is a plain top-level package: install `sillo-wire`, import
+`sillo_wire`. Warder is the exception to the naming, most deliberately of all,
+because it is not an extension of `sillo` but an application you mount on
+yours. Nothing here is ever installed into the framework's own `sillo`
+directory — the [Packages index](/packages/) explains why that matters.
 
 ##  The tools
 
@@ -138,7 +137,7 @@ used to be.
 | Built-in admin panel | [`warder`](/packages/warder/) |
 | HTML templating layer (Jinja) | Removed; `mail` is the one place a template is still rendered |
 | WebSocket rooms, channels and groups | [`sillo-wire`](/packages/wire/) |
-| `sillo.graphql` in the framework | [`sillo-graphql`](/packages/graphql/), claiming the same import name |
+| `sillo.graphql` in the framework | [`sillo-graphql`](/packages/graphql/), imported as `sillo_graphql` |
 
 The same reason applies to all four: each had grown a dependency, a release
 cadence or a scope of its own. A package that claims a name the framework still
diff --git a/docs/docs/src/content/docs/v1.0/guides/faq.md b/docs/docs/src/content/docs/v1.0/guides/faq.md
index 03843a9d..404cd3c7 100644
--- a/docs/docs/src/content/docs/v1.0/guides/faq.md
+++ b/docs/docs/src/content/docs/v1.0/guides/faq.md
@@ -204,7 +204,7 @@ Four things left the framework and became packages of their own:
 | Built-in admin panel | [`warder`](/packages/warder/), a separate install with a React interface |
 | HTML templating layer (Jinja) | Gone from core; mail templates are the one place Jinja remains |
 | WebSocket rooms, channels and groups | [`sillo-wire`](/packages/wire/) |
-| `sillo.graphql` | [`sillo-graphql`](/packages/graphql/), which claims that same import name |
+| `sillo.graphql` | [`sillo-graphql`](/packages/graphql/), which imports as `sillo_graphql` |
 
 Each of those left for the same reason: a dependency, a release cadence, or a
 scope that core should not carry on everyone's behalf. See
diff --git a/docs/docs/src/content/docs/v1.0/guides/websockets/events.mdx b/docs/docs/src/content/docs/v1.0/guides/websockets/events.mdx
index f39b1a0a..8198d384 100644
--- a/docs/docs/src/content/docs/v1.0/guides/websockets/events.mdx
+++ b/docs/docs/src/content/docs/v1.0/guides/websockets/events.mdx
@@ -67,7 +67,7 @@ a registry.
 ```python title="a dispatch table on the consumer"
 import logging
 
-from sillo.wire import RoomConsumer
+from sillo_wire import RoomConsumer
 
 logger = logging.getLogger(__name__)
 
@@ -126,7 +126,7 @@ class Dispatcher(RoomConsumer):
 Then handlers are declarative:
 
 ```python title="using the dispatcher"
-from sillo.wire import Hub
+from sillo_wire import Hub
 
 hub = Hub()