diff --git a/docs/datamodel/aliases.rst b/docs/datamodel/aliases.rst
index fc56a1dd911..587c9eb4c3f 100644
--- a/docs/datamodel/aliases.rst
+++ b/docs/datamodel/aliases.rst
@@ -6,85 +6,99 @@ Aliases
 
 .. index:: alias, virtual type
 
-.. important::
+You can think of *aliases* as a way to give schema names to arbitrary EdgeQL
+expressions. You can later refer to aliases in queries and in other aliases.
 
-  This section assumes a basic understanding of EdgeQL. If you aren't familiar
-  with it, feel free to skip this page for now.
+Aliases are functionally equivalent to expression aliases defined in EdgeQL
+statements in :ref:`with block <ref_eql_statements_with>`, but are available
+to all queries using the schema and can be introspected.
 
+Like computed properties, the aliased expression is evaluated on the fly
+whenever the alias is referenced.
 
-An **alias** is a *pointer* to a set of values. This set is defined with an
-arbitrary EdgeQL expression.
 
-Like computed properties, this expression is evaluated on the fly whenever the
-alias is referenced in a query. Unlike computed properties, aliases are
-defined independent of an object type; they are standalone expressions.
-As such, aliases are fairly open ended. Some examples are:
-
-**Scalar alias**
+Scalar alias
+============
 
 .. code-block:: sdl
 
+  # in your schema:
   alias digits := {0,1,2,3,4,5,6,7,8,9};
 
-**Object type alias**
+Later, in some query:
+
+.. code-block:: edgeql
+
+  select count(digits);
+
+
+Object type alias
+=================
 
 The name of a given object type (e.g. ``User``) is itself a pointer to the *set
 of all User objects*. After declaring the alias below, you can use ``User`` and
-``UserAlias`` interchangably.
+``UserAlias`` interchangeably:
 
 .. code-block:: sdl
 
   alias UserAlias := User;
 
-**Object type alias with computeds**
+Object type alias with computeds
+================================
 
-Object type aliases can include a *shape* that declare additional computed
-properties or links.
+Object type aliases can include a *shape* that declares additional computed
+properties or links:
 
 .. code-block:: sdl
 
-    type Post {
-      required title: str;
-    }
+  type Post {
+    required title: str;
+  }
+
+  alias PostWithTrimmedTitle := Post {
+    trimmed_title := str_trim(.title)
+  }
 
-    alias PostAlias := Post {
-      trimmed_title := str_trim(.title)
-    }
+Later, in some query:
 
-In effect, this creates a *virtual subtype* of the base type, which can be
-referenced in queries just like any other type.
+.. code-block:: edgeql
 
-**Other arbitrary expressions**
+  select PostWithTrimmedTitle {
+    trimmed_title
+  };
+
+Arbitrary expressions
+=====================
 
 Aliases can correspond to any arbitrary EdgeQL expression, including entire
 queries.
 
 .. code-block:: sdl
 
-    # Tuple alias
-    alias Color := ("Purple", 128, 0, 128);
-
-    # Named tuple alias
-    alias GameInfo := (
-      name := "Li Europan Lingues",
-      country := "Iceland",
-      date_published := 2023,
-      creators := (
-        (name := "Bob Bobson", age := 20),
-        (name := "Trina Trinadóttir", age := 25),
-      ),
-    );
-
-    type BlogPost {
-      required title: str;
-      required is_published: bool;
-    }
-
-    # Query alias
-    alias PublishedPosts := (
-      select BlogPost
-      filter .is_published = true
-    );
+  # Tuple alias
+  alias Color := ("Purple", 128, 0, 128);
+
+  # Named tuple alias
+  alias GameInfo := (
+    name := "Li Europan Lingues",
+    country := "Iceland",
+    date_published := 2023,
+    creators := (
+      (name := "Bob Bobson", age := 20),
+      (name := "Trina Trinadóttir", age := 25),
+    ),
+  );
+
+  type BlogPost {
+    required title: str;
+    required is_published: bool;
+  }
+
+  # Query alias
+  alias PublishedPosts := (
+    select BlogPost
+    filter .is_published = true
+  );
 
 .. note::
 
