diff --git a/src/items/use-declarations.md b/src/items/use-declarations.md
index 94638b6a12..2d760b6893 100644
--- a/src/items/use-declarations.md
+++ b/src/items/use-declarations.md
@@ -396,12 +396,26 @@ r[items.use.ambiguities]
 > This section is incomplete.
 
 r[items.use.ambiguities.intro]
-Some situations are an error when there is an ambiguity as to which name a `use` declaration refers. This happens when there are two name candidates that do not resolve to the same entity.
+Some situations are an error when there is an ambiguity as to which name a
+`use` declaration refers. This happens when there are two name candidates that
+do not resolve to the same entity where neither import is
+[permitted](names.resolution.expansion.imports.shadowing) to shadow the other.
+
+r[names.resolution.early.imports.errors.ambiguity.globvsglob]
+* it is an error to name an item through ambiguous use declarations
+    * two globs imports which both have an item matching that name where the items are different
+        * this is still an error even if there is a third non glob binding resolution to an item with the same name
+* it is not an error to have two glob imports which include items which would be ambiguous so long as you do not name one of those items through the ambiguous glob imports
 
 r[items.use.ambiguities.glob]
 Glob imports are allowed to import conflicting names in the same namespace as long as the name is not used.
 For example:
 
+TODO: move this section? It's documenting a situation that _isnt_ an ambiguity
+error. I've been working off of a pattern I think I saw in a few other
+locations, where we have specific error sections that document all of the
+reference relevant error cases associated with an some part of the language.
+
 ```rust
 mod foo {
     pub struct Qux;
@@ -442,6 +456,146 @@ fn main() {
 }
 ```
 
+r[names.resolution.early.imports.errors.ambiguity.builtin-attr]
+* it is an error to use a user defined attribute or derive macro with the same name as a builtin attribute (e.g. inline)
+    * I think we may special case this one and allow certain kinds of
+      ambiguities where the builtin-attr is shadowed by a user attribute (not
+      sure if this actually exists or is just proposed, TODO investigate)
+
+```rust
+use derive as inline; // OK
+
+#[inline] // Not OK, ambiguity at use time
+fn main() {}
+```
+
+<!-- ignore: test doesn't support proc-macro -->
+```rust,ignore
+// myinline/src/lib.rs
+use proc_macro::TokenStream;
+
+#[proc_macro_attribute]
+pub fn inline(_attr: TokenStream, item: TokenStream) -> TokenStream {
+    item
+}
+```
+
+<!-- ignore: requires external crates -->
+```rust,ignore
+// src/lib.rs
+use myinline::inline;
+use myinline::inline as myinline;
+
+#[myinline::inline]
+pub fn foo() {}
+
+#[crate::inline]
+pub fn bar() {}
+
+#[myinline]
+pub fn baz() {}
+
+#[inline] // ERROR `inline` is ambiguous
+pub fn quix() {}
+```
+
+r[names.resolution.early.imports.errors.ambiguity.textualvspathbasedscope]
+* path-based scope bindings for macros may not shadow textual scope bindings to macros
+    * This is sort of an intersection between macros and imports, because at
+      least in stable rust you can only get path-based macro resolutions from
+      imports of mbe macros (and presumably from proc macro crates), but you
+      can only get textual scope of macros from macro declarations
+    * https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces.use-shadow
+    * [macro.decl.scope.path.ambiguity]
+r[names.resolution.early.imports.errors.ambiguity.globvsouter]
+* it is an error to shadow an outer name binding with a glob import
+    * This seems to only apply to early resolution (duh, I documented this as part of an early resolution codepath)
+        *   // Below we report various ambiguity errors.
+            // We do not need to report them if we are either in speculative resolution,
+            // or in late resolution when everything is already imported and expanded
+            // and no ambiguities exist.
+    * I attempted to produce an example using structs and it allowed the outer import to shadow the inner glob just fine
+
+```rust
+mod bar {
+    pub struct Name;
+}
+
+mod baz {
+    pub struct Name;
+}
+
+use baz::Name;
+
+pub fn foo() {
+    use bar::*;
+    Name;
+}
+```
+
+* I'd like to have a better understanding of why this doesn't trigger ambiguity errors.
+    * I'm taking a guess but I think it has to do with how and when we resolve
+      names during early resolution. We resolve all the imports but ambiguities
+      only occur when observed, so we'd need to try to resolve Name during
+      early resolution which simply won't happen because it is a struct so it
+      will never be visited for resolution during expansion.
+    * We will end up resolving the imports themselves, but they'll resolve fine
+      because the imports themselves aren't ambiguous
+    * By the time we get to late resolution we no longer expect there to be any
+      ambiguities, so we will happily return the first resolution result and
+      never search for additional ambiguities, so we resolve directly to
+      `bar::Name` through the glob import
+
+    * doing it with macros produced the expected error
+```rust
+mod bar {
+    macro_rules! name {
+        () => {}
+    }
+    pub(crate) use name;
+}
+
+mod baz {
+    macro_rules! name {
+        () => {}
+    }
+    pub(crate) use name;
+}
+
+use baz::name;
+
+pub fn foo() {
+    use bar::*;
+    name!(); // ERROR `name` is ambiguous
+}
+```
+
+* how does it work with imports? The same as macros, same error during early resolution
+
+```rust
+mod bar {
+    pub mod foo {
+        pub struct Name;
+    }
+}
+
+mod baz {
+    pub mod foo {
+        pub struct Name;
+    }
+}
+
+use baz::foo;
+
+pub fn foo() {
+    use bar::*;
+    use foo::Name; // `foo` is ambiguous
+}
+```
+
+r[names.resolution.early.imports.errors.ambiguity.globvsexpanded]
+* Grey Area
+
 [`extern crate`]: extern-crates.md
 [`macro_rules`]: ../macros-by-example.md
 [`self`]: ../paths.md#self