@@ -92,11 +106,127 @@ queries.
   <ref_graphql_index>`.
 
 
+.. _ref_eql_sdl_aliases:
+.. _ref_eql_sdl_aliases_syntax:
+
+Defining aliases
+================
+
+Syntax
+------
+
+Define a new alias corresponding to the :ref:`more explicit DDL
+commands <ref_eql_ddl_aliases>`.
+
+.. sdl:synopsis::
+
+  alias <alias-name> := <alias-expr> ;
+
+  alias <alias-name> "{"
+      using <alias-expr>;
+      [ <annotation-declarations> ]
+  "}" ;
+
+Where:
+
+:eql:synopsis:`<alias-name>`
+  The name (optionally module-qualified) of an alias to be created.
+
+:eql:synopsis:`<alias-expr>`
+  The aliased expression.  Must be a :ref:`Stable <ref_reference_volatility>`
+  EdgeQL expression.
+
+The valid SDL sub-declarations are listed below:
+
+:sdl:synopsis:`<annotation-declarations>`
+  Set alias :ref:`annotation <ref_eql_sdl_annotations>`
+  to a given *value*.
+
+
+.. _ref_eql_ddl_aliases:
+
+DDL commands
+============
+
+This section describes the low-level DDL commands for creating and
+dropping aliases. You typically don't need to use these commands
+directly, but knowing about them is useful for reviewing migrations.
+
+Create alias
+------------
+
+:eql-statement:
+:eql-haswith:
+
+Define a new alias in the schema.
+
+.. eql:synopsis::
+
+  [ with <with-item> [, ...] ]
+  create alias <alias-name> := <alias-expr> ;
+
+  [ with <with-item> [, ...] ]
+  create alias <alias-name> "{"
+      using <alias-expr>;
+      [ create annotation <attr-name> := <attr-value>; ... ]
+  "}" ;
+
+  # where <with-item> is:
+
+  [ <module-alias> := ] module <module-name>
+
+Parameters
+^^^^^^^^^^
+
+Most sub-commands and options of this command are identical to the
+:ref:`SDL alias declaration <ref_eql_sdl_aliases_syntax>`, with some
+additional features listed below:
+
+:eql:synopsis:`[ <module-alias> := ] module <module-name>`
+  An optional list of module alias declarations to be used in the
+  alias definition.
+
+:eql:synopsis:`create annotation <annotation-name> := <value>;`
+  An optional list of annotation values for the alias.
+  See :eql:stmt:`create annotation` for details.
+
+Example
+^^^^^^^
+
+Create a new alias:
+
+.. code-block:: edgeql
+
+  create alias Superusers := (
+      select User filter User.groups.name = 'Superusers'
+  );
+
+
+Drop alias
+----------
+
+:eql-statement:
+:eql-haswith:
+
+Remove an alias from the schema.
+
+.. eql:synopsis::
+
+  [ with <with-item> [, ...] ]
+  drop alias <alias-name> ;
+
+Parameters
+^^^^^^^^^^
+
+*alias-name*
+  The name (optionally qualified with a module name) of an existing
+  expression alias.
+
+Example
+^^^^^^^
+
+Remove an alias:
 
-.. list-table::
-  :class: seealso
+.. code-block:: edgeql
 
-  * - **See also**
-  * - :ref:`SDL > Aliases <ref_eql_sdl_aliases>`
-  * - :ref:`DDL > Aliases <ref_eql_ddl_aliases>`
-  * - :ref:`Cheatsheets > Aliases <ref_cheatsheet_aliases>`
+  drop alias SuperUsers;
diff --git a/docs/datamodel/extensions.rst b/docs/datamodel/extensions.rst
index d5585b6a0c6..1d6a1f5b308 100644
--- a/docs/datamodel/extensions.rst
+++ b/docs/datamodel/extensions.rst
@@ -60,7 +60,7 @@ List installed extensions:
 
 .. code-block:: bash
 
-  $ gel extension list -I my_instance
+  $ gel extension list
   ┌─────────┬─────────┐
   │ Name    │ Version │
   └─────────┴─────────┘
@@ -69,7 +69,7 @@ List available extensions:
 
 .. code-block:: bash
 
-  $ gel extension list-available -I my_instance
+  $ gel extension list-available
   ┌─────────┬───────────────┐
   │ Name    │ Version       │
   │ postgis │ 3.4.3+6b82d77 │
@@ -79,7 +79,7 @@ Install the ``postgis`` extension:
 
 .. code-block:: bash
 
-  $ gel extension install -I my_instance -E postgis
+  $ gel extension install -E postgis
   Found extension package: postgis version 3.4.3+6b82d77
   00:00:03 [====================] 22.49 MiB/22.49 MiB
   Extension 'postgis' installed successfully.
@@ -88,7 +88,7 @@ Check that extension is installed:
 
 .. code-block:: bash
 
-  $ gel extension list -I my_instance
+  $ gel extension list
   ┌─────────┬───────────────┐
   │ Name    │ Version       │
   │ postgis │ 3.4.3+6b82d77 │
@@ -98,7 +98,7 @@ After installing extensions, make sure to restart your instance:
 
 .. code-block:: bash
 
-  $ gel instance restart -I my_instance
+  $ gel instance restart
 
 Standalone extensions can now be declared in the schema, same as
 built-in extensions:
diff --git a/docs/reference/ddl/aliases.rst b/docs/reference/ddl/aliases.rst
deleted file mode 100644
index 60404397836..00000000000
--- a/docs/reference/ddl/aliases.rst
+++ /dev/null
@@ -1,123 +0,0 @@
-.. _ref_eql_ddl_aliases:
-
-=======
-Aliases
-=======
-
-This section describes the DDL commands pertaining to
-:ref:`expression aliases <ref_datamodel_aliases>`.
-
-
-Create alias
-============
-
-:eql-statement:
-:eql-haswith:
-
-:ref:`Define <ref_eql_sdl_aliases>` a new expression alias in the schema.
-
-.. eql:synopsis::
-
-    [ with <with-item> [, ...] ]
-    create alias <alias-name> := <alias-expr> ;
-
-    [ with <with-item> [, ...] ]
-    create alias <alias-name> "{"
-        using <alias-expr>;
-        [ create annotation <attr-name> := <attr-value>; ... ]
-    "}" ;
-
-    # where <with-item> is:
-
-    [ <module-alias> := ] module <module-name>
-
-
-Description
------------
-
-The command ``create alias`` defines a new expression alias in the schema.
-The schema-level expression aliases are functionally equivalent
-to expression aliases defined in a statement :ref:`with block
-<ref_eql_statements_with>`, but are available to all queries using the schema
-and can be introspected.
-
-If *name* is qualified with a module name, then the alias is created
-in that module, otherwise it is created in the current module.
-The alias name must be distinct from that of any existing schema item
-in the module.
-
-
-Parameters
-----------
-
-Most sub-commands and options of this command are identical to the
-:ref:`SDL alias declaration <ref_eql_sdl_aliases_syntax>`, with some
-additional features listed below:
-
-:eql:synopsis:`[ <module-alias> := ] module <module-name>`
-    An optional list of module alias declarations to be used in the
-    alias definition.
-
-:eql:synopsis:`create annotation <annotation-name> := <value>;`
-    An optional list of annotation values for the alias.
-    See :eql:stmt:`create annotation` for details.
-
-
-Example
--------
-
-Create a new alias:
-
-.. code-block:: edgeql
-
-    create alias Superusers := (
-        select User filter User.groups.name = 'Superusers'
-    );
-
-
-Drop alias
-==========
-
-:eql-statement:
-:eql-haswith:
-
-
-Remove an expression alias from the schema.
-
-.. eql:synopsis::
-
-    [ with <with-item> [, ...] ]
-    drop alias <alias-name> ;
-
-
-Description
------------
-
-The command ``drop alias`` removes an expression alias from the schema.
-
-
-Parameters
-----------
-
-*alias-name*
-    The name (optionally qualified with a module name) of an existing
-    expression alias.
-
-
-Example
--------
-
-Remove an alias:
-
-.. code-block:: edgeql
-
-    drop alias SuperUsers;
-
-
-.. list-table::
-  :class: seealso
-
-  * - **See also**
-  * - :ref:`Schema > Aliases <ref_datamodel_aliases>`
-  * - :ref:`SDL > Aliases <ref_eql_sdl_aliases>`
-  * - :ref:`Cheatsheets > Aliases <ref_cheatsheet_aliases>`
diff --git a/docs/reference/ddl/index.rst b/docs/reference/ddl/index.rst
index 2b85df2f61c..c7b742c1393 100644
--- a/docs/reference/ddl/index.rst
+++ b/docs/reference/ddl/index.rst
@@ -10,7 +10,6 @@ DDL
     objects
     scalars
     properties
-    aliases
     globals
     mutation_rewrites
     future
diff --git a/docs/reference/sdl/aliases.rst b/docs/reference/sdl/aliases.rst
deleted file mode 100644
index e0520f98d9c..00000000000
--- a/docs/reference/sdl/aliases.rst
+++ /dev/null
@@ -1,66 +0,0 @@
-.. _ref_eql_sdl_aliases:
-
-==================
-Expression Aliases
-==================
-
-This section describes the SDL declarations pertaining to
-:ref:`expression aliases <ref_datamodel_aliases>`.
-
-Example
--------
-
-Declare a "UserAlias" that provides additional information for a "User"
-via a :ref:`computed link <ref_datamodel_computed>` "friend_of":
-
-.. code-block:: sdl
-
-    alias UserAlias := User {
-        # declare a computed link
-        friend_of := User.<friends[is User]
-    };
-
-.. _ref_eql_sdl_aliases_syntax:
-
-Syntax
-------
-
-Define a new alias corresponding to the :ref:`more explicit DDL
-commands <ref_eql_ddl_aliases>`.
-
-.. sdl:synopsis::
-
-    alias <alias-name> := <alias-expr> ;
-
-    alias <alias-name> "{"
-        using <alias-expr>;
-        [ <annotation-declarations> ]
-    "}" ;
-
-
-Description
------------
-
-This declaration defines a new alias with the following options:
-
-:eql:synopsis:`<alias-name>`
-    The name (optionally module-qualified) of an alias to be created.
-
-:eql:synopsis:`<alias-expr>`
-    The aliased expression.  Must be a :ref:`Stable <ref_reference_volatility>`
-    EdgeQL expression.
-
-The valid SDL sub-declarations are listed below:
-
-:sdl:synopsis:`<annotation-declarations>`
-    Set alias :ref:`annotation <ref_eql_sdl_annotations>`
-    to a given *value*.
-
-
-.. list-table::
-  :class: seealso
-
-  * - **See also**
-  * - :ref:`Schema > Aliases <ref_datamodel_aliases>`
-  * - :ref:`DDL > Aliases <ref_eql_ddl_aliases>`
-  * - :ref:`Cheatsheets > Aliases <ref_cheatsheet_aliases>`
diff --git a/docs/reference/sdl/index.rst b/docs/reference/sdl/index.rst
index e5aad8a7555..d36c7de67ea 100644
--- a/docs/reference/sdl/index.rst
+++ b/docs/reference/sdl/index.rst
@@ -107,7 +107,6 @@ to the previous migration:
     objects
     scalars
     properties
-    aliases
     globals
     mutation_rewrites
     future