@@ -460,3 +614,4 @@ fn main() {
 [tool attributes]: ../attributes.md#tool-attributes
 [type alias]: type-aliases.md
 [type namespace]: ../names/namespaces.md
+[macro.decl.scope.path.ambiguity]: ../macros-by-example.md#macro.decl.scope.path.ambiguity
diff --git a/src/macros-by-example.md b/src/macros-by-example.md
index b1c585da7a..5199a9abda 100644
--- a/src/macros-by-example.md
+++ b/src/macros-by-example.md
@@ -326,6 +326,50 @@ fn foo() {
 // m!(); // Error: m is not in scope.
 ```
 
+* textual scope name bindings for macros may shadow path-based scope bindings
+  to macros
+
+```rust
+macro_rules! m {
+    () => {
+        println!("m");
+    };
+}
+
+#[macro_export]
+macro_rules! m2 {
+    () => {
+        println!("m2");
+    };
+}
+
+use crate::m2 as m;
+
+m!(); // prints "m\n"
+```
+
+r[macro.decl.scope.textual.ambiguity.moreexpandedvsouter]
+* it is an error for name bindings from macro expansions to shadow name bindings from outside of those expansions
+
+```rust
+macro_rules! name {
+    () => {}
+}
+
+macro_rules! define_name {
+    () => {
+        macro_rules! name {
+            () => {}
+        }
+    }
+}
+
+fn foo() {
+    define_name!();
+    name!(); // ERROR `name` is ambiguous
+}
+```
+
 r[macro.decl.scope.macro_use]
 ### The `macro_use` attribute
 
@@ -393,10 +437,54 @@ mod mac {
 }
 ```
 
+r[macro.decl.scope.path.reexport]
+
+* macros can be re-exported to give them path-based scope from a module other than the crate root.
+    * there's some visibility stuff here that may already be mentioned
+      elsewhere. I'm pretty sure that w/o a #[macro_export] the macro being
+      re-exported is implicitly pub(crate) and with one it is implicitly pub.
+      The later is mentioned below, don't remember where I saw the former.
+
+```
+mac::m!(); // OK: Path-based lookup finds m in the mac module.
+
+mod mac {
+    macro_rules! m {
+        () => {};
+    }
+    pub(crate) use m;
+}
+```
+
+
 r[macro.decl.scope.path.export]
 Macros labeled with `#[macro_export]` are always `pub` and can be referred to
 by other crates, either by path or by `#[macro_use]` as described above.
 
+r[macro.decl.scope.path.ambiguity]
+* path-based scope bindings for macros may not shadow textual scope bindings to macros
+    * This is sort of an intersection between macros and imports, because at
+      least in stable rust you can only get path-based macro resolutions from
+      imports of mbe macros (and presumably from proc macro crates), but you
+      can only get textual scope of macros from macro declarations
+    * https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces.use-shadow
+
+```rust
+#[macro_export]
+macro_rules! m2 {
+    () => {}
+}
+
+macro_rules! m {
+    () => {}
+}
+
+pub fn foo() {
+    m!(); // ERROR `m` is ambiguous
+    use crate::m2 as m;
+}
+```
+
 r[macro.decl.hygiene]
 ## Hygiene
 
diff --git a/src/names.md b/src/names.md
index b9af0e5359..2d96c371ac 100644
--- a/src/names.md
+++ b/src/names.md
@@ -28,7 +28,6 @@ r[names.namespace]
 Names are segregated into different [*namespaces*], allowing entities in
 different namespaces to share the same name without conflict.
 
-r[names.resolution]
 [*Name resolution*] is the compile-time process of tying paths, identifiers,
 and labels to entity declarations.
 
diff --git a/src/names/name-resolution.md b/src/names/name-resolution.md
index da60d7eb32..61c01cc0cc 100644
--- a/src/names/name-resolution.md
+++ b/src/names/name-resolution.md
@@ -1,4 +1,174 @@
+r[names.resolution]
 # Name resolution
 
-> [!NOTE]
-> This is a placeholder for future expansion.
+r[names.resolution.intro]
+
+_Name resolution_ is the process of tying paths and other identifiers to the
+declarations of those entities. Names are segregated into different
+[namespaces], allowing entities in different namespaces to share the same name
+without conflict. Each name is valid within a [scope], or a region of source
+text where that name may be referenced. Access to certain names may be
+restricted based on their [visibility].
+
+Name resolution is split into three stages throughout the compilation process.
+The first stage, Expansion-time resolution, resolves all [use declarations] and
+[macro invocations]. The second stage, Primary resolution, resolves all names
+that have not yet been resolved that do not depend on type information to
+resolve. The last stage, Type-relative resolution, resolves the remaining names
+once type information is available.
+
+> Note
+>
+> * Expansion-time resolution is also known as "Early Resolution"
+> * Primary resolution is also known as "Late Resolution"
+
+r[names.resolution.expansion]
+## Expansion-time name resolution
+
+r[names.resolution.expansion.intro]
+
+Expansion-time name resolution is the stage of name resolution necessary to
+complete macro expansion and fully generate a crate's AST. This stage requires
+the resolution of macro invocations and use declarations. Resolving use
+declarations is required to resolve [path-based scope] macro invocations.
+Resolving macro invocations is required in order to expand them.
+
+The expansion process is iterative, alternately resolving imports, resolving
+and expanding macro invocations, then repeating until there are no further
+macros invocations to resolve. Once this process is completed all the imports
+are resolved again to ensure that the macro expansion process did not introduce
+any new ambiguious imports.
+
+TODO: do we want to talk about this? feels like an implementation detail but
+also really helps to understand certain kinds of ambiguity errors that users
+can run into.
+
+> Note
+>
+> This causes so called time traveling ambiguities, such as when a glob import introduces an item that is ambiguous with its own base path.
+>
+```rust
+macro_rules! m {
+    () => { mod bar {} }
+}
+
+mod bar {
+    pub(crate) use m;
+}
+
+fn f() {
+    // * initially speculatively resolve bar to the module in the crate root
+    // * expansion of m introduces a second bar module inside the body of f
+    // * expansion-time resolution finalizes resolutions by re-resolving all
+    //   imports and macro invocations, sees the introduced ambiguity
+    //   and reports it as an error
+    bar::m!(); // ERROR `bar` is ambiguous
+}
+```
+
+TODO I would like to be able to link to a path-based scope section that
+     discusses the various kinds of macros that can be invoked via path-based scope.
+     Right now the section I know of off of the top of my head lives in the macros
+     by example chapter.
+
+r[names.resolution.expansion.imports]
+
+All use declarations are fully resolved during this stage of resolution.
+Type-relative paths cannot be resolved at this stage of compilation and will
+produce an error.
+
+* `Type::assoc_item`, `<Type>::assoc_item`, `<Enum>::Variant` and `EnumTyAlias::Variant` are resolved during type checking
+    * `Trait::assoc_item`, `<Type as Trait>::assoc_item` and `Enum::Variant` are resolved during late resolution
+
+```rust
+mod my_mod {
+    pub const Const: () = ();
+
+    pub enum MyEnum {
+        MyVariant
+    }
+
+    impl MyEnum {
+        pub const Const: () = ();
+    }
+
+    pub type TypeAlias = MyEnum;
+}
+
+fn foo() {
+    use my_mod::MyEnum; // OK
+    use my_mod::MyEnum::MyVariant; // OK
+    use my_mod::TypeAlias; // OK
+    use my_mod::TypeAlias::MyVariant; // Doesn't work
+    use my_mod::MyEnum::Const; // Doesn't work
+    use my_mod::Const; // OK
+    let _ = my_mod::TypeAlias::MyVariant; // OK
+    let _ = my_mod::MyEnum::Const; // OK
+}
+```
+
+r[names.resolution.expansion.imports.shadowing]
+
+The following is a list of situations where shadowing of use declarations is permitted:
+
+* [use glob shadowing]
+* [macro textual scope shadowing]
+
+r[names.resolution.expansion.imports.errors]
+r[names.resolution.expansion.imports.errors.ambiguity]
+
+TODO shadowing and ambiguity may or may not represent the same section or one may be a subsection of the other
+
+The following is a list of situations where shadowing of use declarations is
+_NOT_ permitted, otherwise known as ambiguity errors:
+
+* Builtin Attributes
+* Derive Helpers
+* Textual Vs Path-based Scope
+* Glob vs Outer
+* Glob vs Glob
+* ~~Glob vs Expanded~~ pretty certain we don't want to mention this one
+* More Expanded vs Outer
+
+r[names.resolution.expansion.macros]
+
+* .visitation-order
+    * derive helpers
+        * not visited when resolving derive macros in the parent scope (starting scope)
+    * derive helpers compat
+        * always visited
+    * macro rules bindings (textual scope macros)
+        * always visited
+    * modules (path-based scope macros)
+        * always visited
+    * macrouseprelude
+        * not visited in 2018 and later when `#[no_implicit_prelude]` is present
+    * stdlibprelude
+        * always visited for macro resolutions
+        * is it? what about no-std + no-core?
+    * builtinattrs
+        * always visited
+* .subnamespaces
+    * macros are split into two subnamespaces, one for bang macros, and the other for attributes and derives. Resolution candidates from the incorrect subnamespace are ignored
+        * https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces
+
+r[names.resolution.expansion.macros.errors.reserved-names]
+
+the names cfg and cfg_attr are reserved in the macro attribute sub-namespace
+
+* https://doc.rust-lang.org/nightly/reference/names/namespaces.html#r-names.namespaces.sub-namespaces
+
+
+r[names.resolution.late]
+
+r[names.resolution.type-dependent]
+
+[use glob shadowing]: ../items/use-declarations.md#r-items.use.glob.shadowing
+[Macros]: ../macros.md
+[use declarations]: ../items/use-declarations.md
+[macro textual scope shadowing]: ../macros-by-example.md#r-macro.decl.scope.textual.shadow
+[`let` bindings]: ../statements.md#let-statements
+[item definitions]: ../items.md
+[namespaces]: ../names/namespaces.md
+[scope]: ../names/scopes.md
+[visibility]: ../visibility-and-privacy.md
diff --git a/src/names/namespaces.md b/src/names/namespaces.md
index 1794b0fd82..ae85d2ebd8 100644
--- a/src/names/namespaces.md
+++ b/src/names/namespaces.md
@@ -119,6 +119,7 @@ For example, the [`cfg` attribute] and the [`cfg` macro] are two different entit
 
 r[names.namespaces.sub-namespaces.use-shadow]
 It is still an error for a [`use` import] to shadow another macro, regardless of their sub-namespaces.
+* TODO revisit
 
 [`cfg` attribute]: ../conditional-compilation.md#the-cfg-attribute
 [`cfg` macro]: ../conditional-compilation.md#the-cfg-macro
diff --git a/src/procedural-macros.md b/src/procedural-macros.md
index 28c93080ea..5b6533cd97 100644
--- a/src/procedural-macros.md
+++ b/src/procedural-macros.md
@@ -228,6 +228,32 @@ A helper attribute for a derive macro is declared by adding its identifier to th
 > }
 > ```
 
+r[names.resolution.early.imports.errors.ambiguity.derivehelper]
+* derive helpers used before their associated derive may not shadow other attributes or other derive helpers that are otherwise in scope after their derive
+    * TODO example? This ones harder to do concisely afaik
+
+Helper attributes may not be used before the macro that introduces them.
+
+* What happens if two macros introduce the same helper, will the second one not
+  be able to see the attribute of the first anymore, assuming their order is
+  "firstmacro" "helper" "secondmacro"?
+
+> [!NOTE]
+> rustc currently allows derive helpers to be used before their attribute macro
+> introduces them into scope so long as they do not shadow any other attributes
+> or derive helpers that are otherwise correctly in scope. This behavior
+> deprecated and slated for removal.
+> <!-- ignore: requires external crates -->
+> ```rust,ignore
+> #[helper] // deprecated, hard error in the future
+> #[derive(WithHelperAttr)]
+> struct Struct {
+>     field: (),
+> }
+> ```
+>
+> For more details, see [Rust issue #79202](https://github.com/rust-lang/rust/issues/79202).
+
 r[macro.proc.attribute]
 ## Attribute macros